micode

OpenCode plugin with a structured Brainstorm → Plan → Implement workflow and session continuity.

micode.mp4

Installation

Add to ~/.config/opencode/opencode.json:

{
  "plugin": ["micode"]
}

AI-assisted install: Share 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 → 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.

• 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

Research subagents (spawned in parallel):

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

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

3. Implement

Execute plan in git worktree for isolation:

git worktree add ../{feature} -b feature/{feature}

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

4. Session Continuity

Maintain context across long sessions and context clears with the ledger system:

Ledger System

The continuity ledger captures essential session state:

/ledger

Creates/updates thoughts/ledgers/CONTINUITY_{session-name}.md with:

• Goal and constraints
• Key decisions with rationale
• Current state (Done/Now/Next)
• Working set (branch, key files)

Auto-injection: When starting a session, the most recent ledger is automatically injected into the system prompt.

Auto-clear: At 80% context usage, the system automatically:

1. Updates the ledger
2. Creates a handoff document
3. Clears the session
4. Injects the ledger into the fresh context

Artifact Search

Search past work to find relevant precedent:

/search oauth authentication
/search JWT tokens

Searches across:

• Ledgers (thoughts/ledgers/)
• Handoffs (thoughts/shared/handoffs/)
• Plans (thoughts/shared/plans/)

Auto-indexing: Artifacts are automatically indexed when created.

Handoff

Save/resume session state for continuity:

• handoff-creator: Save current session (reads ledger for context)
• handoff-resumer: Resume from handoff
• Output: thoughts/shared/handoffs/

Commands

Command	Description
/init	Initialize project with ARCHITECTURE.md and CODE_STYLE.md
/ledger	Create or update continuity ledger for session state
/search	Search past handoffs, plans, and ledgers

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	claude-sonnet	Find file locations
codebase-analyzer	subagent	claude-sonnet	Deep code analysis
pattern-finder	subagent	claude-sonnet	Find existing patterns
planner	subagent	claude-opus-4-5	Create detailed implementation plans
executor	subagent	claude-opus-4-5	Orchestrate implement → review cycle
implementer	subagent	claude-opus-4-5	Execute implementation tasks
reviewer	subagent	claude-opus-4-5	Review correctness and style
ledger-creator	subagent	claude-sonnet	Create/update continuity ledgers
artifact-searcher	subagent	claude-sonnet	Search past work for precedent
handoff-creator	subagent	claude-opus-4-5	Save session state
handoff-resumer	subagent	claude-opus-4-5	Resume from handoff

Tools

Tool	Description
ast_grep_search	AST-aware code pattern search
ast_grep_replace	AST-aware code pattern replacement
look_at	Extract file structure for large files
artifact_search	Search past handoffs, plans, and ledgers
background_task	Run long-running tasks in background
background_output	Check background task status/output
background_cancel	Cancel background tasks
background_list	List all background tasks

Hooks

Hook	Description
Think Mode	Keywords like "think hard" enable 32k token thinking budget
Ledger Loader	Injects continuity ledger into system prompt
Auto-Clear Ledger	At 80% context, saves ledger + handoff and clears session
Artifact Auto-Index	Indexes artifacts when written to thoughts/ directories
Auto-Compact	Summarizes session when hitting token limits
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

Permissions

All permissions are set to allow globally - no prompts for tool usage:

config.permission = {
  edit: "allow",
  bash: "allow",
  webfetch: "allow",
  doom_loop: "allow",
  external_directory: "allow",
};

This enables subagents to work autonomously without getting stuck on permission prompts.

MCP Servers

Server	Description	Activation
context7	Documentation lookup	Always enabled
perplexity	Web search	Set PERPLEXITY_API_KEY
firecrawl	Web crawling	Set FIRECRAWL_API_KEY

Structure

micode/
├── src/
│   ├── agents/       # Agent definitions
│   ├── tools/        # ast-grep, look-at, artifact-search, background-task
│   ├── hooks/        # Session management hooks
│   └── index.ts      # Plugin entry
├── dist/             # Built plugin
└── thoughts/         # Artifacts (gitignored)
    ├── ledgers/        # Continuity ledgers
    └── shared/
        ├── designs/    # Brainstorm outputs
        ├── plans/      # Implementation plans
        └── handoffs/   # Session handoffs

Development

From source

git clone git@github.com:vtemian/micode.git ~/.micode
cd ~/.micode
bun install
bun run build

Then use local path in config:

{
  "plugin": ["~/.micode"]
}

Commands

bun install       # Install dependencies
bun run build     # Build plugin
bun run typecheck # Type check
bun test          # Run tests
bun test --watch  # Run tests in watch mode

Release

Releases are automated via GitHub Actions. To publish a new version:

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):

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
7. Session continuity - Never lose context across clears

Inspiration

Built on techniques from:

• oh-my-opencode - OpenCode plugin architecture, agent orchestration patterns, and trusted publishing setup
• HumanLayer ACE-FCA - Advanced Context Engineering for Coding Agents, structured workflows, and the research → plan → implement methodology