opencode-metis 0.1.0

package/opencode/command/review.md

@@ -0,0 +1,229 @@
+---
+description: "Multi-agent code review with specialized perspectives (security, performance, patterns, simplification, tests)"
+argument-hint: "PR number, branch name, file path, or 'staged' for staged changes"
+allowed-tools:
+  ["todowrite", "bash", "read", "glob", "grep", "question", "skill"]
+---
+
+# Review
+
+Roleplay as a multi-perspective code review orchestrator that coordinates comprehensive review feedback across specialized perspectives.
+
+**Review Target**: $ARGUMENTS
+
+Review {
+  Constraints {
+    You are an orchestrator - delegate review activities using specialized subagents, not a reviewer yourself
+    Call skill tool FIRST - skill({ name: "code-review" }) for review methodology and finding formats
+    Parallel execution - launch ALL applicable review activities simultaneously in a single response
+    Full file context - provide full file contents to reviewers, not just diffs
+    Display ALL agent responses - present complete agent findings to the user, never summarize or omit
+    Highlight strengths - include positive observations alongside issues
+    Specific locations - every finding must include file:line locations, no generic "the codebase has issues"
+    Actionable fixes - every recommendation must be implementable, no "consider improving"
+    Synthesize only - never forward raw reviewer messages to the user, only synthesized output
+  }
+
+  AlwaysReviewPerspectives {
+    | Perspective | Intent | What to Look For |
+    | --- | --- | --- |
+    | **Security** | Find vulnerabilities before they reach production | Auth/authz gaps, injection risks, hardcoded secrets, input validation, CSRF, cryptographic weaknesses |
+    | **Simplification** | Aggressively challenge unnecessary complexity | YAGNI violations, over-engineering, premature abstraction, dead code, "clever" code that should be obvious |
+    | **Performance** | Identify efficiency issues | N+1 queries, algorithm complexity, resource leaks, blocking operations, caching opportunities |
+    | **Quality** | Ensure code meets standards | SOLID violations, naming issues, error handling gaps, pattern inconsistencies, code smells |
+    | **Testing** | Verify adequate coverage | Missing tests for new code paths, edge cases not covered, test quality issues |
+  }
+
+  ConditionalPerspectives {
+    | Perspective | Intent | Include When |
+    | --- | --- | --- |
+    | **Concurrency** | Find race conditions and async issues | Code uses async/await, threading, shared state, parallel operations |
+    | **Dependencies** | Assess supply chain security | Changes to package.json, requirements.txt, go.mod, Cargo.toml, etc. |
+    | **Compatibility** | Detect breaking changes | Modifications to public APIs, database schemas, config formats |
+    | **Accessibility** | Ensure inclusive design | Frontend/UI component changes |
+    | **Constitution** | Check project rules compliance | Project has CONSTITUTION.md |
+  }
+
+  SeverityClassification {
+    CRITICAL => Security vulnerability, data loss, production crash
+    HIGH => Incorrect behavior, perf regression, a11y blocker
+    MEDIUM => Code smell, maintainability, minor perf
+    LOW => Style preference, minor improvement
+  }
+
+  ConfidenceClassification {
+    HIGH => Clear violation of established pattern or security rule => Present as definite issue
+    MEDIUM => Likely issue but context-dependent => Present as probable concern
+    LOW => Potential improvement, may not be applicable => Present as suggestion
+  }
+
+  Workflow {
+    Phase1_GatherChangesContext {
+      1. Parse $ARGUMENTS to determine review target:
+         PR number => fetch PR diff via gh pr diff
+         Branch name => diff against main/master
+         "staged" => use git diff --cached
+         File path => read file and recent changes
+      
+      2. Retrieve full file contents for context (not just diff)
+      3. Read project context: CLAUDE.md, CONSTITUTION.md if present, relevant specs
+      
+      4. Analyze changes to determine which conditional perspectives apply:
+         Contains async/await, Promise, threading => include Concurrency
+         Modifies dependency files => include Dependencies
+         Changes public API/schema => include Compatibility
+         Modifies frontend components => include Accessibility
+         Project has CONSTITUTION.md => include Constitution
+      
+      5. Count applicable perspectives and assess scope of changes
+    }
+
+    Phase2_LaunchReviewActivities {
+      Launch ALL applicable review activities in parallel (single response with multiple task calls)
+      
+      Template {
+        Review this code for [PERSPECTIVE]:
+        
+        CONTEXT:
+        - Files changed: [list]
+        - Changes: [the diff or code]
+        - Full file context: [surrounding code]
+        - Project standards: [from CLAUDE.md, .editorconfig, etc.]
+        
+        FOCUS: [What this perspective looks for - from perspectives table above]
+        
+        OUTPUT: Return findings as a structured list:
+        - id: (leave blank - assigned during synthesis)
+        - title: Brief title (max 40 chars)
+        - severity: CRITICAL | HIGH | MEDIUM | LOW
+        - confidence: HIGH | MEDIUM | LOW
+        - location: file:line
+        - finding: What was found
+        - recommendation: Actionable fix
+        - diff: (Required for CRITICAL, recommended for HIGH)
+        - principle: (If applicable - YAGNI, SRP, OWASP, etc.)
+        
+        If no findings for this perspective, return: NO_FINDINGS
+      }
+    }
+
+    Phase3_SynthesizePresent {
+      Deduplication {
+        1. Collect all findings from all reviewers
+        2. Group by location (file:line range overlap -- within 5 lines = potential overlap)
+        3. For overlapping findings: keep highest severity, merge complementary details, credit all perspectives
+        4. Sort by severity (Critical > High > Medium > Low) then confidence
+        5. Assign finding IDs (C1, C2, H1, H2, M1, M2, L1, etc.)
+      }
+      
+      PresentationFormat {
+        ## Code Review: [target]
+        
+        **Verdict**: [VERDICT from decision table]
+        
+        ### Summary
+        
+        | Category | Critical | High | Medium | Low |
+        | --- | --- | --- | --- | --- |
+        | Security | X | X | X | X |
+        | Simplification | X | X | X | X |
+        | Performance | X | X | X | X |
+        | Quality | X | X | X | X |
+        | Testing | X | X | X | X |
+        | **Total** | X | X | X | X |
+        
+        *Critical & High Findings (Must Address)*
+        
+        | ID | Finding | Remediation |
+        | --- | --- | --- |
+        | C1 | Brief title *(file:line)* | Specific fix *(concise issue description)* |
+        
+        #### Code Examples for Critical Fixes
+        
+        **[C1] Title**
+        // Before -> After code diff
+        
+        *Medium Findings (Should Address)*
+        
+        | ID | Finding | Remediation |
+        | --- | --- | --- |
+        | M1 | Brief title *(file:line)* | Specific fix *(concise issue description)* |
+        
+        *Low Findings (Consider)*
+        
+        | ID | Finding | Remediation |
+        | --- | --- | --- |
+        | L1 | Brief title *(file:line)* | Specific fix *(concise issue description)* |
+        
+        ### Strengths
+        
+        - [Positive observation with specific code reference]
+        
+        ### Verdict Reasoning
+        
+        [Why this verdict was chosen based on findings]
+      }
+      
+      TableColumnGuidelines {
+        ID => Severity letter + number (C1 = Critical #1, H2 = High #2, M1 = Medium #1, L1 = Low #1)
+        Finding => Brief title + location in italics
+        Remediation => Fix recommendation + issue context in italics
+      }
+      
+      CodeExamples {
+        REQUIRED for all Critical findings (before/after style)
+        Include for High findings when the fix is non-obvious
+        Medium/Low findings use table-only format
+      }
+    }
+
+    Phase4_Verdict {
+      Apply verdict decision table to determine review outcome based on finding severity counts
+    }
+
+    Phase5_NextSteps {
+      Use question with options based on verdict:
+      
+      If REVISIONS_NEEDED {
+        "Address critical issues first"
+        "Show me fixes for [specific issue]"
+        "Explain [finding] in more detail"
+      }
+      
+      If APPROVED_WITH_NOTES {
+        "Apply suggested fixes"
+        "Create follow-up issues for medium findings"
+        "Proceed without changes"
+      }
+      
+      If APPROVED {
+        "Add to PR comments (if PR review)"
+        "Done"
+      }
+    }
+  }
+
+  VerdictDecisionMatrix {
+    | Critical | High | Verdict |
+    | --- | --- | --- |
+    | > 0 | Any | REVISIONS_NEEDED |
+    | 0 | > 3 | REVISIONS_NEEDED |
+    | 0 | 1-3 | APPROVED_WITH_NOTES |
+    | 0 | 0 (Medium > 0) | APPROVED_WITH_NOTES |
+    | 0 | 0 (Low only or none) | APPROVED |
+    
+    Note: BLOCKED is reserved for findings that indicate the review cannot be completed (e.g., insufficient context, missing files)
+  }
+
+  ReferenceFiles {
+    reference.md => Detailed per-perspective review checklists, severity/confidence matrices, agent prompt templates, synthesis protocol, example findings
+  }
+}
+
+## Important Notes
+
+- **Parallel execution** - All review activities run simultaneously for speed
+- **Intent-driven** - Describe what to review; the system routes to specialists
+- **Actionable output** - Every finding must have a specific, implementable fix
+- **Positive reinforcement** - Always highlight what's done well alongside issues
+- **Context matters** - Provide full file context, not just diffs

package/opencode/command/simplify.md

@@ -0,0 +1,267 @@
+---
+description: "Simplify and refine code for clarity, consistency, and maintainability while preserving functionality"
+argument-hint: "'staged', 'recent', file path, or 'all' for broader scope"
+allowed-tools:
+  [
+    "todowrite",
+    "grep",
+    "glob",
+    "bash",
+    "read",
+    "edit",
+    "write",
+    "question",
+    "skill",
+  ]
+---
+
+# Simplify
+
+Roleplay as a code simplification orchestrator that coordinates parallel analysis across multiple perspectives, then executes safe refactorings to enhance clarity, consistency, and maintainability while preserving exact functionality.
+
+**Simplification Target**: $ARGUMENTS
+
+Simplify {
+  Constraints {
+    You are an orchestrator - delegate analysis using specialized subagents
+    Display ALL agent responses - show complete agent findings to user, not summaries
+    Call skill tool FIRST - skill({ name: "safe-refactoring" }) for methodology guidance
+    Parallel analysis - launch ALL analysis perspectives simultaneously in a single response
+    Sequential execution - apply changes one at a time with test verification
+    Behavior preservation is mandatory - never change what code does, only how it does it
+  }
+
+  OutputLocations {
+    docs/refactor/[NNN]-simplify-[name].md => Simplification analysis reports and execution logs
+  }
+
+  SimplificationPerspectives {
+    | Perspective | Intent | What to Find |
+    | --- | --- | --- |
+    | Complexity | Reduce cognitive load | Long methods (>20 lines), deep nesting, complex conditionals, convoluted loops, tangled async/promise chains, high cyclomatic complexity |
+    | Clarity | Make intent obvious | Unclear names, magic numbers, inconsistent patterns, overly defensive code, unnecessary ceremony, mixed paradigms, nested ternaries |
+    | Structure | Improve organization | Mixed concerns, tight coupling, bloated interfaces, god objects, too many parameters, hidden dependencies, feature envy |
+    | Waste | Eliminate what shouldn't exist | Duplication, dead code, unused abstractions, speculative generality, copy-paste patterns, unreachable paths |
+  }
+
+  PerspectiveGuidance {
+    Complexity => Find long methods, deep nesting, complex conditionals, convoluted loops; suggest Extract Method, Guard Clauses, Early Return, Decompose Conditional
+    Clarity => Find unclear names, magic numbers, inconsistent patterns, verbose ceremony; suggest Rename, Introduce Constant, Standardize Pattern, Modern Syntax
+    Structure => Find mixed concerns, tight coupling, bloated interfaces; suggest Extract Class, Move Method, Parameter Object, Dependency Injection
+    Waste => Find duplication, dead code, unused abstractions; suggest Extract Function, Remove Dead Code, Inline Unused
+  }
+
+  Workflow {
+    Phase1_GatherTargetAndBaseline {
+      1. Initialize methodology: skill({ name: "safe-refactoring" })
+      
+      2. Parse $ARGUMENTS to determine scope:
+         staged => git diff --cached
+         recent => commits since last push or last 24h
+         File path => specific file(s)
+         all => entire codebase (caution)
+      
+      3. Retrieve full file contents (not just diffs)
+      4. Load project standards (CLAUDE.md, Agent.md, linting rules, conventions)
+      
+      5. Run tests to establish baseline and report:
+         Target: [files/scope]
+         Tests: [X] passing, [Y] failing
+         Coverage: [Z]% for target files
+         Baseline Status: [READY / TESTS FAILING / COVERAGE GAP]
+      
+      6. If tests are failing => Stop and report before proceeding
+    }
+
+    Phase2_LaunchAnalysisAgents {
+      Launch ALL analysis perspectives in parallel (single response with multiple task calls)
+      
+      Template {
+        Analyze this code for [PERSPECTIVE] simplification opportunities:
+        
+        CONTEXT:
+        - Files: [list of files]
+        - Code: [the code to analyze]
+        - Project standards: [from CLAUDE.md, Agent.md]
+        
+        FOCUS: [What this perspective looks for - from SimplificationPerspectives table]
+        
+        OUTPUT: Findings formatted as:
+          [EMOJI] **Issue Title** (IMPACT: HIGH|MEDIUM|LOW)
+          Location: file:line
+          Problem: What's wrong and why it matters
+          Refactoring: Specific technique to apply
+          Example: Before/after if helpful
+      }
+    }
+
+    Phase3_SynthesizeFindings {
+      1. Collect all findings from analysis agents
+      2. Deduplicate overlapping findings (keep highest impact)
+      3. Rank by: Impact (High > Medium > Low), then Independence (isolated changes first)
+      4. Filter out findings in untested code (flag for user decision)
+      
+      PresentationFormat {
+        ## Simplification Analysis: [target]
+        
+        ### Summary
+        
+        | Perspective | High | Medium | Low |
+        | --- | --- | --- | --- |
+        | Complexity | X | X | X |
+        | Clarity | X | X | X |
+        | Structure | X | X | X |
+        | Waste | X | X | X |
+        | **Total** | X | X | X |
+        
+        ### High Impact Opportunities
+        
+        **[Complexity] Long Method in calculateTotal** (HIGH)
+        Location: src/billing.ts:45-120
+        Problem: 75-line method with 4 responsibilities
+        Refactoring: Extract Method - Split into validateOrder, applyDiscounts, calculateTax, formatResult
+        
+        ### Medium Impact Opportunities
+        ...
+        
+        ### Low Impact Opportunities
+        ...
+        
+        ### Untested Code (Requires Decision)
+        - src/legacy.ts:10-50 - No test coverage, skip or add tests first?
+      }
+    }
+
+    Phase4_PlanAndConfirm {
+      Create prioritized execution plan:
+        Order: Independent changes first, then dependent changes
+        1. [Extract Method] - billing.ts:45 - Risk: Low - Tests: checked
+        2. [Rename] - utils.ts:12 - Risk: Low - Tests: checked
+        3. [Guard Clauses] - auth.ts:30 - Risk: Medium - Tests: checked
+        Estimated: [N] refactorings across [M] files
+        Execution: One at a time with test verification
+      
+      Use question with options:
+        "Document and proceed" => Save plan to docs/refactor/[NNN]-simplify-[name].md, then execute
+        "Proceed without documenting" => Execute simplifications directly
+        "Apply high-impact only" => Execute only high-impact changes
+        "Review each change individually" => Interactive approval for each change
+        "Cancel" => Abort simplification
+      
+      If user chooses to document => Create file with target scope, baseline metrics, findings summary, planned refactorings, risk assessment BEFORE execution
+    }
+
+    Phase5_ExecuteSimplifications {
+      CRITICAL: One refactoring at a time!
+      
+      For EACH simplification {
+        1. Apply single change
+        2. Run tests immediately
+        3. If pass => Continue to next
+        4. If fail => Revert immediately, report, decide next action
+      }
+      
+      Progress format:
+        Executing Simplification [N] of [Total]
+        Target: file:line
+        Refactoring: [Technique]
+        Status: [Applying / Testing / Complete / Reverted]
+        Tests: [Passing / Failing]
+    }
+
+    Phase6_FinalSummary {
+      PresentationFormat {
+        ## Simplification Complete
+        
+        **Applied**: [N] of [M] planned changes
+        **Tests**: All passing
+        **Behavior**: Preserved
+        
+        ### Changes Summary
+        
+        | File | Refactoring | Before | After |
+        | --- | --- | --- | --- |
+        | billing.ts | Extract Method | 75 lines | 4 functions, 20 lines each |
+        | utils.ts | Rename | calc() | calculateTotalWithTax() |
+        
+        ### Quality Improvements
+        
+        - Reduced average method length from X to Y lines
+        - Eliminated N lines of duplicate code
+        - Improved naming clarity in M locations
+        - Reduced cyclomatic complexity by Z%
+        
+        ### Skipped
+        
+        - legacy.ts:10 - No test coverage (user declined)
+      }
+    }
+
+    Phase7_NextSteps {
+      Use question with options:
+        "Commit these changes"
+        "Run full test suite"
+        "Address skipped items (add tests first)"
+        "Done"
+    }
+  }
+
+  ClarityOverBrevity {
+    | Avoid | Prefer |
+    | --- | --- |
+    | Nested ternaries | if/else or switch |
+    | Dense one-liners | Multi-line with clear steps |
+    | Clever tricks | Obvious implementations |
+    | Abbreviations | Descriptive names |
+    | Magic numbers | Named constants |
+  }
+
+  AntiPatterns {
+    DontOverSimplify {
+      Combining concerns for "fewer files"
+      Inlining everything for "fewer abstractions"
+      Removing helpful abstractions that aid understanding
+    }
+    
+    DontMixConcerns {
+      Simplification + feature changes together
+      Multiple refactorings before running tests
+      Refactoring untested code without adding tests
+    }
+  }
+
+  ErrorRecovery {
+    TestsFailAfterChange {
+      Simplification Paused
+      Change: [What was attempted]
+      Result: Tests failing
+      Action: Reverted to working state
+      
+      Options:
+        1. Try alternative approach
+        2. Add tests first, then retry
+        3. Skip this simplification
+        4. Stop and review all changes
+    }
+    
+    NoTestCoverage {
+      Untested Code Detected
+      Target: [file:line]
+      Coverage: None
+      
+      Options:
+        1. Add characterization tests first (recommended)
+        2. Proceed with manual verification (risky)
+        3. Skip this file
+    }
+  }
+}
+
+## Important Notes
+
+- **Parallel analysis, sequential execution** - Analyze fast, change safely
+- **Behavior preservation is mandatory** - External functionality must remain identical
+- **Test after every change** - Never batch changes before verification
+- **Revert on failure** - Working code beats simplified code
+- **Balance is key** - Simple enough to understand, not so simple it's inflexible
+- **Confirm before writing documentation** - Always ask user before persisting plans to docs/

package/opencode/command/specify.md

@@ -0,0 +1,191 @@
+---
+description: "Create a comprehensive specification from a brief description. Manages specification workflow including directory creation, README tracking, and phase transitions."
+argument-hint: "describe your feature or requirement to specify"
+allowed-tools:
+  [
+    "todowrite",
+    "bash",
+    "grep",
+    "read",
+    "write",
+    "edit",
+    "question",
+    "skill",
+  ]
+---
+
+# Specify
+
+Roleplay as an expert requirements gatherer that creates specification documents for one-shot implementation.
+
+**Description:** $ARGUMENTS
+
+Specify {
+  Constraints {
+    You are an orchestrator - delegate research tasks using specialized subagents
+    Display ALL agent responses - show complete agent findings to user (not summaries)
+    Call skill tool FIRST - before starting any phase work for methodology guidance
+    Ask user for direction - use question after initialization to let user choose path
+    Phases are sequential - PRD => SDD => PLAN (can skip phases with user approval)
+    Track decisions in specification README - log skipped phases and non-default choices
+    Wait for confirmation - require user approval between each document phase
+    Never start a phase without calling the appropriate skill tool first
+    Git integration is optional - offer branch/commit workflow only when user requests it
+  }
+
+  ResearchPerspectives {
+    | Perspective | Intent | What to Research |
+    | --- | --- | --- |
+    | **Requirements** | Understand user needs | User stories, stakeholder goals, acceptance criteria, edge cases |
+    | **Technical** | Evaluate architecture options | Patterns, technology choices, constraints, dependencies |
+    | **Security** | Identify protection needs | Authentication, authorization, data protection, compliance |
+    | **Performance** | Define capacity targets | Load expectations, latency targets, scalability requirements |
+    | **Integration** | Map external boundaries | APIs, third-party services, data flows, contracts |
+  }
+
+  ParallelTaskExecution {
+    Decompose research into parallel activities
+    Launch multiple specialist agents in a SINGLE response
+    
+    Template {
+      Research [PERSPECTIVE] for specification:
+      
+      CONTEXT:
+      - Description: [User's feature description]
+      - Codebase: [Relevant existing code, patterns]
+      - Constraints: [Known limitations, requirements]
+      
+      FOCUS: [What this perspective researches - from table above]
+      
+      OUTPUT: Findings formatted as:
+        **[Topic]**
+        Discovery: [What was found]
+        Evidence: [Code references, documentation]
+        Recommendation: [Actionable insight for spec]
+        Open Questions: [Needs clarification]
+    }
+  }
+
+  ResearchSynthesis {
+    1. Collect all findings from research agents
+    2. Deduplicate overlapping discoveries
+    3. Identify conflicts requiring user decision
+    4. Organize by document section (PRD, SDD, PLAN)
+  }
+
+  Workflow {
+    Phase1_Initialize {
+      Context: Creating new spec or checking existing spec status
+      
+      1. Call: skill({ name: "specification-management" })
+      2. Initialize specification using $ARGUMENTS (skill handles directory creation/reading)
+      3. Call: question to let user choose direction
+      
+      ForNewSpecs {
+        Ask where to start:
+        Option1 (Recommended) => Start with PRD - Define requirements first, then design, then plan
+        Option2 => Start with SDD - Skip requirements, go straight to technical design
+        Option3 => Start with PLAN - Skip to implementation planning
+      }
+      
+      ForExistingSpecs {
+        Analyze document status (check for [NEEDS CLARIFICATION] markers and checklist completion):
+        PRD incomplete => Continue PRD
+        SDD incomplete => Continue SDD
+        PLAN incomplete => Continue PLAN
+        All complete => Finalize & Assess
+      }
+    }
+
+    Phase2_PRD {
+      Context: Working on product requirements, defining user stories, acceptance criteria
+      
+      1. Call: skill({ name: "requirements-analysis" })
+      2. Focus: WHAT needs to be built and WHY it matters
+      3. Scope: Business requirements only (defer technical details to SDD)
+      4. Deliverable: Complete Product Requirements
+      
+      AfterCompletion => Call: question - Continue to SDD (recommended) or Finalize PRD
+    }
+
+    Phase3_SDD {
+      Context: Working on solution design, designing architecture, defining interfaces
+      
+      1. Call: skill({ name: "architecture-design" })
+      2. Focus: HOW the solution will be built
+      3. Scope: Design decisions and interfaces (defer code to implementation)
+      4. Deliverable: Complete Solution Design
+      
+      ConstitutionAlignment (if CONSTITUTION.md exists) {
+        Call: skill({ name: "constitution-validation" }) in planning mode
+        Verify proposed architecture aligns with constitutional rules
+        Ensure ADRs are consistent with L1/L2 constitution rules
+        Report any potential conflicts for resolution before finalizing SDD
+      }
+      
+      AfterCompletion => Call: question - Continue to PLAN (recommended) or Finalize SDD
+    }
+
+    Phase4_PLAN {
+      Context: Working on implementation plan, planning phases, sequencing tasks
+      
+      1. Call: skill({ name: "implementation-planning" })
+      2. Focus: Task sequencing and dependencies
+      3. Scope: What and in what order (defer duration estimates)
+      4. Deliverable: Complete Implementation Plan
+      
+      AfterCompletion => Call: question - Finalize Specification (recommended) or Revisit PLAN
+    }
+
+    Phase5_Finalization {
+      Context: Reviewing all documents, assessing implementation readiness
+      
+      1. Call: skill({ name: "specification-management" })
+      2. Review documents and assess context drift between them
+      3. Generate readiness and confidence assessment
+      
+      GitFinalization (if user requested git integration) {
+        Offer to commit specification with conventional message (docs(spec-[id]): ...)
+        Offer to create spec review PR via gh pr create
+        Handle push and PR creation
+      }
+      
+      Summary {
+        Specification Complete
+        
+        Spec: [NNN]-[name]
+        Documents: PRD | SDD | PLAN
+        
+        Readiness: [HIGH/MEDIUM/LOW]
+        Confidence: [N]%
+        
+        Next Steps:
+        1. /validate [ID] - Validate specification quality
+        2. /implement [ID] - Begin implementation
+      }
+    }
+  }
+
+  DocumentationStructure {
+    docs/specs/[NNN]-[name]/
+    ├── README.md                 # Decisions and progress
+    ├── product-requirements.md   # What and why
+    ├── solution-design.md        # How
+    └── implementation-plan.md    # Execution sequence
+  }
+
+  DecisionLogging {
+    When user skips a phase or makes a non-default choice, log it in README.md:
+    
+    | Date | Decision | Rationale |
+    | --- | --- | --- |
+    | [date] | PRD skipped | User chose to start directly with SDD |
+    | [date] | Started from PLAN | Requirements and design already documented elsewhere |
+  }
+}
+
+## Important Notes
+
+- **Git integration is optional** - Offer branch/commit workflow only when user requests it
+- **User confirmation required** - Wait for user approval between each document phase
+- **Log all decisions** - Record skipped phases and non-default choices in README.md