aidokitwiki
User Docs Wiki

Scenario: Add a feature to an existing project (brownfield)

Audience-User Status-Shipped v0.5

When to use #

You have an existing codebase already scaffolded with aidokit (or about to be). You want to add a feature using the full Intake → Plan → Build loop, with brownfield ingestion so the Researcher and Architect roles see the real code before proposing tasks.

At a glance #

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
flowchart LR
  classDef actor    fill:#ede9fe,stroke:#6d28d9,color:#1e1b4b,stroke-width:1.2px;
  classDef cli      fill:#dbeafe,stroke:#1d4ed8,color:#0c1f4a,stroke-width:1.4px;
  classDef adapter  fill:#cffafe,stroke:#0e7490,color:#083344;
  classDef pack     fill:#dcfce7,stroke:#15803d,color:#052e16;
  classDef core     fill:#fef9c3,stroke:#a16207,color:#422006;
  classDef artifact fill:#f1f5f9,stroke:#475569,color:#0f172a;
  classDef stop     fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,stroke-dasharray:4 3;
  classDef ok       fill:#ecfdf5,stroke:#047857,color:#064e3b;
  classDef external fill:#fff7ed,stroke:#c2410c,color:#431407;
  you(["you"]):::actor
  intake["/intake --brownfield"]:::cli
  res["Researcher"]:::actor
  arch["Architect"]:::actor
  plan["Planner"]:::actor
  s1{"S1: approve brief"}:::stop
  impl["/implement-task"]:::cli
  build["Builder"]:::actor
  test["Tester-Reviewer"]:::actor
  maint["Maintainer"]:::actor
  s2{"S2: task closed"}:::stop
  nxt["/orchestrator-next"]:::cli
  you --> intake --> res --> arch --> plan --> s1 --> impl --> build --> test --> maint --> s2 --> nxt

Step-by-step #

1. Confirm the project is initialised #

ls .aido/adapter.md

Expected: the file exists. If not, fall back to the new-project scenario first.

2. Run a thorough health check #

aidokit doctor --all

--all runs every opt-in check at once (drift, hygiene, model-drift, rules, conflicts, budget-map, model-policy) so manifest, rules-file, and doc-graph drift surface before you build — not after.

Expected: one section per check confirming adapter, tier, and stack pack match the manifest; any drift is listed with a suggested fix.

2b. Build the project index (orientation) #

aidokit index build

Optional but recommended on a codebase you don't have fully in your head. It writes a local-only, deterministic map of files, exports, tests, and docs (ADR-0024) to .aidokit/index.json. Read-only scan, zero network, zero model calls.

3. Open your AI CLI for intake #

If Claude Code

claude

If Codex

codex

If Copilot

gh copilot

Expected: the CLI loads with the scaffolded workflow available.

4. Kick off brownfield intake #

/intake --brownfield "I want to add <feature>; relevant code lives in <path>"

Expected: Researcher digests the codebase; Architect proposes shape; Planner produces task briefs in agent-artifacts/briefs/.

5. Review the brief and approve #

Open agent-artifacts/briefs/<latest>.md, read it end to end, and approve. Intake stops here (hard-stop S1). Note the Beads task <id> — the next steps key off it.

Expected: no code is written yet. This is by design.

6. Gate the brief quality #

aidokit task score <id>

A deterministic 0–100 / A–F score of the brief (ADR-0021) before you spend model time on it. A low grade means the objective, acceptance criteria, or scope is underspecified — fix the brief, not the code later. Advisory; always exits 0.

7. Pre-flight the task (Tier-2 chain) #

aidokit task run <id>

Runs score → goal draft → goal plan, then stops before any model (ADR-0027). It writes a goal contract (objective, allowed files, validation commands, stop rules) and a commented run-plan to agent-artifacts/goals/, then hands control back to you. aidokit never invokes a model — the model step is yours to run next, inside that contract.

8. Open your AI CLI and work within the contract #

claude       # or: codex / gh copilot

This is the human/model step — aidokit does not run it for you. Drive your CLI (e.g. /implement-task) staying inside the allowed files and validation commands from <id>-goal.md.

Expected: Builder runs; Tester-Reviewer does two-stage review (spec compliance, then code quality); Maintainer finalises and updates CHANGELOG.md.

9. Run the acceptance criteria #

aidokit eval --task <id>

Executes the ## Acceptance criteria checkboxes from the brief — shell criteria run argv-style, manual criteria are reported for you to confirm.

Expected: per-criterion PASS / FAIL / MANUAL. Exit 1 if any FAIL, 2 if the brief has no criteria.

10. Gate every verify facet #

aidokit verify --all-facets

Runs all umbrella facets (secrets, budget, deps, license, loop-cap) in one read-only pass (ADR-0018) before the change leaves your machine.

11. Assemble the PR review packet #

aidokit pr packet --task <id>

Compiles a markdown PR packet — summary, changed files from git diff --name-only main...HEAD, and the brief's Goal / Validation / Risks / Rollback — so the reviewer gets context without spelunking (ADR-0026). Add --output pr.md to write it to a file (refuses to clobber without --force). Zero model calls.

12. Pull the next task #

/orchestrator-next

Expected: the orchestrator picks the next unblocked task from the Beads graph.

Common mistakes #

See also #