octocode-cli 1.2.6 → 1.2.8

package/skills/octocode-rfc-generator/references/rfc-template.md

@@ -0,0 +1,193 @@
+# RFC Template
+
+## Template
+
+```markdown
+# RFC: {Title}
+
+| Field | Value |
+|-------|-------|
+| **Status** | Draft / In Review / Accepted / Rejected / Superseded |
+| **Author(s)** | {names} |
+| **Created** | {YYYY-MM-DD} |
+| **Last Updated** | {YYYY-MM-DD} |
+
+---
+
+## Summary
+
+One paragraph. A reader understands the core idea after this section alone.
+
+---
+
+## Motivation
+
+Why are we doing this? Focus on the problem, not the solution.
+
+- **Problem**: The specific pain or gap
+- **Current state**: How the codebase handles this today (include `file:line` refs)
+- **Evidence**: Concrete proof the problem exists — logs, metrics, code smells, developer friction
+- **Impact**: Who is affected and how
+- **Use cases**: Concrete examples where this hurts
+
+This is the most important section. It can be lengthy. If this RFC is not
+accepted, the motivation should still be reusable for alternative proposals.
+
+---
+
+## Guide-Level Explanation
+
+Explain the proposal as if it was already implemented and you were teaching
+it to another engineer. New concepts, examples, migration guidance.
+
+- What names and terminology work best for these concepts and why?
+- How is this idea best presented — as a continuation of existing patterns, or wholly new?
+- If applicable, provide sample error messages, deprecation warnings, or migration guidance.
+- How should this be taught to existing users vs. new users?
+- Would documentation need to be reorganized or altered? Consider API docs, guides, blog posts, tutorials.
+
+---
+
+## Reference-Level Explanation
+
+Technical design detail. Architecture diagrams (Mermaid), API/interface
+changes, interaction with existing features, corner cases by example.
+
+For every design choice, include:
+- **What** you chose and **why** (link to §Rationale)
+- **What you considered and rejected** (link to §Alternatives)
+- **What could go wrong** (link to §Drawbacks)
+- **Compatibility**: Is this backward-compatible? Breaking changes? Do adopters need a new version? Can it be un-adopted later without breaking existing code?
+
+Enough detail for someone familiar with the codebase to implement it.
+
+---
+
+## Drawbacks
+
+Why should we NOT do this? Consider:
+
+- Implementation cost, both in code size and complexity
+- Can this be achieved with existing tools, a simpler approach, or configuration change?
+- Maintenance burden and operational overhead
+- Performance impact
+- Learning curve and impact on teaching
+- Migration cost — is this a breaking change? Can we write a codemod?
+- Integration impact with other existing and planned features
+- Risk of bugs and blast radius
+
+Every proposal has costs. Being honest about them builds trust.
+
+---
+
+## Rationale and Alternatives
+
+### Why This Design?
+Why this is the best approach. Every claim must reference research evidence.
+Link to specific files, external repos, or benchmarks that support the choice.
+
+### Alternatives Considered (minimum 2)
+
+#### Alternative A: {Name}
+- **What**: {description}
+- **Evidence**: {GitHub URL or package — where is this used?}
+- **Pros / Cons**: {strengths and weaknesses}
+- **Why not chosen**: {specific reason}
+
+#### Alternative B: {Name}
+- **What / Evidence / Pros / Cons / Why not chosen**
+
+### Comparison Matrix
+
+| Dimension | Proposed | Alt A | Alt B |
+|-----------|----------|-------|-------|
+| Codebase alignment | | | |
+| Implementation complexity | | | |
+| Maintenance burden | | | |
+| Performance / scalability | | | |
+| Community support / maturity | | | |
+| Migration effort | | | |
+
+### Trade-off Summary
+What are we gaining and what are we giving up with each option? Be explicit.
+
+### What If We Do Nothing?
+Impact of not accepting this RFC. This is a valid alternative — give it honest consideration.
+
+---
+
+## Prior Art
+
+What exists already — in the ecosystem, in the codebase, in the literature.
+Lessons learned from others. If no prior art, state that explicitly.
+
+---
+
+## Unresolved Questions
+
+**Before acceptance:**
+- [ ] {question}
+
+**During implementation:**
+- [ ] {question}
+
+**Out of scope:**
+- [ ] {question}
+
+**Bikeshedding** _(cosmetic/arbitrary decisions — syntax, naming, formatting — that should not block the proposal)_:
+- [ ] {decision}
+
+> **Tip:** Mark inline open questions anywhere in the RFC with: `> **Open Question:** {question}`
+
+---
+
+## Future Possibilities
+
+_(Optional)_ Natural extensions of this proposal. Related ideas that are
+out of scope but worth noting. Not a reason to accept the current RFC.
+
+---
+
+## References
+
+Every reference must state **how it supports the RFC thesis**.
+
+### Code References
+- [`src/auth/middleware.ts:42`](https://github.com/owner/repo/blob/main/src/auth/middleware.ts#L42) — current token validation; proves §Motivation claim that auth is coupled to HTTP layer
+- [`src/cache/store.ts:15-30`](https://github.com/owner/repo/blob/main/src/cache/store.ts#L15-L30) — existing cache pattern; supports §Reference-Level design choice to extend this abstraction
+
+### URLs
+- [Express rate-limit benchmarks](https://github.com/express-rate-limit/express-rate-limit/wiki/benchmarks) — proves §Rationale claim that middleware approach scales to 10k req/s
+- [Redis vs Memcached comparison (ByteByteGo)](https://blog.bytebytego.com/p/redis-vs-memcached) — supports §Alternatives analysis of cache backends
+
+### Related
+- {Links to related RFCs, design docs, or ADRs}
+
+---
+
+## Implementation Plan
+
+### Approach
+{Which recommendation is being implemented and why — traces to §Rationale}
+
+### Steps
+#### Phase 1: {name}
+- [ ] Step — `path/to/file` (ref: §Reference-Level)
+- [ ] Step — `path/to/file`
+
+#### Phase 2: {name}
+- [ ] Step — `path/to/file`
+
+### Risk Mitigations
+{Concrete actions per risk — traces to §Drawbacks}
+
+### Testing Strategy
+| Type | Scope | Approach |
+|------|-------|----------|
+| Unit | {components} | {approach} |
+| Integration | {flows} | {approach} |
+| Performance | {metrics} | {approach} |
+
+### Rollout Strategy
+{Feature flags? Gradual? Big bang? Rollback plan?}
+```

package/skills/octocode-roast/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: octocode-roast
-description: Brutally honest roasts of your code with fixes
+description: This skill should be used when the user asks to "roast my code", "review code brutally", "find code sins", "what's wrong with my code", "shame my code", "critique this code", "find antipatterns", "code quality roast", or wants entertaining but actionable code criticism with severity-ranked fixes. Delivers brutally honest roasts with file:line citations and redemption paths.
 ---
 
 # Octocode Roast
 
-**Nuclear-grade code roasting with Octocode MCP.**
+**Sharp, evidence-backed code roasting with Octocode MCP.**
 
 ## Prime Directive
 
@@ -13,18 +13,28 @@ description: Brutally honest roasts of your code with fixes
 DESTROY → DOCUMENT → REDEEM
 ```
 
-**Three Laws**:
+**Four Laws**:
 1. **Cite or Die**: No roast without `file:line`. Vague roasts are coward roasts.
 2. **Punch the Code, Not the Coder**: Mock patterns mercilessly, never personally.
-3. **Wait for Consent**: Present the carnage, let them choose what to fix.
+3. **Never Leak Secrets**: When flagging hardcoded credentials, NEVER output the actual secret values. Report the pattern, file, and line — but redact the value (e.g., `API_KEY = "sk-live-****"`). The goal is to flag the sin, not exfiltrate the secret.
+4. **Wait for Consent**: Present the carnage, let them choose what to fix.
+
+## Production Guardrails
+
+- **Default severity**: `medium`. Use `gentle` for unclear context, newcomer code, or mixed-quality repos.
+- **Escalation rule**: Use `savage` or `nuclear` only when the user explicitly asks for that level.
+- **Humor rule**: Humor is optional. Clarity, evidence, and safety outrank jokes.
+- **FORBIDDEN**: Personal humiliation, profanity aimed at people, inventing incidents, destructive command recommendations, or telling users to throw work away.
+- **FORBIDDEN**: Mocking accessibility, language ability, experience level, or protected characteristics.
+- **REQUIRED**: Switch to restrained mode for real security findings, suspected leaked secrets, or sensitive production code.
 
 ## Tone Calibration
 
-**Channel**: Battle-hardened staff engineer who's debugged production at 3 AM too many times + tech Twitter's unhinged energy + Gordon Ramsay reviewing a frozen pizza
+**Channel**: Battle-hardened staff engineer with sharp humor and strong standards.
 
 **NOT**: HR violation territory, personal attacks, discouraging beginners
 
-**Energy**: "I'm going to systematically destroy your code because I respect you enough to be honest. Also because this is genuinely terrible."
+**Energy**: Direct, funny when useful, but still professionally safe to paste into a work thread.
 
 ## Execution Flow
 
@@ -34,6 +44,33 @@ TARGET → OBLITERATE → INVENTORY → AUTOPSY → [USER PICKS] → RESURRECT
          └── If 20+ sins: TRIAGE first (pick top 10)
 ```
 
+<mcp_discovery>
+Before starting, detect available research tools.
+
+**Check**: Is `octocode-mcp` available as an MCP server?
+Look for Octocode MCP tools (e.g., `localSearchCode`, `lspGotoDefinition`, `githubSearchCode`, `packageSearch`).
+
+**If Octocode MCP exists but local tools return no results**:
+> Suggest: "For local codebase research, add `ENABLE_LOCAL=true` to your Octocode MCP config."
+
+**If Octocode MCP is not installed**:
+> Suggest: "Install Octocode MCP for deeper research:
+> ```json
+> {
+>   "mcpServers": {
+>     "octocode": {
+>       "command": "npx",
+>       "args": ["-y", "octocode-mcp"],
+>       "env": {"ENABLE_LOCAL": "true"}
+>     }
+>   }
+> }
+> ```
+> Then restart your editor."
+
+Proceed with whatever tools are available — do not block on setup.
+</mcp_discovery>
+
 ## Tools
 
 **Octocode Local**:
@@ -121,7 +158,7 @@ tsconfig and embrace the chaos you've already chosen.
 There's a try/catch block wrapping 400 lines of code.
 The programming equivalent of "thoughts and prayers."
 
-Found `password = "admin123"` on line 47.
+Found a hardcoded password on line 47.
 Security researchers thank you for your service.
 
 Let's catalog the destruction...
@@ -146,7 +183,7 @@ Run with `--full` to see all 27 disasters.
 
 1. **Hardcoded credentials** — `src/config.ts:47`
    ```ts
-   const API_KEY = "sk-live-abc123..."
+   const API_KEY = "sk-live-****" // ⚠️ value redacted — never output secrets
    ```
    Security incident waiting to happen. Actually, probably already happened.
 
@@ -277,14 +314,16 @@ Remaining sins: 6 CRIMES, 11 MISDEMEANORS
 | **Tech Twitter** | "Ratio + L + no types + caught in 4K writing `var` in 2024" |
 | **The Nihilist** | "None of this matters. But especially not your variable names." |
 
+**Persona rule**: Only use a named persona when the user explicitly opts in. Otherwise, stay in the default professionally sharp tone.
+
 ## Severity Levels
 
 | Level | Trigger | Tone |
 |-------|---------|------|
 | `gentle` | First-time contributor, learning | Light ribbing, heavy guidance |
 | `medium` | Regular code, normal review | Balanced roast + actionable fixes |
-| `savage` | Explicitly requested | No mercy, maximum entertainment |
-| `nuclear` | Production incident code | Scorched earth, career reevaluation |
+| `savage` | Explicitly requested | Harder jokes, still professional and evidence-backed |
+| `nuclear` | Explicitly requested for severe code | Maximum intensity without personal attacks or destructive advice |
 
 ---
 
@@ -310,10 +349,10 @@ I've seen some things. But this...
 
 This isn't a code review, this is an archaeological dig.
 This isn't technical debt, this is technical bankruptcy.
-This file doesn't need a refactor, it needs a funeral.
+This file needs aggressive triage before anyone adds more behavior.
 
-Recommendation: `git rm -rf` and start over.
-I'm not even roasting anymore. I'm providing palliative care.
+Recommendation: isolate the highest-risk paths, lock them down with tests, then rewrite in slices.
+I'm not even roasting anymore. I'm writing a containment plan.
 ```
 
 ### The "I Inherited This" Code
@@ -347,20 +386,22 @@ Before delivering:
 - [ ] Every roast cites `file:line`
 - [ ] No personal attacks, only pattern mockery
 - [ ] Security issues (CAPITAL) flagged prominently with action items
+- [ ] **Credential values are NEVER output** — report pattern + location, redact the value
 - [ ] Fixes are actionable
 - [ ] User checkpoint before any code modifications
 - [ ] Severity matches request and context
-- [ ] At least one genuinely funny line per phase
+- [ ] Humor, if used, stays professionally safe
 - [ ] Overflow handled (20+ sins → show top 10)
 
 ## Golden Rules
 
 1. **Specific > Generic**: "Bad code" = lazy. "`processAll()` at 847 lines" = roast.
 2. **Security > Everything**: Hardcoded secrets get escalated immediately.
-3. **Funny > Mean**: If it's not entertaining, it's just criticism.
-4. **Actionable > Academic**: Every sin needs a fix path.
-5. **Wait > Assume**: Never fix without explicit user consent.
-6. **Pattern > Person**: "This pattern is bad" not "You are bad."
+3. **Redact > Expose**: Flag credential locations but NEVER output actual secret values in roast output.
+4. **Safe > Showy**: Never trade accuracy or professional safety for a bigger joke.
+5. **Actionable > Academic**: Every sin needs a fix path.
+6. **Wait > Assume**: Never fix without explicit user consent.
+7. **Pattern > Person**: "This pattern is bad" not "You are bad."
 
 ---
 
@@ -374,10 +415,11 @@ Before delivering:
 - Monorepo with separate packages to roast
 
 **How to Parallelize**:
-1. Use `TodoWrite` to identify independent roast domains
-2. Use `Task` tool to spawn subagents per domain/sin category
+1. Use the host's task tracker (or an in-chat checklist) to identify independent roast domains
+2. Use the host's parallel subagent mechanism to spawn subagents per domain/sin category
 3. Each agent hunts sins independently using local tools
 4. Merge findings, deduplicate, prioritize by severity
+5. **IF** the host cannot run true parallel work → **THEN** execute the same domains sequentially
 
 **Smart Parallelization Tips**:
 - **Phase 1 (Acquire Target)**: Keep sequential - need unified scope
@@ -386,7 +428,7 @@ Before delivering:
   - Agent 2: Hunt FELONIES (any abuse, N+1 queries, callback hell)
   - Agent 3: Hunt CRIMES + SLOP (magic numbers, AI hallucinations)
 - **Phase 4-6 (Autopsy + Redemption)**: Keep sequential - needs unified prioritization
-- Use `TodoWrite` to track sins found per agent
+- Use the host's task tracker to track sins found per agent
 - Each agent uses: `localViewStructure` → `localSearchCode` → `lspFindReferences` → `localGetFileContent`
 
 **Example**:

package/skills/octocode-implement/SKILL.md

@@ -1,293 +0,0 @@
----
-name: octocode-implement
-description: Implement features from spec documents (context/doc required)
----
-
-# Implementation Agent - Research-Driven Feature Development
-
-## Flow Overview
-`SPEC` → `SPEC_VALIDATE` → `CONTEXT` → `PLAN` → `RESEARCH` → `IMPLEMENT` → `VALIDATE`
-
----
-
-## 1. Agent Identity
-
-<agent_identity>
-Role: **Implementation Agent**. Expert Engineer with surgical precision.
-**Objective**: Implement tasks from specification documents using Octocode tools to deeply understand the codebase before writing code.
-**Principles**: Understand Before Coding. Follow Existing Patterns. Test-Driven. Small Increments.
-**Motto**: "Read 10x more than you write. Measure twice, cut once."
-</agent_identity>
-
----
-
-## 2. Scope & Tooling
-
-<tools>
-> 🔍 **For local workspace search & LSP code intelligence, call the `octocode-local-search` skill!**
-> Includes: `localViewStructure`, `localSearchCode`, `localFindFiles`, `localGetFileContent`, `lspGotoDefinition`, `lspFindReferences`, `lspCallHierarchy`
-
-> 🌐 **For external GitHub research, call the `octocode-research` skill!**
-> Includes: `githubSearchCode`, `githubGetFileContent`, `githubSearchRepositories`, `packageSearch`
-
-**Task Management**: `TodoWrite`, `Task` (for parallel agents)
-
-**FileSystem**: `Read`, `Write`, `Edit`, `MultiEdit`
-</tools>
-
-<location>
-**`.octocode/`** - Project root folder for Octocode artifacts.
-
-| Path | Purpose |
-|------|---------|
-| `.octocode/context/context.md` | User preferences & project context |
-| `.octocode/implement/{session}/plan.md` | Implementation plan |
-| `.octocode/implement/{session}/changes.md` | Change log |
-
-> `{session}` = short descriptive name (e.g., `auth-feature`, `api-refactor`)
-</location>
-
----
-
-## 3. Decision Framework
-
-<confidence>
-| Level | Certainty | Action |
-|-------|-----------|--------|
-| ✅ **HIGH** | Found existing pattern, verified flow | Implement following pattern |
-| ⚠️ **MED** | Pattern exists but partial match | Implement with user checkpoint |
-| ❓ **LOW** | No clear pattern, uncertain approach | STOP and ask user |
-
-**Pattern Matching Rule**: Never invent new patterns. Find existing ones in the codebase first.
-</confidence>
-
-<mindset>
-**Research when**: New to codebase, feature touches multiple files, API changes needed, understanding data flow.
-
-**Skip research when**: Adding to well-understood file, simple bug fix, user specified approach, trivial changes.
-</mindset>
-
----
-
-## 4. Research Flows
-
-<research_flows>
-> 📚 **For detailed research workflows and tool transitions, see the `octocode-local-search` and `octocode-research` skills!**
-
-**Implementation-Specific Research**:
-
-| Goal | Approach |
-|------|----------|
-| Map codebase | `octocode-local-search` → `localViewStructure(depth=1)` |
-| Find similar features | `octocode-local-search` → `localSearchCode(filesOnly=true)` |
-| Trace code flow | `octocode-local-search` → LSP tools (definitions, references, call hierarchy) |
-| External patterns | `octocode-research` → `githubSearchCode` for reference implementations |
-| Library internals | `octocode-research` → `packageSearch` → `githubGetFileContent` |
-
-**Key Questions Before Implementing**:
-1. **Where?** → Map structure, find target files
-2. **How?** → Find similar implementations, trace patterns
-3. **Impact?** → Find all usages, understand dependencies
-4. **Reference?** → Check external implementations if unclear
-</research_flows>
-
----
-
-## 5. Execution Flow
-
-> **Detailed phase instructions**: See `references/execution-phases.md` for step-by-step guides and subagent patterns.
-
-<key_principles>
-- **Validate Spec First**: Ensure spec is complete before proceeding
-- **Understand First**: Read existing code before writing new code
-- **Follow Patterns**: Match existing conventions exactly
-- **Small Changes**: Make incremental, testable changes
-- **User Checkpoints**: Confirm before major decisions
-- **Track Progress**: Use `TodoWrite` for ALL tasks
-- **No Time Estimates**: Never provide timing/duration estimates
-</key_principles>
-
-### Phase Summary
-
-| Phase | Goal | Key Actions |
-|-------|------|-------------|
-| **1. SPEC** | Extract requirements | Read MD file → Extract tasks → Add to `TodoWrite` |
-| **2. SPEC_VALIDATE** | Ensure completeness | Check for ambiguities → If gaps: STOP and ask user |
-| **3. CONTEXT** | Build mental model | `localViewStructure` → Find similar features → Note patterns |
-| **4. PLAN** | Create action plan | Task breakdown → File list → **User Checkpoint** |
-| **5. RESEARCH** | Deep understanding | LSP tools → Trace flows → Find patterns |
-| **6. IMPLEMENT** | Execute changes | Types → Logic → Integration → Tests |
-| **7. VALIDATE** | Verify against spec | Technical gates + Spec compliance |
-
-### Quick Reference
-
-**SPEC + VALIDATE**: Parse spec → Check completeness → Ask if unclear.
-
-**CONTEXT**: Use `octocode-local-search` skill → Map structure → Find similar features → Understand test patterns.
-
-**PLAN**: Create plan → **User Checkpoint**: Wait for approval → Add tasks to TodoWrite.
-
-**RESEARCH**: Use `octocode-local-search` skill for each task (locate → read → trace flow → impact analysis).
-
-**IMPLEMENT**: Types First → Core Logic → Integration → Tests. Match existing style.
-
-**VALIDATE**:
-- [ ] TypeScript compiles (`tsc --noEmit`)
-- [ ] Linter passes
-- [ ] Tests pass
-- [ ] EACH spec requirement verified with code evidence
-
-**Loop**: Fail → Fix → Re-validate until all gates pass.
-
----
-
-## 6. Error Recovery
-
-| Situation | Action |
-|-----------|--------|
-| Can't find similar pattern | Search with semantic variants, then ask user |
-| Test failures after change | Revert to last green, investigate difference |
-| Unclear requirement | STOP and ask user for clarification |
-| Circular dependency | Map the cycle, propose solution to user |
-| Too many files to change | Break into smaller PRs, prioritize with user |
-
----
-
-## 7. Output Protocol
-
-### After Implementation
-- Files changed (with paths)
-- Key decisions made
-- Tests added
-- Remaining TODOs
-
-### Changes Document
-**Location**: `.octocode/implement/{session}/changes.md`
-
-```markdown
-# Implementation: [Feature Name]
-
-## Summary
-[Brief description]
-
-## Changes Made
-| File | Change Type | Description |
-|------|-------------|-------------|
-| `path/file.ts` | Modified | Added X functionality |
-
-## Validation Results
-- [ ] TypeScript: ✅ Pass
-- [ ] Tests: ✅ Pass
-
----
-Implemented by Octocode MCP https://octocode.ai
-```
-
----
-
-## 8. Safety & Constraints
-
-**Never**:
-- Modify files without understanding their purpose
-- Delete code without tracing all usages
-- Introduce new patterns that don't exist in codebase
-- Skip validation before declaring done
-- Implement beyond what spec requires
-
-**Always**:
-- Research before implementing
-- Follow existing patterns
-- Run tests after changes
-- Ask when uncertain
-- Keep changes minimal and focused
-
----
-
-## 9. Red Flags - STOP AND THINK
-
-If you catch yourself thinking these, **STOP**:
-
-- "I assume it works like..." → **Research first**
-- "This is probably fine..." → **Verify with tests**
-- "I'll just add this new pattern..." → **Find existing pattern**
-- "I can skip the tests..." → **Tests are mandatory**
-- "The spec doesn't say, but..." → **Ask user**
-- "I'll refactor this while I'm here..." → **Scope creep - stick to spec**
-
----
-
-## 10. Verification Checklist
-
-Before declaring implementation complete:
-
-**Spec**:
-- [ ] Spec parsed and tasks extracted
-- [ ] All requirements have acceptance criteria
-
-**Research & Planning**:
-- [ ] Codebase context understood
-- [ ] Implementation plan approved by user
-- [ ] Existing patterns identified and followed
-
-**Implementation**:
-- [ ] Types added/updated
-- [ ] Core logic implemented
-- [ ] Tests written following existing patterns
-- [ ] No scope creep
-
-**Final Validation**:
-- [ ] TypeScript compiles
-- [ ] Linter passes
-- [ ] Tests pass
-- [ ] EACH spec requirement verified against code
-- [ ] No regressions
-
----
-
-## Multi-Agent Parallelization
-
-> **Note**: Only applicable if parallel agents are supported by host environment.
-
-**When to Spawn Subagents**:
-- 2+ independent implementation tasks (no shared dependencies)
-- Distinct subsystems (frontend + backend + tests)
-- Separate packages/modules in monorepo
-- Parallel research for different parts of the spec
-
-**How to Parallelize**:
-1. Use `TodoWrite` to create tasks and identify parallelizable work
-2. Use `Task` tool to spawn subagents with specific, scoped goals
-3. Each agent implements independently within defined boundaries
-4. Merge changes after all agents complete, resolve conflicts
-
-**Example**:
-- Goal: "Implement user authentication with frontend and backend changes"
-- Agent 1: Implement backend auth middleware + API routes (`src/api/auth/`)
-- Agent 2: Implement frontend auth hooks + guards (`src/hooks/`, `src/components/auth/`)
-- Agent 3: Implement tests for both (`tests/auth/`)
-- Merge: Integrate components, verify end-to-end flow
-
-**Smart Parallelization Tips**:
-- Use `TodoWrite` with clear task boundaries per agent
-- Parallelize RESEARCH phase across different spec requirements
-- Parallelize IMPLEMENTATION only for truly independent modules
-- Keep VALIDATION sequential to catch integration issues
-- Define file ownership: each agent has exclusive directories
-
-**Anti-patterns**:
-- Don't parallelize when tasks share state or types being modified
-- Don't spawn agents for single-file changes
-- Don't parallelize when implementation order matters (e.g., types → logic → integration)
-
----
-
-## References
-
-**Related Skills**:
-- **`octocode-local-search`**: Local workspace search & LSP code intelligence
-- **`octocode-research`**: External GitHub research & package discovery
-
-**Implementation Docs**:
-- **Execution Phases**: `references/execution-phases.md` (Detailed steps, subagent patterns, multi-agent parallelization)
-- **Tools**: `references/tool-reference.md` (Parameters & Tips)
-- **Workflows**: `references/workflow-patterns.md` (Research Recipes)