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

~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

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
  1. Very specific:

    If on main and a PRD exists (e.g., docs/product/02_PRD/{NNN}-*.md), automatically create the feature branch (git checkout -b …

    line 19
  2. Distinctive:

    Open Draft PR: After creating the branch, push it and open a draft PR so work is visible early:

    line 20
  3. Very specific:

    If gh is unavailable, skip silently (graceful degradation).

    line 28
  4. Very specific:

    If no specs directory found, check .aod/spec.md as fallback

    line 30
  5. Very specific:

    If no feature context found: warn and suggest /aod.define first

    line 31
  6. Very specific:

    Read .aod/memory/constitution.md and extract the governance tier:

    line 56
  7. Very specific:

    Look for the ## Governance Tiers section

    line 58
  8. Very specific:

    If not found or invalid: default to standard

    line 61
  9. Distinctive:

    After each approved sub-step, display a brief status line before advancing:

    line 127
  10. Very specific:

    If the user runs /aod.plan but there is no approved PRD for the current feature (no docs/product/02_PRD/{NNN}-*.md), warn:

    line 141
  11. Very specific:

    If a governance gate rejects (e.g., PM requests changes to spec.md), the user fixes issues and re-runs /aod.plan.

    line 153
  12. Very specific:

    If the user previously completed spec.md and plan.md (both approved) and runs /aod.plan, the orchestrator skips directly to /aod.tasks — it …

    line 156

≈ “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

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

  1. Get branch: git branch --show-current → extract NNN prefix
  2. If on main and 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.
  3. Open Draft PR: After creating the branch, push it and open a draft PR so work is visible early:
    git 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."
    If gh is unavailable, skip silently (graceful degradation). Store the PR number for later use.
  4. Derive specs directory: specs/{NNN}-*/
  5. If no specs directory found, check .aod/spec.md as fallback
  6. If no feature context found: warn and suggest /aod.define first

Step 2: Read Artifact States

For each artifact (spec.md, plan.md, tasks.md), determine its approval status:

  1. Check file existence — if file cannot be read (missing, permissions, encoding), treat as "does not exist"
  2. Parse YAML frontmatter — extract the triad: block between --- delimiters
  3. Extract sign-off status — read triad.{role}_signoff.status for the required reviewers

Step 3: Evaluate Frontmatter (with error handling)

For each artifact file, apply these rules in order:

  1. File does not exist → status = missing
  2. File exists but has no --- frontmatter delimiters → status = not_approved, emit: "Note: {file} has no frontmatter. Running {sub-step} for review."
  3. File has frontmatter but no triad: key → status = not_approved, emit: "Note: {file} frontmatter missing triad block. Running {sub-step} for review."
  4. triad: exists but required sign-off field is null or missing → status = not_approved
  5. Sign-off status is not a recognized value → status = not_approved, emit: "Warning: Unexpected status '{value}' in {file}. Re-running {sub-step}."
  6. 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:

  1. Look for the ## Governance Tiers section
  2. Find the configuration block: governance: → tier: value
  3. Valid values: light, standard, full
  4. 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
YesNo————Invoke /aod.spec (needs PM sign-off)
YesYesNo———Invoke /aod.project-plan
YesYesYesNo——Invoke /aod.project-plan (needs dual sign-off)
YesYesYesYesNo—Invoke /aod.tasks
YesYesYesYesYesNoInvoke /aod.tasks (needs triple sign-off)
YesYesYesYesYesYesReport "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
YesNo———Invoke /aod.project-plan (skip PM spec sign-off)
YesYesNo——Invoke /aod.project-plan (needs dual sign-off)
YesYesYesNo—Invoke /aod.tasks
YesYesYesYesNoInvoke /aod.tasks (needs triple sign-off)
YesYesYesYesYesReport "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.status is approved
  • spec.md (Light): existence is sufficient — PM sign-off not required
  • plan.md: triad.pm_signoff.status AND triad.architect_signoff.status are both approved
  • tasks.md: triad.pm_signoff.status AND triad.architect_signoff.status AND triad.techlead_signoff.status are 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:

  1. Invoke the current sub-step using the Skill tool (aod.spec, aod.project-plan, or aod.tasks)
  2. 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.plan to resume.
  3. 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-off
  • specs/{NNN}-*/plan.md — check existence and dual sign-off
  • specs/{NNN}-*/tasks.md — check existence and triple sign-off
  • docs/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

RationalizationReality
"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.tasks directly 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 of not_approved per 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.spec for a PM sign-off the tier doesn't require.

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.