resumable-implementation-plan

name

resumable-implementation-plan

description

Generates a structured, agent-resumable implementation plan as a downloadable Markdown file. Use this skill whenever a user wants to turn a technical design, architecture discussion, or feature spec into a step-by-step implementation plan that a coding agent can follow across multiple sessions — especially when context resets, usage limits, or long-running builds mean the agent needs to resume mid-task without losing state. Trigger this skill for prompts like: "turn this into an implementation plan", "create a task tracker for this project", "make a plan a coding agent can follow", "I want to implement this with Claude Code", "create a resumable plan", "generate a todo file for this", or any time the user is about to hand off a design to a coding agent and wants structured guidance. Also trigger when the user says things like "let's start building this" after a design discussion — proactively offer the plan as the right first artifact.

Resumable Implementation Plan Skill

Generate a structured Markdown implementation plan that a coding agent can use to track progress across multiple sessions, context resets, and usage limit interruptions.

When to use this skill

Use this whenever:

• A design, architecture, or feature has been discussed and implementation is next
• The user wants to hand off work to Claude Code or another coding agent
• The task is complex enough to span multiple sessions
• The user says "make a plan", "create a todo", "turn this into tasks", or similar

Output format

Always produce a single Markdown file saved to /mnt/user-data/outputs/ and presented with present_files. Name it descriptively in SCREAMING_SNAKE_CASE: <PROJECT_NAME>_IMPLEMENTATION_PLAN.md

The file must be immediately usable as a drop-in to a repo root.

---

Plan structure (always include all sections)

1. Header block

# <ProjectName> — Coding Agent Implementation Plan

> **How to use this file**
> This is a living task tracker for a coding agent. After each work session, update task
> statuses, fill in the "Agent notes" fields, and commit this file alongside code changes.
> When resuming, read "Current focus" and "Context snapshot" first, then find the first
> `[ ]` task under the active phase.
>
> Status legend: `[ ]` not started · `[~]` in progress · `[x]` complete · `[!]` blocked

2. Project overview

One paragraph. Include: app/system name, purpose (2–3 sentences), key tech stack, target platform/environment. Written so an agent with zero prior context can understand the goal.

3. Context snapshot block

This is the most important section for resumability. Always include it verbatim as a fenced code block so the agent can find and update it programmatically.

## Context snapshot
> Update this section at the end of every session before stopping.

​```
Last updated      : <AGENT: fill in date/time>
Last file changed : <AGENT: fill in path>
Last passing test : <AGENT: fill in test name>
Current phase     : Phase 0 — Project bootstrap
Current focus     : <AGENT: fill in task ID, e.g. "1.2">
Blockers          : none
Open questions    :
  - <list any unresolved decisions>
Notes             :
  - <key decisions already made, constraints, gotchas>
​```

Pre-populate Open questions with any genuinely unresolved decisions from the design conversation (e.g. "confirm library version X vs Y"). Pre-populate Notes with the key decisions that WERE made so the agent doesn't re-litigate them.

4. Repo / directory structure

Show the target file tree. This gives the agent a map to navigate, and helps it know what files to create vs what already exists.

5. Phases (core of the plan)

Break implementation into 5–10 sequential phases. Each phase has:

Phase header:

### Phase N — <Phase name>
> Goal: <one sentence describing what "done" looks like for this phase>
> **This phase is done on [environment], not in [other environment].**  ← include when relevant

Tasks within each phase:

• Numbered as N.M (e.g. 2.3) — unique IDs the agent references in Context snapshot
• Status prefix: [ ] / [~] / [x] / [!]
• One clear action per task — not vague, not compound
• Include exact commands, file paths, or code snippets where the action is non-obvious
• Group logically into sub-sections (e.g. #### 2a — Core client, #### 2b — Tests)

Test tasks: Every phase that produces code must include at least one test task. Name the exact test command to run. Mark these clearly.

Commit tasks: End every phase with a commit task:

- [ ] **N.M** Commit: `<type>: <short description of what this phase delivered>`

6. Key architectural decisions table

## Key architectural decisions (do not revisit without good reason)

| Decision | Choice | Reason |
|---|---|---|
| <what was decided> | <the choice> | <why, in ≤10 words> |

Capture every non-obvious technology or design choice made during the design conversation. This prevents the agent from second-guessing settled decisions mid-implementation.

7. Critical constraints

## Critical constraints (never violate)

1. **<Constraint name>.** <One sentence explanation.>

List 3–6 absolute rules the agent must never break regardless of what it encounters. Examples: "never commit secrets", "all inference must be on-device", "tests must pass before commit".

8. Dependency quick reference

A compact key: version or package: purpose list. The agent uses this to avoid searching pubspec/package.json when it just needs to know what's available.

9. How to resume (always last)

## How to resume after a context reset

1. Read **Context snapshot** — find `Current phase` and `Current focus`
2. Read **Key architectural decisions** table
3. Read **Critical constraints**
4. Open the current phase section, find the first `[~]` task, then the first `[ ]` task
5. Run the test suite — understand what is passing before making changes
6. Continue from where the previous session stopped

---

Quality rules

Specificity over generality. Vague tasks like "set up the database" are useless. Write "Run prisma migrate dev --name init and confirm zero errors" instead.

Agent-readable IDs. Every task gets a N.M ID. The agent writes Current focus: 3.4 in the snapshot, not "the SSH thing in phase 3".

No orphan decisions. Every tech choice visible in the repo structure or dependency list must appear in the architectural decisions table with a reason.

Test gates. Never let two phases pass without a flutter test / pytest / npm test task. Agents drift without test feedback.

Pre-populated snapshot. Don't leave the Context snapshot entirely blank. Fill in Current phase: Phase 0 and known Open questions and Notes from the conversation. The agent should be able to start from this file without reading the chat history.

Commit messages follow conventional commits: feat: / fix: / chore: / docs: / test: + short description.

---

Phase ordering heuristic

Use this order unless the project demands otherwise:

1. Bootstrap — project scaffold, deps, passing smoke test
2. Infrastructure / host setup — VPN, DB, external services (if any)
3. Core data layer — models, storage, repositories
4. Core feature A (the foundation everything else builds on)
5. Core feature B (next layer up)
6. Integration — wire features together end-to-end
7. Safety / validation — classifiers, guards, edge cases
8. Optional / stretch features — label clearly as optional
9. Polish + hardening — error states, accessibility, linting, full test run

---

Generating the file

1. Extract all design decisions, tech choices, constraints, and open questions from the conversation before writing anything.
2. Write the full plan in one pass — do not ask the user for more input mid-generation unless a critical decision is genuinely missing.
3. Save to /mnt/user-data/outputs/<PROJECT_NAME>_IMPLEMENTATION_PLAN.md
4. Call present_files with the output path.
5. In your response text (outside the file), summarize: how many phases, total task count, and the one or two open questions the user should resolve before the agent starts.

---

Example context snapshot (filled in, mid-project)

Last updated      : 2026-04-12 14:32
Last file changed : lib/features/ssh/ssh_client.dart
Last passing test : test/ssh/ssh_client_test.dart — 4/4 passing
Current phase     : Phase 2 — SSH client + terminal widget
Current focus     : 2.6
Blockers          : none
Open questions    :
  - Confirm whether dartssh2 supports ed25519 keys on Android API < 28
Notes             :
  - dartssh2 ^2.9.0 chosen over ssh_client — better programmatic write() support
  - xterm.dart ^4.0.0 pairs with dartssh2
  - Gemma inference must be fully on-device — no API calls permitted
  - SafetyClassifier.destructive commands must never auto-run regardless of timer state