~aod-plan
Skill95 starsChanged 37 days agoApache-2.0View on GitHub
Plan stage orchestrator that runs all three Plan sub-steps (spec → project-plan → tasks) in sequence with governance gates. Stops on rejection, continues through approvals. Use this skill when you need to run the full Plan stage, navigate planning sub-steps, or resume after a rejection.
- Commits and pushes
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ~aod-blueprintSkill
- ~aod-bugfixSkill
- ~aod-buildSkill
- ~aod-defineSkill
- ~aod-deliverSkill
- ~aod-discoverSkill
- aod-foundationSkill
- ~aod-kickstartSkill
- aod-lensSkill
- aod-orchestrateSkill
- ~aod-project-planSkill
- ~aod-runSkill
- ~aod-scoreSkill
- ~aod-specSkill
- aod-stackSkill
- ~aod-statusSkill
- code-execution-helperSkill
- git-workflow-helperSkill
- kb-createSkill
- kb-querySkill
- root-cause-analyzerSkill
- securitySkill
- tachi-control-analysisSkill
- tachi-infographicsSkill
- tachi-orchestrationSkill
- tachi-report-assemblySkill
- tachi-risk-scoringSkill
- tachi-sharedSkill
- tachi-threat-reportingSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 2 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
If on main and a PRD exists (e.g., docs/product/02_PRD/{NNN}-*.md), automatically create the feature branch (git checkout -b …
- Distinctive: line 20
Open Draft PR: After creating the branch, push it and open a draft PR so work is visible early:
- Very specific: line 28
If gh is unavailable, skip silently (graceful degradation).
- Very specific: line 30
If no specs directory found, check .aod/spec.md as fallback
- Very specific: line 31
If no feature context found: warn and suggest /aod.define first
- Very specific: line 56
Read .aod/memory/constitution.md and extract the governance tier:
- Very specific: line 58
Look for the ## Governance Tiers section
- Very specific: line 61
If not found or invalid: default to standard
- Distinctive: line 127
After each approved sub-step, display a brief status line before advancing:
- Very specific: line 141
If the user runs /aod.plan but there is no approved PRD for the current feature (no docs/product/02_PRD/{NNN}-*.md), warn:
- Very specific: line 153
If a governance gate rejects (e.g., PM requests changes to spec.md), the user fixes issues and re-runs /aod.plan.
- Very specific: line 156
If the user previously completed spec.md and plan.md (both approved) and runs /aod.plan, the orchestrator skips directly to /aod.tasks — it …
≈ “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.
Files
Plan Stage Orchestrator Skill
Purpose
Orchestrates the full Plan stage by running spec → project-plan → tasks in sequence. After each sub-step completes and its governance review passes (APPROVED), the orchestrator automatically advances to the next sub-step. If any review returns CHANGES_REQUESTED or BLOCKED, the orchestrator stops and reports the rejection so the user can fix and re-run /aod.plan to resume.
With 1M context, all three artifacts and their reviews fit comfortably in a single session.
How It Works
Step 1: Determine Feature Context
- Get branch:
git branch --show-current→ extract NNN prefix - If on
mainand a PRD exists (e.g.,docs/product/02_PRD/{NNN}-*.md), automatically create the feature branch (git checkout -b {NNN}-{kebab-name}) per git workflow rules. Do NOT ask the user — feature branches are mandatory, not optional. - Open Draft PR: After creating the branch, push it and open a draft PR so work is visible early:
Ifgit commit --allow-empty -m "chore({NNN}): open feature branch" git push -u origin {NNN}-{kebab-name} gh pr create --draft \ --title "{NNN}: {Feature Name}" \ --body "Draft PR for feature {NNN}. Opened automatically at plan stage."ghis unavailable, skip silently (graceful degradation). Store the PR number for later use. - Derive specs directory:
specs/{NNN}-*/ - If no specs directory found, check
.aod/spec.mdas fallback - If no feature context found: warn and suggest
/aod.definefirst
Step 2: Read Artifact States
For each artifact (spec.md, plan.md, tasks.md), determine its approval status:
- Check file existence — if file cannot be read (missing, permissions, encoding), treat as "does not exist"
- Parse YAML frontmatter — extract the
triad:block between---delimiters - Extract sign-off status — read
triad.{role}_signoff.statusfor the required reviewers
Step 3: Evaluate Frontmatter (with error handling)
For each artifact file, apply these rules in order:
- File does not exist → status =
missing - File exists but has no
---frontmatter delimiters → status =not_approved, emit: "Note: {file} has no frontmatter. Running {sub-step} for review." - File has frontmatter but no
triad:key → status =not_approved, emit: "Note: {file} frontmatter missing triad block. Running {sub-step} for review." triad:exists but required sign-off field is null or missing → status =not_approved- Sign-off status is not a recognized value → status =
not_approved, emit: "Warning: Unexpected status '{value}' in {file}. Re-running {sub-step}." - YAML parse error → status =
not_approved, emit: "Warning: Could not parse frontmatter in {file}. Re-running {sub-step}."
Recognized approved statuses: APPROVED, APPROVED_WITH_CONCERNS, BLOCKED_OVERRIDDEN
Step 3b: Read Governance Tier
Read .aod/memory/constitution.md and extract the governance tier:
- Look for the
## Governance Tierssection - Find the configuration block:
governance:→tier:value - Valid values:
light,standard,full - If not found or invalid: default to
standard
Tier affects Step 4 decision table — specifically the spec PM sign-off check.
Step 4: Apply Decision Table
Standard and Full tiers (default behavior):
| spec.md exists? | spec PM approved? | plan.md exists? | plan dual-approved? | tasks.md exists? | tasks triple-approved? | Action |
| No | — | — | — | — | — | Invoke /aod.spec |
| Yes | No | — | — | — | — | Invoke /aod.spec (needs PM sign-off) |
| Yes | Yes | No | — | — | — | Invoke /aod.project-plan |
| Yes | Yes | Yes | No | — | — | Invoke /aod.project-plan (needs dual sign-off) |
| Yes | Yes | Yes | Yes | No | — | Invoke /aod.tasks |
| Yes | Yes | Yes | Yes | Yes | No | Invoke /aod.tasks (needs triple sign-off) |
| Yes | Yes | Yes | Yes | Yes | Yes | Report "Plan stage complete" |
Light tier (reduced gates):
| spec.md exists? | plan.md exists? | plan dual-approved? | tasks.md exists? | tasks triple-approved? | Action |
| No | — | — | — | — | Invoke /aod.spec |
| Yes | No | — | — | — | Invoke /aod.project-plan (skip PM spec sign-off) |
| Yes | Yes | No | — | — | Invoke /aod.project-plan (needs dual sign-off) |
| Yes | Yes | Yes | No | — | Invoke /aod.tasks |
| Yes | Yes | Yes | Yes | No | Invoke /aod.tasks (needs triple sign-off) |
| Yes | Yes | Yes | Yes | Yes | Report "Plan stage complete" |
In Light tier, when spec.md exists but has no PM sign-off, the router skips the PM spec sign-off check and proceeds directly to /aod.project-plan. Emit: "Note: Light governance tier — PM spec sign-off skipped."
Full tier uses the same table as Standard. The difference between Standard and Full is that Full requires a separate PM spec sign-off step (the PM reviews spec.md independently before plan creation). This distinction is enforced within /aod.spec itself, not in the router.
Approval checks per artifact:
- spec.md (Standard/Full):
triad.pm_signoff.statusis approved - spec.md (Light): existence is sufficient — PM sign-off not required
- plan.md:
triad.pm_signoff.statusANDtriad.architect_signoff.statusare both approved - tasks.md:
triad.pm_signoff.statusANDtriad.architect_signoff.statusANDtriad.techlead_signoff.statusare all approved
Invariant: Triple sign-off on tasks.md is the governance floor for ALL tiers, including Light.
Step 5: Execute Orchestration Loop
Based on the decision table, determine the starting sub-step (the first one that needs work). Then run sub-steps in sequence, advancing automatically on approval.
Loop logic:
- Invoke the current sub-step using the Skill tool (
aod.spec,aod.project-plan, oraod.tasks) - After the sub-step completes, check the governance outcome:
- APPROVED (or APPROVED_WITH_CONCERNS): Display a brief progress line, then re-read artifact states (Step 2) and re-apply the decision table (Step 4) to determine the next sub-step. Continue the loop.
- CHANGES_REQUESTED or BLOCKED: Stop the loop. Display the rejection details and instruct the user to fix the issues, then re-run
/aod.planto resume.
- If the decision table returns "Plan stage complete": Exit the loop and display:
PLAN STAGE COMPLETE
All artifacts approved:
- spec.md: PM sign-off ✓
- plan.md: PM + Architect sign-off ✓
- tasks.md: PM + Architect + Team-Lead sign-off ✓
Next: Run /aod.build to start implementation.Progress display between sub-steps:
After each approved sub-step, display a brief status line before advancing:
✓ spec.md — PM approved. Advancing to project-plan...✓ plan.md — PM + Architect approved. Advancing to tasks...Important: Re-read artifact states after each sub-step. Do NOT assume the next sub-step — the decision table handles edge cases (e.g., plan.md exists but lost dual approval).
Edge Cases
No PRD exists
If the user runs /aod.plan but there is no approved PRD for the current feature (no docs/product/02_PRD/{NNN}-*.md), warn:
No approved PRD found for this feature.
The Plan stage requires a PRD as input. Run /aod.define first to create one,
then return to /aod.plan.Direct sub-command invocation
The orchestrator does NOT block direct invocation of /aod.spec, /aod.project-plan, or /aod.tasks. Those commands work independently — the orchestrator is a convenience layer, not a gatekeeper.
Re-run after rejection
If a governance gate rejects (e.g., PM requests changes to spec.md), the user fixes issues and re-runs /aod.plan. The orchestrator detects the missing/rejected sign-off and re-invokes the correct sub-step, then continues the loop from there.
Mid-stage resume
If the user previously completed spec.md and plan.md (both approved) and runs /aod.plan, the orchestrator skips directly to /aod.tasks — it only runs what's needed.
Integration
Reads
specs/{NNN}-*/spec.md— check existence and PM sign-offspecs/{NNN}-*/plan.md— check existence and dual sign-offspecs/{NNN}-*/tasks.md— check existence and triple sign-offdocs/product/02_PRD/{NNN}-*.md— check PRD existence (edge case)
Invokes (in sequence, advancing on approval)
/aod.spec— when spec needs creation or PM approval/aod.project-plan— when plan needs creation or dual approval/aod.tasks— when tasks need creation or triple approval
Updates
- None (orchestrator reads artifact state, sub-commands write artifacts)
Common Rationalizations
| Rationalization | Reality |
| "I know what's done, I'll skip re-reading state between sub-steps" | Step 5 Loop point 3 mandates re-read after each sub-step — assumed-state advancement misses lost approvals. |
| "This branch is small, I'll commit straight to main" | Step 1 point 2 auto-creates the feature branch on main — bypassing it skips the draft PR opened in point 3. |
| "spec.md exists, the gate must already be green" | Step 4 decision table requires pm_signoff.status approved per Step 2 — existence alone routes back to /aod.spec. |
| "Light tier means skip triple sign-off on tasks too" | Step 4 invariant (line 100) keeps tasks.md triple sign-off as the floor for ALL tiers, including Light. |
| "Approved with concerns is close enough — I'll fix later" | Step 4 recognized list (line 52) treats it as approved, but the concerns must still be addressed before delivery. |
Red Flags
- Agent advances past an approved sub-step without re-running Step 4's decision table.
- Agent invokes
/aod.tasksdirectly when plan.md lacks dual sign-off per the Step 4 plan row. - Agent skips the draft PR open in Step 1 point 3 because
gh"felt slow." - Agent treats a missing
triad:block as approved instead ofnot_approvedper Step 3 rule 3. - Agent reports "Plan stage complete" without all three artifacts hitting the Step 4 final row.
- Agent ignores the Light-tier note in Step 4 and re-runs
/aod.specfor a PM sign-off the tier doesn't require.
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
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.

