Augment an existing Execution Plan (ExecPlan) with CLI design requirements and project scaffolding guidance. Use this skill whenever the user wants to "augment a plan", "add CLI requirements to a plan", "add scaffolding to a plan", "enrich a plan with CLI design", "make my plan CLI-ready", "add agent-first CLI patterns to my plan", or mentions "augment plan", "plan augmentation", "CLI plan", or "scaffold plan" in the context of enhancing an existing ExecPlan. Also triggers when the user has an existing PLAN.md and wants to add CLI interface design, structured output patterns, error handling contracts, or project scaffolding milestones. Covers both adding CLI-specific milestones (structured envelopes, error codes, exit codes, guide commands, dry-run, safety flags) and scaffolding milestones (repo layout, documentation, agent guidance files, quality infrastructure). Even if the user only mentions one aspect (e.g., "add CLI stuff to my plan" or "add scaffolding steps"), use this skill — it handles both independently.
From augment-plannpx claudepluginhub thomasrohde/marketplace --plugin augment-planThis skill uses the workspace's default tool permissions.
references/cli-manifest.mdreferences/scaffold-from-prd.mdGuides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Orchestrates subagents to execute phased plans: deploys for implementation, verification, anti-pattern checks, code quality review, and commits only after passing checks.
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.
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:
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.
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.
Ask the user for the ExecPlan file path if not provided. Read it thoroughly. Pay attention to:
If the PRD that generated this plan exists in the repo, read it too. It provides context about:
If no PRD is available, work from the plan alone and ask the user to confirm your inferences.
Not every plan needs both layers. Ask yourself:
Does the project include a CLI?
references/cli-manifest.md for the full contract)Does the plan already include scaffolding steps?
Tell the user what you plan to add before modifying the file:
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:
guide command for progressive discovery--helpLLM=true environment variable supportRead 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.
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:
ERR_ prefixed codes organized by category)guide command that returns the full CLI schema as JSONisatty() detection and LLM=true support--output flag (json/text) with json as default when pipedFor 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:
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.
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 to testPROJECT.md — problem statement, goals, non-goals, constraints, assumptionsARCHITECTURE.md — stack rationale, component map, data flows, trade-offsTESTING.md — strategy, test pyramid, coverage expectations, CI validationCONTRIBUTING.md — branch workflow, code style, commit conventions, review checklistCHANGELOG.md — initial entryDECISIONS/ADR-0001-initial-architecture.md — record the foundational architecture decisionAgent guidance files:
AGENTS.md — project overview for agents, where to look first, coding rules, invariants, how to validate, when to stop and leave a TODO.instructions.md files where appropriate (backend, frontend, testing conventions)Quality infrastructure (appropriate to the plan's tech stack):
.editorconfig.gitignore.github/workflows/ci.yml or equivalent)Placeholder pattern — For anything the PRD doesn't specify, instruct the implementing agent to use this format:
TODO: <what is missing>
Why it matters: <one sentence>
How to fill this in: <one or two concrete instructions>
Example: <optional short example>
The scaffolding milestone's validation step should verify:
After adding milestones and steps, update the plan's living sections:
Progress — Add unchecked items for every new step you introduced, grouped under the new milestone headings.
Decision Log — Add entries for:
Context and Orientation — If you added new concepts (structured envelope, error taxonomy, guide command), define them here so the plan remains self-contained.
Before presenting to the user, verify:
Save the augmented plan back to the same file (or a new file if the user prefers). Tell the user:
When reading references/cli-manifest.md, here's what to extract for each part:
Focus on principles 1 (envelope), 2 (error codes), 3 (exit codes), 4 (guide command), 5 (naming), 7 (TOON), and 8 (LLM=true). These are the non-negotiable baseline. Principles 6 (help examples), 9 (observability), and 10 (schema versioning) are important but lighter-weight.
Focus on principle 11 (read/write separation) and 12 (structured metadata). If the CLI has any list, inspect, show, or get commands, add steps to ensure they return rich structured metadata with stable ordering and cursor pagination.
Focus on principles 13 (dry-run), 14 (change records), and 15 (safety flags). These three transform a "hope it works" CLI into a recoverable one. Add 16 (backup) and 17 (atomic writes) if the CLI modifies files on disk.
Only apply if the CLI has a plan/apply pattern (like Terraform, Alembic, or Helm). Focus on 18 (fingerprinting) and 19 (plan/validate/apply/verify). Principles 20 and 21 are for more sophisticated CLIs.
Only apply if multiple agents or agents + humans will use the CLI concurrently on shared resources. Focus on 22 (locking) and 23 (concurrency docs).
references/cli-manifest.md — The complete CLI-MANIFEST specification. Read this before writing CLI augmentation. It contains the full contract, implementation hints for Python/TypeScript/Go, and do/don't examples for every principle.references/scaffold-from-prd.md — The complete project scaffolding guide. Read this before writing scaffolding augmentation. It contains the full list of deliverables, content guidance per file, and the placeholder pattern.