Scaffold Flow

Purpose #

The full aidokit init pipeline from CLI invocation to atomic commit. Source: .docs/ARCHITECTURE.md §8 and the 14-step sequence in .docs/docs/specs/adapter-contract.md §4.1.

Diagram #

%%{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 TD
  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;

  start(["npx aidokit init [flags]"]):::cli

  parse["1. Parse args
(@aidokit/cli)"]:::cli
  env["2. Probe host + scan project
(prereq-check + stack-detect)"]:::cli
  prereq{"3. Required prereqs OK?"}:::stop
  printInstall["Print install commands
(no auto-install — ADR-0008)
Exit 10 if --no-prompts"]:::stop
  pause["Pause for user"]:::stop
  select["4. Interactive selection
adapter, conformance, packs, MCPs, Beads"]:::cli
  ctx["5. Build ProjectContext (immutable)"]:::cli

  subgraph plan ["6. Compute file plan"]
    adRules["adapter.emitAgentRulesFile"]:::adapter
    adEngine["adapter.emitEngineConfig"]:::adapter
    adVerbs["adapter.emitVerbs"]:::adapter
    adRoles["adapter.emitRoles"]:::adapter
    adSkills["adapter.emitSkills(skills = base + packs)"]:::adapter
    adWd["adapter.emitWatchdog"]:::adapter
    adOs["adapter.emitOutputStyles"]:::adapter
    sdEmit["shared-docs: getDocsSkeleton + getArtifactsSkeleton"]:::core
  end

  dry{"7. --dry-run?"}:::stop
  dryExit["Print plan; exit 0"]:::ok
  confirm{"--yes or confirmed?"}:::stop
  staging["8. Write to .aido-staging/"]:::artifact
  commit["Atomic move to project root"]:::artifact

  mcp["9. Install MCPs
adapter.installMCP for each"]:::external
  postI["10. postInstall
chmod 0o755, bd init, .gitignore"]:::external
  manifest["11. Write .aido/adapter.md"]:::artifact
  report["12. Print summary + next steps; exit 0"]:::ok

  start --> parse --> env --> prereq
  prereq -->|no| printInstall --> pause --> select
  prereq -->|yes| select
  select --> ctx --> plan
  plan --> dry
  dry -->|yes| dryExit
  dry -->|no| confirm
  confirm -->|yes| staging --> commit --> mcp --> postI --> manifest --> report
  confirm -->|no| cancel(["Exit 40 USER_CANCELLED"]):::stop

  staging -.fails.-> rollback["Delete staging
project root untouched
Exit 20"]:::stop

Notes #

• Steps 1–7 are read-only and side-effect-free. --dry-run exits cleanly here.
• Step 8 is the first write. Until the atomic move at the end of step 8, the project root is untouched.
• Steps 9–10 invoke external commands (claude mcp add, bd init). They are declared in the adapter's capabilityDeclarations.runsShellCommands and verified by AD-STD-CAP-01.
• The securitySensitive confirmation for sensitive MCPs (Filesystem, graphify) cannot be bypassed by --yes — see concepts/security-model.md.
• Exit codes by stage: 10 prereq, 11 adapter, 12 stack pack, 13 conformance, 20 fs, 21 mcp, 40 cancelled. Full taxonomy in reference/error-codes.md.

Related Pages #

• data-flow.md — ProjectContext build, manifest parsing, interpolation
• adapter-composition.md — how the file plan is composed
• .docs/ARCHITECTURE.md §8
• .docs/docs/specs/adapter-contract.md §4.1