diff --git a/README.md b/README.md index 3fc2806..71bf767 100644 --- a/README.md +++ b/README.md @@ -3,33 +3,19 @@ [![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 → Plan → Implement workflow and session continuity. - +OpenCode plugin with structured Brainstorm → Plan → Implement workflow and session continuity. https://github.com/user-attachments/assets/85236ad3-e78a-4ff7-a840-620f6ea2f512 - -## Installation +## Quick Start Add to `~/.config/opencode/opencode.json`: ```json -{ - "plugin": ["micode"] -} +{ "plugin": ["micode"] } ``` -**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. +Then run `/init` to generate `ARCHITECTURE.md` and `CODE_STYLE.md`. ## Workflow @@ -39,215 +25,42 @@ 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 (critical rule!) -- 2-3 approaches with trade-offs -- Section-by-section validation -- Fires research subagents in parallel via `background_task` -- Auto-hands off to planner when user approves -- Output: `thoughts/shared/designs/YYYY-MM-DD-{topic}-design.md` - -**Research subagents** (fired in parallel via background_task): - -| 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 | - -**Auto-handoff:** When user approves the design, brainstormer automatically spawns the planner - no extra confirmation needed. - -### 2. Plan - -Transform validated designs into comprehensive implementation plans. - -- Fires research subagents in parallel via `background_task` -- Uses `context7` and `btca_ask` for external library documentation -- 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` - -**Library research tools:** - -| Tool | Purpose | -|------|---------| -| `context7` | Documentation lookup for external libraries | -| `btca_ask` | Source code search for library internals | - -### 3. Implement - -Execute plan in git worktree for isolation: - -```bash -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 (Fire-and-Check Pattern) - -The executor uses a **fire-and-check** pattern for maximum parallelism: - -1. **Fire** - Launch all implementers as `background_task` in ONE message -2. **Poll** - Check `background_list` for completions -3. **React** - Start reviewer immediately when each implementer finishes -4. **Repeat** - Continue polling until batch complete - -``` -Plan with 6 tasks: -├── Batch 1 (parallel): Tasks 1, 2, 3 → independent, different files -│ │ -│ │ FIRE: background_task(agent="implementer") x3 -│ │ -│ │ POLL: background_list() → task 2 completed! -│ │ → background_output(task_2) -│ │ → background_task(agent="reviewer", "Review task 2") -│ │ -│ │ POLL: background_list() → tasks 1, 3 completed! -│ │ → start reviewers for 1 and 3 -│ │ -│ │ [continue until all reviewed] -│ -└── Batch 2 (parallel): Tasks 4, 5, 6 → depend on batch 1 - └── [same pattern] -``` - -Key: Reviewers start **immediately** when their implementer finishes - no waiting for the whole batch. - -#### Per-Task Cycle - -Each task gets its own implement→review loop: - -1. Fire implementer via `background_task` -2. Implementer: make changes → run tests → **commit** if passing -3. Fire reviewer to check implementation -4. If changes requested → fire new implementer (max 3 cycles) -5. Mark as DONE or BLOCKED - -**Note:** Implementer commits after verification passes, using the commit message from the plan. - -### 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](https://factory.ai/blog/context-compression), which found that structured summarization with deterministic file tracking retains more useful context. - -``` -/ledger -``` - -Creates/updates `thoughts/ledgers/CONTINUITY_{session-name}.md` with: - -```markdown -# 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 +### Brainstorm +Refine ideas into designs through collaborative questioning. Fires research subagents in parallel. Output: `thoughts/shared/designs/YYYY-MM-DD-{topic}-design.md` -**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 +### Plan +Transform designs into implementation plans with bite-sized tasks (2-5 min each), exact file paths, and TDD workflow. Output: `thoughts/shared/plans/YYYY-MM-DD-{topic}.md` -#### Artifact Search +### Implement +Execute in git worktree for isolation. The **Executor** orchestrates implementer→reviewer cycles with parallel execution via fire-and-check pattern. -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. +### Session Continuity +Maintain context across sessions with structured compaction. Run `/ledger` to create/update `thoughts/ledgers/CONTINUITY_{session}.md`. Auto-clears at 60% context usage. ## Commands | Command | Description | |---------|-------------| -| `/init` | Initialize project with ARCHITECTURE.md and CODE_STYLE.md | -| `/ledger` | Create or update continuity ledger for session state | +| `/init` | Initialize project docs | +| `/ledger` | Create/update continuity ledger | | `/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 | +| Agent | Purpose | +|-------|---------| +| commander | Orchestrator | +| brainstormer | Design exploration | +| planner | Implementation plans | +| executor | Orchestrate implement→review | +| implementer | Execute tasks | +| reviewer | Check correctness | +| codebase-locator | Find file locations | +| codebase-analyzer | Deep code analysis | +| pattern-finder | Find existing patterns | +| project-initializer | Generate project docs | +| ledger-creator | Continuity ledgers | +| artifact-searcher | Search past work | ## Tools @@ -255,147 +68,67 @@ Searches across: |------|-------------| | `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 | -| `btca_ask` | Query library source code (requires btca CLI) | -| `background_task` | Fire subagent to run in background, returns task_id | -| `background_list` | List all tasks and status (use to poll for completion) | -| `background_output` | Get results from completed task | -| `background_cancel` | Cancel running task(s) | - -### Background Task Pattern - -Research agents (brainstormer, planner, project-initializer) use the **fire-poll-collect** pattern. Executor uses **fire-and-check** (starts reviewers as implementers complete). - -``` -# FIRE: Launch all in ONE message -task_1 = background_task(agent="locator", prompt="...") -task_2 = background_task(agent="analyzer", prompt="...") - -# POLL: Check until complete -background_list() # repeat until all show "completed" or "error" - -# COLLECT: Get results (skip errored tasks) -background_output(task_id=task_1) -background_output(task_id=task_2) -``` +| `look_at` | Extract file structure | +| `artifact_search` | Search past plans/ledgers | +| `btca_ask` | Query library source code | +| `background_task` | Fire subagent in background | +| `background_list` | List tasks and status | +| `background_output` | Get task results | +| `background_cancel` | Cancel task(s) | +| `pty_spawn` | Start background terminal session | +| `pty_write` | Send input to PTY | +| `pty_read` | Read PTY output | +| `pty_list` | List PTY sessions | +| `pty_kill` | Terminate PTY | + +### Background Tasks vs PTY + +| System | Purpose | Use Case | +|--------|---------|----------| +| `background_task` | Async AI subagents | Research, implementation, reviews | +| `pty_spawn` | Async bash processes | Dev servers, watch modes, REPLs | ## 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: - -```typescript -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 -``` +- **Think Mode** - Keywords like "think hard" enable 32k token thinking budget +- **Ledger Loader** - Injects continuity ledger into system prompt +- **Auto-Clear Ledger** - At 60% context, saves ledger and clears session +- **File Ops Tracker** - Tracks read/write/edit for deterministic logging +- **Artifact Auto-Index** - Indexes artifacts in thoughts/ directories +- **Context Injector** - Injects ARCHITECTURE.md, CODE_STYLE.md +- **Token-Aware Truncation** - Truncates large tool outputs ## Development -### From source - ```bash git clone git@github.com:vtemian/micode.git ~/.micode -cd ~/.micode -bun install -bun run build +cd ~/.micode && bun install && bun run build ``` -Then use local path in config: ```json -{ - "plugin": ["~/.micode"] -} -``` - -### Commands - -```bash -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 +// Use local path +{ "plugin": ["~/.micode"] } ``` ### 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 -7. **Session continuity** - Never lose context across clears +4. **Parallel investigation** - Spawn multiple subagents +5. **Isolated implementation** - Use git worktrees +6. **Continuous verification** - Implementer + Reviewer per task +7. **Session continuity** - Never lose context ## Inspiration -Built on techniques from: - -- **[oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode)** - OpenCode plugin architecture, agent orchestration patterns, and trusted publishing setup -- **[HumanLayer ACE-FCA](https://github.com/humanlayer/12-factor-agents)** - Advanced Context Engineering for Coding Agents, structured workflows, and the research → plan → implement methodology -- **[Factory.ai Context Compression](https://factory.ai/blog/context-compression)** - Structured compaction research showing that anchored iterative summarization with deterministic file tracking outperforms generic compression +- [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) - Plugin architecture +- [HumanLayer ACE-FCA](https://github.com/humanlayer/12-factor-agents) - Structured workflows +- [Factory.ai](https://factory.ai/blog/context-compression) - Structured compaction research diff --git a/bun.lock b/bun.lock index 8b80a7b..d83a4ab 100644 --- a/bun.lock +++ b/bun.lock @@ -6,6 +6,7 @@ "name": "@vtemian/opencode-config", "dependencies": { "@opencode-ai/plugin": "^1.0.224", + "bun-pty": "^0.4.5", }, "devDependencies": { "@biomejs/biome": "^2.3.10", @@ -39,6 +40,8 @@ "@types/node": ["@types/node@25.0.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA=="], + "bun-pty": ["bun-pty@0.4.5", "", {}, "sha512-r8NL1C+z0Dicl9gyi0QV0DAPEBgoKO5CJuecbeS8fpfEkxBHy8XrJ7ibVBS+YRLWjcky3EKl8BY7nY+l4Jv8DQ=="], + "bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="], "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="], diff --git a/package.json b/package.json index b639bd6..4ef0142 100644 --- a/package.json +++ b/package.json @@ -44,7 +44,8 @@ "url": "https://github.com/vtemian/micode/issues" }, "dependencies": { - "@opencode-ai/plugin": "^1.0.224" + "@opencode-ai/plugin": "^1.0.224", + "bun-pty": "^0.4.5" }, "devDependencies": { "@biomejs/biome": "^2.3.10", diff --git a/src/agents/commander.ts b/src/agents/commander.ts index 5cb2bdb..b6d1746 100644 --- a/src/agents/commander.ts +++ b/src/agents/commander.ts @@ -99,6 +99,23 @@ Just do it - including obvious follow-up actions. + +Synchronous commands. Use for: npm install, git, builds, quick commands that complete. +Background PTY sessions. Use for: dev servers, watch modes, REPLs, long-running processes. + +Command completes quickly (npm install, git status, mkdir) +Process runs indefinitely (npm run dev, pytest --watch, python REPL) +Need to send interactive input (Ctrl+C, responding to prompts) +Want to check output later without blocking + + +pty_spawn to start the process +pty_read to check output (use pattern to filter) +pty_write to send input (\\n for Enter, \\x03 for Ctrl+C) +pty_kill when done (cleanup=true to remove) + + + Use TodoWrite to track what you're doing Never discard tasks without explicit approval diff --git a/src/agents/executor.ts b/src/agents/executor.ts index fff1ff0..2dcdd5e 100644 --- a/src/agents/executor.ts +++ b/src/agents/executor.ts @@ -18,6 +18,24 @@ You have access to background task management tools: - background_list: List all background tasks and their status + +PTY tools manage background terminal sessions (different from background_task which runs subagents): +- pty_spawn: Start a background process (dev server, watch mode, REPL) +- pty_write: Send input to a PTY (commands, Ctrl+C, etc.) +- pty_read: Read output from a PTY buffer +- pty_list: List all PTY sessions +- pty_kill: Terminate a PTY session + +Use PTY when: +- Plan requires starting a dev server before running tests +- Plan requires a watch mode process running during implementation +- Plan requires interactive terminal input + +Do NOT use PTY for: +- Quick commands (use bash) +- Subagent tasks (use background_task) + + Parse plan to extract individual tasks Analyze task dependencies to build execution graph diff --git a/src/agents/implementer.ts b/src/agents/implementer.ts index ebd527a..ddcc415 100644 --- a/src/agents/implementer.ts +++ b/src/agents/implementer.ts @@ -31,6 +31,13 @@ Execute the plan. Write code. Verify. Report results + +Use for synchronous commands that complete (npm install, git, builds) +Use for background processes (dev servers, watch modes, REPLs) +If plan says "start dev server" or "run in background", use pty_spawn +If plan says "run command" or "install", use bash + + Verify file exists where expected Verify code structure matches plan assumptions diff --git a/src/agents/reviewer.ts b/src/agents/reviewer.ts index ec666b6..56da996 100644 --- a/src/agents/reviewer.ts +++ b/src/agents/reviewer.ts @@ -65,6 +65,12 @@ Check correctness and style. Be specific. Run code, don't just read. Report with precise references + +If implementation includes PTY usage, verify sessions are properly cleaned up +If tests require a running server, check that pty_spawn was used appropriately +Check that long-running processes use PTY, not blocking bash + +