plan-with-specs

Plan with Specs

Skill Info

Part of the spec-manager agent. This skill generates detailed, actionable implementation plans from finalized specifications.

Input

The user provides a task slug (or task title) as arguments: $ARGUMENTS

If no arguments are provided:

1. List all */specs.md files in specs/ directory
2. Ask the user which one to generate a plan for

If a task title (not slug) is provided, convert it to a slug to find the matching files.

Process

Step 1: Read All Spec Documents

1. Read specs/{slug}/requirements.md - for original context and goals
2. Read specs/{slug}/specs.md - for technical specifications
3. If either file doesn't exist or specs status is still "Pending", inform the user and suggest running the appropriate prior step

Step 2: Validate Specs Readiness

Check that specs are sufficiently detailed for planning:

• Status is not "Pending"
• Technical specifications are defined
• Architecture section is filled in
• No critical open questions remain

If specs have unresolved open questions, warn the user and ask whether to proceed or resolve them first.

Step 3: Analyze Codebase

Before generating the plan:

1. Examine the existing codebase structure (project layout, frameworks, patterns)
2. Identify existing files that need modification
3. Find reusable components, utilities, or patterns
4. Check test structure and conventions
5. Review configuration and build setup

Step 4: Generate Implementation Plan

Update specs/{slug}/plans.md with the implementation plan:

# Plans: {Original Task Title}

> Created: {original date}
> Updated: {YYYY-MM-DD}
> Status: Ready
> Requirements: [requirements.md](./requirements.md)
> Specs: [specs.md](./specs.md)

## Overview

{Brief summary of what will be implemented and the approach}

## Prerequisites

- {Any setup, dependencies, or preparatory work needed before starting}

## Implementation Steps

### Step 1: {Step Name}

- **Goal**: {What this step achieves}
- **Specs Reference**: TS-{X}
- **Files**:
  - `{path/to/file}` - {Create | Modify} - {What changes}
- **Details**:
  {Detailed implementation instructions}
- **Validation**:
  - {How to verify this step is complete}
- **Complexity**: Simple | Medium | Complex

### Step 2: {Step Name}

{Same structure}

{Continue for all steps...}

## Task Breakdown

Ordered checklist for tracking progress:

- [ ] **Step 1**: {Brief description}
- [ ] **Step 2**: {Brief description}
- [ ] ...
- [ ] **Final**: Verify all acceptance criteria

## File Change Summary

| File | Action | Step | Description |
|------|--------|------|-------------|
| `path/to/file` | Create/Modify/Delete | Step N | Brief description |

## Dependencies Between Steps

{Describe which steps depend on others and which can be parallelized}

Step 1 ─── Step 2 ─── Step 4 │ Step 3 ─── Step 5

## Testing Strategy

### Unit Tests
- {What to test and where}

### Integration Tests
- {What to test and where}

### Manual Verification
- {Steps to manually verify the feature works}

## Rollback Plan

{How to safely undo changes at each major checkpoint}

1. **After Step N**: {How to rollback}
2. **After Step M**: {How to rollback}

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| {Risk} | Low/Medium/High | Low/Medium/High | {How to mitigate} |

## Progress Tracking

| Step | Status | Started | Completed | Notes |
|------|--------|---------|-----------|-------|
| Step 1 | Pending | | | |
| Step 2 | Pending | | | |

## Acceptance Criteria Checklist

From requirements:
- [ ] {Criterion from FR-1}
- [ ] {Criterion from FR-2}
- [ ] ...

Step 5: Report and Request Review

After generating the plan, display a summary:

Implementation plan generated for: "{Original Task Title}"

Updated: specs/{slug}/plans.md

Summary:
  - {N} implementation steps
  - {X} files to create, {Y} files to modify
  - Estimated complexity: {overall assessment}
  - {Z} risks identified

Please review the plan in specs/{slug}/plans.md

When ready to start implementation:
1. Follow the steps in order
2. Check off tasks as you complete them
3. Update the Progress Tracking table

During Implementation

When the user is implementing and discusses progress or issues:

1. Update Progress: Mark steps as In Progress / Completed in the plans.md
2. Update Specs: If implementation reveals spec changes needed, update specs.md
3. Track Deviations: Log any deviations from the plan in the Notes column
4. Adapt Plan: If the plan needs adjustment based on discoveries during implementation, update the remaining steps

Handling Changes

If user requests requirement changes:

1. Update specs/{slug}/requirements.md with new/changed requirements
2. Re-read and update specs/{slug}/specs.md to reflect changes
3. Regenerate affected sections of specs/{slug}/plans.md
4. Clearly mark which steps changed and why
5. Preserve progress on already-completed steps

If user requests spec changes:

1. Update specs/{slug}/specs.md with the changes
2. Regenerate affected sections of specs/{slug}/plans.md
3. Clearly mark which steps changed and why
4. Preserve progress on already-completed steps

If implementation reveals issues:

1. Log the issue in the Progress Tracking table
2. Update affected specs in specs/{slug}/specs.md if needed
3. Adjust remaining plan steps
4. Add new risk entries if applicable

Important

• Always read both requirements AND specs before generating plans
• Examine the actual codebase - plans must be grounded in the real project structure
• Steps should be ordered by dependency, not arbitrary sequence
• Each step must be independently verifiable
• Include rollback strategies for risky steps
• Keep the plan actionable - avoid vague instructions like "implement the feature"
• Reference specific file paths based on the actual project layout
• Plans should be detailed enough that another developer could follow them