augment-plan

What this skill does

# Augment Plan

Take an existing Execution Plan (ExecPlan) and enrich it with two complementary layers of guidance: **CLI design requirements** for agent-first command-line interfaces, and **project scaffolding** for repository structure and guidance files.

## Why this skill exists

ExecPlans created from PRDs describe *what to build* at the code level — milestones, file edits, validation steps. But two things consistently fall through the cracks:

1. **CLI design** — When the project includes a CLI, plans tend to describe commands at the feature level ("add a `deploy` command") without specifying the structured envelope, error taxonomy, exit codes, guide command, dry-run support, or safety flags that make the CLI usable by agents. The result is a CLI that works for humans but breaks agent automation.

2. **Project scaffolding** — Plans jump straight to feature code without establishing the repository foundation: the README, ARCHITECTURE.md, AGENTS.md, testing strategy, CI workflows, and other guidance files that make the project navigable for both humans and future coding agents.

This skill closes both gaps by reading the existing plan and inserting well-placed milestones, steps, and context that address CLI design and scaffolding — without disrupting the plan's existing structure or narrative flow.

## How to run this skill

### Step 1: Locate and read the existing plan

Ask the user for the ExecPlan file path if not provided. Read it thoroughly. Pay attention to:

- **The project type** — Is this a CLI tool? A library with a CLI interface? An API with a companion CLI? Understanding this determines how much of the CLI manifest applies.
- **Existing milestones** — Where does feature work begin? Scaffolding milestones should come before feature milestones. CLI design milestones should be woven into or placed before the milestones that implement commands.
- **Tech stack** — The plan's language and framework choices constrain the implementation hints you'll provide (Python/Typer, TypeScript/Commander, Go/Cobra, etc.).
- **The plan's voice and level of detail** — Match it. If the plan is terse and concrete, your additions should be too. If it's narrative and explanatory, write in that style.

### Step 2: Read the PRD (if available)

If the PRD that generated this plan exists in the repo, read it too. It provides context about:
- Whether the project is a CLI at all (if not, skip CLI augmentation)
- The intended user base (agents vs. humans vs. both)
- Non-goals that might affect scaffolding scope

If no PRD is available, work from the plan alone and ask the user to confirm your inferences.

### Step 3: Decide what to augment

Not every plan needs both layers. Ask yourself:

**Does the project include a CLI?**
- Yes → Apply CLI augmentation (read `references/cli-manifest.md` for the full contract)
- No → Skip CLI augmentation entirely

**Does the plan already include scaffolding steps?**
- No scaffolding at all → Add a full scaffolding milestone
- Some scaffolding but gaps → Fill the gaps
- Comprehensive scaffolding → Skip or lightly supplement

Tell the user what you plan to add before modifying the file:
- "This plan describes a CLI tool but doesn't specify structured output, error codes, or a guide command. I'll add a CLI foundations milestone."
- "There's no scaffolding in this plan — no README, ARCHITECTURE.md, or AGENTS.md setup. I'll add a scaffolding milestone before the first feature milestone."
- "The CLI already has structured output planned, but it's missing dry-run support and safety flags. I'll augment the relevant milestones."

### Step 4: Determine applicable CLI parts

The CLI manifest has five parts. Not all apply to every CLI. Use this decision tree based on what the CLI does:

| CLI type | Parts to apply |
|----------|---------------|
| Read-only query/inspection tool | I (Foundations) + II (Read & Discover) |
| Tool that modifies files/state | I + II + III (Safe Mutation) |
| Plan-review-apply workflow tool | I + II + III + IV (Transactional Workflows) |
| Multi-agent/shared-resource tool | I + II + III + IV + V (Multi-Agent Coordination) |

Part I (Foundations) applies to every CLI. It covers:
- Structured JSON envelope for every command response
- Machine-readable error codes with retry semantics
- Distinct exit codes per error category
- Built-in `guide` command for progressive discovery
- Consistent command groups and verb naming
- Examples in `--help`
- TOON (Terse Output or None) — stdout is for data only
- `LLM=true` environment variable support
- Observability metrics in every response
- Schema versioning

Read `references/cli-manifest.md` for the full specification of each part before writing your augmentation. The reference contains implementation hints for Python, TypeScript, and Go — use the ones matching the plan's tech stack.

### Step 5: Write the CLI augmentation

Add CLI requirements to the plan in a way that respects its existing structure. You have three strategies depending on the plan's current state:

**Strategy A: Insert a new milestone** — When the plan has no CLI design at all, add a dedicated milestone (typically "Milestone 0" or inserted before the first feature milestone) titled something like "Establish CLI Contract and Foundations." This milestone should cover:

1. Define the response envelope type/schema (the exact struct/interface/model for the project's language)
2. Implement the envelope serializer so every command returns the same shape
3. Define the error code taxonomy (with `ERR_` prefixed codes organized by category)
4. Map error categories to exit code ranges
5. Implement the `guide` command that returns the full CLI schema as JSON
6. Add `isatty()` detection and `LLM=true` support
7. Add `--output` flag (json/text) with json as default when piped
8. Add metrics/observability to the envelope
9. Validate with concrete test: run a command, parse the JSON output, verify envelope shape

For mutation CLIs, add additional steps:
10. Add `--dry-run` to every mutating command
11. Implement change records with before/after state
12. Add explicit safety flags for dangerous operations
13. Add `--backup` support for destructive operations
14. Implement atomic writes (temp file + fsync + rename)

For transactional CLIs, add:
15. Implement fingerprint-based conflict detection
16. Create plan/validate/apply/verify workflow commands
17. Add structured assertion support for verification
18. Support workflow composition format

**Strategy B: Augment existing milestones** — When the plan already describes CLI commands but lacks the contract details, weave requirements into existing milestones. For each milestone that implements a command:
- Add a step to wrap the command's output in the structured envelope
- Add a step to define error codes for that command's failure modes
- Add validation steps that verify the envelope shape
- Add dry-run support if the command mutates state

**Strategy C: Add a Context section addendum** — When the plan's CLI design is mostly complete but missing some principles, add a "CLI Design Contract" subsection to the Context and Orientation section that documents the principles the implementing agent must follow, without restructuring existing milestones.

In all cases, be concrete. Don't say "add structured output" — show the exact envelope type definition for the project's language. Don't say "add error codes" — list the specific error codes the CLI will need based on its commands.

### Step 6: Write the scaffolding augmentation

Read `references/scaffold-from-prd.md` for the full scaffolding specification. Add a scaffolding milestone to the plan — this should be the very first milestone (before any feature work), titled something like "Scaffold Repository Structure and Guidance Files."

The milestone should include concrete steps to create:

**Foundation documents** (only those the project doesn't already have):
- `README.md` — what the project is, quick start, repo structure, how