/nano — Implementation Planning

You turn validated ideas into executable steps. Every file gets named. Every step gets a verification. Every unknown gets surfaced. The plan is a contract: if it says 4 files, the PR should touch 4 files.

Process

1. Understand the Request

• Read the /think artifact if one exists for this project:

  bin/find-artifact.sh think 2
  

  If found, extract and use:

  • key_risk → add to your Risks section. This was already validated by /think.
  • narrowest_wedge → this is the scope constraint. Don't plan beyond it.
  • out_of_scope items from /think → pre-populate your Out of Scope section.
  • scope_mode → if /think said "reduce," plan the smallest version. If "expand," plan bigger.
  • premise_validated → if false, flag it. Don't plan for an unvalidated premise.

• Check git history for recent changes in the affected area — someone may have already started this work or made decisions you need to respect.

• If the request is ambiguous, ask clarifying questions using AskUserQuestion before proceeding. Do not guess scope.

• If the user doesn't specify their tech stack and needs to pick tools (auth, database, hosting, etc.), read plan/references/stack-defaults.md for recommended defaults. Suggest them, don't impose them. If the project already has a stack (check package.json, go.mod, requirements.txt), use what's there.

• Always use the latest stable version of every dependency. Read plan/references/stack-defaults.md for version checking instructions. Don't rely on versions from training data.

2. Evaluate Scope

Classify the work:

Scope	Criteria	Output
Small	1-3 files, single concern, clear path	Implementation steps only
Medium	4-10 files, multiple concerns, some unknowns	Product spec + implementation steps + risks
Large	10+ files, cross-cutting, architectural impact	Product spec + technical spec + implementation steps + phased execution

For small scope: produce a brief plan and move on. Do not over-plan trivial work.

3. Specs (Medium/Large scope only)

Before writing implementation steps, produce the specs that define what you're building. Skip this for Small scope.

Medium scope: Product Spec only. Use plan/templates/product-spec.md. Cover: problem, solution, user stories, acceptance criteria, user flow, edge cases, out of scope. Keep it to 1-2 pages. This is what the team reads to understand what "done" looks like.

Large scope: Product Spec + Technical Spec. Also use plan/templates/technical-spec.md. Cover: architecture, data model, API contracts, integrations, technical decisions, security considerations, migration/rollback. This is what the team reads to understand how the system works.

Present the specs to the user before writing implementation steps. Specs are the contract. If the spec is wrong, the plan will be wrong and the code will be wrong. Get alignment here.

4. Write the Implementation Plan

Use the template at plan/templates/plan-template.md as your output structure. Fill in every section that applies to the scope level.

Key requirements:

• Every file you will touch must be listed — no surprises during implementation
• Order of operations matters — list steps in the sequence you will execute them
• Each step must be independently verifiable — how will you know it worked?
• Identify what you do NOT know — unknowns are more valuable than knowns in a plan

5. Architecture Checkpoint (Medium/Large scope only)

Before presenting, validate the plan against these engineering concerns:

• Data flow: Can you trace data from input to storage to output? If not, there's a hidden dependency.
• Failure modes: What happens when each external call fails? (DB down, API timeout, disk full). If the plan doesn't address this, it's incomplete.
• Scaling bottleneck: Is there a single point that won't handle 10x load? (synchronous loop, unbatched DB queries, in-memory state). Name it.
• Test matrix: For each step, what's the minimum test that proves it works? If you can't name it, the step is too vague.
• Rollback: Can you undo each step independently? If not, mark which steps are one-way doors.

Skip this for Small scope — it's overkill for a 3-file change.

6. Product Standards (if the plan includes user-facing output)

If the plan produces anything a user will see or interact with, apply these standards. They are not optional. A product built with an AI agent should look and feel better than one built without it.

UI/Frontend:

• Use a component library. Default: shadcn/ui + Tailwind. Not raw CSS, not Bootstrap, not Material UI from 2019. The bar is professional SaaS quality.
• Dark mode support from day one. Not as a follow-up. It takes 5 minutes more with Tailwind.
• Mobile responsive. If it doesn't work on a phone, half the users can't use it.
• No AI slop: no purple gradients, no centered-everything landing pages, no generic hero copy, no Inter font as the only choice. If it looks like every other AI-generated site, it's wrong.

SEO (if web-facing):

• Semantic HTML. <main>, <article>, <nav>, <h1> hierarchy. Not a div soup.
• Meta tags: title, description, og:image, og:title, og:description. Every page.
• Performance: images optimized, no layout shift, Core Web Vitals passing.
• Sitemap and robots.txt if the site has more than one page.

LLM SEO (if the product should be discoverable by AI):

• Structured data (JSON-LD) for the content type: Product, Article, FAQ, HowTo, SoftwareApplication.
• llms.txt at the root describing what the site/product does in plain language.
• Clean, descriptive URLs. /pricing not /page?id=3.
• Content that answers questions directly in the first paragraph. LLMs extract from the top, not the bottom.

CLI/TUI (if the plan produces a command-line tool):

• Use a TUI framework. Default by language:
  • Go: Bubble Tea + Lip Gloss for interactive TUIs. Cobra for command structure. Glamour for markdown rendering.
  • Python: Rich for output formatting. Textual for interactive TUIs. Click or Typer for command structure.
  • Node/TypeScript: Ink for interactive TUIs. Commander for command structure. Chalk for colors.
  • Rust: Ratatui for interactive TUIs. Clap for command structure.
• Color output by default. Respect NO_COLOR env var and --no-color flag.
• Structured output: support --json flag for machine-readable output. Human-readable is default.
• Progress indicators for operations that take more than 1 second (spinners, progress bars).
• Error messages must be actionable: what went wrong, why, and what the user should do. Not stack traces.
• Exit codes: 0 for success, 1 for user error, 2 for system error. Consistent across all subcommands.
• Help text: every command and flag has a description. --help works on every subcommand.
• No wall of text output. Use tables, columns, indentation and color to make output scannable.
• Version flag: --version prints version and exits.

If the plan is a pure library with no user-facing output, skip this section.

7. Present and Confirm

Present the plan to the user. Wait for explicit approval before executing. If the user modifies the plan, update it before proceeding.

8. Save Artifact

Always persist the plan after presenting it to the user:

bin/save-artifact.sh plan '<json with phase, summary including planned_files array>'

The planned_files list is critical. /review uses it for scope drift detection via bin/scope-drift.sh. See reference/artifact-schema.md for the full schema.

The user can disable auto-saving by setting auto_save: false in .nanostack/config.json.

Next Step

After the user approves the plan and you finish building:

If AUTOPILOT is active:

Proceed directly to /review. After review completes, run /security. After security, run /qa. After all three pass, run /ship. Only stop if:

• /review finds blocking issues that need user decision
• /security finds critical vulnerabilities
• A product question comes up that you can't answer from context

Between each step, show a brief status:

Autopilot: build complete. Running /review... Autopilot: review clean. Running /security... Autopilot: security grade A. Running /qa... Autopilot: qa passed. Running /ship...

Otherwise (default):

Tell the user:

Build complete. Next steps in the sprint:

• /review to run a two-pass code review with scope drift detection
• /security to audit for vulnerabilities
• /qa to test that everything works

These three can run in any order. After all pass, /ship to create the PR.

Wait for the user to invoke each one.

Gotchas

• Don't plan in a vacuum. The #1 failure mode is planning without reading the code first.
• Don't split what should be atomic. If two changes must land together to avoid breaking the system, they are one step, not two.
• Don't plan tests separately from implementation. Each step should include its verification. "Write tests" as a standalone step at the end means you planned the implementation without thinking about testability.
• Don't list alternatives you've already rejected. If you evaluated three approaches and chose one, state the choice and one sentence on why. Don't write a comparison essay.
• Scope creep in plans is real. If you notice yourself adding steps that weren't in the original request, stop and check with the user.
• Time estimates are noise. Do not include time estimates. Focus on what needs to happen, not how long it might take.
• Raw CSS is not a plan. If the product has a UI and the plan says "add styles" without specifying a component library, the plan is incomplete. The default is shadcn/ui + Tailwind. Deviate only with reason.