micode 0.2.0 → 0.3.0

package/README.md

@@ -3,7 +3,11 @@
 [![CI](https://github.com/vtemian/micode/actions/workflows/ci.yml/badge.svg)](https://github.com/vtemian/micode/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/micode.svg)](https://www.npmjs.com/package/micode)
 
-OpenCode plugin with a structured Brainstorm → Research → Plan → Implement workflow.
+OpenCode plugin with a structured Brainstorm → Plan → Implement workflow.
+
+
+https://github.com/user-attachments/assets/85236ad3-e78a-4ff7-a840-620f6ea2f512
+
 
 ## Installation
 
@@ -17,12 +21,26 @@ Add to `~/.config/opencode/opencode.json`:
 
 **AI-assisted install:** Share [INSTALL_CLAUDE.md](./INSTALL_CLAUDE.md) with your AI assistant for guided setup.
 
+## Getting Started
+
+**Important:** Run `/init` first to generate project documentation:
+
+```
+/init
+```
+
+This creates `ARCHITECTURE.md` and `CODE_STYLE.md` which agents reference during brainstorming, planning, and implementation. Without these files, agents lack context about your codebase patterns.
+
 ## Workflow
 
 ```
-Brainstorm → Research → Plan → Implement → Review
+Brainstorm → Plan → Implement
+     ↓         ↓        ↓
+  research  research  executor
 ```
 
+Research subagents (codebase-locator, codebase-analyzer, pattern-finder) are spawned within brainstorm and plan phases - not as a separate step.
+
 ### 1. Brainstorm
 
 Refine rough ideas into fully-formed designs through collaborative questioning.
@@ -30,11 +48,10 @@ Refine rough ideas into fully-formed designs through collaborative questioning.
 - One question at a time
 - 2-3 approaches with trade-offs
 - Section-by-section validation
+- Spawns research subagents to understand codebase
 - Output: `thoughts/shared/designs/YYYY-MM-DD-{topic}-design.md`
 
-### 2. Research
-
-Parallel codebase investigation using specialized subagents:
+**Research subagents** (spawned in parallel):
 
 | Subagent | Purpose |
 |----------|---------|
@@ -42,19 +59,18 @@ Parallel codebase investigation using specialized subagents:
 | `codebase-analyzer` | Explain HOW code works (with file:line refs) |
 | `pattern-finder` | Find existing patterns to follow |
 
-Output: `thoughts/shared/research/YYYY-MM-DD-{topic}.md`
-
-### 3. Plan
+### 2. Plan
 
 Transform validated designs into comprehensive implementation plans.
 
+- Spawns research subagents for exact paths, signatures, patterns
 - Bite-sized tasks (2-5 minutes each)
 - Exact file paths, complete code examples
 - TDD workflow: failing test → verify fail → implement → verify pass → commit
 - Get human approval before implementing
 - Output: `thoughts/shared/plans/YYYY-MM-DD-{topic}.md`
 
-### 4. Implement
+### 3. Implement
 
 Execute plan in git worktree for isolation:
 
@@ -62,12 +78,91 @@ Execute plan in git worktree for isolation:
 git worktree add ../{feature} -b feature/{feature}
 ```
 
-- **Executor** orchestrates the implement → review cycle automatically
-- Spawns Implementer → waits → spawns Reviewer → loops if changes requested
-- Maximum 3 cycles before escalating to human
-- Commit with descriptive messages when approved
+The **Executor** orchestrates task execution with intelligent parallelization:
+
+#### How It Works
+
+1. **Parse** - Extract individual tasks from the plan
+2. **Analyze** - Build dependency graph between tasks
+3. **Batch** - Group independent tasks for parallel execution
+4. **Execute** - Run implementer→reviewer cycle per task
+5. **Aggregate** - Collect results and report status
+
+#### Dependency Analysis
+
+Tasks are grouped into batches based on their dependencies:
+
+```
+Independent tasks (can parallelize):
+- Modify different files
+- Don't depend on each other's output
+- Don't share state
+
+Dependent tasks (must be sequential):
+- Task B modifies a file Task A creates
+- Task B imports something Task A defines
+- Task B's test relies on Task A's implementation
+```
+
+#### Parallel Execution
+
+Within a batch, all tasks run concurrently by spawning multiple subagents in a single message:
+
+```
+Plan with 6 tasks:
+├── Batch 1 (parallel): Tasks 1, 2, 3 → independent, different files
+│   ├── implementer: task 1 ─┐
+│   ├── implementer: task 2 ─┼─ spawn in ONE message
+│   └── implementer: task 3 ─┘
+│   [wait for all]
+│   ├── reviewer: task 1 ─┐
+│   ├── reviewer: task 2 ─┼─ spawn in ONE message
+│   └── reviewer: task 3 ─┘
+│   [wait for all]
+│
+└── Batch 2 (parallel): Tasks 4, 5, 6 → depend on batch 1
+    └── [same pattern]
+```
+
+#### Per-Task Cycle
+
+Each task gets its own implement→review loop:
+
+1. Spawn implementer with task details
+2. Spawn reviewer to check implementation
+3. If changes requested → re-spawn implementer (max 3 cycles)
+4. Mark as DONE or BLOCKED
+
+#### Example Output
+
+```
+## Execution Complete
+
+**Plan**: thoughts/shared/plans/2024-01-15-auth-feature.md
+**Total tasks**: 6
+**Batches**: 2
+
+### Dependency Analysis
+- Batch 1 (parallel): Tasks 1, 2, 3 - independent, no shared files
+- Batch 2 (parallel): Tasks 4, 5, 6 - depend on batch 1
+
+### Results
+
+| Task | Status | Cycles | Notes |
+|------|--------|--------|-------|
+| 1 | ✅ DONE | 1 | |
+| 2 | ✅ DONE | 2 | Fixed type error |
+| 3 | ✅ DONE | 1 | |
+| 4 | ✅ DONE | 1 | |
+| 5 | ❌ BLOCKED | 3 | Test assertion failing |
+| 6 | ✅ DONE | 1 | |
+
+### Summary
+- Completed: 5/6 tasks
+- Blocked: 1 task needs human intervention
+```
 
-### 5. Handoff
+### 4. Handoff
 
 Save/resume session state for continuity:
 

package/dist/index.js

@@ -16,6 +16,7 @@ var brainstormerAgent = {
   mode: "primary",
   model: "anthropic/claude-opus-4-5",
   temperature: 0.7,
+  tools: { ask: true },
   prompt: `<purpose>
 Turn ideas into fully formed designs through natural collaborative dialogue.
 This is DESIGN ONLY. The planner agent handles detailed implementation plans.
@@ -699,93 +700,149 @@ Check correctness and style. Be specific. Run code, don't just read.
 
 // src/agents/executor.ts
 var executorAgent = {
-  description: "Executes plan then reviews - orchestrates implementer and reviewer",
+  description: "Executes plan task-by-task with parallel execution where possible",
   mode: "subagent",
   model: "anthropic/claude-opus-4-5",
   temperature: 0.2,
   prompt: `<purpose>
-Execute the plan completely: implement then review.
-You orchestrate the implementer and reviewer subagents.
+Execute plan tasks with maximum parallelism.
+Each task gets its own implementer \u2192 reviewer cycle.
+Detect and parallelize independent tasks.
 </purpose>
 
 <workflow>
-<step>Spawn implementer with the plan</step>
-<step>Wait for implementer to complete</step>
-<step>Spawn reviewer to check the implementation</step>
-<step>If reviewer requests changes: spawn implementer again with fixes</step>
-<step>Repeat until reviewer approves or issues are blocking</step>
-<step>Report final status</step>
+<step>Parse plan to extract individual tasks</step>
+<step>Analyze task dependencies to build execution graph</step>
+<step>Group tasks into parallel batches (independent tasks run together)</step>
+<step>For each batch: spawn implementer \u2192 reviewer per task IN PARALLEL</step>
+<step>Wait for batch to complete before starting dependent batch</step>
+<step>Aggregate results and report</step>
 </workflow>
 
+<dependency-analysis>
+Tasks are INDEPENDENT (can parallelize) when:
+- They modify different files
+- They don't depend on each other's output
+- They don't share state
+
+Tasks are DEPENDENT (must be sequential) when:
+- Task B modifies a file that Task A creates
+- Task B imports/uses something Task A defines
+- Task B's test relies on Task A's implementation
+- Plan explicitly states ordering
+
+When uncertain, assume DEPENDENT (safer).
+</dependency-analysis>
+
+<execution-pattern>
+Example: 9 tasks where tasks 1-3 are independent, 4-6 depend on 1-3, 7-9 depend on 4-6
+
+Batch 1 (parallel):
+  - Spawn implementer for task 1 \u2192 reviewer
+  - Spawn implementer for task 2 \u2192 reviewer
+  - Spawn implementer for task 3 \u2192 reviewer
+  [Wait for all to complete]
+
+Batch 2 (parallel):
+  - Spawn implementer for task 4 \u2192 reviewer
+  - Spawn implementer for task 5 \u2192 reviewer
+  - Spawn implementer for task 6 \u2192 reviewer
+  [Wait for all to complete]
+
+Batch 3 (parallel):
+  - Spawn implementer for task 7 \u2192 reviewer
+  - Spawn implementer for task 8 \u2192 reviewer
+  - Spawn implementer for task 9 \u2192 reviewer
+  [Wait for all to complete]
+</execution-pattern>
+
 <available-subagents>
-  <subagent name="implementer" spawn="sequential">
-    Executes implementation tasks from a plan.
-    Input: The plan or specific tasks to implement.
-    Output: List of changes made and verification results.
+  <subagent name="implementer" spawn="parallel-per-task">
+    Executes ONE task from the plan.
+    Input: Single task with context (which files, what to do).
+    Output: Changes made and verification results for that task.
   </subagent>
-  <subagent name="reviewer" spawn="sequential">
-    Reviews implementation for correctness and style.
-    Input: Implicitly reviews current state against plan.
-    Output: APPROVED or CHANGES REQUESTED with specific issues.
+  <subagent name="reviewer" spawn="parallel-per-task">
+    Reviews ONE task's implementation.
+    Input: Single task's changes against its requirements.
+    Output: APPROVED or CHANGES REQUESTED for that task.
   </subagent>
 </available-subagents>
 
+<per-task-cycle>
+For each task:
+1. Spawn implementer with task details
+2. Wait for implementer to complete
+3. Spawn reviewer to check that task
+4. If reviewer requests changes: re-spawn implementer for fixes
+5. Max 3 cycles per task before marking as blocked
+6. Report task status: DONE / BLOCKED
+</per-task-cycle>
+
+<parallel-spawning>
+Within a batch, spawn ALL implementers in a SINGLE message:
+
+Example for batch with tasks 1, 2, 3:
+- In ONE message, spawn:
+  - implementer: "Execute task 1: [details]"
+  - implementer: "Execute task 2: [details]"
+  - implementer: "Execute task 3: [details]"
+
+Then after all complete, in ONE message spawn:
+  - reviewer: "Review task 1 implementation"
+  - reviewer: "Review task 2 implementation"
+  - reviewer: "Review task 3 implementation"
+</parallel-spawning>
+
 <rules>
-<rule>ALWAYS spawn reviewer after implementer completes</rule>
-<rule>Never skip the review step</rule>
-<rule>If reviewer finds issues, spawn implementer to fix them</rule>
-<rule>Maximum 3 implement-review cycles before escalating</rule>
-<rule>Report blocking issues immediately - don't loop forever</rule>
+<rule>Parse ALL tasks from plan before starting execution</rule>
+<rule>ALWAYS analyze dependencies before parallelizing</rule>
+<rule>Spawn parallel tasks in SINGLE message for true parallelism</rule>
+<rule>Wait for entire batch before starting next batch</rule>
+<rule>Each task gets its own implement \u2192 review cycle</rule>
+<rule>Max 3 review cycles per task</rule>
+<rule>Continue with other tasks if one is blocked</rule>
 </rules>
 
-<on-reviewer-approved>
-Report success with summary of changes and verification status.
-</on-reviewer-approved>
-
-<on-reviewer-requests-changes>
-<action>Parse the specific issues from reviewer output</action>
-<action>Spawn implementer with the list of issues to fix</action>
-<action>After implementer completes, spawn reviewer again</action>
-<rule>Track cycle count - max 3 cycles</rule>
-</on-reviewer-requests-changes>
-
-<on-max-cycles-reached>
-<action>Report that implementation could not satisfy review after 3 attempts</action>
-<action>Include all outstanding issues from last review</action>
-<action>Request human guidance</action>
-</on-max-cycles-reached>
-
 <output-format>
 <template>
 ## Execution Complete
 
-**Status**: APPROVED / NEEDS HUMAN REVIEW
+**Plan**: [plan file path]
+**Total tasks**: [N]
+**Batches**: [M] (based on dependency analysis)
 
-**Cycles**: [N] implement-review cycles
+### Dependency Analysis
+- Batch 1 (parallel): Tasks 1, 2, 3 - independent, no shared files
+- Batch 2 (parallel): Tasks 4, 5 - depend on batch 1
+- Batch 3 (sequential): Task 6 - depends on task 5 specifically
 
-### Implementation Summary
-[From implementer output]
-- \`file:line\` - [what changed]
+### Results
 
-### Review Summary
-[From reviewer output]
-- Status: [APPROVED / issues remaining]
-- [Any outstanding issues]
+| Task | Status | Cycles | Notes |
+|------|--------|--------|-------|
+| 1 | \u2705 DONE | 1 | |
+| 2 | \u2705 DONE | 2 | Fixed type error on cycle 2 |
+| 3 | \u274C BLOCKED | 3 | Could not resolve: [issue] |
+| ... | | | |
 
-### Verification
-- [x] Tests pass
-- [x] Types check
-- [x] Review approved
+### Summary
+- Completed: [X]/[N] tasks
+- Blocked: [Y] tasks need human intervention
 
-**Next**: [Ready to commit / Needs human decision on: X]
+### Blocked Tasks (if any)
+**Task 3**: [description of blocker and last reviewer feedback]
+
+**Next**: [Ready to commit / Needs human decision on blocked tasks]
 </template>
 </output-format>
 
 <never-do>
-<forbidden>Never skip the review step</forbidden>
-<forbidden>Never report success without reviewer approval</forbidden>
-<forbidden>Never loop more than 3 times without escalating</forbidden>
-<forbidden>Never ignore reviewer feedback</forbidden>
+<forbidden>Never skip dependency analysis</forbidden>
+<forbidden>Never spawn dependent tasks in parallel</forbidden>
+<forbidden>Never skip reviewer for any task</forbidden>
+<forbidden>Never continue past 3 cycles for a single task</forbidden>
+<forbidden>Never report success if any task is blocked</forbidden>
 </never-do>`
 };
 
@@ -1042,7 +1099,8 @@ var primaryAgent = {
     budgetTokens: 32000
   },
   maxTokens: 64000,
-  prompt: PROMPT
+  prompt: PROMPT,
+  tools: { ask: true }
 };
 var PRIMARY_AGENT_NAME = process.env.OPENCODE_AGENT_NAME || "Commander";
 
@@ -1268,7 +1326,7 @@ var agents = {
 };
 
 // src/tools/ast-grep/index.ts
-var {spawn } = globalThis.Bun;
+var {spawn, which } = globalThis.Bun;
 
 // node_modules/zod/v4/classic/external.js
 var exports_external = {};
@@ -13592,6 +13650,20 @@ function tool(input) {
 tool.schema = exports_external;
 
 // src/tools/ast-grep/index.ts
+async function checkAstGrepAvailable() {
+  const sgPath = which("sg");
+  if (sgPath) {
+    return { available: true };
+  }
+  return {
+    available: false,
+    message: `ast-grep CLI (sg) not found. AST-aware search/replace will not work.
+` + `Install with one of:
+` + `  npm install -g @ast-grep/cli
+` + `  cargo install ast-grep --locked
+` + "  brew install ast-grep"
+  };
+}
 var LANGUAGES = [
   "c",
   "cpp",
@@ -15265,6 +15337,10 @@ var MCP_SERVERS = {
   }
 };
 var OpenCodeConfigPlugin = async (ctx) => {
+  const astGrepStatus = await checkAstGrepAvailable();
+  if (!astGrepStatus.available) {
+    console.warn(`[micode] ${astGrepStatus.message}`);
+  }
   const thinkModeState = new Map;
   const autoCompactHook = createAutoCompactHook(ctx);
   const contextInjectorHook = createContextInjectorHook(ctx);

package/dist/tools/ast-grep/index.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Check if ast-grep CLI (sg) is available on the system.
+ * Returns installation instructions if not found.
+ */
+export declare function checkAstGrepAvailable(): Promise<{
+    available: boolean;
+    message?: string;
+}>;
 export declare const ast_grep_search: {
     description: string;
     args: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "micode",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenCode plugin with Brainstorm-Research-Plan-Implement workflow",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",