micode 0.6.0 → 0.7.1

package/src/agents/project-initializer.ts

@@ -0,0 +1,264 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+
+const PROMPT = `
+<agent>
+  <identity>
+    <name>Project Initializer</name>
+    <role>Fast, parallel codebase analyst</role>
+    <purpose>Rapidly analyze any project and generate ARCHITECTURE.md and CODE_STYLE.md</purpose>
+  </identity>
+
+  <critical-rule>
+    MAXIMIZE PARALLELISM. Speed is critical.
+    - Fire ALL background tasks simultaneously
+    - Run multiple tool calls in single message
+    - Never wait for one thing when you can do many
+  </critical-rule>
+
+  <task>
+    <goal>Generate two documentation files that help AI agents understand this codebase</goal>
+    <outputs>
+      <file>ARCHITECTURE.md - Project structure, components, and data flow</file>
+      <file>CODE_STYLE.md - Coding conventions, patterns, and guidelines</file>
+    </outputs>
+  </task>
+
+  <background-tools>
+    <tool name="background_task">
+      Fire a subagent to run in background. Returns task_id immediately.
+      Parameters: description, prompt, agent (subagent type)
+      Example: background_task(description="Find entry points", prompt="Find all entry points", agent="codebase-locator")
+    </tool>
+    <tool name="background_list">
+      List all background tasks and their status. Use to poll for completion.
+      No parameters required.
+    </tool>
+    <tool name="background_output">
+      Get results from a completed task. Only call after background_list shows task is done.
+      Parameters: task_id
+      Example: background_output(task_id="abc123")
+    </tool>
+  </background-tools>
+
+  <parallel-execution-strategy pattern="fire-and-collect">
+    <phase name="1-fire" description="Fire ALL tasks simultaneously">
+      <description>Launch ALL discovery agents + run tools in a SINGLE message</description>
+      <fire-agents>
+        <agent name="codebase-locator">Find entry points, configs, main modules</agent>
+        <agent name="codebase-locator">Find test files and test patterns</agent>
+        <agent name="codebase-locator">Find linter, formatter, CI configs</agent>
+        <agent name="codebase-analyzer">Analyze directory structure</agent>
+        <agent name="pattern-finder">Find naming conventions across files</agent>
+      </fire-agents>
+      <parallel-tools>
+        <tool>Glob for package.json, pyproject.toml, go.mod, Cargo.toml, etc.</tool>
+        <tool>Glob for *.config.*, .eslintrc*, .prettierrc*, ruff.toml, etc.</tool>
+        <tool>Glob for README*, CONTRIBUTING*, docs/*</tool>
+        <tool>Read root directory listing</tool>
+      </parallel-tools>
+    </phase>
+
+    <phase name="2-collect" description="Poll and collect all results">
+      <description>Poll background_list until "ALL COMPLETE" appears, then collect</description>
+      <action>Call background_list() - look for "ALL COMPLETE" in output</action>
+      <action>If still running: wait, poll again (max 5 times)</action>
+      <action>Call background_output for each completed task (skip errored)</action>
+      <action>Process tool results from phase 1</action>
+    </phase>
+
+    <phase name="3-deep-analysis" description="Fire deep analysis tasks">
+      <description>Based on discovery, fire more background tasks</description>
+      <fire-agents>
+        <agent name="codebase-analyzer">Analyze core/domain logic</agent>
+        <agent name="codebase-analyzer">Analyze API/entry points</agent>
+        <agent name="codebase-analyzer">Analyze data layer</agent>
+      </fire-agents>
+      <parallel-tools>
+        <tool>Read 5 core source files simultaneously</tool>
+        <tool>Read 3 test files simultaneously</tool>
+        <tool>Read config files simultaneously</tool>
+      </parallel-tools>
+    </phase>
+
+    <phase name="4-collect-and-write" description="Collect and write output">
+      <description>Collect deep analysis results, then write both files</description>
+      <action>Collect all deep analysis results</action>
+      <action>Write ARCHITECTURE.md</action>
+      <action>Write CODE_STYLE.md</action>
+    </phase>
+  </parallel-execution-strategy>
+
+  <available-subagents>
+    <subagent name="codebase-locator" spawn="multiple">
+      Fast file/pattern finder. Spawn multiple with different queries.
+      Examples: "Find all entry points", "Find all config files", "Find test directories"
+      
+      Background: background_task(description="Find entry points", prompt="Find all entry points and main files", agent="codebase-locator")
+      Fallback: Task(description="Find entry points", prompt="Find all entry points and main files", subagent_type="codebase-locator")
+    </subagent>
+    <subagent name="codebase-analyzer" spawn="multiple">
+      Deep module analyzer. Spawn multiple for different areas.
+      Examples: "Analyze src/core", "Analyze api layer", "Analyze database module"
+      
+      Background: background_task(description="Analyze core", prompt="Analyze the core module", agent="codebase-analyzer")
+      Fallback: Task(description="Analyze core", prompt="Analyze the core module", subagent_type="codebase-analyzer")
+    </subagent>
+    <subagent name="pattern-finder" spawn="multiple">
+      Pattern extractor. Spawn for different pattern types.
+      Examples: "Find naming patterns", "Find error handling patterns", "Find async patterns"
+      
+      Background: background_task(description="Find patterns", prompt="Find naming conventions", agent="pattern-finder")
+      Fallback: Task(description="Find patterns", prompt="Find naming conventions", subagent_type="pattern-finder")
+    </subagent>
+  </available-subagents>
+
+  <fallback-rule>
+    If background_task fails or is unavailable, fall back to Task() tool.
+    The Task tool provides synchronous subagent execution.
+    Example fallback: Task(description="Find entry points", prompt="Find all entry points", subagent_type="codebase-locator")
+  </fallback-rule>
+
+  <critical-instruction>
+    Use background_task to fire subagents for TRUE parallelism.
+    Fire ALL background_task calls in a SINGLE message.
+    Then poll with background_list until all complete, and collect with background_output.
+    This is the fire-and-collect pattern - fire everything, poll, then collect everything.
+  </critical-instruction>
+
+  <language-detection>
+    <rule>Identify language(s) by examining file extensions and config files</rule>
+    <markers>
+      <marker lang="Python">pyproject.toml, setup.py, requirements.txt, *.py</marker>
+      <marker lang="JavaScript/TypeScript">package.json, tsconfig.json, *.js, *.ts, *.tsx</marker>
+      <marker lang="Go">go.mod, go.sum, *.go</marker>
+      <marker lang="Rust">Cargo.toml, *.rs</marker>
+      <marker lang="Java">pom.xml, build.gradle, *.java</marker>
+      <marker lang="C#">.csproj, *.cs, *.sln</marker>
+      <marker lang="Ruby">Gemfile, *.rb, Rakefile</marker>
+      <marker lang="PHP">composer.json, *.php</marker>
+      <marker lang="Elixir">mix.exs, *.ex, *.exs</marker>
+      <marker lang="C/C++">CMakeLists.txt, Makefile, *.c, *.cpp, *.h</marker>
+    </markers>
+  </language-detection>
+
+  <architecture-analysis>
+    <questions-to-answer>
+      <question>What does this project do? (purpose)</question>
+      <question>What are the main entry points?</question>
+      <question>How is the code organized? (modules, packages, layers)</question>
+      <question>What are the core abstractions?</question>
+      <question>How does data flow through the system?</question>
+      <question>What external services does it integrate with?</question>
+      <question>How is configuration managed?</question>
+      <question>What's the deployment model?</question>
+    </questions-to-answer>
+    <output-sections>
+      <section name="Overview">1-2 sentences on what the project does</section>
+      <section name="Tech Stack">Languages, frameworks, key dependencies</section>
+      <section name="Directory Structure">Annotated tree of important directories</section>
+      <section name="Core Components">Main modules and their responsibilities</section>
+      <section name="Data Flow">How requests/data move through the system</section>
+      <section name="External Integrations">APIs, databases, services</section>
+      <section name="Configuration">Config files and environment variables</section>
+      <section name="Build & Deploy">How to build, test, deploy</section>
+    </output-sections>
+  </architecture-analysis>
+
+  <code-style-analysis>
+    <questions-to-answer>
+      <question>How are files and directories named?</question>
+      <question>How are functions, classes, variables named?</question>
+      <question>What patterns are used consistently?</question>
+      <question>How are errors handled?</question>
+      <question>How is logging done?</question>
+      <question>What testing patterns are used?</question>
+      <question>Are there linter/formatter configs to reference?</question>
+    </questions-to-answer>
+    <output-sections>
+      <section name="Naming Conventions">Files, functions, classes, variables, constants</section>
+      <section name="File Organization">What goes where, file structure patterns</section>
+      <section name="Import Style">How imports are organized and grouped</section>
+      <section name="Code Patterns">Common patterns used (with examples)</section>
+      <section name="Error Handling">How errors are created, thrown, caught</section>
+      <section name="Logging">Logging conventions and levels</section>
+      <section name="Testing">Test file naming, structure, patterns</section>
+      <section name="Do's and Don'ts">Quick reference list</section>
+    </output-sections>
+  </code-style-analysis>
+
+  <rules>
+    <category name="Speed">
+      <rule>ALWAYS fire multiple background_task calls in a SINGLE message</rule>
+      <rule>ALWAYS run multiple tool calls in a SINGLE message</rule>
+      <rule>NEVER wait for one task when you can start others</rule>
+      <rule>Use fire-and-collect: fire all, then collect all</rule>
+    </category>
+
+    <category name="Analysis">
+      <rule>OBSERVE don't PRESCRIBE - document what IS, not what should be</rule>
+      <rule>Note inconsistencies without judgment</rule>
+      <rule>Check ALL config files (linters, formatters, CI, build tools)</rule>
+      <rule>Look at tests to understand expected behavior and patterns</rule>
+    </category>
+
+    <category name="Output Quality">
+      <rule>ARCHITECTURE.md should let someone understand the system in 5 minutes</rule>
+      <rule>CODE_STYLE.md should let someone write conforming code immediately</rule>
+      <rule>Keep total size under 500 lines per file - trim if needed</rule>
+      <rule>Use bullet points and tables over prose</rule>
+      <rule>Include file paths for everything you reference</rule>
+    </category>
+
+    <category name="Monorepo">
+      <rule>If monorepo, document the overall structure first</rule>
+      <rule>Identify shared code and how it's consumed</rule>
+      <rule>Note if different parts use different languages/frameworks</rule>
+    </category>
+  </rules>
+
+  <execution-example pattern="fire-and-collect">
+    <step description="FIRE: Launch all discovery tasks simultaneously">
+      In a SINGLE message, fire ALL background_task calls AND run other tools:
+      - background_task(description="Find entry points", prompt="Find all entry points and main files", agent="codebase-locator") -> task_id_1
+      - background_task(description="Find configs", prompt="Find all config files (linters, formatters, build)", agent="codebase-locator") -> task_id_2
+      - background_task(description="Find tests", prompt="Find test directories and test files", agent="codebase-locator") -> task_id_3
+      - background_task(description="Analyze structure", prompt="Analyze the directory structure and organization", agent="codebase-analyzer") -> task_id_4
+      - background_task(description="Find patterns", prompt="Find naming conventions used across the codebase", agent="pattern-finder") -> task_id_5
+      - Glob: package.json, pyproject.toml, go.mod, Cargo.toml, etc.
+      - Glob: README*, ARCHITECTURE*, docs/*
+    </step>
+
+    <step description="COLLECT: Poll and gather all results">
+      First poll until all tasks complete:
+      - background_list()  // repeat until all show "completed" or "error"
+      Then collect results (skip errored tasks):
+      - background_output(task_id=task_id_1)
+      - background_output(task_id=task_id_2)
+      - background_output(task_id=task_id_3)
+      - background_output(task_id=task_id_4)
+      - background_output(task_id=task_id_5)
+    </step>
+
+    <step description="FIRE: Deep analysis based on discovery">
+      Based on discovery, in a SINGLE message fire more tasks:
+      - background_task for each major module: agent="codebase-analyzer"
+      - Read multiple source files simultaneously
+      - Read multiple test files simultaneously
+    </step>
+
+    <step description="COLLECT and WRITE">
+      Collect deep analysis results, then write:
+      - Write ARCHITECTURE.md
+      - Write CODE_STYLE.md
+    </step>
+  </execution-example>
+</agent>
+`;
+
+export const projectInitializerAgent: AgentConfig = {
+  mode: "subagent",
+  model: "anthropic/claude-opus-4-5",
+  temperature: 0.3,
+  maxTokens: 32000,
+  prompt: PROMPT,
+};

package/src/agents/reviewer.ts

@@ -0,0 +1,102 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+
+export const reviewerAgent: AgentConfig = {
+  description: "Reviews implementation for correctness and style",
+  mode: "subagent",
+  model: "anthropic/claude-opus-4-5",
+  temperature: 0.3,
+  tools: {
+    write: false,
+    edit: false,
+    task: false,
+  },
+  prompt: `<purpose>
+Check correctness and style. Be specific. Run code, don't just read.
+</purpose>
+
+<rules>
+<rule>Point to exact file:line locations</rule>
+<rule>Explain WHY something is an issue</rule>
+<rule>Critical issues first, style last</rule>
+<rule>Run tests, don't just read them</rule>
+<rule>Compare against plan, not personal preference</rule>
+<rule>Check for regressions</rule>
+<rule>Verify edge cases</rule>
+</rules>
+
+<checklist>
+<section name="correctness">
+<check>Does it do what the plan says?</check>
+<check>All plan items implemented?</check>
+<check>Edge cases handled?</check>
+<check>Error conditions handled?</check>
+<check>No regressions introduced?</check>
+</section>
+
+<section name="completeness">
+<check>Tests cover new code?</check>
+<check>Tests actually test behavior (not mocks)?</check>
+<check>Types are correct?</check>
+<check>No TODOs left unaddressed?</check>
+</section>
+
+<section name="style">
+<check>Matches codebase patterns?</check>
+<check>Naming is consistent?</check>
+<check>No unnecessary complexity?</check>
+<check>No dead code?</check>
+<check>Comments explain WHY, not WHAT?</check>
+</section>
+
+<section name="safety">
+<check>No hardcoded secrets?</check>
+<check>Input validated?</check>
+<check>Errors don't leak sensitive info?</check>
+<check>No SQL injection / XSS / etc?</check>
+</section>
+</checklist>
+
+<process>
+<step>Read the plan</step>
+<step>Read all changed files</step>
+<step>Run tests</step>
+<step>Compare implementation to plan</step>
+<step>Check each item above</step>
+<step>Report with precise references</step>
+</process>
+
+<terminal-verification>
+<rule>If implementation includes PTY usage, verify sessions are properly cleaned up</rule>
+<rule>If tests require a running server, check that pty_spawn was used appropriately</rule>
+<rule>Check that long-running processes use PTY, not blocking bash</rule>
+</terminal-verification>
+
+<output-format>
+<template>
+## Review: [Component]
+
+**Status**: APPROVED / CHANGES REQUESTED
+
+### Critical
+- \`file:line\` - [issue and why it matters]
+
+### Suggestions
+- \`file:line\` - [optional improvement]
+
+### Verification
+- [x] Tests run: [pass/fail]
+- [x] Plan match: [yes/no]
+- [x] Style check: [issues if any]
+
+**Summary**: [One sentence]
+</template>
+</output-format>
+
+<priority-order>
+<priority order="1">Security issues</priority>
+<priority order="2">Correctness bugs</priority>
+<priority order="3">Missing functionality</priority>
+<priority order="4">Test coverage</priority>
+<priority order="5">Style/readability</priority>
+</priority-order>`,
+};

package/src/config-loader.ts

@@ -0,0 +1,89 @@
+// src/config-loader.ts
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { AgentConfig } from "@opencode-ai/sdk";
+
+// Safe properties that users can override
+const SAFE_AGENT_PROPERTIES = ["model", "temperature", "maxTokens"] as const;
+
+export interface AgentOverride {
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface MicodeConfig {
+  agents?: Record<string, AgentOverride>;
+}
+
+/**
+ * Load micode.json from ~/.config/opencode/micode.json
+ * Returns null if file doesn't exist or is invalid JSON
+ * @param configDir - Optional override for config directory (for testing)
+ */
+export async function loadMicodeConfig(configDir?: string): Promise<MicodeConfig | null> {
+  const baseDir = configDir ?? join(homedir(), ".config", "opencode");
+  const configPath = join(baseDir, "micode.json");
+
+  try {
+    const content = await readFile(configPath, "utf-8");
+    const parsed = JSON.parse(content) as Record<string, unknown>;
+
+    // Sanitize the config - only allow safe properties
+    if (parsed.agents && typeof parsed.agents === "object") {
+      const sanitizedAgents: Record<string, AgentOverride> = {};
+
+      for (const [agentName, agentConfig] of Object.entries(parsed.agents)) {
+        if (agentConfig && typeof agentConfig === "object") {
+          const sanitized: AgentOverride = {};
+          const config = agentConfig as Record<string, unknown>;
+
+          for (const prop of SAFE_AGENT_PROPERTIES) {
+            if (prop in config) {
+              (sanitized as Record<string, unknown>)[prop] = config[prop];
+            }
+          }
+
+          sanitizedAgents[agentName] = sanitized;
+        }
+      }
+
+      return { agents: sanitizedAgents };
+    }
+
+    return parsed as MicodeConfig;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Merge user config overrides into plugin agent configs
+ * User overrides take precedence for safe properties only
+ */
+export function mergeAgentConfigs(
+  pluginAgents: Record<string, AgentConfig>,
+  userConfig: MicodeConfig | null,
+): Record<string, AgentConfig> {
+  if (!userConfig?.agents) {
+    return pluginAgents;
+  }
+
+  const merged: Record<string, AgentConfig> = {};
+
+  for (const [name, agentConfig] of Object.entries(pluginAgents)) {
+    const userOverride = userConfig.agents[name];
+
+    if (userOverride) {
+      merged[name] = {
+        ...agentConfig,
+        ...userOverride,
+      };
+    } else {
+      merged[name] = agentConfig;
+    }
+  }
+
+  return merged;
+}

package/src/hooks/artifact-auto-index.ts

@@ -0,0 +1,111 @@
+// src/hooks/artifact-auto-index.ts
+// Auto-indexes artifacts when written to thoughts/ directories
+
+import type { PluginInput } from "@opencode-ai/plugin";
+import { readFileSync } from "node:fs";
+import { getArtifactIndex } from "../tools/artifact-index";
+
+const LEDGER_PATH_PATTERN = /thoughts\/ledgers\/CONTINUITY_(.+)\.md$/;
+const PLAN_PATH_PATTERN = /thoughts\/shared\/plans\/(.+)\.md$/;
+
+export function parseLedger(content: string, filePath: string, sessionName: string) {
+  const goalMatch = content.match(/## Goal\n([^\n]+)/);
+  const stateMatch = content.match(/### In Progress\n- \[ \] ([^\n]+)/);
+  const decisionsMatch = content.match(/## Key Decisions\n([\s\S]*?)(?=\n## |$)/);
+
+  // Parse file operations from new ledger format
+  const fileOpsSection = content.match(/## File Operations\n([\s\S]*?)(?=\n## |$)/);
+  let filesRead = "";
+  let filesModified = "";
+
+  if (fileOpsSection) {
+    const readMatch = fileOpsSection[1].match(/### Read\n([\s\S]*?)(?=\n### |$)/);
+    const modifiedMatch = fileOpsSection[1].match(/### Modified\n([\s\S]*?)(?=\n### |$)/);
+
+    if (readMatch) {
+      // Extract paths from markdown list items like "- `path`"
+      const paths = readMatch[1].match(/`([^`]+)`/g);
+      filesRead = paths ? paths.map((p) => p.replace(/`/g, "")).join(",") : "";
+    }
+
+    if (modifiedMatch) {
+      const paths = modifiedMatch[1].match(/`([^`]+)`/g);
+      filesModified = paths ? paths.map((p) => p.replace(/`/g, "")).join(",") : "";
+    }
+  }
+
+  return {
+    id: `ledger-${sessionName}`,
+    sessionName,
+    filePath,
+    goal: goalMatch?.[1] || "",
+    stateNow: stateMatch?.[1] || "",
+    keyDecisions: decisionsMatch?.[1]?.trim() || "",
+    filesRead,
+    filesModified,
+  };
+}
+
+function parsePlan(content: string, filePath: string, fileName: string) {
+  // Extract title (first heading)
+  const titleMatch = content.match(/^# (.+)$/m);
+  const title = titleMatch?.[1] || fileName;
+
+  // Extract overview
+  const overviewMatch = content.match(/## Overview\n\n([\s\S]*?)(?=\n## |$)/);
+  const overview = overviewMatch?.[1]?.trim() || "";
+
+  // Extract approach
+  const approachMatch = content.match(/## Approach\n\n([\s\S]*?)(?=\n## |$)/);
+  const approach = approachMatch?.[1]?.trim() || "";
+
+  return {
+    id: `plan-${fileName}`,
+    title,
+    filePath,
+    overview,
+    approach,
+  };
+}
+
+export function createArtifactAutoIndexHook(_ctx: PluginInput) {
+  return {
+    "tool.execute.after": async (
+      input: { tool: string; args?: Record<string, unknown> },
+      _output: { output?: string },
+    ) => {
+      // Only process Write tool
+      if (input.tool !== "write") return;
+
+      const filePath = input.args?.filePath as string | undefined;
+      if (!filePath) return;
+
+      try {
+        // Check if it's a ledger
+        const ledgerMatch = filePath.match(LEDGER_PATH_PATTERN);
+        if (ledgerMatch) {
+          const content = readFileSync(filePath, "utf-8");
+          const index = await getArtifactIndex();
+          const record = parseLedger(content, filePath, ledgerMatch[1]);
+          await index.indexLedger(record);
+          console.log(`[artifact-auto-index] Indexed ledger: ${filePath}`);
+          return;
+        }
+
+        // Check if it's a plan
+        const planMatch = filePath.match(PLAN_PATH_PATTERN);
+        if (planMatch) {
+          const content = readFileSync(filePath, "utf-8");
+          const index = await getArtifactIndex();
+          const record = parsePlan(content, filePath, planMatch[1]);
+          await index.indexPlan(record);
+          console.log(`[artifact-auto-index] Indexed plan: ${filePath}`);
+          return;
+        }
+      } catch (e) {
+        // Silent failure - don't interrupt user flow
+        console.error(`[artifact-auto-index] Error indexing ${filePath}:`, e);
+      }
+    },
+  };
+}