The emitted workflow

A tour of every file aidokit init writes into your project, what each owns, and who is allowed to edit it.

Ownership at a glance

Three colours, three owners. Knowing who owns what is the most important rule of the emitted workflow.

flowchart TB classDef adapter fill:#eff6ff,stroke:#2563eb,color:#0f172a; classDef userown fill:#f0fdf4,stroke:#15803d,color:#14532d; classDef agent fill:#fffbeb,stroke:#b45309,color:#78350f; subgraph proj ["your project root"] CL["CLAUDE.md
user-owned, regen-aware"]:::userown EN[".claude/
engine — adapter-owned"]:::adapter DOCS["docs/
user-owned, never overwritten"]:::userown ART["agent-artifacts/
agent-written work products"]:::agent AIDO[".aido/
aidokit manifest + audit log"]:::adapter BD[".beads/
task graph (optional)"]:::agent end

Figure 1. Three ownership classes. aidokit sync only touches blue boxes — and even then with diff+confirm.

End-to-end task sequence

How a single user request travels through the seven roles, from /intake through to the diff you review on disk.

sequenceDiagram autonumber actor U as User participant I as /intake participant R as Researcher participant A as Architect participant P as Planner participant B as Builder participant T as Tester-Reviewer participant M as Maintainer participant FS as Project files U->>I: "build feature X" I->>R: investigate R-->>I: research notes I->>A: design A-->>I: architecture decisions I->>P: decompose P-->>I: task brief(s) I-->>U: STOP — approve briefs? U->>B: /implement-task #1 B->>FS: edits in-scope files B->>T: hand off diff T->>T: Stage 1 — spec compliance T->>T: Stage 2 — code quality T-->>B: PASS / FAIL + report T->>M: cleanup & docs M->>FS: docs, CHANGELOG, changeset M-->>U: STOP — review diff

Figure 2. The full lifecycle. Two explicit user-approval gates (after intake, after one task) make the workflow review-friendly.

Layout (Claude Code adapter, Standard conformance, Node-TS pack)

tree

my-app/
├── CLAUDE.md                   ← agent rules (project-level, you customize)
├── .claude/                    ← engine directory (adapter-owned)
│   ├── settings.json           ← hook + permission config
│   ├── commands/               ← /intake, /implement-task, /orchestrator-next
│   ├── agents/                 ← 7 role definitions (Standard+)
│   ├── skills/                 ← 18 base skills + stack-pack contributions
│   ├── output-styles/          ← 5 styles (Standard+)
│   ├── schemas/                ← 8 JSON schemas for artifacts
│   └── scripts/                ← 19 watchdog hook scripts (mode 0o755)
├── docs/                       ← project documentation skeleton (you customize)
├── agent-artifacts/            ← task briefs, change summaries, reports
├── .aido/
│   ├── adapter.md              ← YAML manifest of your selections
│   ├── state.json              ← selected MCPs, sync history, audit log
│   └── conformance-snapshot.json
└── .beads/                     ← task graph DB (if Beads is enabled)

The Codex and Copilot adapters emit different engine directories (.codex/, .copilot/) and different agent rules file names (AGENTS.md, .github/copilot-instructions.md). The docs/, agent-artifacts/, .aido/, and .beads/ trees are shared across adapters.

What each tree is for

`CLAUDE.md` (or `AGENTS.md` / `.github/copilot-instructions.md`)

The project-level rules file the target CLI auto-loads at session start. It contains the source-of-truth chain, validation commands derived from your stack pack, and reference to your docs/ tree. You customize this file over time — aidokit sync never overwrites it without explicit confirmation.

`.claude/` (engine directory)

Adapter-owned. Everything here is regenerable. aidokit sync updates this tree from the adapter package while preserving any user-modified files (with diff + confirm).

Subdir / file	What it holds
`settings.json`	Hook registrations, permission modes per role, MCP scoping.
`commands/`	Slash-command implementations of the three workflow verbs: `intake`, `implement-task`, `orchestrator-next`.
`agents/`	Role definitions. Each role has a frontmatter with capability profile, MCP scope, preloaded skills.
`skills/`	Procedural-knowledge files the agent loads on demand or per autoload trigger. 18 base + per-stack contributions.
`output-styles/`	Structured formats for test reports, change summaries, maintenance reports, blocker reports. Standard+.
`schemas/`	JSON schemas validated by `aidokit validate <file>`.
`scripts/`	Node.js hook scripts (mode `0o755`) that implement the watchdog stop conditions. PreToolUse, PostToolUse, Stop, SubagentStop.

`docs/` (project docs skeleton)

14 starter files covering architecture, specs, ADR template, capability summaries. You own these. aidokit sync never touches them.

`agent-artifacts/`

Where the workflow writes its work products. Seven subdirectories: task briefs, change summaries, test reports, maintenance reports, blockers, digest reports, monitoring events. Each has a README documenting the owner role and file-naming convention.

`.aido/`

adapter.md — YAML manifest of your selections (adapter, conformance, spec version, capability declarations).
state.json — selected MCPs, sync history, the audit log of every install with userConfirmed and source fields.
conformance-snapshot.json — the conformance report captured at install time. aidokit doctor diffs against this for drift detection.

`.beads/` (optional)

If you opted into Beads, this is the SQLite-backed task-graph database. Use the bd CLI directly or through the Beads MCP server.

The verbs

Verb	Purpose	Hard stop after
`/intake`	Classify, research, design, and plan a change into Beads tasks.	Runs entirely in plan mode; stops before any code.
`/implement-task`	Execute one approved task end-to-end: Builder, two-stage Tester-Reviewer, then Maintainer.	Stops after one task; no auto-progression.
`/orchestrator-next`	Read project + Beads state and recommend the safest next action. Read-only.	Never edits files.

The hard stops are spec-required (intake-stops-before-code, implement-task-stops-after-one) and verified by the conformance harness.

The watchdog

Hooks live under .claude/scripts/*.mjs with execute permission. They run on every relevant tool invocation:

validate-scope.mjs — blocks writes outside the active task brief's in-scope file list.
validate-bash.mjs — refuses dangerous shell patterns.
validate-version.mjs — blocks version bumps without explicit approval.
track-test-failures.mjs — stops after three same-test failures.
track-command-failures.mjs — stops after five same-command failures.
track-file-edits.mjs — warns at five edits to the same file in one task.
health-check.mjs, inject-active-task.mjs, … (full set: 19 scripts).

When a stop fires, a blocker report lands at agent-artifacts/blockers/blocker-<id>.md with the stage, trigger, last 10 actions, and a suggested next action.

The first session

Open the project in Claude Code (claude).
Run /intake "describe what you want to build".
Approve the resulting Beads tasks.
Run /implement-task on the first task. It will stop after one task.
Run /orchestrator-next to see what should come next.
Loop.

Staged writes & atomicity

aidokit writes every file plan to .aido-staging/ first, then atomically moves them into place. If anything fails mid-write, the staging dir is preserved with a warning and your project root is untouched.