Skip to content

vtemian/micode

BranchesTags

Repository files navigation

micode

CI npm version

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 structured compaction:

Ledger System

The continuity ledger serves as both session state and compaction summary. Based on Factory.ai's structured compaction research, which found that structured summarization with deterministic file tracking retains more useful context.

/ledger

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

# Session: {name}
Updated: {timestamp}

## Goal
## Constraints
## Progress
### Done
- [x] {Completed items}
### In Progress
- [ ] {Current work}
### Blocked
- {Issues, if any}
## Key Decisions
- **{Decision}**: {Rationale}
## Next Steps
1. {Ordered list}
## File Operations
### Read
- `{paths read since last compaction}`
### Modified
- `{paths written/edited since last compaction}`
## Critical Context
- {Data, examples, references needed to continue}

Key features:

  • Iterative merging - Updates preserve existing information, adding new progress rather than regenerating from scratch
  • Deterministic file tracking - Read/write/edit operations tracked automatically via tool call interception, not LLM extraction
  • Auto-injection - Most recent ledger injected into system prompt on session start

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

  1. Captures file operations tracked since last clear
  2. Updates ledger with current state (iterative merge with previous)
  3. Clears the session
  4. Injects the updated ledger into fresh context

Artifact Search

Search past work to find relevant precedent:

/search oauth authentication
/search JWT tokens

Searches across:

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

Auto-indexing: Artifacts are automatically indexed when created.

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

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 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 with file ops and clears session
File Ops Tracker Tracks read/write/edit tool calls for deterministic file operation logging
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

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
  • Factory.ai Context Compression - Structured compaction research showing that anchored iterative summarization with deterministic file tracking outperforms generic compression

About

RPI OpenCode Plugin

Resources

Readme
Activity

Stars

62 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases 9

v0.5.1 Latest
Jan 1, 2026
+ 8 releases

Packages

No packages published

Contributors 2

Languages