mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/006-named-error-system.rispec.md

@@ -0,0 +1,155 @@
+# RISE-006: Named Error System
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/006-named-error-system.rispec.md
+
+## Creative Intent
+
+mia-code enables precise, machine-readable error handling throughout the system. Every error has a dot-notation name (`session.not_found`), a human-readable message, and optional metadata. Error handlers match on names, not on message strings. API responses serialize errors cleanly to JSON. Monitoring aggregates errors by name. No more `catch(e) { if (e.message.includes("not found")) ... }` — errors are data, not prose.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code throws raw `Error` objects with free-text messages
+- Error handling relies on string matching against `error.message` — fragile and locale-dependent
+- There is no hierarchy or categorization of errors — a config parse error looks the same as a network timeout
+- Errors cannot carry structured metadata (which session failed, which file was missing)
+- When the HTTP API (RISE-001) is added, errors must be serialized to JSON — raw Error objects lose their stack and carry only a message string
+- There is no way to aggregate errors by type for monitoring or debugging
+
+**Desired State:**
+- Every error in the system is a `NamedError` with a machine-readable name, human message, and metadata
+- Error names follow dot-notation: `module.error_type` (e.g., `session.not_found`, `config.invalid_field`, `agent.timeout`)
+- Catch blocks match on `error.name` for reliable handling
+- Errors serialize to JSON with name, message, and metadata — perfect for API responses
+- Error aggregation by name enables patterns like "10 `agent.timeout` errors in the last hour"
+- Raw `throw new Error(...)` is banned — linting or convention enforces `NamedError` usage
+
+## Desired Outcome Definition
+
+A `NamedError` class that extends `Error` with a structured `name`, `message`, and `metadata` object. All error paths in mia-code use `NamedError`. A utility function wraps unknown caught errors into `NamedError`.
+
+## Natural Language Functional Description
+
+### NamedError Class
+
+```typescript
+class NamedError extends Error {
+  readonly name: string;        // dot-notation: "session.not_found"
+  readonly message: string;     // human-readable: "Session not found"
+  readonly metadata: Record<string, unknown>;  // structured context
+
+  constructor(
+    name: string,
+    message: string,
+    metadata?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = name;
+    this.metadata = metadata ?? {};
+  }
+
+  toJSON(): { name: string; message: string; metadata: Record<string, unknown> } {
+    return { name: this.name, message: this.message, metadata: this.metadata };
+  }
+}
+```
+
+### Throwing Named Errors
+
+Modules throw NamedErrors with descriptive names and relevant metadata:
+
+```typescript
+throw new NamedError("session.not_found", "Session not found", {
+  sessionId: "abc-123", projectRoot: "/home/dev/myproject",
+});
+
+throw new NamedError("config.invalid_field", "Invalid configuration value", {
+  field: "defaultEngine", value: "gpt4", expected: ["gemini", "claude"],
+});
+
+throw new NamedError("agent.timeout", "Agent did not respond within timeout", {
+  engine: "gemini", timeoutMs: 30000, sessionId: "abc-123",
+});
+```
+
+### Catching by Name
+
+Error handlers match on the `name` property for reliable dispatch:
+
+```typescript
+try {
+  await Session.resume(sessionId);
+} catch (e) {
+  if (e instanceof NamedError && e.name === "session.not_found") {
+    return await Session.create({ projectRoot });
+  }
+  throw e;
+}
+```
+
+### Wrapping Unknown Errors
+
+When catching errors from third-party code or the runtime, wrap them into NamedErrors:
+
+```typescript
+function wrapError(error: unknown, name: string): NamedError {
+  if (error instanceof NamedError) return error;
+  if (error instanceof Error) {
+    return new NamedError(name, error.message, {
+      originalName: error.name,
+      stack: error.stack,
+    });
+  }
+  return new NamedError(name, String(error));
+}
+
+// Usage
+try {
+  await fs.readFile(path);
+} catch (e) {
+  throw wrapError(e, "fs.read_failed");
+}
+```
+
+### Error Name Conventions
+
+Names follow `module.error_type` pattern:
+
+| Module    | Error Names                                                     |
+|-----------|-----------------------------------------------------------------|
+| session   | `session.not_found`, `session.corrupted`, `session.limit_reached` |
+| config    | `config.invalid_field`, `config.file_unreadable`, `config.parse_failed` |
+| agent     | `agent.timeout`, `agent.process_failed`, `agent.invalid_response` |
+| tool      | `tool.not_found`, `tool.execution_failed`, `tool.permission_denied` |
+| bus       | `bus.invalid_payload`, `bus.handler_failed`                     |
+| api       | `api.unauthorized`, `api.invalid_request`, `api.rate_limited`   |
+
+### API Error Serialization
+
+The HTTP server (RISE-001) catches NamedErrors and serializes them via `err.toJSON()`, mapping error names to HTTP status codes (`session.not_found` → 404, `config.invalid_field` → 400, `api.unauthorized` → 401, `agent.timeout` → 504). Unknown NamedErrors default to 500.
+
+### Integration with Zod Validation
+
+A utility `parseOrThrow(schema, data, errorName)` wraps `schema.safeParse()` — on failure, it throws a `NamedError` with the given name and the first Zod issue as the message, with all issues in metadata.
+
+## Supporting Structures
+
+- **Zod Schema Validation (RISE-005)** generates validation errors that are wrapped into NamedErrors
+- **Event Bus (RISE-002)** uses NamedErrors for invalid payload errors
+- **Structured Logging (RISE-007)** logs NamedErrors with their name and metadata as structured fields
+- **Client-Server Architecture (RISE-001)** serializes NamedErrors to JSON for API responses
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Graceful Session Recovery:**
+`Session.resume()` throws `NamedError("session.corrupted", ...)`. The caller catches it by name, deletes the corrupted session, and creates a fresh one. The user sees "Session was corrupted, starting fresh" — not a stack trace.
+
+**Scenario 2 — API Error Response:**
+A client sends an invalid request. The server catches the NamedError and returns `{"name":"config.invalid_field","message":"Invalid engine 'gpt4'","metadata":{"field":"engine","expected":["gemini","claude"]}}`. The client renders a specific, helpful error message.
+
+**Scenario 3 — Error Metrics Dashboard:**
+A monitoring module subscribes to `Error.Event.Occurred` on the event bus. It counts errors by name. The team sees that `agent.timeout` spiked — Gemini's API is slow today. They switch the default engine to Claude.
+
+**Scenario 4 — Third-Party Error Wrapping:**
+The Gemini CLI process crashes with an opaque error. The agent module catches it and wraps it: `NamedError("agent.process_failed", "Gemini CLI exited with code 1", { stderr: "..." })`. Upstream code handles it by name without parsing stderr.

package/rispecs/borrowed_from_opencode/007-structured-logging.rispec.md

@@ -0,0 +1,138 @@
+# RISE-007: Structured Logging
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/007-structured-logging.rispec.md
+
+## Creative Intent
+
+mia-code enables observable, filterable, structured logging across every module. Every log line carries a service tag, a level, a timestamp, and structured metadata — not a concatenated string. Developers debug by filtering: `MIA_LOG=session:debug,agent:warn` shows verbose session logs and only agent warnings. In production, logs are JSON lines. In development, logs are human-readable. No `console.log` survives — all output flows through the Log system.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code uses `console.log` and chalk-styled output directly in business logic
+- There is no distinction between "output for the user" and "output for debugging" — both go to stdout
+- Debugging requires adding and removing `console.log` statements manually
+- There is no way to enable verbose logging for one module without drowning in output from others
+- Log lines carry no structured context — a message like `"Session created"` doesn't tell you which session or which project
+- When the HTTP server (RISE-001) runs headlessly, console output is lost unless piped to a file
+
+**Desired State:**
+- Every module creates a tagged logger: `const log = Log.create({ service: "session" })`
+- Log calls include structured metadata: `log.info("created", { sessionId, projectRoot })`
+- Log levels (debug, info, warn, error) filter output by severity
+- Per-module log level control via environment variable: `MIA_LOG=session:debug,agent:info`
+- Development mode: human-readable colored output with timestamps
+- Production/headless mode: JSON lines for machine parsing
+- User-facing output (the TUI) is separate from logging — logs go to stderr or a file, UI goes to stdout
+
+## Desired Outcome Definition
+
+A `Log` module that provides per-service tagged loggers with structured metadata, configurable levels, and environment-based filtering.
+
+## Natural Language Functional Description
+
+### Logger Creation
+
+Each module creates a logger with a service tag:
+
+```typescript
+import { Log } from "./log";
+
+const log = Log.create({ service: "session" });
+
+log.debug("loading index", { path: "~/.mia-code-sessions.json" });
+log.info("created", { sessionId: "abc-123", projectRoot: "/dev/myproject" });
+log.warn("stale session", { sessionId: "old-456", ageHours: 72 });
+log.error("failed to save", { path: "~/.mia-code-sessions.json", error: err.message });
+```
+
+### Log Levels
+
+Four levels in ascending severity:
+
+| Level | Purpose | Default visibility |
+|-------|---------|-------------------|
+| `debug` | Detailed internal state, iteration steps, raw data | Hidden |
+| `info`  | Significant state changes, lifecycle events | Visible |
+| `warn`  | Recoverable issues, degraded behavior | Visible |
+| `error` | Failures that prevent normal operation | Visible |
+
+### Log Output Format
+
+**Development mode** (when stdout is a TTY):
+
+```
+12:34:56.789 [session] INFO  created sessionId=abc-123 projectRoot=/dev/myproject
+12:34:56.790 [agent]   DEBUG spawning engine=gemini model=gemini-2.5-pro
+12:34:57.123 [agent]   WARN  slow response elapsed=2341ms threshold=2000ms
+```
+
+Format: `HH:mm:ss.SSS [service] LEVEL message key=value key=value`
+
+Colors: debug=gray, info=blue, warn=yellow, error=red. Service tag is cyan. Keys are dimmed.
+
+**Production mode** (when stdout is not a TTY, or `MIA_LOG_FORMAT=json`):
+
+```json
+{"ts":"2025-02-17T04:47:57.789Z","service":"session","level":"info","msg":"created","sessionId":"abc-123","projectRoot":"/dev/myproject"}
+```
+
+One JSON object per line. Fields: `ts` (ISO 8601), `service`, `level`, `msg`, and all metadata keys flattened into the object.
+
+### Level Filtering
+
+The `MIA_LOG` environment variable controls per-module levels: `MIA_LOG=info,session:debug,agent:error`. Comma-separated entries; bare levels set the global default, `module:level` sets overrides. Per-module takes precedence.
+
+### Separation from UI Output
+
+UI output (prompts, agent responses, ceremony) goes to **stdout** via chalk/ora. Log output goes to **stderr** (or `MIA_LOG_FILE`). This means `mia-code 2>debug.log` captures logs without disrupting the TUI.
+
+### Error Logging with NamedError
+
+When logging errors, the logger extracts NamedError fields automatically:
+
+```typescript
+try {
+  await Session.resume(id);
+} catch (e) {
+  log.error("resume failed", {
+    sessionId: id,
+    ...(e instanceof NamedError ? { errorName: e.name, ...e.metadata } : { error: String(e) }),
+  });
+}
+```
+
+This produces structured log entries like:
+```json
+{"ts":"...","service":"session","level":"error","msg":"resume failed","sessionId":"abc-123","errorName":"session.corrupted","reason":"invalid JSON"}
+```
+
+### Child Loggers
+
+`log.child({ sessionId: "abc-123", operation: "resume" })` creates a child logger with pre-bound context. Every log call from the child includes the bound fields automatically. The child inherits the parent's service tag and level.
+
+### No Console.log
+
+Zero `console.log`/`console.warn`/`console.error` in production code. All output goes through `Log` (debugging → stderr) or chalk/ora formatting (user-facing UI → stdout).
+
+## Supporting Structures
+
+- **Named Error System (RISE-006)** provides structured error data that loggers extract automatically
+- **Event Bus (RISE-002)** can subscribe to error events and log them centrally
+- **Instance State (RISE-003)** scopes logger context to the active project
+- **Client-Server Architecture (RISE-001)** uses JSON log format for server-side observability
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Debugging a Session Resume Failure:**
+A user reports that session resume fails silently. The developer asks them to run `MIA_LOG=session:debug mia-code` and share the output. The debug logs show: `loading index path=~/.mia-code-sessions.json`, `found session sessionId=abc-123`, `resume failed errorName=agent.process_failed stderr="API key expired"`. Root cause identified in one exchange.
+
+**Scenario 2 — Server Log Aggregation:**
+The mia-code server runs with `MIA_LOG_FORMAT=json MIA_LOG_FILE=/var/log/mia-code.log`. A log aggregator (like `tail -f | jq`) processes JSON lines. The ops team queries: "show all `level:error` entries from `service:agent` in the last hour."
+
+**Scenario 3 — Isolating a Noisy Module:**
+During development, the agent module emits hundreds of debug lines per request. The developer sets `MIA_LOG=debug,agent:warn` — full debug output from session, config, and bus modules, but only warnings and errors from agent. Signal without noise.
+
+**Scenario 4 — CI Pipeline Logging:**
+In CI, mia-code runs headlessly with `MIA_LOG=info MIA_LOG_FORMAT=json`. Logs are JSON lines captured by the CI system. On failure, the CI shows structured error entries with full metadata — no need to reproduce the failure locally.

package/rispecs/borrowed_from_opencode/008-lazy-initialization.rispec.md

@@ -0,0 +1,127 @@
+# RISE-008: Lazy Initialization
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/008-lazy-initialization.rispec.md
+
+## Creative Intent
+
+mia-code enables fast startup by deferring expensive work until it is actually needed. A database connection, an LSP server, an MCP transport, a provider API client — none of these initialize at startup. They initialize on first use, cache the result, and return it instantly on every subsequent access. The user types their first prompt in milliseconds; the heavy resources spin up in the background as the agent needs them.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code spawns agent CLI processes (Gemini, Claude) at the start of a session — even if the user hasn't typed a prompt yet
+- Configuration is loaded synchronously at startup via `loadConfig()` in `config.ts`, blocking the main thread
+- Session index is loaded from disk on every operation — no caching between calls within the same process
+- If mia-code adds features like database-backed sessions, LSP integration, or MCP connections, each adds to startup latency
+- There is no pattern for "initialize once, reuse forever" — developers either use module-level variables (no cleanup) or re-initialize on every call (no caching)
+
+**Desired State:**
+- Expensive resources initialize only when first accessed
+- Subsequent accesses return the cached result with zero overhead
+- Concurrent first-access calls share one initialization — no double-init
+- Resources can register cleanup callbacks for graceful shutdown
+- The pattern is generic, composable, and type-safe
+- Startup time remains constant regardless of how many lazy resources are declared
+
+## Desired Outcome Definition
+
+A `lazy<T>(factory, dispose?)` function that returns an accessor. The accessor runs the factory on first call, caches the result, and returns it on subsequent calls. Concurrent first calls share one initialization. An optional dispose callback enables cleanup.
+
+## Natural Language Functional Description
+
+### Basic Usage
+
+```typescript
+import { lazy } from "./lazy";
+
+const db = lazy(async () => {
+  const connection = await connectToDatabase({
+    path: "~/.mia-code/sessions.db",
+  });
+  await connection.migrate();
+  return connection;
+});
+
+// Later, anywhere in the codebase:
+const conn = await db();           // first call: connects and migrates
+const conn2 = await db();          // subsequent call: returns same connection instantly
+console.log(conn === conn2);       // true
+```
+
+### Implementation
+
+The `lazy` function wraps a factory in a stateful accessor. It stores three pieces of state: the in-flight promise (for concurrent safety), the resolved value, and an initialized flag. On first call, it runs the factory and stores the promise. On subsequent calls, it returns the cached value. The accessor exposes `dispose()` (runs cleanup, resets state so next access re-initializes) and `isInitialized()` (check without triggering init).
+
+### Concurrent Safety
+
+If two code paths call `await db()` simultaneously before initialization completes, both receive the same promise. The factory runs exactly once — the second caller sees the in-flight promise and awaits it.
+
+### Synchronous Variant
+
+`lazySync<T>(factory, dispose?)` provides the same pattern for synchronous initialization (e.g., parsing a config file). Same API shape, minus the `async`.
+
+### Disposal and Reset
+
+Calling `dispose()` runs the cleanup callback and resets the accessor. The next call re-runs the factory, returning a fresh resource.
+
+### Use Cases in mia-code
+
+**Database connection** (when migrating from JSON file to SQLite):
+```typescript
+const db = lazy(async () => {
+  const conn = await openDatabase("~/.mia-code/sessions.db");
+  await conn.exec(SCHEMA_SQL);
+  return conn;
+}, async (conn) => conn.close());
+```
+
+**Agent process pool:**
+```typescript
+const agentProcess = lazy(async () => {
+  const proc = spawn("gemini", ["--headless"], { stdio: "pipe" });
+  await waitForReady(proc);
+  return proc;
+}, async (proc) => {
+  proc.kill("SIGTERM");
+  await waitForExit(proc);
+});
+```
+
+**Configuration:**
+```typescript
+const config = lazy(async () => {
+  const raw = await readFile("~/.mia-code.json", "utf-8").catch(() => "{}");
+  return ConfigSchema.parse(JSON.parse(raw));
+});
+```
+
+Other use cases follow the same pattern: MCP clients, LSP servers, provider API clients — any resource with async setup and teardown.
+
+### Composition with Instance State
+
+`Instance.state()` (RISE-003) is built on `lazy()`, adding project-directory scoping and automatic cleanup on instance disposal: `lazy()` = init once + cache + optional dispose; `Instance.state()` = `lazy()` + directory scope + auto-dispose on teardown.
+
+### Global Dispose All
+
+A registry tracks all lazy accessors. On process shutdown (`SIGTERM`), `disposeAll()` iterates the registry in reverse creation order (LIFO), calling `dispose()` on each. This ensures orderly cleanup without manual bookkeeping.
+
+## Supporting Structures
+
+- **Instance State (RISE-003)** builds on lazy initialization, adding per-directory scoping
+- **Client-Server Architecture (RISE-001)** benefits from lazy init — server resources initialize on first request, not on server start
+- **Structured Logging (RISE-007)** can observe initialization timing via lazy wrappers that log init duration
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Instant Startup:**
+A developer runs `mia-code`. The TUI appears instantly. They type a prompt. Only then does the agent process spawn, the session database open, and the config load. Startup time: ~50ms. First-prompt latency absorbs the initialization cost invisibly.
+
+**Scenario 2 — Unused Resource Never Initializes:**
+mia-code has an MCP client for connecting to external tool servers. If the user never invokes an MCP tool, the client never initializes. Zero cost for features not used.
+
+**Scenario 3 — Graceful Shutdown:**
+The user presses Ctrl+C. The process handler calls `disposeAll()`. Each lazy accessor's dispose callback runs: the database connection closes cleanly (flushing pending writes), the agent process receives SIGTERM (not SIGKILL), the LSP server shuts down gracefully. No orphan processes, no corrupted files.
+
+**Scenario 4 — Reconnection After Error:**
+The database connection drops. The code calls `db.dispose()` to reset the lazy accessor, then `await db()` to reconnect. The factory runs again, establishing a fresh connection. The reset-and-retry pattern is natural with lazy accessors.

package/rispecs/borrowed_from_opencode/009-multi-agent-system.rispec.md

@@ -0,0 +1,97 @@
+# RISE-009: Multi-Agent System
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/009-multi-agent-system.rispec.md
+
+## Creative Intent
+
+mia-code enables developers to work with multiple specialized agents within a single application, each possessing distinct capabilities, permissions, and purposes. Instead of one monolithic agent that does everything, users select the right agent for the right task — a focused explorer for codebase discovery, a cautious planner for analysis, a powerful builder for execution. The agent system transforms mia-code from a single-voice tool into an ensemble of specialized collaborators, each with the 🧠 Mia / 🌸 Miette dual perspective but tuned to different operational registers.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code runs a single agent mode: the user sends a prompt, the engine (gemini/claude) responds, and the unifier interprets
+- There is no concept of agent specialization — the same system prompt, permissions, and model apply to every interaction
+- The engine selection (`gemini` vs `claude`) is the only axis of variation; it changes the backend but not the agent's behavior or constraints
+- All tool access is uniform — there is no way to restrict an agent from editing files or running commands
+- Switching between "exploration" and "execution" mindsets requires the user to mentally adjust, not the system
+- The unifier treats every response identically regardless of task type
+
+**Desired State:**
+- Multiple named agents coexist in a single mia-code session, each with its own permission ruleset, system prompt, and optional model override
+- Agents operate in two modes: "primary" (user-facing, full interaction loop) and "subagent" (invoked by other agents for subtasks)
+- A third mode "all" marks agents available in both primary and subagent capacities
+- Switching between primary agents is instantaneous via the Tab key — same session context, different capabilities
+- Subagents are invoked via `@mention` syntax in user messages, delegating specific tasks to specialized agents
+- Each agent's permission boundary is enforced independently — an explore agent cannot edit files even if the build agent can
+- The unifier adapts its interpretation style based on which agent produced the output
+
+## Desired Outcome Definition
+
+A running mia-code session offers multiple agents selectable via Tab (for primary agents) or `@mention` (for subagents). Each agent operates within its defined permission boundary, uses its configured model, and follows its system prompt. The user moves fluidly between agents without losing session context.
+
+## Natural Language Functional Description
+
+### Built-in Agents
+
+mia-code ships with four built-in agents:
+
+1. **build** — The default primary agent. Full access to all tools: file read/write, bash execution, code editing, project manipulation. Uses the session's default model. System prompt emphasizes execution, implementation, and delivery. Mode: "primary".
+
+2. **plan** — A read-only analysis agent. File edits are denied. Bash execution requires explicit user permission per invocation. Ideal for exploring unfamiliar codebases, analyzing architecture, or planning changes before committing to them. Mode: "primary".
+
+3. **explore** — A fast codebase search agent. Limited to read operations and search tools (grep, glob, file viewing). Uses a faster/cheaper model by default for rapid iteration. Cannot edit, write, or execute. Mode: "all" (usable as primary or subagent).
+
+4. **general** — A full-capability subagent for complex multi-step tasks. Invoked by other agents when they need to delegate work that requires multiple tool calls and reasoning steps. Runs in a separate context but shares the session. Mode: "subagent".
+
+### Agent Properties
+
+Each agent is defined by:
+
+- **name**: Display name shown in UI and Tab switcher
+- **description**: Brief purpose statement, shown in agent list
+- **mode**: One of "primary", "subagent", or "all"
+- **permissions**: A ruleset (see RISE-011) controlling tool and resource access
+- **model**: Optional override `{providerID, modelID}` — defaults to session model if unset
+- **prompt**: Custom system prompt template (see RISE-012) — defaults to built-in if unset
+- **temperature**: Optional float (0.0–2.0) for response randomness
+- **topP**: Optional float (0.0–1.0) for nucleus sampling
+
+### Agent Switching
+
+Primary agents appear in a Tab-accessible switcher. The UI displays the current agent name prominently. When the user presses Tab, a selection menu shows all primary-mode agents with their descriptions. Switching is instant — the session context (message history, file state, working directory) persists, but the active permission ruleset and system prompt change immediately.
+
+### Subagent Invocation
+
+Users invoke subagents by typing `@agentname` followed by a task description in their message. The current primary agent recognizes the mention, extracts the task, and delegates to the named subagent. The subagent executes within its own permission boundary and returns results to the primary agent, which synthesizes and presents them to the user.
+
+### Session Context Sharing
+
+All agents in a session share: message history, file system state, working directory, environment variables, and session metadata. Each agent maintains isolated: permission boundaries, active system prompt, model selection, and tool availability. This means an explore agent can reference files the build agent modified earlier, but cannot modify them itself.
+
+### Unifier Adaptation
+
+The unifier's dual 🧠/🌸 interpretation adjusts based on the active agent. Build agent output gets execution-focused commentary. Plan agent output gets analytical commentary. Explore agent output gets discovery-focused commentary. The unifier reads the agent's mode and name to calibrate its interpretive lens.
+
+## Supporting Structures
+
+- **Agent Definition Config (RISE-010)** enables user-defined custom agents beyond the built-in four
+- **Agent Permission Rulesets (RISE-011)** provides the permission enforcement mechanism each agent relies on
+- **Agent Prompt Templates (RISE-012)** supplies the system prompt framework agents use
+- **Plan/Build Mode Toggle (RISE-014)** is the primary user-facing expression of agent switching
+- **Subagent Task Delegation (RISE-015)** details the `@mention` delegation protocol
+- **Event Bus (RISE-002)** broadcasts agent switch events to the UI and connected clients
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Exploration Before Execution:**
+A developer opens a new codebase. They start in `plan` mode, asking questions about architecture and dependencies. The plan agent reads files, searches code, and builds understanding — but never modifies anything. Once the developer has a mental model, they press Tab, switch to `build`, and say "refactor the auth module as we discussed." The build agent has full context from the plan conversation and executes immediately.
+
+**Scenario 2 — Delegated Code Search:**
+While in build mode, the developer types: `@explore find all files that import the SessionStore class`. The explore agent runs rapidly through the codebase using its fast model, returns a list of files and line numbers. The build agent receives this, presents it to the user, and uses it to inform the next refactoring step.
+
+**Scenario 3 — Custom Reviewer Agent:**
+A team creates a custom "reviewer" agent (via RISE-010) with read-only permissions and a system prompt focused on code quality. During a pairing session, one developer works in build mode while the other occasionally switches to the reviewer agent to get automated code review feedback on recent changes — same session, different perspectives.
+
+**Scenario 4 — Safe Onboarding:**
+A junior developer's mia-code config sets `plan` as the default agent. They can explore, analyze, and plan freely. When they switch to `build`, additional confirmation prompts appear for destructive operations. The agent system provides guardrails without blocking productivity.

package/rispecs/borrowed_from_opencode/010-agent-definition-config.rispec.md

@@ -0,0 +1,135 @@
+# RISE-010: Agent Definition Config
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/010-agent-definition-config.rispec.md
+
+## Creative Intent
+
+mia-code enables developers to define custom agents through configuration files, extending the built-in agent roster without writing code. A user describes an agent's name, purpose, model, prompt, and permissions in JSON — and the system instantiates it alongside the defaults. This transforms agent creation from a developer-only activity into a configurable, shareable, team-level practice. Custom agents become part of the project's development infrastructure, versioned alongside code.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code's configuration lives in `_env.sh` and environment variables — there is no structured config file for agent behavior
+- The only behavioral axis is engine selection (`gemini` vs `claude`), controlled by CLI flags or environment variables
+- There is no mechanism to define new agents, their prompts, or their constraints
+- The UNIFIER_SYSTEM_PROMPT is hardcoded in the source — users cannot customize agent personalities without modifying source code
+- Team-specific conventions (e.g., "always review before committing") must be enforced by human discipline, not system configuration
+- No config file format exists for mia-code beyond package.json scripts
+
+**Desired State:**
+- A `mia-code.json` (or `opencode.json`) configuration file in the project root defines custom agents
+- Each agent entry specifies: name, description, model override, system prompt, permission ruleset, temperature, topP, and visibility
+- Custom agents merge with built-in agents — they extend, not replace
+- The config file is human-readable JSON, easily diffable, and version-controllable
+- Hidden agents can exist for programmatic invocation without cluttering the agent list
+- Agent definitions support inheritance — custom agents start with default permissions and override selectively
+
+## Desired Outcome Definition
+
+A developer creates a `mia-code.json` file in their project root containing custom agent definitions. When mia-code starts, it reads this config, merges custom agents with built-ins, and makes all agents available in the session. Custom agents behave identically to built-in ones — same switching, same permission enforcement, same unifier interpretation.
+
+## Natural Language Functional Description
+
+### Configuration File Location
+
+mia-code searches for configuration in this order:
+1. `mia-code.json` in the current working directory
+2. `opencode.json` in the current working directory
+3. `~/.config/mia-code/config.json` for global defaults
+
+Project-level config overrides global config. Multiple config sources merge with project-level taking precedence.
+
+### Agent Definition Schema
+
+Each agent is defined under the `"agent"` key, keyed by a unique identifier:
+
+```json
+{
+  "agent": {
+    "reviewer": {
+      "name": "Code Reviewer",
+      "description": "Reviews code changes for quality, security, and style issues",
+      "model": {
+        "providerID": "anthropic",
+        "modelID": "claude-sonnet-4-20250514"
+      },
+      "prompt": "You are a code reviewer. Focus on bugs, security vulnerabilities, and logic errors. Never modify code directly — only suggest changes.",
+      "permissions": [
+        {"permission": "write", "action": "deny"},
+        {"permission": "edit", "action": "deny"},
+        {"permission": "read", "action": "allow"},
+        {"permission": "bash", "action": "ask"}
+      ],
+      "temperature": 0.3,
+      "topP": 0.9,
+      "hidden": false
+    }
+  }
+}
+```
+
+### Field Definitions
+
+- **name** (string, required): Human-readable display name. Shown in Tab switcher and agent list.
+- **description** (string, optional): Brief purpose statement. Shown alongside name in selection UI. Defaults to empty.
+- **model** (object, optional): `{providerID: string, modelID: string}`. When omitted, the agent uses the session's default model. `providerID` maps to a configured API provider (e.g., "anthropic", "google", "openai"). `modelID` is the specific model identifier.
+- **prompt** (string, optional): Custom system prompt text. Replaces the default agent prompt template. Supports variable interpolation (see RISE-012). Can be a multi-line string or a file path prefixed with `@` (e.g., `"@prompts/reviewer.md"`).
+- **permissions** (array, optional): Permission ruleset array (see RISE-011). Merged with default permissions — custom rules take precedence over defaults.
+- **temperature** (number, optional): Float 0.0–2.0. Controls response randomness. Lower values for deterministic tasks (code review), higher for creative tasks (brainstorming).
+- **topP** (number, optional): Float 0.0–1.0. Nucleus sampling parameter. Defaults to model-specific value.
+- **hidden** (boolean, optional): When `true`, the agent does not appear in the Tab switcher or agent list. It remains invocable via `@mention` or programmatic API. Useful for internal/utility agents.
+
+### Merging with Built-in Agents
+
+Custom agents are added to the agent roster alongside built-in agents (build, plan, explore, general). If a custom agent uses the same key as a built-in (e.g., `"build"`), the custom definition overrides the built-in fields selectively — unspecified fields retain their built-in defaults. This enables users to customize built-in agents without redefining them entirely.
+
+### Validation
+
+On startup, mia-code validates the config:
+- Agent keys must be unique lowercase alphanumeric identifiers (no spaces, hyphens allowed)
+- Model references must point to configured providers
+- Permission rules must use valid action values ("allow", "deny", "ask")
+- Temperature and topP must be within valid ranges
+- Invalid agent definitions emit a warning and are skipped — they do not prevent startup
+
+### File-Based Prompts
+
+When the `prompt` field starts with `@`, the remainder is treated as a relative file path. mia-code reads the file contents as the prompt text. This enables long, structured prompts stored in dedicated files:
+
+```json
+{
+  "agent": {
+    "architect": {
+      "name": "System Architect",
+      "prompt": "@.mia-code/prompts/architect.md"
+    }
+  }
+}
+```
+
+### Runtime Behavior
+
+Custom agents are instantiated at session start. They participate in the same lifecycle as built-in agents: Tab switching, `@mention` invocation, permission enforcement, and unifier interpretation. The agent system makes no distinction between built-in and custom agents at runtime.
+
+## Supporting Structures
+
+- **Multi-Agent System (RISE-009)** defines the agent architecture that custom definitions plug into
+- **Agent Permission Rulesets (RISE-011)** specifies the permission array format used in agent definitions
+- **Agent Prompt Templates (RISE-012)** defines variable interpolation available in custom prompts
+- **Agent Generation (RISE-013)** can produce agent definitions that are saved directly to this config format
+- **Namespace Module Pattern (RISE-004)** guides the config loading module structure
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Team-Wide Code Standards:**
+A team adds a `mia-code.json` to their repository defining a "standards" agent with a prompt encoding their code conventions, naming rules, and architectural patterns. Every developer who clones the repo gets the same standards agent. Code reviews become consistent because the agent enforces shared expectations.
+
+**Scenario 2 — Project-Specific Security Agent:**
+A fintech project defines a "security" agent with deny rules for any file matching `*.key`, `*.pem`, or `*.env`, and a prompt focused on OWASP top-10 vulnerabilities. The agent reviews changes through a security lens. It's hidden by default and invoked via `@security` when needed.
+
+**Scenario 3 — Lightweight Exploration Override:**
+A developer overrides the built-in `explore` agent to use Google's Gemini Flash model for even faster responses: `{"agent": {"explore": {"model": {"providerID": "google", "modelID": "gemini-2.0-flash"}}}}`. The explore agent now runs on a fast, cheap model while build stays on Claude Sonnet.
+
+**Scenario 4 — Prompt Iteration Workflow:**
+A developer creates `@.mia-code/prompts/reviewer.md` containing a detailed review prompt. They iterate on the prompt file, restarting mia-code to test changes. Once satisfied, they commit both the config and prompt file. The agent definition evolves with the project.