tomevault-io 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
Step 0: Initialize Progress Tracking
Create TaskCreate entry for planning phase (TaskCreate analyzing - marks /00_plan start).
Step 1: Explore Codebase via planning-team
Create planning-team for comprehensive discovery. Team lead operates in delegate mode.
Spawn Pattern:
Spawn teammate "codebase-explorer" with prompt:
"You are an explorer (see @.claude/agents/explorer.md).
Explore codebase for [domain] related to [task].
Find: files, patterns, config, tests. Share findings via Message.
Output: File list with descriptions."
Spawn teammate "docs-researcher" with prompt:
"You are a researcher (see @.claude/agents/researcher.md).
Research external docs for [task].
Find: official docs, best practices, security. Share findings via Message.
Output: Research summary with links."
Coordination: Teammates share findings via direct messaging, team lead synthesizes results for plan creation.
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):
| Anti-Pattern | Example | Remedy |
|---|---|---|
| Vague language | "I think", "probably" | Use "Verified" OR "Cannot Verify" |
| Uncited claims | "Tests will pass" (no run) | Run command, cite output |
| Assumption as fact | "File exists" (not checked) | Verify with Read/Glob, cite result |
| Missing verification | "Pattern found" (no grep) | Execute verification, show output |
| Skipped exploration | "Didn't check X but confident" | Mark "Cannot Verify", create artifact |
| Implicit unknowns | Proceed without stating gaps | Enumerate unknowns explicitly |
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/agent-teams/SKILL.md - Agent Teams coordination patterns | @.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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.