SKILL: Spec-Driven Workflow (Planning)

Purpose: Analyze codebase and create SPEC-First execution plan through dialogue (read-only phase) Target: Planner Agent executing /00_plan command

Quick Start

When to Use This Skill

• Create new implementation plan
• Explore codebase for task requirements
• Gather user requirements through dialogue

Quick Reference

# Invoked by: /00_plan "task description"
# Output: Complete plan in .pilot/plan/draft/ + user decision

Core Philosophy

Read-Only: NO code modifications, only exploration/analysis/planning | SPEC-First: Requirements before implementation | Efficient Dialogue: Ask user only for business/intent; handle technical details autonomously or via GPT

What This Skill Covers

In Scope: Codebase exploration (parallel agents), requirement gathering, SPEC-First plan (PRP framework), decision tracking, dialogue with question filtering Out of Scope: Implementation → execute-plan/SKILL.md | Confirmation → confirm-plan/SKILL.md

EXECUTION DIRECTIVE

DIALOGUE PHASE - NOT EXECUTION: ASK only when necessary (filter first) | WAIT for response | NEVER auto-execute /01_confirm or /02_execute | Selection ≠ Execution (user chooses approach → continue planning, NOT implement)

Question Filtering (CRITICAL)

Self-Decide (do NOT ask): Technical details (file naming, folder structure), obvious patterns, standard practices, minor trade-offs Consult GPT First: Architecture decisions, security, complex trade-offs (use gpt-delegation skill → "read-only" mode) MUST Consult GPT: Architecture keywords OR confidence < 0.5 → MUST consult before AskUserQuestion (REFERENCE.md, gpt-delegation/SKILL.md) Ask User ONLY: Business requirements, direction choices (2+ genuinely different outcomes), scope clarification, user intent ambiguity

Execution Steps

⛔ MAIN ORCHESTRATOR RESTRICTIONS

FORBIDDEN: Direct codebase exploration (use explorer/researcher agents via Task tool), direct gate resolution without delegation MANDATORY: Step 1 exploration (parallel agents), Step 1.9/1.10 gap investigation (agents before user), GPT via gpt-delegation EXCEPTIONS: Keyword detection, pattern matching, draft file creation, question filtering WHY: Subagent isolation = 50-80% context savings (CLAUDE.md:58-59)

Step 0: Initialize Progress Tracking

Create TaskCreate entry for planning phase (TaskCreate analyzing - marks /00_plan start).

Step 1: Explore Codebase

Launch explorer + researcher in parallel for comprehensive discovery.

Step 1.5: Scope Clarity Check

Triggers: Completeness keywords, reference-based requests, ambiguous scope, multi-layer arch. Action: Ask user to select scope. Details: REFERENCE.md

Step 1.6: Design Direction Check

Triggers: landing, marketing, redesign, beautiful, modern, premium, hero, pricing. Action: Ask aesthetic direction or use defaults. Details: REFERENCE.md

Step 1.8: External Context Detection

Triggers: "Like X", external links, "Use API/library", refactor refs. Action: Capture context, create Context Pack. Details: REFERENCE.md

Step 1.8.5: Context Manifest

Generate Manifest with Collected/Related/Missing Context tables. Details: REFERENCE.md

Step 1.9: Absolute Certainty Gate

Checklist: Codebase understanding, Dependencies, Impact, Test strategy, Edge cases, Rollback. Loop: Max 30min. Blocking: Escalate to user. Details: REFERENCE.md

Step 1.10: Readiness Gate

Checklist: Unknowns Enumerated, Assumptions Verified, Dependencies Clear, Criteria Measurable, Verification Plan, Rollback Plan. Loop: Max 3 retries. Blocking: Incomplete after MAX_RETRIES. Details: REFERENCE.md

Step 2: Gather Requirements

Create User Requirements table (ID, Timestamp, User Input Original, Summary).

Step 3: Create SPEC-First Plan

PRP: What (Functionality), Why (Context), How (Approach), Success Criteria. Approach Selection: One clear → present directly; multiple → ask user; technical → consult GPT.

Step 3.5: Mandatory Oracle Consultation

GPT at 3 points: start (Analyst), mid (Architect), end (Reviewer). Fallback: WebSearch/Context7. Details: REFERENCE.md

Step 4: Final User Decision

NEVER auto-proceed to /01_confirm or /02_execute. Ask user: A) Continue editing, B) Explore different, C) Run /01_confirm, D) Run /02_execute

Core Concepts

Context Pack

Goal, Inputs (Embedded), Derived Requirements, Assumptions & Unknowns, Traceability Map. Details: REFERENCE.md

Decision Tracking

Draft file: User Requirements table, Decisions Log, Success Criteria with checkboxes. Details: REFERENCE.md

Atomic SC Principle

"One SC = One File OR One Concern" - enables parallel execution, clear ownership. Details: REFERENCE.md

Selection vs Execution

When user says "Go with B": ✅ Continue planning (refine plan) | ❌ Start implementing. Implementation: Only when user runs /01_confirm → /02_execute. Details: REFERENCE.md

Operational Certainty

Binary: Verified (with evidence) OR Cannot Verify (with artifact). Evidence: Code ref (file+lines), Test output (cmd+results), GPT log (ID+summary), User confirm (timestamp+response). Cannot Verify: Create artifact (what, why, needs) + notify user. Details: REFERENCE.md

False Certainty Anti-Patterns

BLOCKED Phrases (never declare certainty with):

Enforcement: Certainty Gate (Step 1.9) blocks if any anti-pattern detected. Details: REFERENCE.md

PROHIBITED Actions

Edit tool: FORBIDDEN | Write tool: ONLY .pilot/plan/draft/*.md | Plan files: No creation without approval | Auto-execute: No /01_confirm or /02_execute | Implementation: Not after user selects approach | Natural language: Never triggers phase transition EXPLICIT COMMAND REQUIRED: User must type /01_confirm or /02_execute to move phases.

Further Reading

Internal: @.claude/skills/spec-driven-workflow/REFERENCE.md - Advanced planning patterns, detailed step implementation, context pack formats, decision tracking examples | @.claude/skills/parallel-subagents/SKILL.md - Parallel agent execution | @.claude/skills/gpt-delegation/SKILL.md - GPT consultation | @.claude/skills/confirm-plan/SKILL.md - Plan confirmation | @.claude/skills/execute-plan/SKILL.md - Plan execution

External: SPEC-First Development | PRP Framework

⚠️ CRITICAL: /00_plan is read-only - NO code modifications. Filter questions: Self-decide technical details, consult GPT for complex trade-offs, ask user only for business/intent. Selection ≠ Execution: When user chooses approach → continue planning, NOT implement. Implementation starts ONLY when user explicitly runs /01_confirm → /02_execute.

Version: claude-pilot 4.4.40