AgentSkillsCN

planning

规划

SKILL.md
--- frontmatter
name: planning
description: Generate and optimize PRDs, Implementation Plans, and Progress Tracking documents optimized as AI artifacts for development agents. Use when creating new feature plans, breaking down long planning docs (>800 lines), or setting up progress tracking. Supports: 1) Create PRD from feature request, 2) Create Implementation Plan from PRD with phase breakdown and subagent assignments, 3) Optimize existing plans by breaking into phase-specific files, 4) Create progress tracking with task assignments. Example: "Create a PRD for user authentication feature" or "Break down the sidebar-polish implementation plan into phase files" or "Create progress tracking for data-layer-fixes PRD".

Planning Skill

About This Skill

The Planning Skill generates and optimizes Product Requirements Documents (PRDs) and Implementation Plans as AI artifacts - file-based context caches optimized for AI agent consumption rather than human reading.

Purpose

  • •Generate comprehensive PRDs from feature requests following MP template
  • •Create phased Implementation Plans with subagent task assignments
  • •Optimize existing planning docs by breaking into token-efficient files
  • •Set up progress tracking structures for multi-phase implementations

Key Benefits

  • •Token Efficiency: Max ~800 lines per file for optimal AI context loading
  • •Progressive Disclosure: Summary → Detail pattern with linked files
  • •Subagent Integration: Automatic task assignment to appropriate specialists
  • •MP Architecture Compliance: Plans follow layered architecture (routers → services → repositories → DB)
  • •Structured Tracking: One progress file per phase following CLAUDE.md policy

When to Use This Skill

  • •Creating PRDs for new features or enhancements
  • •Generating detailed implementation plans from PRDs
  • •Breaking down long planning documents (>800 lines) into manageable files
  • •Setting up progress tracking for multi-phase work
  • •Optimizing existing plans for better AI agent consumption

Quick Start

Create PRD from Feature Request

bash
# User provides feature description
User: "Create a PRD for advanced filtering on the prompts page"

# Skill generates PRD at:
# docs/project_plans/PRDs/[category]/advanced-filtering-v1.md

Create Implementation Plan from PRD

bash
# Provide PRD path
User: "Create implementation plan for docs/project_plans/PRDs/harden-polish/advanced-filtering-v1.md"

# Skill generates:
# - Main plan: docs/project_plans/implementation_plans/harden-polish/advanced-filtering-v1.md
# - Phase files (if needed): docs/project_plans/implementation_plans/harden-polish/advanced-filtering-v1/phase-[N]-[name].md

Optimize Existing Plan

bash
# Provide existing plan path
User: "Optimize docs/project_plans/implementation_plans/harden-polish/sidebar-polish-v1.md"

# Skill:
# 1. Analyzes plan length (e.g., 1200 lines)
# 2. Breaks into phase-specific files (~400 lines each)
# 3. Updates parent plan with links to phase files

Create Progress Tracking

bash
# Provide PRD or Implementation Plan
User: "Create progress tracking for data-layer-fixes PRD"

# Skill generates:
# .claude/progress/[feature-name]/all-phases-progress.md
# With task breakdown, subagent assignments, completion tracking

Core Workflows

Workflow 1: Create PRD from Feature Request

Input: Feature description or request from user

Process:

  1. •

    Analyze Request

    • •Extract feature name, scope, goals
    • •Identify related systems and components
    • •Determine priority and complexity
  2. •

    Structure PRD

    • •Use template: ./templates/prd-template.md
    • •Follow MP architecture patterns (see ./references/mp-architecture.md)
    • •Include frontmatter with proper metadata
    • •Organize into standard PRD sections
  3. •

    Add Implementation Context

    • •Break into phased approach
    • •Identify architectural layers involved
    • •Note dependencies and risks
    • •Define success criteria and acceptance tests
  4. •

    Determine Location

    • •Category: docs/project_plans/PRDs/[category]/
    • •Categories: harden-polish, features, enhancements, refactors
    • •Naming: [feature-name]-v1.md (kebab-case)
  5. •

    Generate File

    • •Write PRD to determined location
    • •Include YAML frontmatter with metadata
    • •Link to related docs (ADRs, guides, etc.)
    • •Add to project tracking if needed

Output:

  • •PRD file at: docs/project_plans/PRDs/[category]/[feature-name]-v1.md
  • •Follows template structure
  • •Ready for implementation planning

Example:

markdown
Input: "Add real-time collaboration features to prompt editing"

Output Location: docs/project_plans/PRDs/features/realtime-collaboration-v1.md

Sections:
1. Executive Summary - Real-time collaborative editing
2. Context & Background - Current single-user editing limitations
3. Problem Statement - Users can't collaborate on prompts
4. Goals & Success Metrics - Multiple concurrent editors, conflict resolution
5. Requirements - WebSocket connections, operational transforms, presence indicators
6. Implementation Phases - Phase 1: Backend infrastructure, Phase 2: Frontend integration
... (full PRD structure)

Workflow 2: Create Implementation Plan from PRD

Input: Path to existing PRD or newly created PRD

Process:

  1. •

    Analyze PRD

    • •Read full PRD content
    • •Extract key requirements
    • •Identify architectural layers needed
    • •Determine phase breakdown strategy
  2. •

    Plan Phase Structure

    • •Follow MP layered architecture: routers → services → repositories → DB
    • •Group related tasks into phases
    • •Common phases: Database → Repository → Service → API → UI → Testing → Docs → Deployment
    • •Consider parallel work opportunities
    • •Identify critical path
  3. •

    Generate Task Breakdown

    • •Use template: ./templates/implementation-plan-template.md
    • •Create tasks for each phase
    • •Format: Task tables with ID, Name, Description, Acceptance Criteria, Estimate
    • •Include quality gates for each phase
  4. •

    Assign Subagents

    • •Use reference: ./references/subagent-assignments.md
    • •Assign based on task type:
      • •Database: data-layer-expert
      • •Backend API: python-backend-engineer, backend-architect
      • •Frontend: ui-engineer-enhanced, frontend-developer
      • •UI Components: ui-designer, ui-engineer
      • •Testing: appropriate testing agents
      • •Docs: documentation-writer, documentation-complex
    • •Add to each task: "Assigned Subagent(s): agent-1, agent-2"
  5. •

    Optimize for Token Efficiency

    • •If total plan >800 lines: break into phase-specific files
    • •Pattern: [feature-name]-v1/phase-[N]-[name].md
    • •Parent plan links to phase files
    • •Each phase file <800 lines
    • •See ./references/optimization-patterns.md
  6. •

    Generate Files

    • •Main plan: docs/project_plans/implementation_plans/[category]/[feature-name]-v1.md
    • •Phase files (if needed): docs/project_plans/implementation_plans/[category]/[feature-name]-v1/phase-[N]-[name].md
    • •Link phase files from parent plan

Output:

  • •Implementation Plan at determined location
  • •Phase breakdown with subagent assignments
  • •Linked phase files if plan >800 lines
  • •Quality gates and success criteria per phase

Example:

markdown
Input PRD: docs/project_plans/PRDs/features/realtime-collaboration-v1.md

Output:
Main Plan: docs/project_plans/implementation_plans/features/realtime-collaboration-v1.md

Phase Breakdown:
- Phase 1: Database Layer (websocket_sessions, edit_locks tables) - data-layer-expert
- Phase 2: Repository Layer (session management, lock management) - python-backend-engineer
- Phase 3: Service Layer (operational transforms, conflict resolution) - backend-architect
- Phase 4: API Layer (WebSocket endpoints, presence API) - python-backend-engineer
- Phase 5: UI Layer (collaborative editor, presence indicators) - ui-engineer-enhanced, frontend-developer
- Phase 6: Testing (unit, integration, E2E conflict scenarios) - testing agents
- Phase 7: Documentation (API docs, user guides) - documentation-writer
- Phase 8: Deployment (feature flags, monitoring) - DevOps

Phase Files (if plan >800 lines):
- realtime-collaboration-v1/phase-1-database.md
- realtime-collaboration-v1/phase-2-repository.md
- realtime-collaboration-v1/phase-3-5-backend.md (grouped related phases)
- realtime-collaboration-v1/phase-6-8-validation.md (grouped related phases)

Workflow 3: Optimize Existing Plans

Input: Path to existing PRD or Implementation Plan that's >800 lines

Process:

  1. •

    Analyze Plan

    • •Read full plan
    • •Count total lines
    • •Identify natural break points (phases, sections)
    • •Determine optimal split strategy
  2. •

    Determine Breakout Strategy

    • •Primary: Break by phase (most common)
    • •Secondary: Break by domain (backend vs frontend)
    • •Tertiary: Break by task type (implementation vs testing)
    • •Goal: Each file <800 lines, logically cohesive
  3. •

    Create Breakout Files

    • •Pattern: [plan-name]/phase-[N]-[name].md
    • •Alternative: [plan-name]/[domain]-tasks.md
    • •Each file includes:
      • •Phase/section overview
      • •Relevant tasks with subagent assignments
      • •Quality gates for that section
      • •Links back to parent plan
  4. •

    Update Parent Plan

    • •Add table of contents linking to breakout files
    • •Keep executive summary and overview in parent
    • •Replace detailed sections with links:
      markdown
      ## Phase 2: Repository Layer
See [Phase 2 Implementation Details](./[plan-name]/phase-2-repository.md)
    • •Maintain quality gates summary in parent
  5. •

    Validate Optimization

    • •Each file <800 lines ✓
    • •All content preserved ✓
    • •Links work correctly ✓
    • •Logical grouping maintained ✓
    • •Progressive disclosure achieved ✓

Output:

  • •Optimized parent plan (summary + links)
  • •Breakout files for detailed content
  • •Improved token efficiency (95%+ reduction in single-load context)

Example:

markdown
Input: docs/project_plans/implementation_plans/harden-polish/sidebar-polish-v1.md (1200 lines)

Analysis:
- 8 phases, ~150 lines each
- Can group related phases: 1-3 (backend), 4-5 (frontend), 6-8 (validation)

Output:
Parent: sidebar-polish-v1.md (200 lines - summary + links)
Phase Files:
- sidebar-polish-v1/phase-1-3-backend.md (450 lines)
- sidebar-polish-v1/phase-4-5-frontend.md (400 lines)
- sidebar-polish-v1/phase-6-8-validation.md (350 lines)

Token Efficiency:
- Before: Load 1200 lines for any query
- After: Load 200-line summary, then specific phase (450 max) = 67% reduction

Workflow 4: Create Progress Tracking

Input: PRD or Implementation Plan

Process:

  1. •

    Extract Implementation Tasks

    • •Read Implementation Plan (or "Implementation" section of PRD)
    • •Extract all tasks by phase
    • •Capture task IDs, names, descriptions, estimates
  2. •

    Structure Progress File

    • •Use template: ./templates/progress-tracking-template.md
    • •Follow CLAUDE.md policy: ONE file per feature (all phases)
    • •Location: .claude/progress/[feature-name]/all-phases-progress.md
    • •Format: Phase overview table + detailed phase sections
  3. •

    Add Subagent Assignments

    • •Use ./references/subagent-assignments.md
    • •Add to each task based on type
    • •Format: "Assigned Subagent(s): agent-1, agent-2"
    • •Example task types:
      • •Database schema: data-layer-expert
      • •API endpoints: python-backend-engineer, backend-architect
      • •React components: ui-engineer-enhanced, frontend-developer
      • •Testing: testing specialists
      • •Documentation: documentation-writer
  4. •

    Set Up Tracking Structure

    • •Phase Overview table with status/completion
    • •Per-phase sections with:
      • •Completion checklist (tasks as checkboxes)
      • •Subagent assignments
      • •Success criteria
      • •Key files involved
    • •Status tracking: NOT STARTED, IN PROGRESS, BLOCKED, COMPLETE
  5. •

    Link from PRD

    • •Update PRD's "Implementation" section
    • •Add link to progress tracking file
    • •Format: See progress tracking: .claude/progress/[feature-name]/all-phases-progress.md

Output:

  • •Progress tracking file at: .claude/progress/[feature-name]/all-phases-progress.md
  • •Linked from PRD
  • •Tasks organized by phase
  • •Subagent assignments on every task
  • •Ready for implementation tracking

Example:

markdown
Input PRD: docs/project_plans/PRDs/harden-polish/data-layer-fixes-filtering-v1.md

Output: .claude/progress/data-layer-fixes-filtering-v1/all-phases-progress.md

Structure:
# All-Phases Progress: Data Layer Fixes & Filtering

**Status**: NOT STARTED
**Last Updated**: 2025-11-11
**Completion**: 0% (0 of 24 story points)

## Phase Overview
| Phase | Title | Effort | Status | Completion |
|-------|-------|--------|--------|-----------|
| 1 | Repository Layer - Transaction Mgmt | 8 pts | NOT STARTED | 0% |
| 2 | Repository Layer - Filter Queries | 8 pts | NOT STARTED | 0% |
| 3 | Service Layer - Validation & DTOs | 5 pts | NOT STARTED | 0% |
| 4 | Frontend Layer - React Query | 5 pts | NOT STARTED | 0% |

## Phase 1: Repository Layer - Transaction Management
**Assigned Subagent(s)**: data-layer-expert, python-backend-engineer

### Completion Checklist
- [ ] TX-001: Fix BaseRepository Rollback (3 pts)
      Assigned Subagent(s): data-layer-expert
- [ ] TX-002: Update PromptRepository Error Handling (3 pts)
      Assigned Subagent(s): python-backend-engineer
- [ ] TX-003: Add Transaction Telemetry (1 pt)
      Assigned Subagent(s): backend-architect
- [ ] TX-004: Integration Tests (1 pt)
      Assigned Subagent(s): testing-specialist

### Success Criteria
- [ ] All repository exceptions trigger automatic rollback
- [ ] Transaction state correctly reset after errors
...

Templates Reference

prd-template.md

Location: ./templates/prd-template.md

Based On: /docs/docs-v2/templates/PRD-TEMPLATE.md

Purpose: Standard PRD structure for MeatyPrompts features

Key Sections:

  • •Feature Brief & Metadata (name, date, author, related docs)
  • •Executive Summary (1-2 paragraphs)
  • •Context & Background (problem space, current state)
  • •Problem Statement (clear gap or pain point)
  • •Goals & Success Metrics (measurable outcomes)
  • •Requirements (functional and non-functional)
  • •Scope (in-scope vs out-of-scope)
  • •Dependencies & Assumptions
  • •Risks & Mitigations
  • •Target State (post-implementation)
  • •Acceptance Criteria (definition of done)
  • •Implementation (phased breakdown with tasks)

When to Use: Creating any new PRD

implementation-plan-template.md

Location: ./templates/implementation-plan-template.md

Based On: /claude-export/templates/pm/implementation-plan-template.md

Purpose: Detailed phased implementation with task breakdown

Key Sections:

  • •Executive Summary (approach, milestones, success criteria)
  • •Implementation Strategy (architecture sequence, parallel work, critical path)
  • •Phase Breakdown (8 standard phases with task tables)
  • •Risk Mitigation (technical and schedule risks)
  • •Resource Requirements (team composition, skills, infrastructure)
  • •Success Metrics (delivery, business, technical)
  • •Communication Plan (status reporting, escalation)
  • •Post-Implementation Plan (monitoring, maintenance)

When to Use: Creating implementation plan from PRD

progress-tracking-template.md

Location: ./templates/progress-tracking-template.md

Purpose: Track implementation progress across all phases

Key Sections:

  • •Status header (overall status, completion %, last updated)
  • •Phase Overview table (phase, title, effort, status, completion)
  • •Per-phase sections (completion checklist, success criteria, key files)
  • •Subagent assignments per task
  • •Links to PRD and Implementation Plan

When to Use: Setting up progress tracking for multi-phase work

phase-breakdown-template.md

Location: ./templates/phase-breakdown-template.md

Purpose: Template for individual phase files when breaking up long plans

Key Sections:

  • •Phase overview (duration, dependencies, team)
  • •Task breakdown table (ID, name, description, acceptance criteria, estimate, assignee)
  • •Subagent assignments
  • •Quality gates
  • •Key files and integration points
  • •Link back to parent plan

When to Use: Breaking long implementation plans into phase-specific files

Scripts Reference

All scripts are in ./scripts/ directory and use Node.js (NOT Python).

generate-prd.sh

Purpose: Generate PRD from feature request

Usage:

bash
./scripts/generate-prd.sh "Feature description" "category"

Process:

  1. •Parse feature description
  2. •Determine category and filename
  3. •Load PRD template
  4. •Generate PRD content
  5. •Write to docs/project_plans/PRDs/[category]/[feature-name]-v1.md

Output: PRD file path

generate-impl-plan.sh

Purpose: Generate implementation plan from PRD

Usage:

bash
./scripts/generate-impl-plan.sh "path/to/prd.md"

Process:

  1. •Read PRD content
  2. •Extract requirements and phases
  3. •Generate task breakdown
  4. •Add subagent assignments
  5. •Determine if plan needs breakout (>800 lines)
  6. •Write main plan and phase files

Output: Implementation plan file path(s)

optimize-plan.sh

Purpose: Break long plan into phase-specific files

Usage:

bash
./scripts/optimize-plan.sh "path/to/plan.md"

Process:

  1. •Read plan and count lines
  2. •Determine optimal breakout strategy
  3. •Create phase-specific files
  4. •Update parent plan with links
  5. •Validate all content preserved

Output: List of created phase files

assign-subagents.sh

Purpose: Add subagent assignments to tasks in plan

Usage:

bash
./scripts/assign-subagents.sh "path/to/plan.md"

Process:

  1. •Read plan and extract tasks
  2. •Determine task type (database, API, frontend, etc.)
  3. •Map to appropriate subagents using ./references/subagent-assignments.md
  4. •Add assignment note to each task
  5. •Update plan file

Output: Updated plan with subagent assignments

create-progress-tracking.sh

Purpose: Create progress tracking document from plan

Usage:

bash
./scripts/create-progress-tracking.sh "path/to/plan.md"

Process:

  1. •Read implementation plan
  2. •Extract all phases and tasks
  3. •Generate progress tracking structure
  4. •Add subagent assignments
  5. •Write to .claude/progress/[feature-name]/all-phases-progress.md
  6. •Update PRD with link to progress file

Output: Progress tracking file path

References

mp-architecture.md

Location: ./references/mp-architecture.md

Purpose: Summary of MeatyPrompts layered architecture

Content:

  • •Layered architecture: routers → services → repositories → DB
  • •Repositories own all DB I/O and RLS
  • •Services return DTOs only
  • •Routers handle HTTP + validation
  • •ErrorResponse envelope for errors
  • •Cursor pagination for lists: { items, pageInfo }
  • •OpenTelemetry spans and structured logging

Used By: PRD generation, implementation planning

subagent-assignments.md

Location: ./references/subagent-assignments.md

Purpose: Mapping of task types to appropriate subagents

Content:

Task TypeSubagentsNotes
Database Schemadata-layer-expertTables, indexes, RLS policies
Database Migrationsdata-layer-expert, python-backend-engineerAlembic migrations
Repository Layerpython-backend-engineer, data-layer-expertDB I/O, transactions
Service Layerpython-backend-engineer, backend-architectBusiness logic, DTOs
API Endpointspython-backend-engineer, backend-architectFastAPI routers
Frontend Componentsui-engineer-enhanced, frontend-developerReact components
UI Designui-designer, ux-researcherDesign system, wireframes
Testingtesting specialistsUnit, integration, E2E
Documentationdocumentation-writer, documentation-complexBased on complexity
Performancereact-performance-optimizerReact optimization
Accessibilityweb-accessibility-checkerWCAG compliance

Used By: Implementation planning, progress tracking creation

file-structure.md

Location: ./references/file-structure.md

Purpose: Directory structure conventions for plans and progress

Content:

code
docs/project_plans/
├── PRDs/
│   ├── harden-polish/         # Bug fixes, polish
│   ├── features/              # New features
│   ├── enhancements/          # Feature enhancements
│   └── refactors/             # Architecture refactors
│
└── implementation_plans/
    ├── harden-polish/
    │   ├── feature-name-v1.md              # Main plan
    │   └── feature-name-v1/                # Phase breakouts
    │       ├── phase-1-database.md
    │       ├── phase-2-3-backend.md
    │       └── phase-4-5-frontend.md
    ├── features/
    ├── enhancements/
    └── refactors/

.claude/
└── progress/
    └── feature-name/
        └── all-phases-progress.md          # ONE file per feature

Naming Conventions:

  • •PRDs: [feature-name]-v1.md (kebab-case)
  • •Implementation Plans: [feature-name]-v1.md
  • •Phase Files: phase-[N]-[name].md or phase-[N]-[M]-[name].md (grouped)
  • •Progress: all-phases-progress.md (one per feature)

Used By: File creation, optimization

optimization-patterns.md

Location: ./references/optimization-patterns.md

Purpose: Patterns for breaking up long files into token-efficient chunks

Content:

Pattern 1: Break by Phase (Most Common)

  • •Split implementation plan by phase (1-3, 4-5, 6-8)
  • •Each phase file <800 lines
  • •Parent links to phase files
  • •Progressive disclosure: Load summary, then specific phase

Pattern 2: Break by Domain

  • •Backend phases (Database, Repository, Service, API)
  • •Frontend phases (UI, Components, State)
  • •Validation phases (Testing, Docs, Deployment)

Pattern 3: Break by Task Type

  • •Implementation tasks
  • •Testing tasks
  • •Documentation tasks
  • •Deployment tasks

Pattern 4: Keep Together

  • •Always keep in parent plan:
    • •Executive summary
    • •Phase overview table
    • •Risk mitigation summary
    • •Success metrics overview
  • •Move to phase files:
    • •Detailed task breakdowns
    • •Specific acceptance criteria
    • •Technical implementation notes

Token Efficiency Gains:

  • •Before: Load entire 1200-line plan
  • •After: Load 200-line summary + 400-line phase = 50% reduction
  • •For targeted queries: Load only relevant phase = 67%+ reduction

Used By: Plan optimization workflow

Best Practices

File Size Management

Guideline: No file should exceed ~800 lines

Rationale:

  • •Optimal token efficiency for AI context loading
  • •Enables progressive disclosure pattern
  • •Reduces cognitive load for agents
  • •Faster file parsing and analysis

Strategies:

  1. •Break plans by phase when >800 lines
  2. •Group short related phases (1-3, 4-5)
  3. •Keep summaries in parent, details in phase files
  4. •Use links for cross-references

Naming Conventions

PRDs: [feature-name]-v1.md

  • •Use kebab-case (lowercase with hyphens)
  • •Include version number (-v1, -v2)
  • •Descriptive name (e.g., advanced-filtering-v1.md)

Implementation Plans: [feature-name]-v1.md

  • •Match PRD naming
  • •Same category as PRD
  • •Version synchronized with PRD

Phase Files: phase-[N]-[name].md

  • •Sequential numbering (phase-1, phase-2)
  • •Can group: phase-1-3-backend.md
  • •Descriptive name (database, repository, frontend)

Progress Files: all-phases-progress.md

  • •ONE file per feature (all phases together)
  • •Location: .claude/progress/[feature-name]/

Directory Organization

PRDs:

  • •docs/project_plans/PRDs/[category]/
  • •Categories: harden-polish, features, enhancements, refactors

Implementation Plans:

  • •docs/project_plans/implementation_plans/[category]/
  • •Match PRD category
  • •Phase breakouts in subdirectory: [plan-name]/

Progress Tracking:

  • •.claude/progress/[feature-name]/
  • •One directory per feature
  • •Contains: all-phases-progress.md

Subagent Assignment Strategy

Match Task Type to Specialist:

  • •Database work → data-layer-expert
  • •API implementation → python-backend-engineer, backend-architect
  • •React components → ui-engineer-enhanced, frontend-developer
  • •UI design → ui-designer, ux-researcher
  • •Testing → appropriate testing specialists
  • •Documentation → documentation-writer (90%), documentation-complex (10%)

Assignment Format:

markdown
- [ ] TASK-001: Task Name (3 pts)
      Assigned Subagent(s): python-backend-engineer, backend-architect

Multiple Agents:

  • •Primary agent first
  • •Supporting agents after
  • •Consider expertise overlap

Token Efficiency Tips

Progressive Disclosure:

  1. •Summary in parent plan (200 lines)
  2. •Link to detailed phase files (400 lines each)
  3. •Agent loads summary first, then specific phase as needed
  4. •50-67% token reduction

Structured References:

  • •Link to ADRs instead of duplicating architecture info
  • •Reference existing docs rather than repeating
  • •Use relative paths for phase file links

Chunk by Logical Units:

  • •Keep related tasks together
  • •Don't split mid-phase
  • •Group short phases if logical
  • •Maintain quality gates with phases

YAML Frontmatter

PRDs:

yaml
---
title: "Feature Name - PRD"
description: "Brief summary (1-2 sentences)"
audience: [ai-agents, developers]
tags: [relevant, tags, for, search]
created: 2025-11-11
updated: 2025-11-11
category: "product-planning"
status: draft|published
related:
  - /docs/architecture/ADRs/relevant-adr.md
  - /docs/guides/relevant-guide.md
---

Implementation Plans:

yaml
---
title: "Feature Name - Implementation Plan"
description: "Brief summary of implementation approach"
audience: [ai-agents, developers]
tags: [implementation, planning, phases]
created: 2025-11-11
updated: 2025-11-11
category: "product-planning"
status: draft|in-progress|published
related:
  - /docs/project_plans/PRDs/category/feature-name-v1.md
---

Progress Tracking: No frontmatter required for .claude/progress/ files (per CLAUDE.md)

Examples

Example 1: Create PRD for Advanced Filtering

Input:

code
User: "Create a PRD for adding advanced filtering to the prompts page. Users need to filter by multiple criteria: model, provider, date range, tags, and favorites."

Process:

  1. •Extract feature name: "Advanced Filtering"
  2. •Determine category: "features"
  3. •Generate PRD using template
  4. •Structure sections:
    • •Problem: Users can only filter by single criteria
    • •Goals: Multi-criteria filtering, saved filter sets
    • •Requirements: UI for filter builder, backend filter query support
    • •Phases: Phase 1 (Backend), Phase 2 (Frontend), Phase 3 (Saved Filters)

Output:

code
File: docs/project_plans/PRDs/features/advanced-filtering-v1.md

# Advanced Filtering - PRD

**Feature Name**: Advanced Filtering
**Date**: 2025-11-11
**Author**: Claude (Sonnet 4.5)
**Related**: Filtering guides, search ADRs

## 1. Executive Summary
Enable users to filter prompts by multiple criteria simultaneously (model, provider, date range, tags, favorites) with the ability to save and reuse filter sets.

## 2. Context & Background
Current filtering supports single criteria only. Users frequently need to filter by combinations (e.g., "OpenAI models from last week tagged 'production'").

... (full PRD structure)

Example 2: Create Implementation Plan with Phase Breakout

Input:

code
User: "Create implementation plan for docs/project_plans/PRDs/features/advanced-filtering-v1.md"

Process:

  1. •Read PRD, extract requirements
  2. •Plan 7 phases following MP architecture
  3. •Generate task breakdown with estimates
  4. •Assign subagents to each task
  5. •Calculate total: 1100 lines → needs breakout
  6. •Create phase files:
    • •phase-1-3-backend.md (500 lines)
    • •phase-4-5-frontend.md (400 lines)
    • •phase-6-7-validation.md (300 lines)
  7. •Update parent plan with links (200 lines)

Output:

code
Main Plan: docs/project_plans/implementation_plans/features/advanced-filtering-v1.md (200 lines)

# Implementation Plan: Advanced Filtering

## Phase Overview
| Phase | Title | Effort | Files |
|-------|-------|--------|-------|
| 1-3 | Backend Implementation | 18 pts | [Details](./advanced-filtering-v1/phase-1-3-backend.md) |
| 4-5 | Frontend Implementation | 12 pts | [Details](./advanced-filtering-v1/phase-4-5-frontend.md) |
| 6-7 | Validation & Deployment | 8 pts | [Details](./advanced-filtering-v1/phase-6-7-validation.md) |

... (executive summary, strategy)

---

Phase Files Created:
- advanced-filtering-v1/phase-1-3-backend.md (500 lines)
  - Phase 1: Database (filter_sets table, indexes)
  - Phase 2: Repository (query builder, filter sets repo)
  - Phase 3: Service (filter validation, DTO mapping)

- advanced-filtering-v1/phase-4-5-frontend.md (400 lines)
  - Phase 4: API (filter endpoints, saved sets API)
  - Phase 5: UI (filter builder component, saved sets UI)

- advanced-filtering-v1/phase-6-7-validation.md (300 lines)
  - Phase 6: Testing (unit, integration, E2E)
  - Phase 7: Deployment (feature flags, monitoring)

Example 3: Optimize Existing Long Plan

Input:

code
User: "Optimize docs/project_plans/implementation_plans/harden-polish/sidebar-polish-v1.md - it's 1200 lines"

Process:

  1. •Read plan: 8 phases, ~150 lines each
  2. •Determine breakout: Group 1-3 (backend), 4-5 (frontend), 6-8 (validation)
  3. •Create phase files:
    • •phase-1-3-backend.md (450 lines)
    • •phase-4-5-frontend.md (400 lines)
    • •phase-6-8-validation.md (350 lines)
  4. •Update parent plan: Keep summary, add links to phase files (200 lines)

Output:

code
Updated: docs/project_plans/implementation_plans/harden-polish/sidebar-polish-v1.md (200 lines)

Created Phase Files:
- sidebar-polish-v1/phase-1-3-backend.md (450 lines)
  Phase 1: Database - Sidebar state, user preferences
  Phase 2: Repository - State management, RLS
  Phase 3: Service - Preference sync, DTOs

- sidebar-polish-v1/phase-4-5-frontend.md (400 lines)
  Phase 4: API - Endpoints for sidebar state
  Phase 5: UI - Sidebar component, animations

- sidebar-polish-v1/phase-6-8-validation.md (350 lines)
  Phase 6: Testing - Unit, integration, visual
  Phase 7: Documentation - Component docs, API docs
  Phase 8: Deployment - Feature flags, rollout

Token Efficiency: 67% reduction for targeted queries

Example 4: Create Progress Tracking

Input:

code
User: "Create progress tracking for data-layer-fixes-filtering PRD"

Process:

  1. •Read PRD: docs/project_plans/PRDs/harden-polish/data-layer-fixes-filtering-v1.md
  2. •Extract "Implementation" section tasks
  3. •Organize by 5 phases
  4. •Assign subagents:
    • •Phase 1 (Transaction Mgmt): data-layer-expert, python-backend-engineer
    • •Phase 2 (Filter Queries): python-backend-engineer
    • •Phase 3 (Service Layer): backend-architect, python-backend-engineer
    • •Phase 4 (Frontend): ui-engineer-enhanced, frontend-developer
    • •Phase 5 (Testing): testing specialists
  5. •Create progress file with checkboxes and success criteria
  6. •Update PRD with link to progress file

Output:

code
Created: .claude/progress/data-layer-fixes-filtering-v1/all-phases-progress.md

Updated PRD Section:
## Implementation

See progress tracking: `.claude/progress/data-layer-fixes-filtering-v1/all-phases-progress.md`

Progress File Structure:
# All-Phases Progress: Data Layer Fixes & Filtering

**Status**: NOT STARTED
**Last Updated**: 2025-11-11
**Completion**: 0% (0 of 24 story points)

## Phase Overview
| Phase | Title | Effort | Status | Completion |
| 1 | Repository - Transaction Mgmt | 8 pts | NOT STARTED | 0% |
| 2 | Repository - Filter Queries | 8 pts | NOT STARTED | 0% |
...

## Phase 1: Repository Layer - Transaction Management
**Assigned Subagent(s)**: data-layer-expert, python-backend-engineer

### Completion Checklist
- [ ] TX-001: Fix BaseRepository Rollback (3 pts)
      Assigned Subagent(s): data-layer-expert
- [ ] TX-002: Update PromptRepository Error Handling (3 pts)
      Assigned Subagent(s): python-backend-engineer
...

### Success Criteria
- [ ] All repository exceptions trigger automatic rollback
- [ ] Transaction state correctly reset after errors
...

Integration with MeatyPrompts

Architecture Compliance

All plans follow MP layered architecture:

  • •Routers → Services → Repositories → DB
  • •Services return DTOs only
  • •Repositories own all DB I/O and RLS
  • •Cursor pagination for lists: { items, pageInfo }
  • •ErrorResponse envelope for errors
  • •OpenTelemetry spans and structured logging

Subagent Ecosystem

Plans integrate with 50+ MeatyPrompts subagents:

Architecture: lead-architect, backend-architect, data-layer-expert Development: python-backend-engineer, frontend-developer, ui-engineer-enhanced UI/UX: ui-designer, ux-researcher Review: code-reviewer, task-completion-validator Documentation: documentation-writer, documentation-complex Testing: testing specialists Performance: react-performance-optimizer, web-accessibility-checker

Documentation Policy

Follows CLAUDE.md documentation policy:

  • •PRDs are product-planning docs (allowed)
  • •Implementation Plans are product-planning docs (allowed)
  • •Progress Tracking follows structured format (.claude/progress/)
  • •One progress file per feature (all phases)
  • •Frontmatter required for /docs/, not for .claude/

File Organization

PRDs: /docs/project_plans/PRDs/[category]/[feature-name]-v1.md Plans: /docs/project_plans/implementation_plans/[category]/[feature-name]-v1.md Progress: .claude/progress/[feature-name]/all-phases-progress.md Phase Files: [plan-name]/phase-[N]-[name].md

Advanced Usage

Customizing Templates

Edit templates in ./templates/ to match project needs:

  1. •

    PRD Template Customization:

    • •Add project-specific sections
    • •Adjust success metrics format
    • •Include standard acceptance criteria
  2. •

    Implementation Plan Template Customization:

    • •Add/remove phases
    • •Adjust quality gates
    • •Customize risk categories
  3. •

    Progress Tracking Template Customization:

    • •Add project-specific status values
    • •Adjust completion tracking format
    • •Include team-specific metadata

Multi-PRD Planning

For complex initiatives spanning multiple PRDs:

  1. •Create parent epic document
  2. •Generate individual PRDs for each component
  3. •Link PRDs to parent epic
  4. •Create unified progress tracking across PRDs

Spike Integration

For research-heavy features:

  1. •Create SPIKE document first (using spike-writer agent)
  2. •Use SPIKE to inform PRD generation
  3. •Reference SPIKE in PRD "Context & Background"
  4. •Link SPIKE from Implementation Plan

Continuous Optimization

Regularly optimize plans as work progresses:

  1. •Update progress tracking with actual completion
  2. •Adjust estimates based on learnings
  3. •Break out new sections if plan grows >800 lines
  4. •Archive completed phases

Troubleshooting

PRD Generation Issues

Problem: PRD missing key sections

Solution:

  • •Check template is complete: ./templates/prd-template.md
  • •Verify feature description is detailed enough
  • •Review example PRDs: /docs/project_plans/PRDs/

Implementation Plan Too Long

Problem: Generated plan exceeds 800 lines

Solution:

  • •Automatically triggers phase breakout
  • •Creates phase-specific files
  • •Updates parent with links
  • •If still too long: Group fewer phases per file

Subagent Assignment Unclear

Problem: Not sure which subagent to assign to task

Solution:

  • •Check ./references/subagent-assignments.md
  • •Look for similar tasks in existing progress files
  • •Default patterns:
    • •Database → data-layer-expert
    • •Backend → python-backend-engineer
    • •Frontend → ui-engineer-enhanced
    • •Docs → documentation-writer

File Organization Confusion

Problem: Not sure where to place generated files

Solution:

  • •Check ./references/file-structure.md
  • •PRDs: /docs/project_plans/PRDs/[category]/
  • •Plans: /docs/project_plans/implementation_plans/[category]/
  • •Progress: .claude/progress/[feature-name]/
  • •Phase files: Subdirectory of plan: [plan-name]/

Progress Tracking Not Updating

Problem: Progress file created but not linked from PRD

Solution:

  • •Manually add link to PRD's "Implementation" section
  • •Format: See progress tracking: .claude/progress/[feature-name]/all-phases-progress.md
  • •Ensure progress file exists at expected location

Related Skills

  • •skill-builder: Create new custom skills
  • •symbols: Token-efficient codebase indexing
  • •codebase-explorer: Fast pattern discovery
  • •explore: Deep codebase analysis

Related Agents

  • •lead-pm: SDLC orchestration
  • •prd-writer: PRD creation
  • •implementation-planner: Detailed implementation planning
  • •task-decomposition-expert: Task breakdown
  • •lead-architect: Architecture planning assistance
  • •documentation-writer: Documentation for plans

Version History

  • •2025-11-11: Initial skill creation
    • •4 core workflows (PRD, Plan, Optimize, Progress)
    • •4 templates (PRD, Plan, Progress, Phase)
    • •5 scripts (generate-prd, generate-impl-plan, optimize-plan, assign-subagents, create-progress-tracking)
    • •4 references (architecture, subagents, file-structure, optimization-patterns)