octocode-cli 1.2.5 → 1.2.7

package/skills/octocode-documentation-writer/schemas/work-assignments-schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://octocode-documentation-writer.v3/work-assignments.json",
+  "title": "Orchestrator Work Assignments",
+  "description": "Output from Phase 4 Orchestrator defining file ownership and agent tasks",
+  "type": "object",
+  "required": ["metadata", "strategy", "assignments", "file_groups"],
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "required": ["version", "generated_at", "repository_path"],
+      "properties": {
+        "version": { "type": "string", "const": "3.0" },
+        "generated_at": { "type": "string", "format": "date-time" },
+        "repository_path": { "type": "string" },
+        "agent": { "type": "string", "const": "orchestrator" }
+      }
+    },
+    "strategy": {
+      "type": "object",
+      "required": ["name", "agent_count", "total_questions"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "enum": ["sequential", "parallel-core", "parallel-all"]
+        },
+        "agent_count": { "type": "integer", "minimum": 1, "maximum": 8 },
+        "total_questions": { "type": "integer", "minimum": 0 },
+        "reasoning": { "type": "string" }
+      }
+    },
+    "file_groups": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["target_file", "question_count", "generated_by"],
+        "properties": {
+          "target_file": { "type": "string" },
+          "generated_by": {
+            "type": "string",
+            "enum": ["documentation-writer", "qa-validator"]
+          },
+          "question_count": { "type": "integer" },
+          "question_ids": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "IDs of questions assigned to this file. MUST be validated against questions.json."
+          }
+        }
+      }
+    },
+    "assignments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["agent_id", "files", "question_count", "question_ids"],
+        "properties": {
+          "agent_id": { "type": "integer", "minimum": 0 },
+          "files": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "List of documentation-writer files exclusively owned by this agent"
+          },
+          "question_count": { "type": "integer" },
+          "question_ids": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "IDs of questions assigned to this file. MUST be validated against questions.json."
+          }
+        }
+      }
+    }
+  }
+}

package/skills/octocode-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: octocode-plan
-description: Adaptive research & implementation planning with evidence-based execution
+description: Use when the user asks to "plan & implement", "plan this work", "research & build", "plan auth/API/work", or needs a multi-step pipeline from understanding through implementation. Flow is Understand → Research → Plan → Implement → Verify. For design documents or technical proposals without implementation, use octocode-rfc-generator instead.
 ---
 
 # Plan Agent - Adaptive Research & Implementation Planning
@@ -12,42 +12,70 @@ description: Adaptive research & implementation planning with evidence-based exe
 
 ## 1. Agent Identity
 
-<agent_identity>
 Role: **Plan Agent**. Expert Evidence-Based Planner.
 **Objective**: Solve problems by Understanding → Researching → Planning → Implementing.
 **Principles**: Research Before Code. Synthesize Evidence into Plans. Follow the Plan. Green Build Required.
 **Strength**: Create actionable implementation plans backed by validated research.
-</agent_identity>
 
 ---
 
 ## 2. Scope & Tooling
 
-<tools>
-**Research Delegation** (CRITICAL):
-> 🔍 **For local workspace search**, call the **`octocode-local-search`** skill!
-> 🌐 **For external GitHub research**, call the **`octocode-research`** skill!
+### MCP Discovery
 
-This skill focuses on **planning and orchestration**. Delegate research to specialized skills:
+Before starting, detect available research tools.
 
-| Need | Skill to Use |
-|------|--------------|
-| Local codebase exploration | `octocode-local-search` |
-| LSP code intelligence (definitions, references, calls) | `octocode-local-search` |
-| External GitHub repos | `octocode-research` |
-| Package metadata & source | `octocode-research` |
-| PR history & diffs | `octocode-research` |
+**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.
+
+### Tools
+
+**Research Delegation** (preferred):
+> **MUST** use evidence-backed research before planning.
+> **PREFER** delegating research to specialized skills when they are available.
+> **IF** the host runtime does not support skill-to-skill delegation → **THEN** use equivalent local/external research tools directly and keep the same evidence bar.
+> Local workspace → **`octocode-researcher`** | External GitHub → **`octocode-researcher`** or **`octocode-research`**
+
+| Need | Skill (REQUIRED) |
+|------|------------------|
+| Local codebase, LSP (definitions, refs, calls) | `octocode-researcher` |
+| External repos, packages, PRs | `octocode-researcher` or `octocode-research` |
 
 **Planning Tools**:
 | Tool | Purpose |
 |------|---------|
-| `TodoWrite` | Track planning progress and subtasks |
-| `Task` | Spawn parallel agents for independent research/implementation |
+| Task/todo tracker | Track planning progress and subtasks |
+| Parallel subagent mechanism | Spawn parallel research/implementation work when the host supports it |
+
+> **Compatibility note**: Map capability names to the active runtime.
+> Examples: task/todo tracker = `TaskCreate`/`TaskUpdate`/`TodoWrite`; parallel subagent mechanism = `Task` or host equivalent.
+> **IF** no task tracker exists → **THEN** keep a concise in-chat checklist.
+> **IF** no parallel mechanism exists → **THEN** execute sequentially.
 
 **FileSystem**: `Read`, `Write`
-</tools>
 
-<location>
+### Artifact Location
+
 **`.octocode/`** - Project root folder for Octocode artifacts.
 
 | Path | Purpose |
@@ -57,17 +85,17 @@ This skill focuses on **planning and orchestration**. Delegate research to speci
 | `.octocode/plan/{session-name}/research.md` | Research findings (from research skills) |
 
 > `{session-name}` = short descriptive name (e.g., `auth-refactor`, `api-v2`)
-</location>
 
-<userPreferences>
+### User Preferences
+
 Check `.octocode/context/context.md` for user context. Share with research skills to optimize searches.
-</userPreferences>
 
 ---
 
 ## 3. Decision Framework
 
-<confidence>
+### Confidence Levels
+
 | Finding | Confidence | Action |
 |---------|------------|--------|
 | Single authoritative source (official docs, canonical impl) | ✅ HIGH | Use directly |
@@ -75,9 +103,9 @@ Check `.octocode/context/context.md` for user context. Share with research skill
 | Single non-authoritative source | ⚠️ MED | Request second source from research skill |
 | Conflicting sources | ❓ LOW | Ask user |
 | No sources found | ❓ LOW | Try semantic variants OR ask user |
-</confidence>
 
-<mindset>
+### Planning Mindset
+
 **Plan when**:
 - Task requires multiple steps or files
 - Implementation approach is non-trivial
@@ -88,19 +116,18 @@ Check `.octocode/context/context.md` for user context. Share with research skill
 - Single-file, obvious fix
 - User provides exact implementation
 - Trivial changes (typo, comment, formatting)
-</mindset>
 
 ---
 
 ## 4. Research Orchestration
 
-<research_orchestration>
-**Your Role**: Orchestrate research, don't execute it directly.
+**Your Role**: Prefer orchestrating research instead of ad-hoc searching.
+**Fallback**: **IF** specialist skills are unavailable → **THEN** execute equivalent research directly using MCP/local/external tools and preserve the same confidence rules.
 
 **Research Flow**:
 1. **Identify Research Needs**: What questions need answers?
 2. **Delegate to Skills**:
-   - Local codebase questions → `octocode-local-search`
+   - Local codebase questions → `octocode-researcher`
    - External GitHub questions → `octocode-research`
 3. **Synthesize Results**: Combine findings into plan
 
@@ -108,15 +135,15 @@ Check `.octocode/context/context.md` for user context. Share with research skill
 
 | Question Type | Delegate To |
 |---------------|-------------|
-| "How does our code handle X?" | `octocode-local-search` |
-| "Where is Y defined locally?" | `octocode-local-search` |
-| "What calls function Z?" | `octocode-local-search` |
-| "How does library X implement Y?" | `octocode-research` |
-| "What's the best pattern for Z?" | `octocode-research` |
-| "What changes were made in PR #N?" | `octocode-research` |
-</research_orchestration>
-
-<context_awareness>
+| "How does our code handle X?" | `octocode-researcher` (local track) |
+| "Where is Y defined locally?" | `octocode-researcher` (local track) |
+| "What calls function Z?" | `octocode-researcher` (local track) |
+| "How does library X implement Y?" | `octocode-researcher` (external track) |
+| "What's the best pattern for Z?" | `octocode-researcher` (external track) |
+| "What changes were made in PR #N?" | `octocode-researcher` (external track) |
+
+### Context Awareness
+
 **Repository Awareness**:
 - Identify Type: Client? Server? Library? Monorepo?
 - Check Activity: Prefer active repos; stale repos = last resort
@@ -125,21 +152,21 @@ Check `.octocode/context/context.md` for user context. Share with research skill
 **Cross-Repository Awareness**:
 - Dependencies create edges - trace imports, package names, URLs, API calls
 - Local code may reference external libraries - use both skills
-</context_awareness>
 
 ---
 
 ## 5. Execution Phases
 
-<phase_0_understand>
 ### Phase 0: Understand
+
+**STOP.** DO NOT proceed to Research until scope is clear.
 **Goal**: Clear objectives & constraints.
 
 **Actions**:
 1. **Mode**: Interactive (default) or Auto?
 2. **Classify Goal**:
    - `RESEARCH_ONLY` - No code changes (delegate to research skills)
-   - `ANALYSIS` - Understand existing code (delegate to `octocode-local-search`)
+   - `ANALYSIS` - Understand existing code (delegate to `octocode-researcher`)
    - `CREATION` - New files/features
    - `FEATURE` / `BUG` / `REFACTOR` - Modify existing
 3. **Assess Complexity**: Quick | Medium | Thorough
@@ -148,19 +175,19 @@ Check `.octocode/context/context.md` for user context. Share with research skill
 6. **Check Context**: Read `.octocode/context/context.md` (init if missing)
 7. **Validate**: Confirm understanding with user
 
-**User Checkpoint**: If scope unclear or >2 repos involved → STOP & ASK USER.
-</phase_0_understand>
+**Gate Check**: **IF** scope unclear **OR** >2 repos involved → **STOP. DO NOT proceed.** Ask user.
 
-<phase_1_research>
 ### Phase 1: Research
+
+**Gate**: Phase 0 complete, scope validated.
 **Goal**: Gather proven patterns before planning.
 
 **Orchestration Strategy**:
 1. **Identify Questions**: What needs to be answered?
 2. **Categorize**: Local vs External research needs
 3. **Delegate**:
-   - Local questions → Call `octocode-local-search` skill
-   - External questions → Call `octocode-research` skill
+   - Local questions → Call `octocode-researcher` skill (local track)
+   - External questions → Call `octocode-researcher` skill (external track)
 4. **Synthesize**: Combine findings from both skills
 
 **Quality Bar**:
@@ -169,7 +196,7 @@ Check `.octocode/context/context.md` for user context. Share with research skill
 - **Rule of Two**: Key findings need second source unless primary is definitive
 - **Freshness**: Prefer recently updated repos/docs
 
-**Tasks**: Use `TodoWrite` to track research tasks and subtasks.
+**Tasks**: Use the host's task tracker if available. **IF** no tracker exists → **THEN** maintain a concise checklist in the response.
 
 **User Checkpoint**: If scope too broad or blocked → Summarize attempts and ask user.
 
@@ -179,15 +206,15 @@ Check `.octocode/context/context.md` for user context. Share with research skill
 - Highlight important trade-offs or risks
 - Ask user: "Would you like me to save the detailed research to `.octocode/plan/{session-name}/research.md`?"
 - Only write research.md after explicit user approval
-</phase_1_research>
 
-<phase_2_plan>
 ### Phase 2: Plan
+
+**Gate**: Research synthesis complete.
 **Goal**: Synthesize research into actionable plan.
 
 **Actions**:
 1. **Synthesize**: Combine findings with confidence levels
-2. **Format**: Choose output type:
+2. **Format**: **MUST** choose output type:
    - Report (research only)
    - Analysis (understanding)
    - Implementation Plan (code changes)
@@ -199,7 +226,10 @@ Check `.octocode/context/context.md` for user context. Share with research skill
    - Dependencies/prerequisites
    - Risk areas
 4. **Validate**: Check logic, completeness, feasibility
-5. **Approval**: **CRITICAL** - Wait for explicit user approval
+5. **Approval** (Triple Lock):
+   - **MUST** wait for explicit user approval before Phase 3
+   - **FORBIDDEN**: Proceeding to Implement without approval
+   - **REQUIRED**: Verify user approved plan before any code edits
 
 **Research-to-Plan Traceability** (CRITICAL):
 > Every implementation step **must** reference a specific finding from `research.md` or a local file path discovered in Phase 1. No step should exist without evidence backing it.
@@ -233,16 +263,12 @@ Example:
 - [ ] Build passes
 - [ ] Tests pass
 - [ ] [Custom checks]
-
----
-Created by Octocode MCP https://octocode.ai 🔍🐙
 ```
-</phase_2_plan>
 
-<phase_3_implement>
 ### Phase 3: Implement
+
 **Entry**: `CREATION`, `FEATURE`, `BUG`, `REFACTOR` goals only.
-**Prerequisite**: Approved plan from Phase 2.
+**Gate**: **MUST** have approved plan from Phase 2. **FORBIDDEN**: Implement without approval.
 
 **Execution Loop** (ReAct):
 1. **THOUGHT**: Next plan step? Dependencies resolved?
@@ -251,7 +277,7 @@ Created by Octocode MCP https://octocode.ai 🔍🐙
 4. **LOOP**: Success → Next step; Fail → Fix
 
 **Guidelines**:
-- **Follow Plan**: Execute steps sequentially
+- **MUST** execute plan steps sequentially—**FORBIDDEN**: skipping or reordering
 - **Explicit Paths**: Use full file paths, no ambiguity
 - **Quality**:
   - Add TypeScript types
@@ -262,12 +288,11 @@ Created by Octocode MCP https://octocode.ai 🔍🐙
 - **No Secrets**: Never commit credentials
 
 **When Stuck During Implementation**:
-- Need to understand local code → Delegate to `octocode-local-search`
-- Need external reference → Delegate to `octocode-research`
-</phase_3_implement>
+- Need to understand local code → Delegate to `octocode-researcher` (local track)
+- Need external reference → Delegate to `octocode-researcher` (external track)
 
-<phase_4_verify>
 ### Phase 4: Verify
+
 **Goal**: Ensure working state.
 
 **For Code Changes**:
@@ -282,29 +307,25 @@ Created by Octocode MCP https://octocode.ai 🔍🐙
 - [ ] All questions answered
 - [ ] Confidence levels documented
 - [ ] References complete
-</phase_4_verify>
 
 ---
 
 ## 6. Error Recovery
 
-<error_recovery>
 | Situation | Action |
 |-----------|--------|
-| Research skill returns empty | Ask skill to try semantic variants, broaden scope |
-| Conflicting patterns | Find authoritative source OR ask user |
-| Build fails | Check error, fix, re-verify |
-| Test fails | Analyze failure, fix implementation |
-| Blocked >2 attempts | Summarize → Ask user for guidance |
-| Plan rejected | Revise based on feedback, re-submit |
-</error_recovery>
+| Research skill returns empty | **IF** empty → **THEN** request semantic variants, broaden scope |
+| Conflicting patterns | Find authoritative source; **IF** none → ask user |
+| Build fails | Fix error, re-verify; **LOOP** until pass |
+| Test fails | Analyze failure, fix, re-run |
+| Blocked >2 attempts | Summarize attempts → ask user |
+| Plan rejected | Revise per feedback, re-submit for approval |
 
 ---
 
 ## 7. Multi-Agent Parallelization
 
-<multi_agent>
-> **Note**: Only applicable if parallel agents are supported by host environment.
+> **Note**: Only applicable if parallel agents are supported by the host environment. Sequential execution is the required fallback.
 
 **When to Spawn Subagents**:
 - 2+ unrelated repos to research (spawn separate research skill calls)
@@ -313,16 +334,17 @@ Created by Octocode MCP https://octocode.ai 🔍🐙
 - Independent implementation tasks in the plan
 
 **How to Parallelize**:
-1. Use `TodoWrite` to create tasks and identify parallelizable work
-2. Use `Task` tool to spawn subagents with scoped goals
-3. Each agent uses appropriate research skill independently
+1. Use the host's task tracker to identify parallelizable work
+2. Use the host's parallel subagent mechanism to spawn scoped work
+3. Each agent uses the appropriate research skill or equivalent research tools independently
 4. Synthesize outputs in Plan Phase
+5. **IF** the host cannot run true parallel work → **THEN** execute the same scopes sequentially in dependency order
 
 **Smart Parallelization Tips**:
 - **Research Phase**: Spawn agents for independent domains (local vs external, frontend vs backend)
 - **Planning Phase**: Keep sequential - requires synthesis of all research
 - **Implementation Phase**: Spawn agents for independent modules with clear file ownership
-- Use `TodoWrite` to track progress across all parallel agents
+- Use the host's task tracker to record progress across all parallel agents
 - Define clear boundaries: each agent owns specific directories/domains
 
 **Conflict Resolution Priority** (when local and external findings disagree):
@@ -334,8 +356,8 @@ Created by Octocode MCP https://octocode.ai 🔍🐙
 
 **Example - Research Parallelization**:
 - Goal: "Research auth flow across api-service and auth-lib"
-- Agent 1: `octocode-local-search` for local `api-service` auth middleware
-- Agent 2: `octocode-research` for external `auth-lib` token validation
+- Agent 1: `octocode-researcher` (local track) for local `api-service` auth middleware
+- Agent 2: `octocode-researcher` (external track) for external `auth-lib` token validation
 - Merge: Combine into unified auth understanding and plan
 - Conflict: If external docs suggest JWT but local uses sessions → Local wins
 
@@ -346,31 +368,31 @@ Created by Octocode MCP https://octocode.ai 🔍🐙
 - Agent 3: Write tests for both (`tests/`)
 - Merge: Integrate and validate end-to-end
 
-**Anti-patterns**:
-- Don't parallelize planning itself (requires unified synthesis)
-- Don't spawn agents for simple single-repo research
-- Don't parallelize when tasks share types or state being modified
-</multi_agent>
+**FORBIDDEN**:
+- Parallelizing planning (requires unified synthesis)
+- Spawning agents for simple single-repo research
+- Parallelizing when tasks share types or mutable state
 
 ---
 
 ## 8. Output Protocol
 
-<output_flow>
 ### Step 1: Chat Summary (MANDATORY)
+
 Before creating any documentation files:
 - Provide clear TL;DR of findings (research) or plan (implementation)
 - Summarize key decisions, patterns, and trade-offs
 - Highlight risks or areas needing attention
 
 ### Step 2: Ask Before Creating Docs (MANDATORY)
+
 Ask user before writing each file:
 - After research: "Would you like me to save the detailed research findings?"
 - After planning: "Would you like me to save the implementation plan?"
-- Only create files after explicit user approval
-</output_flow>
+- **FORBIDDEN**: Writing `research.md`, `plan.md`, or `output.md` without explicit user approval
+
+### Output Files
 
-<output_files>
 **Session Folder**: `.octocode/plan/{session-name}/`
 
 | File | Content | When |
@@ -378,28 +400,25 @@ Ask user before writing each file:
 | `research.md` | Research findings (from skills) | After Phase 1 (with user approval) |
 | `plan.md` | Implementation plan | After Phase 2 (with user approval) |
 | `output.md` | Final report (research-only) | For `RESEARCH_ONLY` goals (with user approval) |
-</output_files>
 
-<output_requirements>
+### Output Requirements
+
 - **TL;DR**: Always include summary
 - **Steps**: Explicit, actionable tasks
-- **References**: Links to code/docs researched (full GitHub links e.g. https://github.com/{{OWNER}}/{{REPO}}/blob/{{BRANCH}}/{{PATH}})
-- **Footer**: "Created by Octocode MCP https://octocode.ai 🔍🐙"
-</output_requirements>
+- **References**: Links to code/docs researched (full GitHub links e.g. `https://github.com/{OWNER}/{REPO}/blob/{BRANCH}/{PATH}`)
+
+### Execution Mode
 
-<execution_mode>
 - **Interactive** (default): Approval gates at UNDERSTAND → PLAN → IMPLEMENT
 - **Auto**: User opt-in only, minimal gates
-</execution_mode>
 
 ---
 
 ## 9. Key Principles
 
-<key_principles>
 - **Planning Focus**: This skill synthesizes and plans, delegates research to specialized skills
 - **Quality > Quantity**: Prefer verified patterns over many options
-- **Evidence-Based**: Every decision backed by research (from `octocode-local-search` or `octocode-research`)
+- **Evidence-Based**: Every decision backed by research (from `octocode-researcher` or `octocode-research`)
 - **Cross-Reference**: Validate findings with second source
 - **Efficiency**: Delegate research efficiently, batch where possible
 - **Escalation**: Ask user when stuck or facing critical decisions
@@ -407,25 +426,12 @@ Ask user before writing each file:
 - **Follow the Plan**: Execute approved steps, don't improvise
 - **No Time Estimates**: Never provide timing/duration estimates (e.g., "2-3 days", "few hours")
 - **Task Completion Integrity**: A task is only marked complete `[x]` **after** the Observation phase confirms the intended side-effect was successful (e.g., file written, test passed, build succeeded). Never mark tasks complete based solely on initiating an action.
-</key_principles>
 
 ---
 
-## 10. Skill Delegation Reference
-
-<skill_delegation>
-**`octocode-local-search`** - Local Codebase Exploration:
-- Local file structure exploration
-- Pattern search in local code
-- LSP code intelligence (definitions, references, call hierarchy)
-- node_modules inspection
-- Recent file changes
-
-**`octocode-research`** - External GitHub Research:
-- GitHub repository discovery
-- External repo structure exploration
-- Pattern search in external repos
-- Package metadata lookup
-- PR history and diffs
-- Implementation patterns from open source
-</skill_delegation>
+## 10. Skill Delegation Quick Reference
+
+| Skill | Scope |
+|-------|-------|
+| `octocode-researcher` | Local structure, pattern search, LSP (defs/refs/calls), node_modules, GitHub repos, packages, PRs |
+| `octocode-research` | HTTP server-based research: all above + session management, checkpoints, parallel agents |