parallel-plan

SCOPE LIMITATION - READ FIRST

THIS SKILL ONLY CREATES PLANNING ARTIFACTS. IT NEVER IMPLEMENTS.

• DO NOT execute any implementation tasks
• DO NOT modify application code
• DO NOT run the implement-plan skill
• DO NOT proceed beyond creating planning artifacts

Outputs:

• ${PLANS_DIR}/[feature-name]/analysis-context.md
• ${PLANS_DIR}/[feature-name]/analysis-code.md
• ${PLANS_DIR}/[feature-name]/analysis-tasks.md
• ${PLANS_DIR}/[feature-name]/parallel-plan.md

After creating planning artifacts and displaying the summary, STOP COMPLETELY.

---

Parallel Implementation Plan Creator

Create parallel-plan.md by orchestrating parallel analysis agents, synthesizing implementation tasks, and validating plan quality.

Workflow Integration

shared-context (step 1) -> parallel-plan (this skill) -> implement-plan (step 3)

This skill requires ${feature_dir}/shared.md and ends after producing analysis artifacts and parallel-plan.md.

BOUNDARY: This skill ENDS after creating parallel-plan.md. The user manually runs /implement-plan when ready.

If shared.md doesn't exist, run /shared-context [feature-name] first.

Arguments

Target: $ARGUMENTS

Parse arguments:

• feature-name: The name of the feature to plan (matches directory name in ${PLANS_DIR})
• --dry-run: Show what would be created without making changes

If no feature name provided, abort with usage instructions.

---

Phase 0: Prerequisites and Dry Run Check

Step 1: Resolve Plans Directory

Use the shared resolver to determine the correct plans directory:

source ${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/resolve-plans-dir.sh
feature_dir="$(get_feature_plan_dir "[feature-name]")"

Step 2: Validate Prerequisites

Extract the feature name from $ARGUMENTS (first non-flag argument).

Run the prerequisites check script:

${CLAUDE_PLUGIN_ROOT}/skills/parallel-plan/scripts/check-prerequisites.sh [feature-name]

If the script exits with error:

• Display the error message
• Instruct user to run /shared-context first to create the shared context document
• STOP HERE - do not proceed

Step 3: Verify Planning Documents

Confirm these files exist in ${feature_dir}/:

• shared.md (required)
• requirements.md (optional but helpful)

Step 4: Handle Dry Run

If --dry-run is present in $ARGUMENTS:

Display:

# Dry Run: Parallel Plan for [feature-name]

## Analysis Agents That Would Run (Phase 1)

1. Context Synthesizer - Condense planning documentation
2. Code Analyzer - Extract code patterns from relevant files
3. Task Structure Agent - Suggest task breakdown and phases

## Files That Would Be Created

- ${PLANS_DIR}/[feature-name]/analysis-context.md (by Context Synthesizer)
- ${PLANS_DIR}/[feature-name]/analysis-code.md (by Code Analyzer)
- ${PLANS_DIR}/[feature-name]/analysis-tasks.md (by Task Structure Agent)
- ${PLANS_DIR}/[feature-name]/parallel-plan.md (final plan)

## Validation Agents That Would Run (Phase 5)

1. File Path Validator - Verify all paths exist
2. Dependency Validator - Check dependency graph
3. Task Completeness Validator - Ensure tasks are actionable

## Execution Model

- Deploy analysis agents in parallel
- Persist analysis artifacts
- Generate plan from condensed analysis
- Validate with parallel validation agents
- Fix issues and finalize

## Next Steps

Remove --dry-run flag to create the plan.

STOP HERE - do not write files or deploy agents.

---

Phase 1: Agent-Based Context Analysis

Step 5: Read Analysis Prompt Templates

Read the analysis prompt templates:

cat ${CLAUDE_PLUGIN_ROOT}/skills/parallel-plan/templates/analysis-prompts.md

This provides prompts for 3 parallel analysis agents that will condense planning context.

Step 6: Deploy Analysis Agents

CRITICAL: Deploy all 3 agents in a SINGLE message with MULTIPLE Task tool calls.

Each agent MUST write its findings to the specified output file. The orchestrator MUST verify file persistence after agents complete.

Agent	Subagent Type	Focus	Output File
Context Synthesizer	codebase-research-analyst	Condense planning docs	analysis-context.md
Code Analyzer	codebase-research-analyst	Extract code patterns	analysis-code.md
Task Structure Agent	codebase-research-analyst	Suggest task breakdown	analysis-tasks.md

Use the prompts from analysis-prompts.md with variables substituted:

• {{FEATURE_NAME}} - The feature directory name
• {{FEATURE_DIR}} - Full output directory path (${feature_dir}, resolved in Step 1)

Each agent will:

• Read relevant source files (planning docs, code files, codebase structure)
• Extract actionable insights
• Write condensed analysis to ${feature_dir}/[output-file]

Why use agents: This prevents loading 50-100K+ tokens of raw files into main context. Agents read everything and return 5-10K tokens of condensed, actionable analysis.

---

Phase 2: Validate and Persist Analysis Artifacts

Step 7: Validate Analysis Artifacts

After agents complete, validate all analysis files:

${CLAUDE_PLUGIN_ROOT}/skills/parallel-plan/scripts/validate-analysis-artifacts.sh "${feature_dir}"

If validation passes, proceed to Step 9. If validation fails, proceed to Step 8.

Step 8: Re-deploy Failed Agents (only if Step 7 failed)

For each missing or invalid file reported by the validation script:

1. Re-deploy ONLY the failed agents with their original prompts
2. Wait for corrected outputs
3. Re-run validation:

${CLAUDE_PLUGIN_ROOT}/skills/parallel-plan/scripts/validate-analysis-artifacts.sh "${feature_dir}"

Repeat until validation passes. If agents repeatedly fail, stop and report what is missing.

Step 9: Pre-Generation Gate (MANDATORY — cannot be skipped)

Run the pre-generation gate script:

${CLAUDE_PLUGIN_ROOT}/skills/parallel-plan/scripts/persist-or-fail.sh "${feature_dir}"

• Exit 0 → proceed to Phase 3

• Exit 1 → the script prints MISSING_FILES and ACTION_REQUIRED. Re-deploy the failed agents, then re-run this gate until it passes (exit 0)

• Do not attempt to generate parallel-plan.md if Step 7 or Step 8 have not passed.

Do NOT proceed to plan generation until persist-or-fail.sh exits 0.

---

Phase 3: Read Analysis

Step 10: Read Condensed Analysis Files

After verifying all files exist, read only the condensed analysis outputs:

1. ${feature_dir}/analysis-context.md - Planning context synthesis
2. ${feature_dir}/analysis-code.md - Code pattern analysis
3. ${feature_dir}/analysis-tasks.md - Task structure suggestions

These files contain 60-80% compressed insights versus reading all source files directly.

---

Phase 4: Plan Generation

Step 11: Create Task List

Using TodoWrite, create a comprehensive task list with:

• Each major task from the plan
• Task dependencies tracked
• In_progress status for current work

Step 12: Generate Implementation Plan

Read the plan template structure:

cat ${CLAUDE_PLUGIN_ROOT}/skills/parallel-plan/templates/plan-structure.md

Create ${feature_dir}/parallel-plan.md following the template exactly:

Required Sections

Title & Overview

• Feature name as title
• 3-4 sentence information-dense breakdown
• Explain what needs to be done and why

Critically Relevant Files and Documentation

## Critically Relevant Files and Documentation

- /path/to/file: Brief description of relevance
- /path/to/doc: When to reference this

Implementation Plan

## Implementation Plan

### Phase 1: [Phase Name]

#### Task 1.1: [Task Title] Depends on [none]

**READ THESE BEFORE TASK**

- /file/path
- /doc/path

**Instructions**

Files to Create

- /file/path

Files to Modify

- /file/path

[Concise instructions on implementation]

Advice Section

## Advice

- Insight that emerged from seeing the full picture
- Cross-cutting concerns and gotchas
- Specific warnings about code dependencies

Step 13: Task Breakdown Guidelines

For each task ensure:

Task Granularity

• Completable in single focused session
• Modifies 1-3 files maximum
• Clear, actionable instructions

Dependencies

• Use Depends on [none] for independent tasks (maximize parallelism)
• Use Depends on [1.1, 2.3] for tasks requiring prior work
• Avoid long dependency chains (prefer wide over deep)
• Each phase should have at least one independent task

File References

• Use relative paths from project root
• Include line numbers for specific code references
• Group related files together
• Link to documentation files for context

---

Phase 5: Validation (Parallel Agents)

Step 14: Deploy Validation Agents

Read the validation prompts:

cat ${CLAUDE_PLUGIN_ROOT}/skills/parallel-plan/templates/validation-prompts.md

CRITICAL: Deploy all 3 agents in a SINGLE message with MULTIPLE Task tool calls.

Agent	Subagent Type	Focus
File Path Validator	explore	Verify all referenced files exist
Dependency Validator	explore	Check for circular/invalid dependencies
Task Completeness Validator	codebase-research-analyst	Ensure tasks are actionable

Use the prompts from validation-prompts.md with the feature name substituted.

Step 15: Review Validation Results

After agents complete:

• Review findings from each validator
• Fix any issues identified:
  • Correct invalid file paths
  • Resolve circular dependencies
  • Add missing details to incomplete tasks
• Re-run validation if significant changes made

---

Phase 6: Output & Summary

Step 16: Validate Plan Structure

Run the validation script:

${CLAUDE_PLUGIN_ROOT}/skills/parallel-plan/scripts/validate-parallel-plan.sh "${feature_dir}/parallel-plan.md"

Report any structural issues found.

Step 17: Display Summary

Provide completion summary:

# Parallel Plan Created

## Location

${feature_dir}/parallel-plan.md

## Analysis Files Generated

- ${feature_dir}/analysis-context.md (Planning context synthesis)
- ${feature_dir}/analysis-code.md (Code pattern analysis)
- ${feature_dir}/analysis-tasks.md (Task structure suggestions)

## Plan Overview

- **Total Phases**: [count]
- **Total Tasks**: [count]
- **Independent Tasks**: [count that can run in parallel]
- **Max Dependency Depth**: [deepest chain]

## Task Breakdown by Phase

Phase 1: [count] tasks ([X] independent)
Phase 2: [count] tasks ([X] independent)
...

## Validation Results

- File Path Validation: [summary]
- Dependency Graph: [summary]
- Task Completeness: [summary]

## Context Efficiency

- Analysis agents condensed context from ~50-100K tokens to ~5-10K tokens
- Main context preserved for plan generation and validation

## Next Steps (FOR USER - NOT FOR THIS SKILL)

**THIS SKILL IS NOW COMPLETE. DO NOT PROCEED.**

The user can manually run the implementation when ready:

/implement-plan [feature-name]

Review steps for user:

1. Review the plan: ${feature_dir}/parallel-plan.md
2. Review analysis files for detailed insights (optional)
3. Refine tasks if needed

---

STOP: Do not execute implement-plan. Do not write any more files. Do not modify any code. This skill is complete.

---

Quality Standards

Task Quality Checklist

Each task must have:

• Clear, descriptive title
• Explicit dependencies listed
• "READ THESE BEFORE TASK" section with relevant files
• Files to Create list (if any)
• Files to Modify list
• Concise, actionable instructions
• Gotchas and warnings documented

Plan Quality Checklist

The overall plan must have:

• Information-dense overview (3-4 sentences)
• Complete list of critically relevant files
• Tasks organized into logical phases
• At least one independent task per phase
• Advice section with implementation insights
• No circular dependencies
• All file paths verified

---

CRITICAL CONSTRAINTS

• PLANNING ONLY - This skill creates documentation, never implementation
• NO CODE CHANGES - Do not modify any application source files
• NO IMPLEMENTATION - Do not execute tasks from the plan you create
• STOP AFTER SUMMARY - After displaying the completion summary, stop completely
• DO NOT CHAIN - Do not automatically proceed to implement-plan
• PERSIST ARTIFACTS - All 3 analysis files must exist before plan generation

Output Contract

All files are written to ${feature_dir}/ (resolved via resolve-plans-dir.sh).

File	Producer	Required Before
analysis-context.md	Context Synthesizer agent	parallel-plan.md generation
analysis-code.md	Code Analyzer agent	parallel-plan.md generation
analysis-tasks.md	Task Structure Agent	parallel-plan.md generation
parallel-plan.md	Orchestrator (this skill)	Skill completion

Contract Rules:

1. Each agent MUST write its own output file using the Write tool
2. The orchestrator MUST run validate-analysis-artifacts.sh after agents complete (Step 7)
3. If validation fails, the orchestrator MUST re-deploy ONLY the failed agents with their original prompts (Step 8)
4. The orchestrator MUST run persist-or-fail.sh as a mandatory pre-generation gate (Step 9)
5. No file may be skipped or deferred — persist-or-fail.sh must exit 0 before plan generation

Monorepo Support

Always resolve plans via resolve-plans-dir.sh.

Default:

• Plans at repo-root docs/plans/

Optional local scope via .plans-config:

plans_dir: docs/plans
scope: local

Important Notes

• You are the planner - break down the feature systematically
• Use agents for context gathering - deploy analysis agents to condense large amounts of information
• Validate with script - run validate-analysis-artifacts.sh after agents complete
• Re-deploy on failure - if validation fails, re-deploy only the failed agents
• Preserve main context - read condensed analysis files (~5-10K tokens) instead of raw source files (~50-100K+ tokens)
• Maximize parallelism - prefer independent tasks over sequential chains
• Be specific - include exact file paths and clear instructions
• Validate thoroughly - use all three validation agents
• Quality over speed - a well-structured plan saves time during implementation
• Monorepo aware - automatically resolves correct plans directory