plan-impl

A Claude Code plugin providing a structured plan → implement → verify workflow.

Installation

/plugin marketplace add ecoffey/plan-impl-skills
/plugin install plan-impl@plan-impl-skills

Local development

1. Symlink the repo into Claude Code's marketplace directory:

ln -s /path/to/plan-impl-skills ~/.claude/plugins/marketplaces/plan-impl-skills

2. Register the marketplace in ~/.claude/settings.json under extraKnownMarketplaces:

{
  "extraKnownMarketplaces": {
    "plan-impl-skills": {
      "source": {
        "source": "directory",
        "path": "/path/to/plan-impl-skills"
      }
    }
  }
}

3. Register the runtime entry in ~/.claude/plugins/known_marketplaces.json:

{
  "plan-impl-skills": {
    "source": {
      "source": "directory",
      "path": "/path/to/plan-impl-skills"
    },
    "installLocation": "/path/to/home/.claude/plugins/marketplaces/plan-impl-skills",
    "lastUpdated": "2026-01-01T00:00:00.000Z"
  }
}

Replace /path/to/plan-impl-skills with the absolute path to your clone and /path/to/home with your home directory (e.g. /Users/yourname).

4. Install the plugin inside any Claude Code session:

/plugin install plan-impl@plan-impl-skills

Changes to the repo are picked up immediately. Use /reload-plugins if a skill doesn't reflect recent edits.

Skills

Skill	Invocation	Auto-triggers?	Description
plan	/plan-impl:plan <description>	Yes	Creates a high-level plan for a feature, bug fix, or change
implement	/plan-impl:implement [plan-path]	No	Creates implementation detail or executes an approved plan with TDD
process-feedback	/plan-impl:process-feedback [plan-path]	Yes	Processes inline comments on a plan file
verify	/plan-impl:verify [plan-path]	No	Adversarially reviews implementation against the plan, surfaces deviations
handoff	/plan-impl:handoff <project> [context]	Yes	Creates a handoff document in ~/.handoff/<project>/ from free-form context or a plan file
pickup	/plan-impl:pickup [project]	Yes	Loads the most recent handoff document for a project into the current session

Workflow

1. /plan-impl:plan <what you want to build> — Claude researches and writes a high-level plan to _plans/
2. Review and leave inline comments, then /plan-impl:process-feedback to incorporate them
3. /plan-impl:implement — Claude writes the implementation detail plan
4. Review, then /plan-impl:implement again — Claude executes using TDD
5. /plan-impl:verify — adversarial review of the implementation against the plan

Cross-session handoff

To continue work in a new session or a different project directory:

1. /plan-impl:handoff <project> <context> — Claude synthesizes a handoff document from your context (free-form text or a plan file path) and writes it to ~/.handoff/<project>/.
2. In the new session: /plan-impl:pickup <project> — Claude loads the most recent handoff doc and summarizes what to do next.

The _plans/ directory

When you run /plan-impl:plan, Claude creates a _plans/ directory at the root of your project (not this repo). Each feature or change produces up to two plan files:

File	Purpose
YYYY-MM-DD-HHmm-<slug>-high-level.md	Architecture-level plan: affected modules, data-flow diagrams, key signatures
YYYY-MM-DD-HHmm-<slug>-impl.md	Step-by-step execution plan: every file touched, exact code, test cases, doc updates

The timestamp prefix keeps files sorted chronologically; the slug is a short kebab-case summary of the work.

Plans as a source-control artifact

Plan files are designed to be committed alongside the code they describe. Checking them in gives you:

• A durable record of why a change was shaped the way it was, not just what changed
• A natural surface for peer review — teammates can leave inline comments on the plan before a single line of production code is written, catching design issues early
• An audit trail that links intent (the high-level plan) to execution (the impl plan) to outcome (the code diff)

The /plan-impl:process-feedback skill reads inline comments directly from the plan file, so feedback left during a code review round-trip back into Claude without any copy-paste.

Reference documents

The plugin ships with default reference documents that inform how the skills plan, implement, and verify code. These live in skills/references/ and are loaded automatically:

File	Purpose
PHILOSOPHY.md	Software design principles (derived from "A Philosophy of Software Design") used during planning and review
IMPLEMENTATION_STRATEGY.md	TDD red-green-refactor cycle enforced during implementation
TESTING_STRATEGY.md	Testing guidelines: prefer integration tests, minimize mocks, write specific assertions

Overriding the defaults

Each reference document can be overridden per project. Place a file with the same name anywhere in your project and the skills will use your version instead of the bundled default. The find-reference.sh script (called internally by the skills) searches the project first and falls back to the plugin's skills/references/ directory.

This lets you commit project-specific philosophy or testing norms alongside your code without forking the plugin.

The ~/.handoff/ store

The handoff and pickup skills use a shared directory at ~/.handoff/ to pass context between sessions and projects.

Directory structure

~/.handoff/
  <project>/
    YYYY-MM-DD-HHmm-<slug>-handoff.md   ← most recent is used by /pickup
    YYYY-MM-DD-HHmm-<slug>-handoff.md
    ...

Each handoff document contains: Goal, Current state, Next steps, Key files, Open questions, and optional Context snippets.

Browsing and managing handoffs

# List all projects with handoffs
ls ~/.handoff/

# List handoffs for a specific project
ls ~/.handoff/my-project/

# View the most recent handoff
ls ~/.handoff/my-project/ | sort | tail -1 | xargs -I{} cat ~/.handoff/my-project/{}

# Delete all handoffs for a project
rm -rf ~/.handoff/my-project/

Known limitation: basename collisions

When /pickup is run without an argument it uses the current directory's basename as the project name. Two unrelated repos with the same basename (e.g., src) will share a handoff store. Avoid this by always passing an explicit project name.

License

MIT