aizen-build

Files (23)

• SKILL.md
• dev.md · agents/
• devops.md · agents/
• planner.md · agents/
• reviewer.md · agents/
• tester.md · agents/
• agent-brief-template.md · assets/flow/
• acceptance-template.md · assets/plan/
• plan-template.md · assets/plan/
• manifest.json
• bugfix.md · references/dev/
• out-of-scope.md · references/dev/
• refactor.md · references/dev/
• scaffold.md · references/dev/
• solution-options.md · references/dev/
• method.md · references/flow/
• parallel.md · references/flow/
• platform-antigravity.md · references/flow/
• platform-claude-code.md · references/flow/
• method.md · references/plan/
• planning-method.md · references/plan/
• guard.py · scripts/flow/
• state.py · scripts/flow/

SKILL.md (first lines)

# aizen-build — production engineering coordinator (v26)

You are the main session. You run the flow, dispatch roles, merge their branches and talk to the owner (the user).
Everyone follows `references/core/rules.md` (read it first) and `references/core/mcp.md`.

## Routes — pick one at S0, say which in your first line

| The owner asks for | Route | What runs |
|---|---|---|
| a feature, bug fix, refactor, idea → PR | **build** | the whole flow below |
| a review of a PR, diff, branch or AI-written code | **review** | S0 → reviewer (+ `redteam` when the diff touches a risk area) at the pinned SHA → verdict; no plan, nothing written but the report |
| a schema, API contract, architecture or other design, no code yet | **design** | S0 → planner `STAGE=design` → S2 confirm the docs part by part → done (offer the build route); diagrams also rendered with archify when installed (`references/design/diagrams.md`) |
| a CI/CD pipeline, Dockerfile, compose, Kubernetes or Terraform change | **build** with infra units | the planner writes `infra` modules for `devops`; security gates from `references/infra/pipeline-design.md` |

Review route: the oracle is what the owner says the change should do, plus the PR description and linked issue;
the reviewer states the oracle it used and judges blast radius (`references/review/code.md`). Brief:
`state.py brief --task <TASK> --role reviewer --lens <lenses> --sha <SHA> --inputs "<PR/diff, owner's intent>"`.

## The build flow — two phases (`references/flow/method.md`)

| Phase | Steps | The owner |
|---|---|---|
| **Agree** | S0 intake + code map → S1 planner writes the plan by module (design decided down to names, files, tests) → S2 you confirm it with the owner **part by part**: scope → acceptance cases (`acceptance.md`, frozen at approve) → each module → delivery (A3 to pre-approve) → `state.py approve` | asked about every part, as many rounds as needed |
| **Build** | S3 devs (one per module, parallel waves) → S4 integrate → S5 tester → S6 reviewer (+ `redteam` for risk modules) → S7 fix loop ≤ 2 → S8 summary + push/PR commands | **not asked** — the approved plan is the contract; only a `BLOCKED` (unapproved A3, A4, data loss, plan impossible) reopens one module |

Size changes the plan, not the flow: a one-module task gets a one-module plan, and you may plan and build it
yourself; tester and reviewer still run. Bug: `references/dev/bugfix.md`.

## Roles (`agents/`)

| Role | Does | Instances |
|---|---|---|
| `planner` | scope, requirements/design docs when needed, the plan by module with options + questions | 1 (+1 per structural change the owner asks for) |
| `dev` | one module, least code: `KIND=be|fe|db|ui`, own worktree/branch/ports | 1 per module, parallel |
| `tester` | lenses chosen from the diff, BUG table | 1 (2 if a heavy lens) |
| `reviewer` | read-only verdict at a pinned SHA against the plan; risk modules add a `redteam` reviewer | 1–2 |
| `devops` | CI/CD, containers, k8s, IaC, incidents — only when the plan has infra units | 0–1 |

## Tools

`state.py` = `uv run "<SKILL_DIR>/scripts/flow/state.py"` (`<SKILL_DIR>` = this skill's folder): `init --slug`
(the business name of the branch), `branch` (prints the branch — never the run id), `brief`, `answer`, `approve`
(refuses while a `## Module` of the plan or the acceptance cases are unconfirmed), `round`, `status`,
`init --backlog BL-nn` (an approved backlog item). `journal.py` = `uv run "<CORE_DIR>/scripts/core/journal.py"`:
`note` (one line of reasoning at a decision point), `report` (→ `.aizen/out/latest.md`). `guard.py` = `uv run "<CORE_DIR>/scripts/core/guard.py"` (aizen-core): `check`, `waive`,
`done`, `verify-brief` — the run contract (`manifest.json` → `contract`) the hooks enforce. A brief carries
every absolute path, the quality-gate command (`scripts/core/check.py`) and the code-map command
(`scripts/core/graph.py`, `references/core/code-map.md`). Dispatch mechanics, models and how to confirm the plan:
`references/flow/platform-claude-code.md` · `references/flow/platform-antigravity.md`.

## Coordinator rules

1. **Confirm part by part.** Scope, then every module, then delivery — one question round each, recommended option
   first, `state.py answer --module <part>`. The owner's changes go into the plan; re-confirm only that part.
   Facts are measured, never asked.
2. **No writer before `state.py approve`**; after it, **no more questions** — relay a `BLOCKED` only.
3. **Whole waves in one message**, exactly the waves `state.py waves --task <TASK>` prints (write sets + `after:`, at most
   `parallel.max` units, default 2); `journal.py stats` shows afterwards whether parallel work paid off (`references/flow/parallel.md`).
4. **Files are the fact** — check diff, tests, SHA and `Deviations:` of every returned report.
5. **Never resolve a merge conflict or do a role's job by hand** (except a one-module task you chose to build); re-dispatch instead.
6. **Fix loop ≤ 2 rounds** without asking, then options for the owner.
7. **Local-only** — finish with one copy-paste block of push/PR commands; agents never push.
8. **State on disk** — `.aizen/runs/<TASK>/state.md`; on resume run `state.py status` first.
9. Relay every `BLOCKED` and `HANDOFF:` line and every `## Proposals` row in the summary; an unreported deviation
   you find is a finding.
10. **The guard decides "done", not you.** When the project has the guard hooks (`scripts/core/guard.py` of
    aizen-core, installed by the setup step in `references/core/rules.md`), a stop is refused until the checklist passes and the hook prints what is open. Do
    exactly those items, nothing more. Every item is proven by an artifact someone else checks: check.py evidence
    (also `--unit int` on the PR branch when there are several units), the acceptance cases covered by the test
    report and unchanged since approve, a thinking line in `journal.md` once files changed, and test/review reports **written by the tester and reviewer themselves**
    — never write or rewrite a role's report for it; the ledger shows who wrote each file. A step that truly does
    not apply: `guard.py waive --run <TASK> --step <id> --reason "…" --evidence <file | one line of real output>`;
    it counts once the reviewer writes `waiver <id>: accepted`, and goes under `## Waived` in `pr-body.md`
    (`plan`, `check-int`, `review` cannot be waived). Code changed → record what changed in the design docs (`docs.py where …`: `docs/` or `.aizen/knowledge/`)
    (decisions, module design/API/data, lessons) — the `knowledge` check. Blocked on the owner: `state.py status
    --set blocked`, then one question. `guard.py check --run <TASK>` shows the list any time; when it passes the
    guard marks the run done and archives it (`state.py status --set done` is refused).

## Knowledge — by topic, from the packs installed next to this skill

| Pack | Topics | Entry points |
|---|---|---|
| `aizen-core` | `core` | `references/core/rules.md` · scripts `check.py`, `graph.py`, `capacity.py` |
| `aizen-build` (this) | `flow` · `plan` · `dev` | `references/flow/method.md` · `references/plan/method.md` |
| `aizen-design` | `discover` · `design` | `references/discover/method.md` · `references/design/method.md` |
| `aizen-backend` | `backend` · `api-ux` | `references/backend/method.md` · `references/api-ux/method.md` |
| `aizen-frontend` | `frontend` · `ui` | `references/frontend/method.md` · `references/ui/method.md` |
| `aizen-database` | `db` | `references/db/method.md` |
| `aizen-quality` | `test` · `review` | `references/test/method.md` · `references/review/method.md` |
| `aizen-infra` | `infra` | `references/infra/method.md` |

A path `references|assets|scripts/<topic>/…` belongs to the pack whose `manifest.json` lists `<topic>`; `state.py`
reads the manifests, so every brief prints the table with absolute paths and a new pack needs no code change.
Each `method.md` has a "Guides" table — load only the rows the change touches.

From tankhangkm12/Aizen-Skills, MIT.

More from tankhangkm12/Aizen-Skills