Planning and architecture decision domain expert. Knows about: - Creating ADRs (Architecture Decision Records) - Creating technical specifications - Listing and discovering planning artifacts - Transforming plans into executable VTM tasks - Integrating with research tools (thinking-partner) Use when: - User wants to document an architectural decision - User needs to create a technical specification - User wants to explore or list existing ADRs/specs - User is ready to convert planning docs into tasks - User needs research before making a decision
Guides you through the complete planning workflow from ideation to executable VTM tasks. Handles ADR and spec creation conversationally, helps you discover existing planning artifacts, and bridges your plans into VTM for execution.
Auto-discovers when you mention planning, documentation, or decision-making activities.
/plan:to-vtm <adr-file> <spec-file> - Transform ADR+Spec pair into VTM tasks/helpers:thinking-partner - Research and ideation support (coming soon)The complete planning-to-execution workflow:
1. Ideation & Research
↓ (use /helpers:thinking-partner)
2. Document Decision (ADR)
↓ (plan-expert creates ADR file)
3. Write Technical Spec
↓ (plan-expert creates spec file)
4. Transform to VTM Tasks
↓ (plan-expert calls /plan:to-vtm)
5. Execute Tasks
↓ (use vtm-expert for execution)
When you say:
Claude will:
docs/adr/ADR-XXX-{topic}.md.claude/templates/adr-template.mdWhen you say:
Claude will:
docs/specs/spec-{topic}.md.claude/templates/spec-template.mdWhen you say:
Claude will:
When you say:
Claude will:
/plan:to-vtm <adr-file> <spec-file>When creating an ADR, the plan-expert follows this template:
# ADR-XXX: {Decision Title}
## Status
Proposed | Accepted | Deprecated | Superseded
## Context
What is the issue we're trying to solve? What constraints exist?
## Decision
What did we decide to do and why?
## Consequences
### Positive
- What benefits come from this decision?
### Negative
- What drawbacks or costs?
- What mitigations exist?
## Alternatives Considered
What other options did we evaluate and why did we reject them?
When creating a spec, the plan-expert follows this template:
# Technical Specification: {Feature Name}
## Related ADR
- ADR-XXX: {Link to decision}
## Overview
Brief description of what we're building and why.
## Architecture
High-level design with components and data flow.
## Implementation Details
Detailed breakdown of what needs to be built.
## Tasks
1. Task 1 description
- Dependencies: None
- Test strategy: TDD/Unit/Integration/Direct
- Estimated hours: X
2. Task 2 description
- Dependencies: Task 1
- Test strategy: TDD
- Estimated hours: Y
## Acceptance Criteria
- AC1: Specific, testable criterion
- AC2: Another testable criterion
## Test Strategy
How to verify this works (unit, integration, e2e).
## Performance Requirements
Any performance constraints or targets.
The /plan:to-vtm command performs intelligent task extraction:
Input:
Process:
Output:
/vtm:nextThe plan-to-vtm bridge achieves 80% token reduction:
ADR First, Spec Second
One ADR per Decision
Detailed Acceptance Criteria
Explicit Dependencies
Test Strategy per Task
The plan-expert skill uses these MCP servers:
Filesystem MCP:
docs/adr/*.md)docs/specs/*.md).claude/templates/adr-template.md and .claude/templates/spec-template.mdFirecrawl MCP (via /helpers:thinking-partner):
Tavily MCP (via /helpers:thinking-partner):
Context7 MCP (via /helpers:thinking-partner):
User: "I need to plan a new authentication system"
Claude (plan-expert): Let me help you plan that. First, have you
researched authentication approaches yet? I can help with that using
the thinking-partner.
User: "Yes, I've decided on JWT with refresh tokens"
Claude: Great! Let's document that decision. I'll create an ADR.
[Creates docs/adr/ADR-047-jwt-authentication.md from adr-template.md]
Claude: I've created ADR-047. Let me populate it with your decision...
[Populates Context, Decision, Consequences sections]
Claude: Now let's create the technical specification. What components
need to be built?
User: "Auth middleware, token service, refresh endpoint, logout"
Claude: Perfect. I'll create the spec with those tasks.
[Creates docs/specs/spec-jwt-authentication.md from spec-template.md]
Claude: I've created the spec with 8 tasks. Ready to add these to VTM?
User: "Yes, do it"
Claude: [Calls /plan:to-vtm docs/adr/ADR-047-jwt-authentication.md docs/specs/spec-jwt-authentication.md]
[Shows preview of 8 tasks with dependencies]
Claude: I see 8 new tasks. Task dependencies look good:
- TASK-020: JWT token service (no dependencies)
- TASK-021: Auth middleware (depends on TASK-020)
- TASK-022: Refresh endpoint (depends on TASK-020, TASK-021)
- ...
Shall I add these to your VTM?
User: "Yes"
Claude: ✅ Added 8 tasks to VTM. Run /vtm:next to see what's ready!
Expected project structure for plan domain:
project-root/
├── docs/
│ ├── adr/
│ │ ├── ADR-001-initial-architecture.md
│ │ ├── ADR-042-database-choice.md
│ │ └── ADR-047-jwt-authentication.md
│ └── specs/
│ ├── spec-initial-setup.md
│ ├── spec-database-layer.md
│ └── spec-jwt-authentication.md
├── .claude/
│ └── templates/
│ ├── adr-template.md
│ └── spec-template.md
└── vtm.json
Edit the frontmatter above to include project-specific terms:
trigger_phrases:
- "create an adr"
- "new architecture decision" # Add this
- "rfp" # Your team uses "RFP" for specs
- "implementation plan" # Alternative to "spec"
The plan-expert uses these templates:
.claude/templates/adr-template.md - ADR format.claude/templates/spec-template.md - Spec formatYou can customize these templates to match your team's preferences.
Architecture:
Data Flow:
User intent → plan-expert detects →
Filesystem MCP (create/list files) →
User edits docs →
/plan:to-vtm (transform) →
vtm CLI (validate + ingest) →
VTM updated
ADR Creation Errors:
docs/adr/ directorySpec Creation Errors:
docs/specs/ directoryTransformation Errors:
specs/spec-plan-to-vtm.md.claude/commands/plan/to-vtm.md.claude/designs/plan.jsonImplemented:
In Progress:
Planned: