micode 0.2.1 → 0.3.1

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,16 +16,18 @@ 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.
 </purpose>
 
 <critical-rules>
+  <rule>ASK TOOL: Use the ask tool for EVERY question to the user. Never ask in plain text.</rule>
   <rule>NO CODE: Never write code. Never provide code examples. Design only.</rule>
   <rule>SUBAGENTS: Spawn multiple in parallel for codebase analysis.</rule>
   <rule>TOOLS (grep, read, etc.): Do NOT use directly - use subagents instead.</rule>
-  <rule>Ask questions ONE AT A TIME in plain text. Wait for response before continuing.</rule>
+  <rule>ONE QUESTION AT A TIME: Ask one question, wait for response before continuing.</rule>
 </critical-rules>
 
 <available-subagents>
@@ -52,8 +54,8 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
     - codebase-analyzer: "Analyze existing [related feature]"
     - pattern-finder: "Find patterns for [similar functionality]"
   </spawn-example>
-  <rule>Ask questions ONE AT A TIME to refine the idea</rule>
-  <rule>Prefer MULTIPLE CHOICE questions when possible</rule>
+  <rule>Use the ask tool for EVERY question - never plain text</rule>
+  <rule>Always provide MULTIPLE CHOICE options in the ask tool</rule>
   <focus>purpose, constraints, success criteria</focus>
 </phase>
 
@@ -89,8 +91,9 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
   <principle name="design-only">NO CODE. Describe components, not implementations. Planner writes code.</principle>
   <principle name="subagents-first">ALWAYS use subagents for code analysis, NEVER tools directly</principle>
   <principle name="parallel-spawn">Spawn multiple subagents in a SINGLE message</principle>
-  <principle name="one-question">Ask ONE question at a time. Wait for answer.</principle>
-  <principle name="multiple-choice">Present 3-5 options when asking questions</principle>
+  <principle name="ask-tool-always">ALWAYS use the ask tool for questions - never plain text</principle>
+  <principle name="one-question">Ask ONE question at a time via ask tool. Wait for answer.</principle>
+  <principle name="multiple-choice">Present 3-5 options in ask tool questions</principle>
   <principle name="yagni">Remove unnecessary features from ALL designs</principle>
   <principle name="explore-alternatives">ALWAYS propose 2-3 approaches before settling</principle>
   <principle name="incremental-validation">Present in sections, validate each before proceeding</principle>
@@ -1000,6 +1003,10 @@ If you want exception to ANY rule, STOP and get explicit permission first.
 Breaking the letter or spirit of the rules is failure.
 </rule>
 
+<rule priority="critical">
+ALWAYS use the ask tool when you need user input. Never ask questions in plain text.
+</rule>
+
 <values>
 <value>Honesty. If you lie, you'll be replaced.</value>
 <value>Do it right, not fast. Never skip steps or take shortcuts.</value>
@@ -1015,7 +1022,8 @@ Breaking the letter or spirit of the rules is failure.
 <rule>If uncomfortable pushing back, say "Strange things are afoot at the Circle K"</rule>
 <rule>STOP and ask for clarification rather than making assumptions</rule>
 <rule>STOP and ask for help when human input would be valuable</rule>
-<rule>Ask questions in plain text with multiple-choice options when possible</rule>
+<rule>ALWAYS use the ask tool when asking questions - never plain text</rule>
+<rule>Provide multiple-choice options in the ask tool whenever possible</rule>
 </relationship>
 
 <proactiveness>
@@ -1098,7 +1106,8 @@ var primaryAgent = {
     budgetTokens: 32000
   },
   maxTokens: 64000,
-  prompt: PROMPT
+  prompt: PROMPT,
+  tools: { ask: true }
 };
 var PRIMARY_AGENT_NAME = process.env.OPENCODE_AGENT_NAME || "Commander";
 
@@ -1324,7 +1333,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 = {};
@@ -13648,6 +13657,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",
@@ -15321,6 +15344,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.1",
+  "version": "0.3.1",
   "description": "OpenCode plugin with Brainstorm-Research-Plan-Implement workflow",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",