Skip to content

execution-flow.md

Latest commit

 

History

History
157 lines (121 loc) · 8.22 KB

execution-flow.md

File metadata and controls

157 lines (121 loc) · 8.22 KB
Raw

aidd v2 Execution Flow

aidd v2 is a Bun and TypeScript orchestration runtime. The high-level path is:

argv -> ParsedArgs -> ResolvedConfig -> RunPlan -> mode handler -> prompt compiler -> backend -> metadata store -> iteration artifacts

Entry Points

  • bun run start -- [options] runs the CLI through cli/src/index.ts.
  • bun run start -- --web starts the local web control panel by calling startWebServer (exported from the aidd-backend barrel, implemented in backend/src/start.ts).
  • bun run start -- --mcp starts the MCP server and requires a --web backend already running.
  • The Telegram chat bridge is owned by the web backend and starts automatically when channels.telegram is configured.
  • cli/src/app.ts owns CLI dispatch, stop-signal setup, metadata scaffolding, and run execution.
  • cli/src/plan/resolve.ts turns parsed arguments and config into a RunPlan.
  • backend/src/server.ts (createWebServer) wires the embedded Elysia web route tree.

Configuration Resolution

Configuration is merged in this order:

  1. ~/.aidd/config.json
  2. <project>/.aidd/aidd.config.json
  3. CLI flags

CLI flags have highest precedence. Relative project names can resolve under applicationsRoot from user config.

Mode Selection

--web and --mcp are handled at CLI dispatch (cli/src/app.ts) before plan resolution, so they are not modes. For everything else, selectMode (cli/src/plan/resolve.ts) picks one AiddMode from the flags, in this precedence order:

Mode Trigger
director --director
audit --audit, --audit-all, or completion audit settings
interview --interview [FILE]
todo --todo
validate --validate, --check-features, or --check-artifacts
role --role ROLE_ID
directive --directive, --prompt, or --ingredient
coding Default project-work mode

--in-progress is a phase modifier (not a mode); it makes coding-like modes target already-started features. In directive mode, the supplied/compiled prompt replaces the base mode prompt rather than being appended. --directive-readonly keeps directive runs from mutating code or metadata unless the prompt explicitly asks for it. Director mode also accepts --director-context PATH; the web Director writes this file from the saved profile plus recent chat when a cycle is launched from a chat session.

Work Selection

Coding-like modes read .aidd/features/*/feature.json, then apply:

  • --feature VALUE
  • --milestone VALUE
  • --filter-by FIELD --filter VALUE
  • dependency gating, where every dependency must have passes: true
  • status gating, where waiting_approval is skipped

in_progress items sort before backlog items. Audit findings are skipped in normal coding unless audit mode or audit-inclusive logic requests them.

Prompt Compilation

The prompt compiler reads prompt fragments from prompts/ and combines:

  1. mode or phase prompt
  2. optional role wrapper
  3. feature, milestone, and field filters
  4. backend-specific fragment from prompts/_cli/
  5. common guardrail fragments from prompts/_common/
  6. v2 structured result contract

Compiled prompt snapshots are generated by:

bun run prompt:snapshot

Backend Execution

Backends implement one normalized event interface:

  • native runs the in-process OpenAI-compatible agent loop in shared/src/agent.
  • ollama uses native backend machinery with Ollama provider defaults.
  • lmstudio uses native backend machinery with LM Studio provider defaults.
  • claude-code, opencode, kilocode, and codex spawn external CLIs and parse their output.

The monitor layer handles stdout/stderr capture, idle timing, provider errors, rate-limit classification, and process termination.

Outputs

Each iteration can write:

  • .aidd/iterations/NNN.log
  • .aidd/iterations/NNN.json
  • .aidd/runs.jsonl (project-local AIDD run ledger)
  • updated .aidd/features/<id>/feature.json
  • .aidd/audit-reports/<AUDIT>-YYYY-MM-DD.md

The web control panel has a separate supervision surface: the SQLite runs table tracks web-launched process records, PID/lifecycle state, pipeline links, and run-log paths. The /runs page combines that live supervision data with project-local .aidd/runs.jsonl and iteration metadata where available.

The /director page has separate persisted chat state. Chat turns run through the selected Director backend/model in an isolated data-directory cwd and store user/assistant messages in SQLite. Director cycles remain the structured suggestion-producing path; when launched from an active chat they receive the saved profile, recent transcript, and optional cycle directive as context.

Feature completion is accepted only when the selected feature metadata and the backend's AIDD_RESULT marker agree.

Stop and Failure Behavior

  • --stop writes the configured stop file and exits.
  • Ctrl+C writes the stop file and lets the active iteration finish.
  • Timeout continuation is enabled by default for idle timeouts and transient provider errors such as provider-side HTTP 5xx responses, network errors, and provider timeouts.
  • --no-continue-on-timeout disables this continuation for fail-fast runs.
  • --quit-on-abort, --stop-when-done, and --no-stop-when-done configure the remaining stop policy.
  • Coding-mode runs are gated by a dirty-tree preflight: when the working tree carries more dirty files than dirtyTreeThreshold, the run stops before backend execution. .aidd/ metadata paths are excluded from that count, so feature/status bookkeeping never trips the gate.
  • Exit codes are defined in shared/src/orchestrator/exit-codes.ts:
Code Meaning
0 Success.
1 General error.
7 Validation error.
70 No assistant output.
71 Timeout-style failure (idle timeout).
72 Provider error.
73 Missing structured result (the backend finished without the expected AIDD_RESULT marker, or an audit produced no findings/report artifacts).
74 Rate limited.
75 Flailing (repeated unproductive iterations).
76 Write-allowlist violation (the run touched paths outside the plan's writeAllowlist).
77 Merge conflict parked.
124 Aborted.

Validation Commands

bun run start -- --project-dir . --check-features
bun run start -- --project-dir . --check-artifacts
bun run smoke:qc