{"id":48694528,"url":"https://github.com/overdrive-dev/aihaus-flow","last_synced_at":"2026-06-01T01:01:42.958Z","repository":{"id":350603425,"uuid":"1207548249","full_name":"overdrive-dev/aihaus-flow","owner":"overdrive-dev","description":"Intent-based, autonomous developer workflows for Claude Code","archived":false,"fork":false,"pushed_at":"2026-05-03T06:05:53.000Z","size":1326,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-03T07:17:29.048Z","etag":null,"topics":["ai-agents","claude-code","cli","developer-tools","workflow-automation"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/overdrive-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T04:32:57.000Z","updated_at":"2026-05-03T06:05:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/overdrive-dev/aihaus-flow","commit_stats":null,"previous_names":["overdrive-dev/aihaus-flow"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/overdrive-dev/aihaus-flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overdrive-dev%2Faihaus-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overdrive-dev%2Faihaus-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overdrive-dev%2Faihaus-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overdrive-dev%2Faihaus-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/overdrive-dev","download_url":"https://codeload.github.com/overdrive-dev/aihaus-flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overdrive-dev%2Faihaus-flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32562118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","cli","developer-tools","workflow-automation"],"created_at":"2026-04-11T07:04:38.843Z","updated_at":"2026-06-01T01:01:42.949Z","avatar_url":"https://github.com/overdrive-dev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# aihaus\n\n```\n    _    ___ _\n   / \\  |_ _| |__   __ _ _   _ ___\n  / _ \\  | || '_ \\ / _` | | | / __|\n / ___ \\ | || | | | (_| | |_| \\__ \\\n/_/   \\_\\___|_| |_|\\__,_|\\__,_|___/\n```\n\n**You think. ai builds.**\n\n### aihaus 3.0 — an autonomous, native-first developer workflow for Claude Code.\n\n**Describe a feature in plain language. It auto-routes to the right sub-flow, drives it through gated stages on a local kanban, builds it in isolated worktrees with adversarial review, and verifies the result — while everything it knows about your project stays on your machine.**\n\n[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)\n[![Version](https://img.shields.io/badge/version-0.39.0-181717?style=for-the-badge\u0026logo=github)](pkg/VERSION)\n[![aihaus 3.0](https://img.shields.io/badge/aihaus-3.0%20·%20native--first-7c3aed?style=for-the-badge)](#whats-new-in-30)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-first--class-d97757?style=for-the-badge)](https://claude.ai/code)\n\n\u003cbr\u003e\n\n```bash\n# 1 — Install aihaus (machine-once)\ngit clone https://github.com/overdrive-dev/aihaus-flow \"$XDG_DATA_HOME/aihaus\"\nbash \"$XDG_DATA_HOME/aihaus/pkg/scripts/install.sh\"\n\n# 2 — Bind it to a project (inside Claude Code)\ncd ~/myproject \u0026\u0026 claude\n\u003e /aih-install\n\u003e /aih-init                      # writes project.md, captures roles + env\n\n# 3 — Launch with full autonomy (DSP wrapper)\nbash .aihaus/auto.sh\n```\n\nRuns on macOS, Windows, Linux. No runtime, no build step — just markdown and shell scripts.\n\n\u003cbr\u003e\n\n*\"Describe it once. It routes, gates, builds, reviews, and tracks it on a local board — and never phones home.\"*\n\n\u003cbr\u003e\n\n[Why](#why-aihaus) · [Quickstart](#your-first-5-minutes) · [The Four Pillars](#the-four-pillars) · [Roles](#roles--the-online-boundary) · [How the Engine Works](#how-the-engine-works) · [Architecture](docs/architecture-3.0.md) · [Commands](#commands) · [Requirements](#requirements)\n\n\u003c/div\u003e\n\n---\n\n## Why aihaus\n\nMost of your time with ai-assisted coding goes into describing *how* instead of deciding *what*. Every prompt re-teaches the model your stack, your conventions, the decisions you already made. Sessions don't share memory, so execution drifts. There's no board tracking where work actually is, no gate stopping a half-understood task from shipping — and the moment you wire up a hosted \"agent memory,\" your project's internals leave your machine.\n\n**aihaus 3.0 inverts the loop.** You think; ai builds. A natural-language request auto-routes into a gated, staged workflow. The system understands the task to 100% before planning, writes failing tests before code, builds in isolated worktrees, runs the suite in local Docker, and parks the result at human-review. Everything it learns about your repo lives in local markdown and a private per-repo index. Nothing is hosted.\n\n\u003e [!NOTE]\n\u003e aihaus is **native-first**. It leans on Claude Code's own primitives — native `/goal`, native plan mode, the native task list, native git worktrees, native subagent memory — and layers gates, roles, a kanban, and a local memory engine *on top*. It does **not** reinvent them.\n\n---\n\n## 🚀 Your first 5 minutes\n\n### Minute 0 — Install once, bind once\n\n```bash\ngit clone https://github.com/overdrive-dev/aihaus-flow \"$XDG_DATA_HOME/aihaus\"\nbash \"$XDG_DATA_HOME/aihaus/pkg/scripts/install.sh\"   # machine-once: global /aih-* skills\n# Windows PowerShell: replace $XDG_DATA_HOME with $env:LOCALAPPDATA\n```\n\nThen, inside the project you want to work in:\n\n```bash\ncd ~/myproject \u0026\u0026 claude\n\u003e /aih-install     # bind the per-repo overlay (hooks + workspace)\n```\n\n### Minute 1 — `/aih-init` captures who you are and how you ship\n\n```\n\u003e /aih-init\n```\n\nIt scans your codebase, detects the stack, and writes `.aihaus/project.md` — the shared context every agent reads. It also **captures your role profile** (pm / builder / dev / qa / devops) and runs `/aih-env` to record your **test environment, credential *locations* (never secret values), and deploy path** into `environment.md`. You describe your setup **once**; every future session and agent reads it without you repeating yourself.\n\n### Minutes 2–4 — Describe a feature; it auto-routes, gates, and tracks\n\nYou don't have to type a slash command. Just say what you want:\n\n```\n\u003e Add multi-tenant workspaces with role-based access\n```\n\naihaus classifies the request, resolves your profile, and **auto-routes** it to the right interactive sub-flow (here, `/aih-plan`). From there it drives the gated stages — and a **local SQLite kanban tracks every move**:\n\n```\nbacklog → entendimento → planejamento → tdd → review-execucao\n        → testes → homolog → human-review → prod → box-dev\n```\n\nEach stage has a gate (PASS / SKIPPED / BLOCKED). It won't leave `planejamento` until the business rules and acceptance criteria are pinned. It writes failing tests in `tdd` before any code. It builds in an isolated worktree, runs a Playwright smoke locally, then the **full suite in local Docker** — and parks the result at `human-review` for you.\n\n### Minute 5 — Walk away with `/goal`\n\n```\n\u003e /goal get the multi-tenant backlog to human-review\n```\n\nSet a completion condition and aihaus works autonomously, turn after turn, until a fast model verifies the condition is met — driving a planned kanban backlog hands-off to human-review.\n\nThat's the whole loop: **describe → auto-route → gate → build → review → track.** No board to babysit, no stack to re-explain, nothing hosted.\n\n---\n\n## 🧱 The Four Pillars\n\naihaus 3.0 stands on four foundations. Everything else is glue.\n\n| Pillar | One line |\n|--------|----------|\n| 🧠 **Local Memory** | Everything aihaus knows about your repo lives on your machine — never hosted. |\n| 📋 **Kanban** | A staged, gated workflow whose live state is a local SQLite board. |\n| ⚙️ **Workflows** | Natural-language requests auto-route to the right sub-flow; native primitives handle fan-out. |\n| 🎯 **Goals** | Native `/goal`: set a condition, walk away, a fast model verifies it's met. |\n\n---\n\n### 🧠 Pillar 1 — Local Memory (everything local, never hosted)\n\nThree layers, all on disk, all yours — auto-injected into every session and every agent so you never repeat yourself.\n\n**(a) Markdown source-of-truth.** A small set of files is the canonical memory, auto-imported into **every session** via `CLAUDE.md` `@`-imports — so it survives `/compact` and never has to be re-pasted:\n\n| File | What it holds |\n|------|---------------|\n| `.aihaus/project.md` | Stack, conventions, architecture — read at runtime by every agent |\n| `.aihaus/decisions.md` | Architecture Decision Records. **Binding.** Every code-writing agent reads it before editing |\n| `.aihaus/knowledge.md` | Lessons and gotchas carried forward so they stop repeating |\n| `.aihaus/memory/workflows/environment.md` | Env access, credential **locations** (never values), and validation commands |\n\n**(b) `aih-graph` — a private, derived index.** A per-repo SQLite + BM25/FTS5 index (with optional local Ollama embeddings) of your **real code** (files, symbols, call-sites, tests), your markdown memory, and your commits. It lives under the OS state directory — **never merged into the repo, never hosted.** Agents query it with `aihaus memory ... --json` to ground planning, edits, review, and verification in what's actually in the tree.\n\n```bash\n▸ aihaus memory query \"where do we validate JWTs\" --json\n▸ aihaus memory callers \"createSession\" --json\n```\n\n**(c) `/aih-env` — capture the environment once.** A skill that interrogates and persists your test environment, credential **locations** (never secret values), env access, and deploy path into `environment.md`. Capture it **once**; every session and agent reads it without you re-explaining.\n\n\u003e [!IMPORTANT]\n\u003e `environment.md` records *where* credentials live and *how* to validate access — it never stores secret values. The private `aih-graph` index never leaves the OS state directory. Nothing about your project is hosted.\n\n---\n\n### 📋 Pillar 2 — Kanban (a gated, staged workflow on local SQLite)\n\nOperational state isn't scattered across files — it lives in a **local SQLite kanban** (`kanban.db`). Every task moves through stages, and **every stage has a gate** (PASS / SKIPPED / BLOCKED):\n\n| Stage | What has to be true to pass |\n|-------|------------------------------|\n| `backlog` | Captured, not yet started |\n| `entendimento` | **100% understanding** of the request |\n| `planejamento` | Business rules + acceptance criteria pinned |\n| `tdd` | Impact mapped + **failing tests** written first |\n| `review-execucao` | Built in a worktree + local **Playwright** smoke |\n| `testes` | **Full suite in local Docker** |\n| `homolog` | Staging + full Playwright |\n| `human-review` | Your call |\n| `prod` | Shipped |\n| `box-dev` | Done |\n\n**Local-first by design.** Tests run **100% in local Docker** by default. The board is the source of operational truth — and it **syncs out** to Linear, Notion, Jira, or GitHub Issues when you want a shared view.\n\n---\n\n### ⚙️ Pillar 3 — Workflows (native primitives, auto-routed)\n\naihaus 3.0 builds workflows on **native Claude Code primitives** rather than a bespoke engine.\n\n- **Auto-routing.** A natural-language request **auto-routes** to the right interactive sub-flow — `/aih-plan`, `/aih-feature`, or `/aih-bugfix`. Typing `/aih-*` is an optional override, never required. Feature work → `aih-feature`; a defect → `aih-bugfix`; \"think first\" → `aih-plan`.\n- **Native fan-out.** Native dynamic JS workflows handle autonomous fan-out — QA sweeps, devops deploys — and are **role-gated** (see below).\n- **Safe parallelism.** Many agents run at once with **zero file conflicts**: worktree isolation + **Owned-Files sharding** + sequential merge-back + a single-writer DB (**ADR-260529-A**).\n- **Native surfaces.** Written plans surface to the native **Plan panel**, and the runner **projects to the native task list** so progress shows in the GUI, not just on disk.\n\n```text\n▸ \"add a tenant switcher to the settings page\"\n   └─ auto-routed → /aih-feature  (interactive scoping → build)\n```\n\n---\n\n### 🎯 Pillar 4 — Goals (native `/goal`, hands-off)\n\n```\n\u003e /goal drive the planned backlog to human-review\n```\n\nSet a **completion condition** and aihaus works autonomously, turn after turn, until a **fast model verifies the condition is met**. It drives a planned kanban backlog through the gates to human-review, hands-off.\n\n\u003e [!NOTE]\n\u003e There is **no `aih-goal` skill** in 3.0. Native `/goal` plus auto-routed sub-flows replace it, and the kanban DB is a **default substrate** — decoupled from any \"goal\" command. This is the native-first thesis in practice.\n\n---\n\n## 🔐 Roles \u0026 the online boundary\n\naihaus 3.0 ships a **real security barrier**, not advice. Captured at `/aih-init`, your profile is one of five roles:\n\n| Profile | Scope | Can cross staging → prod? |\n|---------|-------|:---:|\n| `pm` | Scope, plan, prioritize | ✕ |\n| `builder` | Scope + build features **locally** | ✕ |\n| `dev` | Implement, **offline-local** | ✕ |\n| `qa` | Test, **offline-local** (Docker) | ✕ |\n| `devops` | Build **and** deploy | ✓ |\n\nThe staging → prod boundary **is** the capability boundary, and it's enforced by `role-guard.sh` — a **PreToolUse hook** that blocks deploy / online commands for any non-devops role. `builder` / `dev` / `qa` are **100% offline-local** (Docker).\n\n\u003e [!IMPORTANT]\n\u003e This is what lets a client safely become a **builder**: they can scope and build features locally, end to end — and they **cannot deploy**. The barrier is a hook, not a guideline.\n\n---\n\n## 🛠 How the engine works\n\nUnder the native-first surface sits a deliberate, file-driven engine: **58 specialist agents** and **15 intent-based skills**.\n\n### Thin coordinator, specialist workforce\n\nThe skill running a command is a **coordinator**. It spawns a specialist, reads the file that specialist writes, and picks the next one. The heavy work stays in subagent contexts — your main session window stays clean.\n\n### Files as the handoff protocol\n\naihaus never tries to make agents \"talk to each other.\" **Coordination happens through files** (`PLAN.md`, `REVIEW.md`, `VERIFICATION.md`, …). Every subagent writes its own artifact; the coordinator is the only writer. The payoff: a full audit trail, interruptions that resume cleanly, **zero write races**, and no dependency on an inter-agent messaging primitive Claude Code doesn't offer. See **ADR-001** in `pkg/.aihaus/decisions.md`.\n\n### Adversarial reviewers that must push back\n\nReviewer agents carry a contract: **find at least one real problem, or justify the silence in writing.** A bare PASS is rejected.\n\n| Reviewer | Scope of skepticism |\n|----------|---------------------|\n| `plan-checker` | Does this plan actually achieve its stated goal? Gate before execution |\n| `contrarian` | What premises went unexamined? Whose perspective is missing? |\n| `code-reviewer` | Severity-classified findings on the implementation diff |\n| `verifier` | Goal-backward — start from \"this did NOT work\" and hunt counter-evidence |\n| `integration-checker` | Do the pieces actually connect? Existence ≠ integration |\n| `security-auditor` | Do the threat-model mitigations exist as code, not promises |\n\n### One commit per story\n\nStories land one at a time. Each implementation commit uses an **explicit file list** drawn from that story's **Owned Files** — never `git add -A`, never a directory sweep. The history reads linearly, so `git bisect` lands on the exact failing story and every story is revertable on its own.\n\n```\n9ce646c feat(scripts): add dogfood-brainstorm.sh regression script (Story 8)\n161ee96 feat(agent): add brainstorm-synthesizer fan-in agent (Story 3)\n06dec6b feat(agent): add contrarian adversarial idea-challenger (Story 2)\n```\n\n### Agents that self-evolve\n\nAfter every run, the **reviewer** inspects the accumulated decisions and knowledge, then drafts **evidence-backed** edits to agent definitions — new read requirements, new guardrails, new protocol steps. The completion protocol applies them. Nothing is fine-tuned and no weights move; what changes is the markdown that guides agents, refined against real project experience. **The next run starts slightly smarter.**\n\n---\n\n## 📋 Commands\n\naihaus ships **15 intent-based skills**. Every command follows the same pattern: **ask scoping questions → one approval → fully autonomous** (codified in `pkg/.aihaus/skills/_shared/autonomy-protocol.md`, referenced by every skill). Remember: with auto-routing, **typing these is optional** — a plain-language request lands on the right one.\n\n### Setup \u0026 memory\n\n| Command | What it does |\n|---------|--------------|\n| `/aih-install` | Bind / refresh the per-repo overlay in cwd (resolves `AIHAUS_HOME`) |\n| `/aih-init` | Scan the codebase, write `project.md`, **capture roles + env** |\n| `/aih-env` | Capture the test environment, credential **locations**, access + deploy → `environment.md` |\n\n### Scope, plan \u0026 build (auto-routable)\n\n| Command | What it does |\n|---------|--------------|\n| `/aih-plan` | Research and plan a concrete change → `PLAN.md` |\n| `/aih-feature` | Plan → branch → implement → review → commit (single feature) |\n| `/aih-bugfix` | Triage → branch → fix → test → commit |\n| `/aih-brainstorm` | Multi-specialist exploratory panel for fuzzy topics → `BRIEF.md` |\n| `/aih-milestone` | Conversational gathering + execution for milestone-sized work |\n| `/aih-quick` | Fast-track for trivial changes — skips planning |\n\n### Run, resume \u0026 maintain\n\n| Command | What it does |\n|---------|--------------|\n| `/aih-resume` | Pick up an interrupted run from its manifest |\n| `/aih-close` | Close a stale run (slug or `--bulk`) |\n| `/aih-update` | Pull the latest aihaus, re-link, re-validate (`--check` for a dry run) |\n| `/aih-effort` | Retune agent effort tiers + model assignments (cohort-driven) |\n| `/aih-sync-notion` | Optional kanban sync to Notion |\n| `/aih-help` | List all commands and conventions |\n\n\u003e [!TIP]\n\u003e For autonomous, multi-turn execution against a completion condition, use **native `/goal`** — not a dedicated aih-skill. The kanban tracks the run regardless.\n\n### Global CLI helper\n\n```bash\naihaus memory \u003crefresh|query|context|callers|impact|gotchas|status\u003e   # query the private aih-graph index; --json for agents\n```\n\n---\n\n## ✨ What's new in 3.0\n\n- **Native-first throughout** — native `/goal`, native plan mode, native task list, native worktrees, native subagent memory. aihaus layers gates + roles + kanban + the memory engine on top.\n- **No `aih-goal` skill** — native `/goal` + auto-routed sub-flows replace it; the kanban DB is a **default substrate**, decoupled from any \"goal\" command.\n- **Auto-routing** — describe what you want; the right sub-flow is chosen for you. Slash commands are an optional override.\n- **Local kanban** — operational state lives in `kanban.db` through gated stages; tests run **100% in local Docker** by default; syncs to Linear / Notion / Jira / GitHub Issues.\n- **Role-based online boundary** — `role-guard.sh` makes \"only devops may deploy\" a hook-enforced barrier, so a client can safely build locally.\n- **Private repo memory** — `aih-graph` indexes real code, markdown memory, and commits into a per-repo SQLite/BM25 index under the OS state dir. Never hosted.\n\n---\n\n## 📦 What gets installed\n\n```\nyour-project/\n├── .aihaus/                          # aihaus workspace\n│   ├── skills/                       # 15 intent-based commands\n│   │   └── _shared/\n│   │       └── autonomy-protocol.md  # Binding execution-autonomy rules\n│   ├── agents/                       # 58 specialist agent definitions\n│   ├── hooks/                        # lifecycle + protocol hooks (incl. role-guard.sh)\n│   ├── workflows/                    # stage workflow + kanban DB substrate\n│   ├── memory/                       # local markdown memory (project.md, environment.md, …)\n│   ├── decisions.md                  # Architecture Decision Records (binding)\n│   └── knowledge.md                  # Accumulated lessons\n│\n└── .claude/                          # Claude Code config\n    ├── settings.local.json           # Permissions + hooks (auto-merged)\n    ├── skills/   → .aihaus/skills/\n    ├── agents/   → .aihaus/agents/\n    └── hooks/    → .aihaus/hooks/\n```\n\nThe installer creates symlinks (Unix) or directory junctions (Windows); `--copy` forces file copies. Settings are **merged**, not overwritten.\n\n---\n\n## ⚙️ Requirements\n\n- **Claude Code** v2.0.0+ (the `--dangerously-skip-permissions` flag is required for `bash .aihaus/auto.sh`; older versions trigger a soft warning at install, and the rest of the toolkit still works under bare `claude`).\n- **git**\n- **bash** (Unix) or **Git Bash / WSL / PowerShell 5+** (Windows)\n- **Docker** — to run the test stages locally (Pillar 2 default)\n- **python** or **jq** — for JSON settings merging (optional; the installer degrades gracefully)\n- **Ollama** *(optional)* — for local semantic embeddings in `aih-graph`; BM25/FTS5 works without it\n\nNo runtime. No build step. No package manager. The entire package is **markdown and shell scripts**.\n\n\u003e [!NOTE]\n\u003e aihaus is **stack-agnostic**. Agents read `project.md` at runtime — they never assume Python, Node, Go, or anything else. Install it in a Rust project, a Rails app, or a Go microservice; it adapts.\n\n---\n\n## 📄 License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**You think. ai builds.**\n\n*Describe it once. It routes, gates, builds, and tracks — locally, with a real role barrier, and nothing hosted.*\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foverdrive-dev%2Faihaus-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foverdrive-dev%2Faihaus-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foverdrive-dev%2Faihaus-flow/lists"}