octocode-cli 1.1.1 → 1.2.0

package/skills/octocode-implement/references/execution-phases.md

@@ -0,0 +1,317 @@
+# Execution Phases - Detailed Reference
+
+Detailed step-by-step instructions for each implementation phase.
+
+---
+
+## Phase 1: SPEC (Spec Parsing)
+
+**Goal**: Extract and structure all implementation requirements.
+
+**Subagent Pattern**:
+```
+Task: "Parse specification and extract implementation tasks"
+Scope: Read spec file, identify tasks, classify complexity
+```
+
+**Steps**:
+1. **Read Specification**: Read the provided MD file
+2. **Extract Tasks**: Identify discrete implementation tasks
+3. **Classify Complexity**: Simple | Medium | Complex | Epic
+4. **Identify Dependencies**: What depends on what?
+5. **Create Master Todo**: Add all tasks via `TodoWrite`
+
+**Deliverable**: Structured task list with dependencies.
+
+---
+
+## Phase 2: SPEC_VALIDATE (Spec Validation)
+
+**Goal**: Ensure specification is complete and actionable before proceeding.
+
+**Subagent Pattern**:
+```
+Task: "Validate specification completeness and clarity"
+Scope: Check for ambiguities, missing details, contradictions
+```
+
+**Validation Checklist**:
+| Check | Status | Action if Fails |
+|-------|--------|-----------------|
+| All requirements clearly defined | ❓ | Ask user for clarification |
+| Acceptance criteria specified | ❓ | Request criteria from user |
+| No contradicting requirements | ❓ | Flag conflicts to user |
+| Technical constraints clear | ❓ | Ask for constraints |
+| Dependencies identified | ❓ | Map dependencies |
+| Out-of-scope items listed | ❓ | Confirm scope with user |
+
+**Validation Questions**:
+- Are there ambiguous terms that need definition?
+- Are there implicit requirements not stated?
+- Are there edge cases not covered?
+- Is the scope well-bounded?
+
+**Outcomes**:
+| Result | Action |
+|--------|--------|
+| ✅ All Clear | Proceed to CONTEXT |
+| ⚠️ Minor Gaps | Document assumptions, proceed with checkpoint |
+| ❌ Major Gaps | STOP. Present gaps to user. Wait for clarification. |
+
+---
+
+## Phase 3: CONTEXT (Context Discovery)
+
+**Goal**: Build mental model of codebase architecture.
+
+**Subagent Pattern**:
+```
+Task: "Map codebase architecture for [feature area]"
+Scope: Directory structure, entry points, testing setup
+```
+
+**Parallel Subagents** (spawn via `Task`):
+| Subagent | Focus | Tool |
+|----------|-------|------|
+| Structure Agent | Map directory tree | `localViewStructure` |
+| Pattern Agent | Find similar features | `localSearchCode` |
+| Test Agent | Understand test setup | `localSearchCode` in tests/ |
+
+**Steps**:
+1. **Map Codebase**: `localViewStructure` at root (depth=1)
+2. **Identify Relevant Areas**: Which directories matter for this task?
+3. **Locate Entry Points**: Where does the feature start?
+4. **Find Similar Features**: What analogous implementations exist?
+5. **Understand Testing Setup**: How are tests organized?
+
+**Deliverable**: Mental model of the codebase architecture.
+
+---
+
+## Phase 4: PLAN (Implementation Planning)
+
+**Goal**: Create detailed, actionable implementation plan.
+
+**Subagent Pattern**:
+```
+Task: "Create implementation plan for [task]"
+Scope: Break down into atomic changes, identify files, risks
+```
+
+**Plan Structure**:
+Write implementation plan with:
+- Task breakdown (atomic changes)
+- File changes required
+- Research questions to resolve
+- Testing strategy
+- Risk areas
+
+**Parallel Planning** (for Complex/Epic tasks):
+```
+Task 1: "Plan types and interfaces changes"
+Task 2: "Plan core logic implementation"
+Task 3: "Plan integration points"
+Task 4: "Plan test coverage"
+```
+
+**User Checkpoint**: Present plan → Wait for approval.
+
+---
+
+## Phase 5: RESEARCH (Deep Research)
+
+**Goal**: Understand exactly what to change and how.
+
+**Subagent Pattern**:
+```
+Task: "Research [specific area] for implementation"
+Scope: Locate code, trace flow, find patterns
+```
+
+**Parallel Research Subagents** (spawn via `Task`):
+| Subagent | Focus | Output |
+|----------|-------|--------|
+| Flow Tracer | Trace data flow with LSP | Call hierarchy map |
+| Pattern Finder | Find existing patterns | Pattern examples |
+| Impact Analyzer | Find all affected code | Reference list |
+| Test Researcher | Find test patterns | Test templates |
+
+**Research Steps Per Task**:
+
+1. **Locate Target Area**:
+   ```
+   localSearchCode(pattern="FeatureName", filesOnly=true)
+   ```
+
+2. **Read Implementation Context**:
+   ```
+   localGetFileContent(path="target.ts", matchString="class Feature")
+   ```
+
+3. **Trace Data Flow**:
+   ```
+   lspCallHierarchy(symbolName="handleData", direction="incoming")
+   lspCallHierarchy(symbolName="handleData", direction="outgoing")
+   ```
+
+4. **Find All References** (Impact Analysis):
+   ```
+   lspFindReferences(symbolName="affectedFunction", includeDeclaration=false)
+   ```
+
+5. **Find Existing Patterns**:
+   ```
+   localSearchCode(pattern="similar implementation pattern")
+   ```
+
+6. **Check Test Patterns**:
+   ```
+   localSearchCode(pattern="describe.*SimilarFeature", path="tests")
+   ```
+
+**Deliverable**: Clear understanding of what to change and how.
+
+---
+
+## Phase 6: IMPLEMENT (Code Implementation)
+
+**Goal**: Execute changes following patterns and plan.
+
+**Subagent Pattern**:
+```
+Task: "Implement [specific component/feature]"
+Scope: Types, logic, integration for one atomic task
+```
+
+**Parallel Implementation** (for independent tasks):
+```
+Task 1: "Implement types and interfaces" → Types Agent
+Task 2: "Implement core logic" → Logic Agent
+Task 3: "Implement tests" → Test Agent
+```
+
+**Sequential Implementation** (for dependent tasks):
+Execute changes in order:
+1. **Types First**: Add/modify interfaces and types
+2. **Core Logic**: Implement the feature
+3. **Integration**: Wire into existing code
+4. **Tests**: Add tests following existing patterns
+5. **Documentation**: Update docs if needed
+
+**Implementation Guidelines**:
+- Match existing code style exactly
+- Use existing abstractions, don't create new ones
+- Follow naming conventions found in codebase
+- Add minimal comments (code should be self-documenting)
+- Keep functions focused (Single Responsibility)
+
+---
+
+## Phase 7: VALIDATE (Spec Verification)
+
+**Goal**: Verify ALL spec requirements are correctly implemented.
+
+**Subagent Pattern**:
+```
+Task: "Validate [requirement] implementation"
+Scope: Check specific requirement against code
+```
+
+**Parallel Validation Subagents** (spawn via `Task`):
+| Subagent | Focus | Checks |
+|----------|-------|--------|
+| Tech Validator | Technical checks | Compile, lint, tests |
+| Spec Validator | Requirement coverage | Each spec item |
+| Regression Validator | Side effects | Affected areas |
+| Quality Validator | Code quality | Patterns, style |
+
+**Technical Validation Gates (ALL MANDATORY)**:
+- [ ] TypeScript compiles (`tsc --noEmit`)
+- [ ] Linter passes (`lint`)
+- [ ] Tests pass (`test`)
+- [ ] New code has tests
+- [ ] No regressions in affected areas
+
+**Spec Compliance Validation**:
+| Requirement | Status | Evidence |
+|-------------|--------|----------|
+| [Req 1 from spec] | ✅/❌ | [File:line or test name] |
+| [Req 2 from spec] | ✅/❌ | [File:line or test name] |
+
+**Cross-Reference Check**:
+1. Re-read original spec
+2. For EACH requirement, find corresponding:
+   - Implementation code
+   - Test coverage
+   - Documentation (if needed)
+3. Flag any gaps
+
+**Outcomes**:
+| Result | Action |
+|--------|--------|
+| ✅ All requirements verified | Complete. Generate changes.md |
+| ⚠️ Minor gaps | Document, ask user if acceptable |
+| ❌ Missing requirements | Loop back to IMPLEMENT |
+
+---
+
+## Multi-Agent Parallelization
+
+### Phase-Level Parallelization
+
+| Phase | Parallelizable? | Subagent Strategy |
+|-------|-----------------|-------------------|
+| SPEC | No | Single agent parses spec |
+| SPEC_VALIDATE | Yes | Spawn validators per requirement category |
+| CONTEXT | Yes | Parallel: Structure, Pattern, Test agents |
+| PLAN | Partial | Parallel for independent task areas |
+| RESEARCH | Yes | Parallel: Flow, Pattern, Impact, Test agents |
+| IMPLEMENT | Partial | Parallel for independent components |
+| VALIDATE | Yes | Parallel: Tech, Spec, Regression validators |
+
+### TodoWrite Integration
+
+**Master Task Flow**:
+```
+TodoWrite([
+  { id: "spec", content: "Parse specification", status: "completed" },
+  { id: "spec-validate", content: "Validate spec completeness", status: "in_progress" },
+  { id: "context", content: "Discover codebase context", status: "pending" },
+  { id: "plan", content: "Create implementation plan", status: "pending" },
+  { id: "research", content: "Deep research per task", status: "pending" },
+  { id: "implement", content: "Implement changes", status: "pending" },
+  { id: "validate", content: "Validate against spec", status: "pending" }
+])
+```
+
+### Spawning Subagents with Task Tool
+
+**Pattern for Phase Subagent**:
+```
+Task: "[Phase]: [Specific Goal]"
+Context: [Relevant files, findings so far]
+Scope: [Bounded deliverable]
+Report: [What to return to main agent]
+```
+
+**Example - CONTEXT Phase**:
+```
+// Spawn in parallel:
+Task("CONTEXT: Map directory structure", { depth: 2, focus: "src/" })
+Task("CONTEXT: Find similar features", { pattern: "auth", type: "ts" })
+Task("CONTEXT: Analyze test setup", { path: "tests/" })
+```
+
+### When to Spawn vs Sequential
+
+**Spawn Subagents When**:
+- 2+ independent tasks in same phase
+- Research across different code areas
+- Validation of independent requirements
+- Implementation of unrelated components
+
+**Stay Sequential When**:
+- Tasks have dependencies
+- Small tasks (overhead > benefit)
+- Need to maintain context flow
+- User interaction required