micode 0.1.0

package/INSTALL_CLAUDE.md

@@ -0,0 +1,175 @@
+# micode Installation Guide for LLMs
+
+This document guides AI assistants through the micode plugin installation process.
+
+## Step 0: Ask User About Setup
+
+micode uses Claude Opus 4.5 for its primary agents (Commander, Brainstormer, project-initializer). Ask the user:
+
+### Question 1: Claude Subscription
+
+> Do you have a Claude Pro/Max subscription?
+
+**If YES:**
+- Add ToDo: "Setup Claude Pro/Max Auth"
+- Ask follow-up: "Are you on max20 (20x mode)?"
+  - If max20: Full Claude Opus 4.5 available for all agents
+  - If not max20: Consider using lighter models for subagents
+
+**If NO:**
+- Inform user: "micode works best with Claude Opus 4.5. Without Claude, you'll need to configure alternative models."
+- Create `~/.config/opencode/micode.json`:
+```json
+{
+  "agents": {
+    "Commander": { "model": "opencode/big-pickle" },
+    "Brainstormer": { "model": "opencode/big-pickle" },
+    "project-initializer": { "model": "opencode/big-pickle" }
+  }
+}
+```
+
+## Step 1: Verify OpenCode Installation
+
+```bash
+if command -v opencode &> /dev/null; then
+    echo "OpenCode $(opencode --version) is installed"
+else
+    echo "OpenCode is not installed. Please install it first."
+    echo "Ref: https://opencode.ai/docs"
+fi
+```
+
+If OpenCode isn't installed, guide user to https://opencode.ai/docs or spawn a subagent to handle installation.
+
+## Step 2: Configure micode Plugin
+
+### Check for existing config
+
+```bash
+if [ -f ~/.config/opencode/opencode.jsonc ]; then
+    echo "Found opencode.jsonc - edit this file"
+elif [ -f ~/.config/opencode/opencode.json ]; then
+    echo "Found opencode.json - edit this file"
+else
+    echo "No config found - will create new one"
+fi
+```
+
+### Add micode to plugins
+
+**If config exists:**
+```bash
+if command -v jq &> /dev/null; then
+    jq '.plugin = ((.plugin // []) + ["micode"] | unique)' \
+        ~/.config/opencode/opencode.json > /tmp/oc.json && \
+        mv /tmp/oc.json ~/.config/opencode/opencode.json
+else
+    echo "Please add \"micode\" to the plugin array in ~/.config/opencode/opencode.json"
+fi
+```
+
+**If no config exists:**
+```bash
+mkdir -p ~/.config/opencode
+echo '{"plugin":["micode"]}' > ~/.config/opencode/opencode.json
+```
+
+## Step 3: Verify Setup
+
+```bash
+opencode --version  # Should be 1.0.132 or higher
+cat ~/.config/opencode/opencode.json  # Should contain "micode" in plugin array
+```
+
+## Step 4: Configure Authentication
+
+### Anthropic (Claude) - Recommended
+
+```bash
+opencode auth login
+# Interactive Terminal: Provider: Select Anthropic
+# Interactive Terminal: Login method: Select Claude Pro/Max
+# Guide user through OAuth flow in browser
+# Wait for completion
+# Verify success
+```
+
+## Step 5: Verify Everything Works
+
+1. Run `opencode` in terminal
+2. Check that Commander agent is available
+3. Try `/init` command to test project-initializer
+
+## Step 6: Congratulate User
+
+Say to user:
+
+> Congratulations! 🎉 You have successfully set up micode!
+>
+> **What you can do now:**
+> - Use **Commander** as your main orchestrator
+> - Use **Brainstormer** for design exploration
+> - Run `/init` to generate ARCHITECTURE.md and CODE_STYLE.md
+>
+> **Workflow:** Brainstorm → Research → Plan → Implement → Review
+>
+> Type `opencode` in your terminal to start!
+
+## Step 7: Ask for a Star
+
+After everything is set up and working:
+
+> "If you found this helpful, would you like to star the repository? It helps the project grow! ⭐"
+
+**Only if user explicitly agrees:**
+```bash
+gh repo star vtemian/micode
+```
+
+Never run this automatically without consent.
+
+---
+
+## Quick Reference
+
+### Available Agents
+
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| Commander | claude-opus-4-5 | Main orchestrator |
+| Brainstormer | claude-opus-4-5 | Design exploration |
+| project-initializer | claude-opus-4-5 | Generate docs |
+| codebase-locator | - | Find files |
+| codebase-analyzer | - | Analyze code |
+| pattern-finder | - | Find patterns |
+| implementer | - | Execute tasks |
+| reviewer | - | Review code |
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/init` | Initialize project with ARCHITECTURE.md and CODE_STYLE.md |
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `ast_grep_search` | AST-aware code search |
+| `ast_grep_replace` | AST-aware code replace |
+| `look_at` | Screenshot analysis |
+| `background_task` | Run tasks in background |
+
+### Model Override
+
+To use different models, create `~/.config/opencode/micode.json`:
+
+```json
+{
+  "agents": {
+    "Commander": { "model": "your-preferred-model" },
+    "Brainstormer": { "model": "your-preferred-model" }
+  }
+}
+```

package/README.md

@@ -0,0 +1,192 @@
+# micode
+
+[![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.
+
+## Installation
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["micode"]
+}
+```
+
+**AI-assisted install:** Share [INSTALL_CLAUDE.md](./INSTALL_CLAUDE.md) with your AI assistant for guided setup.
+
+## Workflow
+
+```
+Brainstorm → Research → Plan → Implement → Review
+```
+
+### 1. Brainstorm
+
+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
+- Output: `thoughts/shared/designs/YYYY-MM-DD-{topic}-design.md`
+
+### 2. Research
+
+Parallel codebase investigation using specialized subagents:
+
+| Subagent | Purpose |
+|----------|---------|
+| `codebase-locator` | Find WHERE files live (paths, no content) |
+| `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
+
+Create implementation plan with phases and verification steps.
+
+- Get human approval before implementing
+- Output: `thoughts/shared/plans/YYYY-MM-DD-{topic}.md`
+
+### 4. Implement
+
+Execute plan in git worktree for isolation:
+
+```bash
+git worktree add ../{feature} -b feature/{feature}
+```
+
+- Implementer + Reviewer work per phase
+- Commit with descriptive messages
+- Merge when complete
+
+### 5. Handoff
+
+Save/resume session state for continuity:
+
+- `handoff-creator`: Save current session
+- `handoff-resumer`: Resume from handoff
+- Output: `thoughts/shared/handoffs/`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/init` | Initialize project with ARCHITECTURE.md and CODE_STYLE.md |
+
+## Agents
+
+| Agent | Mode | Model | Purpose |
+|-------|------|-------|---------|
+| Commander | primary | claude-opus-4-5 | Orchestrator, delegates to specialists |
+| Brainstormer | primary | claude-opus-4-5 | Design exploration through questioning |
+| project-initializer | subagent | claude-opus-4-5 | Generate ARCHITECTURE.md and CODE_STYLE.md |
+| codebase-locator | subagent | - | Find file locations |
+| codebase-analyzer | subagent | - | Deep code analysis |
+| pattern-finder | subagent | - | Find existing patterns |
+| implementer | subagent | - | Execute implementation |
+| reviewer | subagent | - | Review correctness |
+| handoff-creator | subagent | - | Save session state |
+| handoff-resumer | subagent | - | Resume from handoff |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `ast_grep_search` | AST-aware code pattern search |
+| `ast_grep_replace` | AST-aware code pattern replacement |
+| `look_at` | Screenshot analysis |
+| `background_task` | Run long-running tasks in background |
+| `check_background_task` | Check background task status |
+
+## Hooks
+
+| Hook | Description |
+|------|-------------|
+| Think Mode | Keywords like "think hard" enable 32k token thinking budget |
+| Auto-Compact | Summarizes session when hitting token limits |
+| Preemptive Compaction | Warns before context exhaustion |
+| Context Injector | Injects ARCHITECTURE.md, CODE_STYLE.md, .cursorrules |
+| Token-Aware Truncation | Truncates large tool outputs |
+| Context Window Monitor | Tracks token usage |
+| Comment Checker | Validates edit tool comments |
+| Session Recovery | Recovers from crashes |
+
+## MCP Servers
+
+| Server | Description |
+|--------|-------------|
+| context7 | Documentation lookup |
+
+## Structure
+
+```
+micode/
+├── src/
+│   ├── agents/       # Agent definitions
+│   ├── tools/        # ast-grep, look-at, background-task
+│   ├── hooks/        # Session management hooks
+│   └── index.ts      # Plugin entry
+├── dist/             # Built plugin
+└── thoughts/         # Artifacts (gitignored)
+    └── shared/
+        ├── designs/    # Brainstorm outputs
+        ├── research/   # Research documents
+        ├── plans/      # Implementation plans
+        └── handoffs/   # Session handoffs
+```
+
+## Development
+
+### From source
+
+```bash
+git clone git@github.com:vtemian/micode.git ~/.micode
+cd ~/.micode
+bun install
+bun run build
+```
+
+Then use local path in config:
+```json
+{
+  "plugin": ["~/.micode/dist/index.js"]
+}
+```
+
+### Commands
+
+```bash
+bun install       # Install dependencies
+bun run build     # Build plugin
+bun run typecheck # Type check
+```
+
+### Release
+
+Releases are automated via GitHub Actions. To publish a new version:
+
+```bash
+npm version patch  # or minor, major
+git push --follow-tags
+```
+
+This triggers the release workflow which publishes to npm.
+
+**Manual publish** (first time or if needed):
+```bash
+npm login
+npm publish
+```
+
+## Philosophy
+
+1. **Brainstorm first** - Refine ideas before coding
+2. **Research before implementing** - Understand the codebase
+3. **Plan with human buy-in** - Get approval before coding
+4. **Parallel investigation** - Spawn multiple subagents for speed
+5. **Isolated implementation** - Use git worktrees for features
+6. **Continuous verification** - Implementer + Reviewer per phase

package/dist/agents/brainstormer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const brainstormerAgent: AgentConfig;

package/dist/agents/codebase-analyzer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const codebaseAnalyzerAgent: AgentConfig;

package/dist/agents/codebase-locator.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const codebaseLocatorAgent: AgentConfig;

package/dist/agents/commander.d.ts

@@ -0,0 +1,3 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const primaryAgent: AgentConfig;
+export declare const PRIMARY_AGENT_NAME: string;

package/dist/agents/handoff-creator.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const handoffCreatorAgent: AgentConfig;

package/dist/agents/handoff-resumer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const handoffResumerAgent: AgentConfig;

package/dist/agents/implementer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const implementerAgent: AgentConfig;

package/dist/agents/index.d.ts

@@ -0,0 +1,13 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+import { brainstormerAgent } from "./brainstormer";
+import { codebaseLocatorAgent } from "./codebase-locator";
+import { codebaseAnalyzerAgent } from "./codebase-analyzer";
+import { patternFinderAgent } from "./pattern-finder";
+import { implementerAgent } from "./implementer";
+import { reviewerAgent } from "./reviewer";
+import { handoffCreatorAgent } from "./handoff-creator";
+import { handoffResumerAgent } from "./handoff-resumer";
+import { primaryAgent, PRIMARY_AGENT_NAME } from "./commander";
+import { projectInitializerAgent } from "./project-initializer";
+export declare const agents: Record<string, AgentConfig>;
+export { primaryAgent, PRIMARY_AGENT_NAME, brainstormerAgent, codebaseLocatorAgent, codebaseAnalyzerAgent, patternFinderAgent, implementerAgent, reviewerAgent, handoffCreatorAgent, handoffResumerAgent, projectInitializerAgent, };

package/dist/agents/pattern-finder.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const patternFinderAgent: AgentConfig;

package/dist/agents/project-initializer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const projectInitializerAgent: AgentConfig;

package/dist/agents/reviewer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+export declare const reviewerAgent: AgentConfig;

package/dist/hooks/auto-compact.d.ts

@@ -0,0 +1,9 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export declare function createAutoCompactHook(ctx: PluginInput): {
+    event: ({ event }: {
+        event: {
+            type: string;
+            properties?: unknown;
+        };
+    }) => Promise<void>;
+};

package/dist/hooks/comment-checker.d.ts

@@ -0,0 +1,9 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export declare function createCommentCheckerHook(ctx: PluginInput): {
+    "tool.execute.after": (input: {
+        tool: string;
+        args?: Record<string, unknown>;
+    }, output: {
+        output?: string;
+    }) => Promise<void>;
+};

package/dist/hooks/context-injector.d.ts

@@ -0,0 +1,15 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export declare function createContextInjectorHook(ctx: PluginInput): {
+    "chat.params": (_input: {
+        sessionID: string;
+    }, output: {
+        options?: Record<string, unknown>;
+        system?: string;
+    }) => Promise<void>;
+    "tool.execute.after": (input: {
+        tool: string;
+        args?: Record<string, unknown>;
+    }, output: {
+        output?: string;
+    }) => Promise<void>;
+};

package/dist/hooks/context-window-monitor.d.ts

@@ -0,0 +1,15 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export declare function createContextWindowMonitorHook(ctx: PluginInput): {
+    "chat.params": (input: {
+        sessionID: string;
+    }, output: {
+        system?: string;
+        options?: Record<string, unknown>;
+    }) => Promise<void>;
+    event: ({ event }: {
+        event: {
+            type: string;
+            properties?: unknown;
+        };
+    }) => Promise<void>;
+};

package/dist/hooks/preemptive-compaction.d.ts

@@ -0,0 +1,9 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export declare function createPreemptiveCompactionHook(ctx: PluginInput): {
+    event: ({ event }: {
+        event: {
+            type: string;
+            properties?: unknown;
+        };
+    }) => Promise<void>;
+};

package/dist/hooks/session-recovery.d.ts

@@ -0,0 +1,9 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export declare function createSessionRecoveryHook(ctx: PluginInput): {
+    event: ({ event }: {
+        event: {
+            type: string;
+            properties?: unknown;
+        };
+    }) => Promise<void>;
+};

package/dist/hooks/token-aware-truncation.d.ts

@@ -0,0 +1,15 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export declare function createTokenAwareTruncationHook(ctx: PluginInput): {
+    event: ({ event }: {
+        event: {
+            type: string;
+            properties?: unknown;
+        };
+    }) => Promise<void>;
+    "tool.execute.after": (input: {
+        name: string;
+        sessionID: string;
+    }, output: {
+        output?: string;
+    }) => Promise<void>;
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const OpenCodeConfigPlugin: Plugin;
+export default OpenCodeConfigPlugin;