agentleFS
davidmatousekdavidmatousek/tachi/.claude/skills/~aod-run/SKILL.md

~aod-run

Skill95 starsChanged 37 days agoApache-2.0View on GitHub

Full lifecycle orchestrator that chains all 6 AOD stages (Discover, Define, Plan, Build, Deliver, Document) with disk-persisted state for session resilience and governance gates at every boundary. Use this skill when you need to run the full lifecycle, orchestrate stages, resume orchestration, or check orchestration status.

The file

Show its rules and text

We split this skill into the rules it gives an agent

78 rules. About 0 are common, 29 are distinctive, and 49 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈29

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 49

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When this skill is invoked, the command file passes a parsed mode and arguments:

    line 42
  2. Distinctive:

    Read the mode and DryRun flag from the invocation context.

    line 53
  3. Very specific:

    DryRun + Status check (first): If DryRun == true AND Mode == status, display "Note: --status is already read-only.

    line 55
  4. Very specific:

    DryRun check (second): If DryRun == true (and Mode is NOT status):

    line 57
  5. Distinctive:

    Follow the Dry-Run Entry instructions from that file.

    line 61
  6. Very specific:

    After the entry handler sets up state, all modes (except status) converge to the Consent Prompt, then the Core Loop.

    line 74
  7. Distinctive:

    Before entering the Core Loop, display the autonomous mode consent prompt and capture the user's choice.

    line 78
  8. Very specific:

    Read loop context: Use Bash to read loop context via bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_get_loop_context' — …

    line 112
  9. Very specific:

    Determine next stage: Use the current_stage and stage_status from step 1.

    line 114
  10. Very specific:

    Write pre-stage checkpoint: Update state with current_stage status = "in_progress" and current timestamp.

    line 116
  11. Distinctive:

    Invoke stage skill: Use the Skill tool to invoke the appropriate stage skill (see Stage Skill Mapping).

    line 130
  12. Distinctive:

    Parallel Triad Reviews: When a governance gate requires multiple reviewers (e.g., plan.md requires PM + Architect, tasks.md requires PM + …

    line 133
  13. Very specific:

    Cache all verdicts: After all reviewers return, cache each verdict via aod_state_cache_governance before evaluating the aggregate result.

    line 136
  14. Very specific:

    Aggregate evaluation: After all reviewers complete, evaluate the combined result.

    line 137
  15. Very specific:

    CHANGES_REQUESTED: Follow the Rejection Handling instructions in references/governance.md (re-read if not already loaded).

    line 143
  16. Very specific:

    BLOCKED: Follow the Blocked Handling instructions in references/governance.md (re-read if not already loaded).

    line 144
  17. Very specific:

    Write post-stage checkpoint: Update state with completion status, artifacts, governance results, timestamp.

    line 146
  18. Very specific:

    Update GitHub Issue label: If gh available, update stage label (see GitHub Integration)

    line 156
  19. Very specific:

    After governance reviews: If reviewer feedback, rejection details, or override justifications produced significant output (>50 lines), …

    line 161
  20. Distinctive:

    Skip re-grounding: when: the previous step produced minimal output (stage map display, short status messages, cache hits).

    line 164
  21. Distinctive:

    All stages completed → display lifecycle summary (6/6)

    line 169
  22. Very specific:

    When entering Plan stage: If current_substage is null, set it to spec (first substage).

    line 182
  23. Very specific:

    Determine active substage: Read current_substage from state.

    line 184
  24. Very specific:

    If "completed": Advance to next substage in sequence

    line 185
  25. Very specific:

    If "pending" or "in_progress": This is the active substage to execute

    line 186
  26. Distinctive:

    When advancing from one substage to the next (spec → project_plan, or project_plan → tasks), apply a context boundary to prevent context …

    line 195
  27. Distinctive:

    If the next substage explicitly needs details from a prior artifact, it can re-read the artifact using the path stored in metadata.

    line 215
  28. Distinctive:

    Write substage checkpoint: After each substage transition, write state atomically.

    line 223
  29. Distinctive:

    Display: When displaying the stage map during Plan, show the active substage:

    line 235
  30. Very specific:

    Invocation pattern: Use the Skill tool with skill: "{skill_name}" and pass arguments as args: "{arguments}".

    line 257
  31. Very specific:

    After Discover completes: extract GitHub Issue number from discovery output.

    line 260
  32. Very specific:

    After Define completes: PRD path is at docs/product/02_PRD/{NNN}-*.md.

    line 261
  33. Very specific:

    After Plan:spec completes: spec path is at specs/{NNN}-*/spec.md.

    line 262
  34. Very specific:

    After Plan:project_plan completes: plan path is at specs/{NNN}-*/plan.md.

    line 263
  35. Very specific:

    After Plan:tasks completes: tasks path is at specs/{NNN}-*/tasks.md.

    line 264
  36. Very specific:

    After Build completes: implementation files tracked via tasks.md [X] markers

    line 265
  37. Distinctive:

    After Deliver completes: delivery summary and metrics captured

    line 266
  38. Very specific:

    When autonomous_mode == true, prepend --autonomous to all skill args:

    line 270
  39. Very specific:

    When autonomous_mode == false (interactive), omit --autonomous:

    line 279
  40. Distinctive:

    Plan stages: no args

    line 283
  41. Distinctive:

    After each stage skill returns, the orchestrator extracts context from the produced artifacts and updates the state file.

    line 290
  42. Very specific:

    Use Bash to scan for new GitHub Issues: gh issue list --label "stage:discover" --json number,title --limit 5 (if gh available)

    line 295
  43. Very specific:

    Create the feature branch if not already on it: git checkout -b {branch} (or confirm current branch matches)

    line 300
  44. Distinctive:

    Write updated state atomically

    line 302
  45. Very specific:

    Use Glob to find the PRD: docs/product/02_PRD/{NNN}-*.md where NNN is feature_id

    line 306
  46. Very specific:

    Use Glob to find the spec: specs/{NNN}-*/spec.md

    line 312
  47. Very specific:

    Use Glob to find the plan: specs/{NNN}-*/plan.md

    line 318
  48. Very specific:

    Use Glob to find tasks and assignments: specs/{NNN}-*/tasks.md, specs/{NNN}-*/agent-assignments.md

    line 324
  49. Distinctive:

    After recording Plan:tasks artifacts and before the Core Loop advances to Build, perform a size estimation:

    line 331
  50. Very specific:

    Read agent-assignments.md from specs/{NNN}-*/agent-assignments.md

    line 333
  51. Distinctive:

    Update state with the estimation:

    line 339
  52. Very specific:

    Read tasks.md from specs/{NNN}-*/tasks.md

    line 356
  53. Very specific:

    Update build_progress in state:

    line 363
  54. Very specific:

    Check existence via Bash: test -f "$halt_record_path" && echo EXISTS

    line 411
  55. Distinctive:

    If the file does NOT exist: assume Deliver succeeded.

    line 412
  56. Very specific:

    If the file exists, parse it via jq:

    line 413
  57. Very specific:

    Autonomous mode policy: If autonomous_mode == true, the halt is non-recoverable within the current run — the lifecycle stops here.

    line 452
  58. Very specific:

    Interactive mode policy: If autonomous_mode == false, display the halt summary and prompt:

    line 458
  59. Very specific:

    Read state from .aod/run-state.json

    line 486
  60. Very specific:

    If Plan is completed → Plan

    line 496
  61. Distinctive:

    After Discover and Define complete, Plan:spec in progress:

    line 512
  62. Distinctive:

    Map stage to number and detail: Use the lookup table below:

    line 538
  63. Very specific:

    After each stage completes successfully (governance gate passed), update the GitHub Issue's stage:* label to reflect the new current stage.

    line 572
  64. Very specific:

    Read github_issue from state.

    line 577
  65. Very specific:

    Check if gh CLI is available: command -v gh >/dev/null 2>&1.

    line 578
  66. Very specific:

    Check if gh is authenticated: gh auth status >/dev/null 2>&1.

    line 579
  67. Very specific:

    Update the label: Use the github-lifecycle.sh function:

    line 596
  68. Distinctive:

    Handle failures gracefully: If the label update fails, log a warning but do NOT halt orchestration.

    line 601
  69. Distinctive:

    Backlog refresh: After updating the label:

    line 604
  70. Very specific:

    Append to state: Use the aod_state_append function:

    line 642
  71. Distinctive:

    Stage skill failure: When a Skill tool invocation produces an error or unexpected output

    line 648
  72. Distinctive:

    Circuit breaker activation: When max retries are reached

    line 650
  73. Distinctive:

    User abort: When the user chooses to abort

    line 651
  74. Distinctive:

    Artifact inconsistency: When resume validation detects missing artifacts

    line 652
  75. Distinctive:

    State corruption: When the state file fails validation

    line 653
  76. Very specific:

    GitHub errors: When gh CLI operations fail

    line 654
  77. Distinctive:

    Error entries are append-only: Never remove or modify existing error log entries.

    line 656
  78. Very specific:

    Resume-after-break flow: When aod.run --resume loads a state where Build is in_progress, it re-invokes aod.build --orchestrated …

    line 693

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Full Lifecycle Orchestrator Skill

Purpose

Single-command lifecycle orchestrator that chains all 6 AOD stages autonomously, pausing at governance gates for Triad sign-offs and persisting state to disk for session resilience. After Deliver completes, Document runs automatically as Stage 6.

Entry Points:

  • Raw idea: "description" → start at Discover
  • Issue number: #NNN or NNN → resume from issue's current stage
  • Resume: --resume → continue from last state checkpoint
  • Status: --status / --status #NNN → read-only display

State File: .aod/run-state.json (atomic write-then-rename via run-state.sh)

Navigation

SectionPurposeLocation
Step 1: Route by ModeEntry point routingThis file
Step 2: Core State Machine LoopCentral orchestration logicThis file
Plan Substage TrackingSpec → project_plan → tasksThis file
Stage Skill MappingStage-to-skill invocation tableThis file
Post-Stage Context ExtractionArtifact discovery after each stageThis file
Stage Map DisplayVisual progress indicatorsThis file
Transition MessagesStage transition headersThis file
GitHub IntegrationLabel updates after stage completionThis file
Error LoggingError/event capture in state fileThis file
Governance Gate DetectionReading approval/rejection from frontmatterreferences/governance.md
Governance TierLight/Standard/Full gate rulesreferences/governance.md
Rejection / Retry / Circuit Breaker / BlockedGovernance result handlingreferences/governance.md
New Idea / Issue / Resume / Status EntryMode-specific handlersreferences/entry-modes.md
Dry-Run Entry--dry-run preview handler (read-only)references/dry-run.md
Corrupted State / Lifecycle CompleteError and completion handlersreferences/error-recovery.md

Execution

When this skill is invoked, the command file passes a parsed mode and arguments:

Mode: {idea | issue | resume | status}
Issue: {number or "none"}
Idea: {text or "none"}
DryRun: {true or false}

Step 1: Route by Mode

Read the mode and DryRun flag from the invocation context. Route to the appropriate handler:

DryRun + Status check (first): If DryRun == true AND Mode == status, display "Note: --status is already read-only. --dry-run flag ignored." and route to Status Entry as normal.

DryRun check (second): If DryRun == true (and Mode is NOT status):

MANDATORY: You MUST use the Read tool to load references/dry-run.md before proceeding with dry-run handling. Do NOT rely on memory of prior dry-run content. If the file cannot be read, display an error and STOP.

Follow the Dry-Run Entry instructions from that file. The Dry-Run Entry handler will perform read-only detection and display a preview, then exit without entering the Core Loop.

Mode routing (if DryRun is false):

MANDATORY: You MUST use the Read tool to load references/entry-modes.md before proceeding with any entry mode handler. Do NOT rely on memory of prior entry mode content. If the file cannot be read, display an error and STOP.

ModeHandlerDescription
ideaNew Idea Entry (in entry-modes.md)Create initial state, start at Discover
issueIssue Entry (in entry-modes.md)Read GitHub Issue, create/load state, resume
resumeResume Entry (in entry-modes.md)Load state file, validate, continue
statusStatus Entry (in entry-modes.md)Read-only display, then exit

After the entry handler sets up state, all modes (except status) converge to the Consent Prompt, then the Core Loop.

Step 1b: Autonomous Mode Consent

Before entering the Core Loop, display the autonomous mode consent prompt and capture the user's choice. This is the only human interaction point in the entire autonomous run.

Display:

AOD ORCHESTRATOR — Autonomous Mode
====================================
This will run the full lifecycle autonomously:

  Discover → Define → Plan → Build → Deliver → Document

Autonomous mode will:
  - Auto-select defaults for all interactive prompts
  - Auto-retry governance rejections (up to 3 attempts)
  - Halt on circuit breaker or BLOCKED (requires manual fix + resume)
  - Split across sessions if the feature is too large

All decisions are logged to run-state.json for post-run review.

Proceed? (Y/n)

Handle response:

  • Yes (or empty/default): Set autonomous_mode = true. All stage skill invocations will include --autonomous in args. Continue to Core Loop.
  • No: Set autonomous_mode = false. Skills are invoked without --autonomous (interactive mode). Continue to Core Loop.

On resume (--resume): If the state file contains "autonomous_mode": true, skip the consent prompt and continue in autonomous mode. Do not re-ask.

Step 2: Core State Machine Loop

This is the central orchestration logic. It runs after any entry handler has established or loaded state.

Loop algorithm:

  1. Read loop context: Use Bash to read loop context via bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_get_loop_context' — returns {stage}|{substage}|{stage_status} (e.g., plan|spec|in_progress). Parse the pipe-delimited result. Do NOT use aod_state_read here — the compound helper extracts only the 3 fields needed for routing.
  2. Check completion: If stage_status from step 1 indicates all stages may be complete, verify by checking all 6 stage statuses via bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_get_multi ".stages.discover.status" ".stages.define.status" ".stages.plan.status" ".stages.build.status" ".stages.deliver.status" ".stages.document.status"'. If all show completed, MANDATORY: You MUST use the Read tool to load references/error-recovery.md, then follow the Lifecycle Complete instructions. Do NOT rely on memory of prior error-recovery content. If the file cannot be read, display an error and STOP. Note: If .stages.document.status returns null (legacy 5-stage state file), treat as pending.
  3. Determine next stage: Use the current_stage and stage_status from step 1. If status is "completed", advance to the next stage in sequence: discover → define → plan → build → deliver → document
  4. Handle Plan substages: If current_stage is plan, use the substage from step 1 and cycle through spec → project_plan → tasks. Only advance past Plan when all 3 substages complete. When advancing between substages, apply context boundary (see Plan Substage Tracking step 3a) to clear previous substage content and retain only approval metadata.
  5. Write pre-stage checkpoint: Update state with current_stage status = "in_progress" and current timestamp. Write atomically via bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_write '"'"'<json>'"'"''.
  6. Display stage map: Show current progress (see Stage Map Display)
  7. Display transition message: Show formatted header for the stage about to execute (see Transition Messages) 7a. Aggressive pre-Build boundary: If the stage about to execute is build, apply an extra-aggressive context boundary before invocation:
    1. Summarize all prior stages into a compact metadata block (~500 tokens max):
      • Feature: {feature_id} - {feature_name}
      • Branch: {branch}
      • Spec: {path} (APPROVED by PM)
      • Plan: {path} (APPROVED by PM + Architect)
      • Tasks: {path} (APPROVED by PM + Architect + Team-Lead)
      • Wave count: {N}
    2. Clear ALL prior stage content from working context
    3. Build skill reads its own context (tasks.md, plan.md, assignments) fresh
    4. Display: "[Pre-Build boundary] Prior stages summarized (~500 tokens). Build reads context fresh."
  8. Invoke stage skill: Use the Skill tool to invoke the appropriate stage skill (see Stage Skill Mapping). Pass required context (idea text, issue number, artifact paths from prior stages).
  9. Detect governance result: After the skill returns, first check the governance cache via bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_get_governance_cache "{artifact}" "{reviewer}"'. If the cache returns a verdict (not "null"), use the cached result. If the cache returns "null", MANDATORY: You MUST use the Read tool to load references/governance.md before proceeding with governance gate detection. Do NOT rely on memory of prior governance content. If the file cannot be read, display an error and STOP. Follow the Governance Gate Detection and Governance Tier instructions from that file. Apply tier-specific rules.

    Parallel Triad Reviews: When a governance gate requires multiple reviewers (e.g., plan.md requires PM + Architect, tasks.md requires PM + Architect + Team-Lead), execute reviews in parallel using multiple Agent tool calls in a single message:

    1. Parallel execution: Launch all required reviewers simultaneously via Agent tool calls in one message. Each reviewer runs in its own agent context, preventing cross-contamination.
    2. Cache all verdicts: After all reviewers return, cache each verdict via aod_state_cache_governance before evaluating the aggregate result.
    3. Aggregate evaluation: After all reviewers complete, evaluate the combined result. If any reviewer returned CHANGES_REQUESTED or BLOCKED, handle per step 10 (use the most severe status).
    4. Same checklists and criteria: Parallel execution uses the same reviewers, review prompts, and approval criteria as sequential — only the execution model changes.

    Context note: Parallel reviews are safe with 1M context. Each reviewer runs in an isolated agent context, so there is no cross-reviewer drift. Re-grounding (see below) applies once after all reviewers return, not between each reviewer.

  10. Handle result:
    • APPROVED / APPROVED_WITH_CONCERNS: Mark stage completed in state, record artifacts, write checkpoint, continue loop
    • CHANGES_REQUESTED: Follow the Rejection Handling instructions in references/governance.md (re-read if not already loaded). This includes Retry Tracking and Max-Retry Circuit Breaker checks.
    • BLOCKED: Follow the Blocked Handling instructions in references/governance.md (re-read if not already loaded).
    • No governance gate for this stage/tier: Mark completed, continue
  11. Write post-stage checkpoint: Update state with completion status, artifacts, governance results, timestamp. Write atomically via bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_write '"'"'<json>'"'"''. 11a. Apply context boundary (all stage transitions): When advancing from one stage to the next:
    1. Display: "[Context boundary] Clearing {completed_stage} context"
    2. Retain ONLY from the completed stage:
      • status (APPROVED / completed)
      • artifact_paths (list of file paths)
      • feature_id, github_issue, branch
      • governance verdict summary (one line per reviewer)
    3. The next stage skill will re-read any artifacts it needs via Read tool
    4. Skill file content from the completed stage is NOT carried forward
  12. Update GitHub Issue label: If gh available, update stage label (see GitHub Integration)
  13. Loop: Return to step 1

Re-grounding policy (context-thrifty): Re-read reference files only when variable-length output has been injected into context since the last read. This prevents template drift without wasting context on redundant reads.

  • After governance reviews: If reviewer feedback, rejection details, or override justifications produced significant output (>50 lines), re-read references/governance.md before continuing the loop. With parallel reviews, this applies once after all reviewers return, since each reviewer runs in an isolated agent context.
  • After rejection/blocked handling: Re-read references/governance.md before re-entering the loop, since user interaction and error display inject variable-length content.
  • After lifecycle complete display: Re-read references/error-recovery.md to ensure the completion template is followed exactly.
  • Skip re-grounding when: the previous step produced minimal output (stage map display, short status messages, cache hits). Unnecessary re-reads waste ~4-7K tokens each.

Stage sequence: discover → define → plan (spec → project_plan → tasks) → build → deliver → document

Exit conditions:

  • All stages completed → display lifecycle summary (6/6)
  • BLOCKED with no resolution → save state, exit
  • User chooses to pause → save state, exit
  • Session ends → user resumes with --resume in new session

Plan Substage Tracking

The Plan stage contains 3 substages executed in strict sequence. The orchestrator tracks each substage independently and only advances past Plan when all 3 are complete.

Substage sequence: spec → project_plan → tasks

Algorithm (detailed expansion of Core Loop step 4):

  1. When entering Plan stage: If current_substage is null, set it to spec (first substage). Update state: stages.plan.status = "in_progress", stages.plan.started_at = {now}, current_substage = "spec".
  2. Determine active substage: Read current_substage from state. Check the substage's status in stages.plan.substages.{substage}.status:
    • If "completed": Advance to next substage in sequence
    • If "pending" or "in_progress": This is the active substage to execute
  3. Substage advancement logic:
    • spec completed → set current_substage = "project_plan", set stages.plan.substages.project_plan.status = "in_progress". Apply context boundary (see step 3a).
    • project_plan completed → set current_substage = "tasks", set stages.plan.substages.tasks.status = "in_progress". Apply context boundary (see step 3a).
    • tasks completed → set current_substage = null, mark overall Plan stage as "completed", set stages.plan.completed_at = {now}

3a. Context boundary at substage transitions (FR-013, FR-014, FR-015, FR-016) — retained for context thrift; prevents accumulation even with 1M window:

When advancing from one substage to the next (spec → project_plan, or project_plan → tasks), apply a context boundary to prevent context accumulation:

Step 1 - Display boundary message:

[Context boundary] Clearing {previous_substage} context

Where {previous_substage} is spec or project_plan.

Step 2 - Extract and retain only approval metadata: From the completed substage, retain only:

  • status: The approval status (e.g., "APPROVED")
  • artifact_path: Path to the artifact (e.g., specs/{NNN}-*/spec.md)
  • feature_id: The 3-digit feature ID (e.g., "047")

These values are already persisted in run-state.json under stages.plan.substages.{substage} and do not require re-extraction.

Step 3 - Clear previous substage full content: The previous substage's artifact content (spec.md or plan.md full text) is NOT carried forward. The next substage skill will read its own required context fresh.

Step 4 - On-demand re-read available: If the next substage explicitly needs details from a prior artifact, it can re-read the artifact using the path stored in metadata. This is NOT automatic — the substage skill must explicitly invoke the Read tool with the artifact path from stages.plan.substages.{prior_substage}.artifacts.

Example boundary output:

[Context boundary] Clearing spec context
Retained metadata: {status: "APPROVED", artifact_path: "specs/047-*/spec.md", feature_id: "047"}
  1. Write substage checkpoint: After each substage transition, write state atomically. This ensures that if the session dies between substages, the orchestrator can resume at the correct substage.
  2. Skill invocation per substage:
    • spec substage → invoke aod.spec skill
    • project_plan substage → invoke aod.project-plan skill
    • tasks substage → invoke aod.tasks skill
  3. Governance per substage: Each substage has its own governance gate. First check the governance cache via aod_state_get_governance_cache (see Core Loop step 9). If the cache returns "null", fall back to reading the substage's artifact frontmatter (load references/governance.md for the detection algorithm):
    • spec: Check specs/{NNN}-*/spec.md for PM sign-off
    • project_plan: Check specs/{NNN}-*/plan.md for PM + Architect sign-off
    • tasks: Check specs/{NNN}-*/tasks.md for PM + Architect + Team-Lead sign-off
  4. Display: When displaying the stage map during Plan, show the active substage:
    [>] Plan (spec)       — spec substage in progress
    [>] Plan (plan)       — project_plan substage in progress
    [>] Plan (tasks)      — tasks substage in progress

Stage Skill Mapping

Each lifecycle stage maps to an existing AOD skill invoked via the Skill tool. The orchestrator delegates all stage work — it never re-implements stage logic.

StageSubstageSkill to InvokeSkill Tool NameArguments to Pass
Discover—Discovery flowaod.discover--autonomous "{idea_text}" (if autonomous_mode) or idea text only
Define—PRD creationaod.define--autonomous "{feature_title}" (if autonomous_mode) or feature title only
PlanspecSpecificationaod.spec--autonomous (if autonomous_mode) or no args
Planproject_planArchitecture planaod.project-plan--autonomous (if autonomous_mode) or no args
PlantasksTask breakdownaod.tasks--autonomous (if autonomous_mode) or no args
Build—Implementationaod.build--orchestrated --autonomous (if autonomous_mode) or --orchestrated only
Deliver—Delivery retrospectiveaod.deliver--autonomous "FEATURE: {NNN} - {name}" {deliver_flags...} (if autonomous_mode) or "FEATURE: {NNN} - {name}" {deliver_flags...} (interactive). {deliver_flags...} expands the per-feature flags forwarded from /aod.orchestrate via the Task description (e.g. --no-tests="<reason>"). When /aod.run is invoked standalone (not via /aod.orchestrate), {deliver_flags...} is empty. See aod-orchestrate SKILL.md Step 4.7 and Step 7.1.1 step 2.5 for the upstream contract.
Document—Documentation reviewaod.document--autonomous (if autonomous_mode) or no args

Invocation pattern: Use the Skill tool with skill: "{skill_name}" and pass arguments as args: "{arguments}".

Context passing between stages (FR-012):

  • After Discover completes: extract GitHub Issue number from discovery output; store in state as github_issue
  • After Define completes: PRD path is at docs/product/02_PRD/{NNN}-*.md; store in state artifacts
  • After Plan:spec completes: spec path is at specs/{NNN}-*/spec.md; store in state artifacts
  • After Plan:project_plan completes: plan path is at specs/{NNN}-*/plan.md; store in state artifacts
  • After Plan:tasks completes: tasks path is at specs/{NNN}-*/tasks.md; store in state artifacts
  • After Build completes: implementation files tracked via tasks.md [X] markers
  • After Deliver completes: delivery summary and metrics captured

Argument formatting per stage:

When autonomous_mode == true, prepend --autonomous to all skill args:

  • Discover: args: "--autonomous {idea_text}" — pass flag + raw idea description
  • Define: args: "--autonomous {feature_title}" — pass flag + feature title/topic
  • Plan stages: args: "--autonomous" — flag only; skills read context from branch
  • Build: args: "--orchestrated --autonomous" — both flags enable orchestrated + autonomous modes
  • Deliver: args: "--autonomous FEATURE: {NNN} - {feature_name} {deliver_flags...}" — flag + feature info + optional per-feature deliver flags forwarded from /aod.orchestrate (e.g. --no-tests="<reason>"). When /aod.run is invoked standalone (not via orchestrator), {deliver_flags...} is empty. See aod-orchestrate SKILL.md Step 4.7 + 7.1.1 step 2.5 for the upstream contract.
  • Document: args: "--autonomous" — flag only; skill reads context from branch

When autonomous_mode == false (interactive), omit --autonomous:

  • Discover: args: "{idea_text}"
  • Define: args: "{feature_title}"
  • Plan stages: no args
  • Build: args: "--orchestrated"
  • Deliver: args: "FEATURE: {NNN} - {feature_name} {deliver_flags...}" — {deliver_flags...} expansion is empty unless forwarded from /aod.orchestrate (see Stage Skill Mapping table note)
  • Document: no args

Post-Stage Context Extraction

After each stage skill returns, the orchestrator extracts context from the produced artifacts and updates the state file. This ensures subsequent stages receive the correct inputs.

After Discover completes:

  1. The Discover skill creates a GitHub Issue and outputs the issue number. Read the orchestration output to find the issue number.
  2. Use Bash to scan for new GitHub Issues: gh issue list --label "stage:discover" --json number,title --limit 5 (if gh available)
  3. Update state fields:
    • github_issue: Set to the issue number
    • feature_id: Zero-pad the issue number to 3 digits (e.g., 22 → "022")
    • branch: Set to {feature_id}-{feature_name} (e.g., "022-add-dark-mode-toggle")
  4. Create the feature branch if not already on it: git checkout -b {branch} (or confirm current branch matches)
  5. Record artifacts: Add the GitHub Issue URL to stages.discover.artifacts
  6. Write updated state atomically

After Define completes:

  1. Use Glob to find the PRD: docs/product/02_PRD/{NNN}-*.md where NNN is feature_id
  2. Record artifacts: Add the PRD path to stages.define.artifacts
  3. Write updated state atomically

After Plan:spec completes:

  1. Use Glob to find the spec: specs/{NNN}-*/spec.md
  2. Record artifacts: Add the spec path to stages.plan.substages.spec.artifacts
  3. Write updated state atomically

After Plan:project_plan completes:

  1. Use Glob to find the plan: specs/{NNN}-*/plan.md
  2. Record artifacts: Add the plan path to stages.plan.substages.project_plan.artifacts
  3. Write updated state atomically

After Plan:tasks completes:

  1. Use Glob to find tasks and assignments: specs/{NNN}-*/tasks.md, specs/{NNN}-*/agent-assignments.md
  2. Record artifacts: Add paths to stages.plan.substages.tasks.artifacts
  3. Mark overall Plan stage as completed
  4. Write updated state atomically

After Plan:tasks completes (continued) — Size Estimation Display:

After recording Plan:tasks artifacts and before the Core Loop advances to Build, perform a size estimation:

  1. Read agent-assignments.md from specs/{NNN}-*/agent-assignments.md
  2. Count the number of waves (sections labeled "Wave 1", "Wave 2", etc.)
  3. Apply the heuristic:
    • wave_count <= 3 → session_strategy = "one-shot", estimated_sessions = 1
    • wave_count <= 6 → session_strategy = "cautious", estimated_sessions = 2
    • wave_count > 6 → session_strategy = "multi-session", estimated_sessions = ceil(wave_count / 3)
  4. Update state with the estimation:
    bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_write '"'"'{"session_strategy":"{strategy}","estimated_sessions":{N},"build_progress":{"total_waves":{wave_count},"completed_waves":0,"session_breaks":[]}}'"'"''
  5. Display the build estimate:

    --- BUILD ESTIMATE ---
    Waves: {wave_count}
    Estimated sessions: {estimated_sessions}
    
    {If wave_count <= 3: "Expected to complete in this session."}
    {If wave_count > 3: "May require ~{estimated_sessions} sessions. The orchestrator will auto-break and resume if needed."}

After Build completes:

  1. Read tasks.md from specs/{NNN}-*/tasks.md
  2. Count total tasks (lines matching - [ ] or - [X])
  3. Count completed tasks (lines matching - [X])
  4. Determine the last completed wave by reading agent-assignments.md and cross-referencing completed tasks
  5. If completed < total (session break protocol):
    • Parse the AOD_BUILD_RESULT comment from build output
    • Log in error_log with type "build_incomplete" and message including wave progress
    • Update build_progress in state:
      bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_write '"'"'{"build_progress":{"total_waves":{total},"completed_waves":{N},"session_breaks":[{"session":{session_count},"waves_completed":"{range}","timestamp":"{now}"}]}}'"'"''
    • Log the session break decision to autonomous_decisions:
      bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_append ".autonomous_decisions" '"'"'{"decision":"session_break","reason":"Build incomplete: {completed}/{total} tasks after wave {N}","timestamp":"{now}"}'"'"''
    • Display the session break message:
      AOD ORCHESTRATOR — Session Break
      ==================================
      Feature: {feature_name} (#{github_issue})
      Build: Wave {N}/{total_waves} complete ({completed_tasks}/{total_tasks} tasks)
      
      The remaining waves require a new conversation.
      
      To continue:
        /aod.run --resume
      
      The orchestrator will pick up from Wave {N+1} automatically.
      
      Resume prompt (copy-paste):
        claude "Resume aod.run for #{github_issue} — {feature_name}. Run /aod.run --resume"
    • STOP — Do NOT continue to Deliver. Exit the Core Loop.
  6. If completed == total: Mark Build as completed, continue to Deliver
  7. Record artifacts: Add "tasks.md (all tasks completed)" to stages.build.artifacts
  8. Write updated state atomically

After Deliver completes:

  1. The deliver stage produces a delivery summary
  2. Check for halt record (FR-024, FR-025) — before marking Deliver as completed, inspect .aod/state/deliver-{NNN}.halt.json (where NNN is the zero-padded feature_id from state). The /aod.deliver skill writes this file when it halts for review per the three-channel halt protocol. Schema and exit-code taxonomy are documented in specs/139-delivery-verified-not-documented/contracts/halt-record.md.

    Exit-code taxonomy (from halt-record contract §Channel 3):

    CodeMeaning/aod.run policy
    0SuccessProceed to Document stage
    10Halted for review (E2E fail, AC-coverage fail, or abandoned heal)Halt lifecycle; emit halt record to operator; do NOT advance to Document
    11Lockfile conflict (concurrent /aod.deliver live)Halt lifecycle; log holding PID from lockfile; operator resolves
    12Abandoned heal sentinel (crash-recovery)Halt lifecycle; emit manual-cleanup prompt; do NOT auto-retry
    1-9Pre-existing delivery errorsHandle per existing stage_error logic (log, surface to operator)

    Inspection algorithm:

    1. Derive the halt-record path: halt_record_path = ".aod/state/deliver-{NNN}.halt.json"
    2. Check existence via Bash: test -f "$halt_record_path" && echo EXISTS
    3. If the file does NOT exist: assume Deliver succeeded; proceed to step 3 below (record artifacts, continue to Document).
    4. If the file exists, parse it via jq:

      jq -r '[.reason, .recovery_status, (.heal_pr_url // "null"), (.heal_pr_number // "null"), (.failing_scenarios | tostring), .timestamp] | @tsv' "$halt_record_path"
    5. Extract fields: reason, recovery_status, heal_pr_url, heal_pr_number, failing_scenarios, timestamp.
    6. Emit human-readable halt summary to the operator (surfaced in stdout via the skill's output):

      =====================================================
      LIFECYCLE HALT — Deliver stage halted for review
      =====================================================
      Feature: {feature_id} — {feature_name}
      Reason: {reason}
      Recovery Status: {recovery_status}
      Heal-PR: {heal_pr_url} (#{heal_pr_number})
      Failing Scenarios:
        - {scenario_1}
        - {scenario_2}
        ...
      Halted At: {timestamp}
      =====================================================
      
      Next steps:
      - Review the heal-PR for failure context and attempted fixes
      - Fix the underlying failure and merge the heal-PR (requires human approval — no auto-merge per FR-023)
      - Re-run /aod.run --resume to retry Deliver after the fix is merged
    7. Mark Deliver as halted in state:

      bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_write '"'"'{"stages":{"deliver":{"status":"failed","halt_record":{"reason":"{reason}","recovery_status":"{recovery_status}","heal_pr_url":"{heal_pr_url}","heal_pr_number":{heal_pr_number},"failing_scenarios":{failing_scenarios_json},"timestamp":"{timestamp}"}}}}'"'"''
    8. Append to error_log (per Error Logging contract) with type: "stage_error" and a summary message.
    9. Autonomous mode policy: If autonomous_mode == true, the halt is non-recoverable within the current run — the lifecycle stops here. Do NOT advance to Document. The operator resolves via manual heal-PR review, then re-runs /aod.run --resume to re-invoke the Deliver stage. Emit an additional line:

      Autonomous mode: lifecycle halted. Manual intervention required before --resume.
    10. Interactive mode policy: If autonomous_mode == false, display the halt summary and prompt:

      Deliver stage halted for review. Options:
        [Pause / Abort]
      • Pause: Save state, exit cleanly. Operator resumes after fix via /aod.run --resume.
      • Abort: Save state with aborted status, exit.
    11. Exit the Core Loop — do NOT advance to Document. The halt is terminal for the current session.
  3. Record artifacts: Add "delivery complete" to stages.deliver.artifacts (only when no halt record is present)
  4. Write updated state atomically

After Document completes:

  1. The document stage produces documentation review artifacts (CHANGELOG updates, docstrings, API docs, code simplification commits)
  2. Record artifacts: Add PR URL and commit SHAs from the document branch merge to stages.document.artifacts
  3. Write updated state atomically
  4. MANDATORY: You MUST use the Read tool to load references/error-recovery.md, then follow the Lifecycle Complete instructions. If the file cannot be read, display an error and STOP.

Stage Map Display

Display the stage map after each stage transition to show progress. This is referenced by Core Loop step 6.

Algorithm:

  1. Read state from .aod/run-state.json
  2. For each stage in sequence (discover, define, plan, build, deliver, document), determine its display marker:
    • status == "completed" → [x]
    • status == "in_progress" → [>]
    • status == "pending" → [ ]
    • status == "failed" → [!]
  3. For the Plan stage, append the active substage in parentheses if in progress:
    • If current_substage == "spec" → Plan (spec)
    • If current_substage == "project_plan" → Plan (plan)
    • If current_substage == "tasks" → Plan (tasks)
    • If Plan is completed → Plan
  4. Display the formatted stage map:
Stage Map:
  {marker} Discover  {marker} Define  {marker} Plan{substage}  {marker} Build  {marker} Deliver  {marker} Document

Examples:

Starting a new lifecycle:

Stage Map:
  [>] Discover  [ ] Define  [ ] Plan  [ ] Build  [ ] Deliver  [ ] Document

After Discover and Define complete, Plan:spec in progress:

Stage Map:
  [x] Discover  [x] Define  [>] Plan (spec)  [ ] Build  [ ] Deliver  [ ] Document

Mid-lifecycle with Build in progress:

Stage Map:
  [x] Discover  [x] Define  [x] Plan  [>] Build  [ ] Deliver  [ ] Document

All stages complete:

Stage Map:
  [x] Discover  [x] Define  [x] Plan  [x] Build  [x] Deliver  [x] Document

Transition Messages

Display a formatted transition header before each stage begins executing. This is referenced by Core Loop step 7.

Algorithm (called by Core Loop step 7, before each stage skill invocation):

  1. Read current state: Get current_stage and current_substage from state.
  2. Map stage to number and detail: Use the lookup table below:

    current_stagecurrent_substageNSTAGE_NAMESubstage Detail
    discovernull1DISCOVER—
    definenull2DEFINE—
    planspec3PLANsub-stage 1/3: Feature Specification
    planproject_plan3PLANsub-stage 2/3: Architecture Plan
    plantasks3PLANsub-stage 3/3: Task Breakdown
    buildnull4BUILD—
    delivernull5DELIVER—
    documentnull6DOCUMENT—
  3. Format and display:

    For non-Plan stages:

    --- STAGE {N}: {STAGE_NAME} ---

    For Plan substages:

    --- STAGE 3: PLAN ({substage detail}) ---

Examples:

--- STAGE 1: DISCOVER ---
--- STAGE 3: PLAN (sub-stage 1/3: Feature Specification) ---
--- STAGE 4: BUILD ---

GitHub Integration

After each stage completes successfully (governance gate passed), update the GitHub Issue's stage:* label to reflect the new current stage. This keeps the GitHub Issue board in sync with the orchestration state (FR-023).

Algorithm (called by Core Loop step 12, after post-stage checkpoint):

  1. Check prerequisites:
    • Read github_issue from state. If null (no GitHub Issue for this feature), skip entirely.
    • Check if gh CLI is available: command -v gh >/dev/null 2>&1. If not, skip silently.
    • Check if gh is authenticated: gh auth status >/dev/null 2>&1. If not, skip silently.
  2. Determine the new stage label: Map the newly-completed stage to the next stage in the sequence:

    Completed StageCompleted SubstageNew Label
    discover—stage:define
    define—stage:plan
    planspecstage:plan (still in Plan)
    planproject_planstage:plan (still in Plan)
    plantasksstage:build
    build—stage:deliver
    deliver—stage:document
    document—stage:done

    Note: Plan substage completions (spec, project_plan) do not change the label — the issue stays at stage:plan until all 3 substages complete.

  3. Update the label: Use the github-lifecycle.sh function:
    bash -c 'source .aod/scripts/bash/github-lifecycle.sh && aod_gh_update_stage {github_issue} {new_stage}'
  4. Handle failures gracefully: If the label update fails, log a warning but do NOT halt orchestration.
    • Display: "Note: GitHub label update skipped ({reason}). Orchestration continues."
  5. Backlog refresh: After updating the label:
    bash .aod/scripts/bash/backlog-regenerate.sh 2>/dev/null || true
    This is fire-and-forget — failure does not affect orchestration.

Error Logging

Capture stage errors and significant events in the state file's error_log array for debugging and auditability. Error entries follow Entity 4 schema.

Algorithm (called whenever an error or significant event occurs during orchestration):

  1. Build error entry:
{
  "timestamp": "{current ISO 8601 timestamp}",
  "stage": "{current_stage}",
  "type": "{error_type}",
  "message": "{descriptive error message}",
  "recoverable": true
}
  1. Error types (standardized values for type field):

    TypeWhen UsedRecoverable
    stage_errorA stage skill invocation fails or returns an errortrue
    governance_rejectionA governance gate returns CHANGES_REQUESTEDtrue
    governance_blockedA governance gate returns BLOCKEDtrue
    circuit_breakerMax retries (3) reached on a governance gatetrue
    user_abortUser chose to abort orchestrationtrue
    artifact_missingArtifact recorded in state not found on disktrue
    state_corruptionState file failed validationtrue
    github_errorGitHub CLI operation failedtrue
    skill_invocation_errorSkill tool invocation returned unexpected resulttrue
  2. Append to state: Use the aod_state_append function:
    bash -c 'source .aod/scripts/bash/run-state.sh && aod_state_append ".error_log" '"'"'{"timestamp":"...","stage":"...","type":"...","message":"...","recoverable":true}'"'"''
  3. When to log errors:
    • Stage skill failure: When a Skill tool invocation produces an error or unexpected output
    • Governance gate rejection: Also tracked in gate_rejections, log summary in error_log
    • Circuit breaker activation: When max retries are reached
    • User abort: When the user chooses to abort
    • Artifact inconsistency: When resume validation detects missing artifacts
    • State corruption: When the state file fails validation
    • GitHub errors: When gh CLI operations fail
  4. Error entries are append-only: Never remove or modify existing error log entries. The log provides a chronological audit trail.

    TypeWhen UsedRecoverable
    build_incompletePost-build verification finds incomplete taskstrue

Adaptive Session Management

The orchestrator adapts its session strategy based on feature size. Small features complete in one session; large features automatically split across sessions when context runs out.

Size Estimation Heuristic (executed after Plan:tasks completes, before Build):

wave_count = count of waves in agent-assignments.md

if wave_count <= 3:
  session_strategy = "one-shot"
  estimated_sessions = 1
elif wave_count <= 6:
  session_strategy = "cautious"
  estimated_sessions = 2
else:
  session_strategy = "multi-session"
  estimated_sessions = ceil(wave_count / 3)

Session breaks are reactive, not predictive: Token heuristics don't work — Claude Code doesn't expose token usage to skills. Instead, aod.build runs waves until either all complete (AOD_BUILD_RESULT:COMPLETE) or context degrades (AOD_BUILD_RESULT:PARTIAL). Post-build verification in the orchestrator then triggers a session break if tasks remain incomplete.

State fields for session management:

FieldTypeDescription
session_strategystring"one-shot", "cautious", or "multi-session" — set after Plan:tasks
estimated_sessionsnumberEstimated session count from heuristic
build_progressobject{total_waves, completed_waves, session_breaks[]} — updated after each build run
autonomous_decisionsarrayLog of automated decisions (session breaks, auto-retries) for post-run review

Resume-after-break flow: When aod.run --resume loads a state where Build is in_progress, it re-invokes aod.build --orchestrated --autonomous. Build's Step 1.6 detects completed waves via [X] markers and continues from the next incomplete wave. This repeats (recursive session breaks) until all waves complete, then the orchestrator advances to Deliver.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.