mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/011-agent-permission-rulesets.rispec.md

@@ -0,0 +1,151 @@
+# RISE-011: Agent Permission Rulesets
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/011-agent-permission-rulesets.rispec.md
+
+## Creative Intent
+
+mia-code enables developers to define precise permission boundaries for each agent, controlling which tools, operations, and file paths an agent may access. Permissions are not binary on/off switches but a layered ruleset evaluated in order — the first matching rule wins. This creates a composable, readable, auditable security model that makes agents safe by design. A plan agent that cannot edit files is not merely advised against editing — it is structurally prevented from doing so.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no permission model — every operation is implicitly allowed for every interaction
+- The Gemini and Claude CLI tools have their own internal safety checks, but mia-code adds no layer of control
+- There is no way to restrict file access by path — an agent queried about `README.md` could also read `.env` files containing secrets
+- Bash execution has no confirmation gate — commands run immediately when the engine requests them
+- Write operations have no scope limitation — an agent asked to edit one file could modify any file
+- There is no audit trail of which permissions were exercised during a session
+
+**Desired State:**
+- Each agent carries a permission ruleset — an ordered array of rules evaluated against every tool invocation
+- Rules specify a permission name (tool/operation), an optional file-path pattern, and an action (allow/deny/ask)
+- Evaluation is first-match-wins: the first rule whose permission and pattern match the request determines the outcome
+- A wildcard `*` matches any permission name; glob patterns scope file paths
+- The "ask" action pauses execution and prompts the user for confirmation before proceeding
+- Rulesets are layered: global defaults → built-in agent defaults → user config overrides
+- Every permission check is logged for auditability
+
+## Desired Outcome Definition
+
+Every tool invocation in mia-code passes through a permission check against the active agent's ruleset. The check evaluates rules in order, finds the first match, and enforces the action. Denied operations return an error to the agent. Asked operations pause for user confirmation. Allowed operations proceed silently.
+
+## Natural Language Functional Description
+
+### Rule Structure
+
+A single permission rule is an object with three fields:
+
+```typescript
+interface PermissionRule {
+  permission: string;   // tool or operation name, or "*" for wildcard
+  pattern?: string;     // optional glob pattern for file-path scoping
+  action: "allow" | "deny" | "ask";
+}
+```
+
+### Permission Names
+
+The following permission names correspond to mia-code tool operations:
+
+- `read` — reading file contents, viewing directories
+- `write` — creating new files
+- `edit` — modifying existing files
+- `bash` — executing shell commands
+- `glob` — searching for files by pattern
+- `grep` — searching file contents
+- `fetch` — making HTTP requests
+- `*` — wildcard, matches any permission not explicitly listed
+
+### Pattern Field
+
+The optional `pattern` field is a glob string matched against the file path argument of the operation. When present, the rule only applies if both the permission name and the file path match. When absent, the rule applies to all invocations of that permission regardless of path.
+
+Examples:
+- `{"permission": "read", "pattern": "*.env", "action": "deny"}` — deny reading any `.env` file
+- `{"permission": "read", "pattern": "src/**/*.ts", "action": "allow"}` — allow reading TypeScript files under `src/`
+- `{"permission": "edit", "pattern": "package.json", "action": "ask"}` — require confirmation before editing `package.json`
+
+### Evaluation Order
+
+Rules are evaluated top-to-bottom. The first rule whose `permission` matches the requested operation (or is `*`) and whose `pattern` matches the file path (or is absent) determines the outcome. If no rule matches, the default action is "deny" — fail closed.
+
+### Built-in Agent Rulesets
+
+**build** (full access):
+```json
+[
+  {"permission": "*", "action": "allow"}
+]
+```
+
+**plan** (read-only analysis):
+```json
+[
+  {"permission": "write", "action": "deny"},
+  {"permission": "edit", "action": "deny"},
+  {"permission": "bash", "action": "ask"},
+  {"permission": "read", "action": "allow"},
+  {"permission": "glob", "action": "allow"},
+  {"permission": "grep", "action": "allow"},
+  {"permission": "*", "action": "deny"}
+]
+```
+
+**explore** (fast search): read/glob/grep allowed, everything else denied.
+
+**general** (subagent, controlled access): read/glob/grep allowed, bash/edit/write require confirmation, everything else denied.
+
+### Layered Precedence
+
+Permission rulesets merge across three layers:
+
+1. **Global defaults**: The fail-closed `[{"permission": "*", "action": "deny"}]` baseline
+2. **Built-in agent defaults**: The rulesets defined above for each built-in agent
+3. **User config overrides**: Rules from `mia-code.json` agent definitions (see RISE-010)
+
+User rules are prepended to the agent's default ruleset. Because evaluation is first-match-wins, user rules take precedence over defaults. This means a user can relax or tighten any built-in agent's permissions:
+
+```json
+{"agent": {"plan": {"permissions": [
+  {"permission": "bash", "action": "allow"}
+]}}}
+```
+This prepends an "allow bash" rule before the plan agent's default "ask bash" rule, effectively removing the confirmation requirement.
+
+### The "ask" Action
+
+When a rule evaluates to "ask", mia-code pauses agent execution and presents the user with:
+- The tool name and parameters
+- The file path (if applicable)
+- The agent requesting the operation
+- Options: Allow Once / Allow for Session / Deny
+
+"Allow for Session" adds a temporary "allow" rule for that specific operation and pattern, avoiding repeated prompts for the same action.
+
+### Audit Logging
+
+Every permission check emits a structured log entry (see RISE-007):
+- Timestamp, agent name, permission name, file path, matched rule index, action taken
+- Denied and asked operations are logged at `warn` level; allowed at `debug`
+
+## Supporting Structures
+
+- **Multi-Agent System (RISE-009)** defines the agent model that rulesets protect
+- **Agent Definition Config (RISE-010)** is where user permission overrides are specified
+- **Structured Logging (RISE-007)** provides the audit trail for permission decisions
+- **Named Error System (RISE-006)** generates typed errors for denied operations
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Secret Protection:**
+A `.env` file contains API keys. The global config adds `{"permission": "read", "pattern": "*.env", "action": "deny"}` to all agents. No agent can read environment files — even if explicitly asked. The developer must manually paste relevant values into the conversation.
+
+**Scenario 2 — Progressive Trust:**
+A new developer starts with the plan agent (read-only). As they gain confidence, they switch to build but keep bash on "ask". Over weeks, they adjust their config to "allow" bash for specific directories. The permission system grows with the developer's trust level.
+
+**Scenario 3 — CI Pipeline Safety:**
+In a CI environment, mia-code runs with a config that denies all write/edit operations outside the `dist/` directory. The agent can build and test but cannot modify source code. This prevents accidental source mutations during automated runs.
+
+**Scenario 4 — Selective File Access:**
+A monorepo contains a `secrets/` directory. The team config adds `{"permission": "read", "pattern": "secrets/**", "action": "deny"}` at the top of every agent's ruleset. Agents can explore the entire codebase except the secrets directory, which remains invisible to them.

package/rispecs/borrowed_from_opencode/012-agent-prompt-templates.rispec.md

@@ -0,0 +1,141 @@
+# RISE-012: Agent Prompt Templates
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/012-agent-prompt-templates.rispec.md
+
+## Creative Intent
+
+mia-code enables developers to shape each agent's personality, capabilities, and behavioral constraints through customizable system prompt templates. Templates are not static strings — they are living documents that incorporate runtime context: available tools, active permissions, project structure, and loaded skills. The prompt template system extends mia-code's existing UNIFIER_SYSTEM_PROMPT pattern into a generalized framework where every agent speaks with a crafted voice, informed by its operational reality.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has a single UNIFIER_SYSTEM_PROMPT defined in source code — the dual 🧠 Mia / 🌸 Miette interpretation layer
+- This prompt is static and hardcoded; changing it requires modifying TypeScript source
+- The underlying engines (Gemini CLI, Claude CLI) have their own system prompts that mia-code does not control or extend
+- There is no mechanism to inject project-specific context, tool descriptions, or permission summaries into the system prompt
+- Different agents would need different prompts, but there is no template system to support this
+- Users who want custom behavior must fork the codebase or manipulate environment variables
+
+**Desired State:**
+- Each agent has a default system prompt template stored as a text file alongside its definition
+- Templates support variable interpolation using `{{variable}}` syntax for runtime context injection
+- The system assembles the final prompt at session start by combining: base template + tool descriptions + active permissions + skill instructions + user customizations
+- Users can override any agent's prompt via configuration (see RISE-010)
+- The existing UNIFIER_SYSTEM_PROMPT becomes the template for the unifier layer, applied after each agent's primary prompt
+- Templates are readable, editable, and versionable as plain text
+
+## Desired Outcome Definition
+
+Every agent in mia-code operates with a system prompt assembled from a template, runtime variables, and optional user overrides. The assembled prompt accurately describes the agent's available tools, active permissions, project context, and behavioral guidelines. Users can customize any agent's prompt without modifying source code.
+
+## Natural Language Functional Description
+
+### Template Syntax
+
+Templates are plain text (Markdown-compatible) with `{{variable}}` interpolation:
+
+```markdown
+You are {{agent_name}}, a specialized coding agent.
+
+## Available Tools
+{{tools}}
+
+## Permissions
+{{permissions}}
+
+## Project Context
+{{project}}
+
+## Skills
+{{skills}}
+
+## Guidelines
+{{guidelines}}
+```
+
+Variables are replaced at session start with runtime values. Unknown variables are replaced with empty strings and logged as warnings.
+
+### Built-in Variables
+
+| Variable | Description |
+|----------|-------------|
+| `{{agent_name}}` | The agent's display name (e.g., "Code Reviewer") |
+| `{{agent_description}}` | The agent's description from its definition |
+| `{{tools}}` | Formatted list of available tools with descriptions and parameter schemas |
+| `{{permissions}}` | Human-readable summary of the agent's active permission ruleset |
+| `{{project}}` | Project context: name, root directory, detected language, framework, key files |
+| `{{skills}}` | Available skill definitions and invocation instructions |
+| `{{guidelines}}` | Agent-specific behavioral guidelines from the template |
+| `{{datetime}}` | Current date and time in ISO format |
+| `{{os}}` | Operating system identifier |
+| `{{cwd}}` | Current working directory |
+| `{{session_id}}` | Active session identifier |
+
+### Template Storage
+
+Built-in agent templates are stored in the mia-code source tree under `src/prompts/`:
+
+```
+src/prompts/
+  build.prompt.md       — build agent default template
+  plan.prompt.md        — plan agent default template
+  explore.prompt.md     — explore agent default template
+  general.prompt.md     — general subagent default template
+  unifier.prompt.md     — 🧠/🌸 dual-perspective template (current UNIFIER_SYSTEM_PROMPT)
+```
+
+Custom agent templates referenced via `@filepath` in config (see RISE-010) are loaded from the project directory.
+
+### Prompt Assembly Pipeline
+
+The final system prompt is assembled through a pipeline:
+
+1. **Load base template**: Read the agent's template file (built-in or custom)
+2. **Resolve variables**: Replace all `{{variable}}` placeholders with runtime values
+3. **Inject tool descriptions**: Generate formatted tool documentation from the agent's available tools (filtered by permissions)
+4. **Inject permission summary**: Convert the agent's ruleset into human-readable constraints
+5. **Inject skill instructions**: Append loaded skill definitions and usage patterns
+6. **Apply user customizations**: If the user config provides a `prompt` field, it replaces steps 1-2 entirely (but steps 3-5 still append)
+7. **Append unifier layer**: For primary agents, append the unifier template that produces the 🧠/🌸 dual perspective
+
+The pipeline ensures that even custom prompts receive accurate tool and permission information — users cannot accidentally describe tools the agent does not have access to.
+
+### Tool and Permission Variable Generation
+
+The `{{tools}}` variable is populated by iterating over the agent's available tools (those not denied by permissions) and generating a structured description with name, purpose, and parameter schemas. Tools denied by the agent's permission ruleset are excluded — this prevents the agent from attempting operations it cannot perform.
+
+The `{{permissions}}` variable generates a human-readable summary of the agent's active access restrictions (e.g., "File editing: DENIED", "Shell commands: ASK — requires user permission", "File reading: ALLOWED").
+
+### Extending the Unifier
+
+The existing UNIFIER_SYSTEM_PROMPT becomes `src/prompts/unifier.prompt.md`. It gains access to `{{agent_name}}` and `{{agent_description}}` variables, allowing the unifier's dual 🧠/🌸 interpretation to reference which agent produced the output:
+
+```markdown
+The {{agent_name}} agent has completed its response.
+Provide your dual-perspective interpretation:
+🧠 Mia: [analytical observation about what {{agent_name}} accomplished]
+🌸 Miette: [narrative/emotional reflection on the interaction]
+```
+
+## Supporting Structures
+
+- **Multi-Agent System (RISE-009)** defines the agents that templates serve
+- **Agent Definition Config (RISE-010)** provides the user override mechanism for prompts
+- **Agent Permission Rulesets (RISE-011)** feeds the `{{permissions}}` variable
+- **Zod Schema Validation (RISE-005)** validates template variable names and structure
+- **Namespace Module Pattern (RISE-004)** organizes the prompt assembly pipeline
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Language-Specific Agent:**
+A Rust project creates a custom agent with a prompt template emphasizing Rust idioms, ownership patterns, and `cargo` tooling. The `{{project}}` variable detects `Cargo.toml` and injects Rust-specific context. The agent speaks Rust fluently because its prompt was crafted for it.
+
+**Scenario 2 — Regulated Industry Compliance:**
+A healthcare application's `mia-code.json` overrides the build agent's prompt to include HIPAA compliance guidelines. Every code suggestion from the agent considers data privacy requirements. The prompt is version-controlled alongside the code it governs.
+
+**Scenario 3 — Teaching Assistant Mode:**
+A developer creates a "tutor" agent with a prompt that explains every action, asks Socratic questions, and never provides direct answers. The `{{tools}}` section is present but the guidelines instruct the agent to describe what it would do rather than doing it. Perfect for learning a new codebase.
+
+**Scenario 4 — Minimal Prompt for Speed:**
+For the explore agent, the template is deliberately minimal — just tool descriptions and a single line: "Search the codebase and answer questions concisely." Less prompt text means faster inference and lower token costs for the lightweight model the explore agent uses.

package/rispecs/borrowed_from_opencode/013-agent-generation.rispec.md

@@ -0,0 +1,142 @@
+# RISE-013: Agent Generation
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/013-agent-generation.rispec.md
+
+## Creative Intent
+
+mia-code enables developers to create new agents from natural language descriptions — no JSON syntax, no permission schema knowledge, no prompt engineering required. A user describes what they want an agent to do, and the system generates a complete agent definition: name, description, permission ruleset, system prompt, and recommended model. This democratizes agent creation, making it accessible to anyone who can describe a task in plain English. The generation process itself uses the current active agent as a meta-agent, turning agent creation into a conversation.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Creating a custom agent (per RISE-010) requires understanding the JSON config schema, permission rule syntax, and prompt template variables
+- Users must manually reason about which permissions to allow or deny — a cognitive burden that discourages experimentation
+- Writing effective system prompts requires prompt engineering expertise — most users will write weak prompts that produce underwhelming agents
+- There is no feedback loop — a user writes a config, restarts mia-code, tests the agent, tweaks the config, restarts again
+- The gap between "I want an agent that does X" and a working agent definition is too wide for most users to cross
+
+**Desired State:**
+- Users describe desired agent behavior in natural language during a conversation
+- The system generates a complete, valid agent definition from the description
+- The generated definition is presented for user review before being saved to config
+- Iterative refinement is supported — users test the generated agent, provide feedback, and the system adjusts
+- The generation process explains its choices, teaching users about permissions and prompts along the way
+- Generated agents are indistinguishable from hand-crafted ones — they use the same config format
+
+## Desired Outcome Definition
+
+A user types a natural language description of their desired agent. mia-code generates a complete agent definition (name, description, permissions, prompt, model recommendation), presents it for review, and saves it to `mia-code.json` upon approval. The generated agent is immediately available in the session.
+
+## Natural Language Functional Description
+
+### Generation Trigger
+
+Agent generation is triggered by a command or conversational intent:
+
+- Explicit: `/agent create` or `/create-agent` command
+- Conversational: "create an agent that..." or "I need an agent for..." detected by the active agent
+
+The system enters an interactive generation flow, guided by the active agent acting as a meta-agent.
+
+### Input Processing
+
+The user's natural language description is analyzed for:
+
+1. **Purpose**: What the agent should do (e.g., "review Python code for security issues")
+2. **Constraints**: What the agent should not do (e.g., "never modify files")
+3. **Scope**: What files or directories the agent should focus on (e.g., "only look at the src/ directory")
+4. **Interaction style**: How the agent should communicate (e.g., "be concise", "explain in detail")
+5. **Model implications**: Whether the task needs a powerful model or a fast one
+
+### Generation Pipeline
+
+The meta-agent processes the description through these steps:
+
+**Step 1 — Name and Description:**
+Generate a concise agent key (lowercase, hyphenated), display name, and description from the user's intent.
+
+Example input: "an agent that reviews Python code for security issues and never modifies files"
+Generated: `{"key": "security-reviewer", "name": "Security Reviewer", "description": "Reviews Python code for security vulnerabilities. Read-only — never modifies files."}`
+
+**Step 2 — Permission Ruleset:**
+Map the user's constraints to a concrete permission ruleset. The meta-agent reasons about which permissions to allow, deny, or gate behind confirmation:
+
+```json
+[
+  {"permission": "write", "action": "deny"},
+  {"permission": "edit", "action": "deny"},
+  {"permission": "bash", "action": "deny"},
+  {"permission": "read", "pattern": "**/*.py", "action": "allow"},
+  {"permission": "read", "action": "allow"},
+  {"permission": "glob", "action": "allow"},
+  {"permission": "grep", "action": "allow"},
+  {"permission": "*", "action": "deny"}
+]
+```
+
+**Step 3 — System Prompt:**
+Generate a system prompt tailored to the agent's purpose. The prompt includes behavioral guidelines, focus areas, and output format expectations derived from the user's description.
+
+**Step 4 — Model Recommendation:**
+Based on the task complexity, recommend a model:
+- Simple search/analysis → fast model (Gemini Flash, Haiku)
+- Code review/planning → balanced model (Sonnet, Gemini Pro)
+- Complex reasoning/generation → powerful model (Opus, Gemini Ultra)
+
+**Step 5 — Assembly and Review:**
+The complete agent definition is assembled and presented to the user in a formatted preview:
+
+```
+Generated Agent: Security Reviewer
+Key: security-reviewer
+Model: anthropic / claude-sonnet-4-20250514
+Permissions: read (allow), write (deny), edit (deny), bash (deny)
+Prompt: [preview of first 3 lines]
+
+Save to mia-code.json? [Yes / Edit / Cancel]
+```
+
+### Iterative Refinement
+
+After saving, the agent is immediately available. The user can test it by switching to it (Tab) or invoking it (`@security-reviewer`). If the behavior doesn't match expectations, the user provides feedback:
+
+- "It's too verbose — make it more concise"
+- "It should also check for SQL injection patterns"
+- "Let it read .sql files too"
+
+The meta-agent regenerates the affected parts of the definition (prompt, permissions, or both) and updates the config. This create-test-refine loop continues until the user is satisfied.
+
+### Config Output
+
+The generated definition is written to `mia-code.json` in the standard format (RISE-010). If the file doesn't exist, it is created with minimal structure. If it exists, the new agent is merged into the existing `"agent"` section.
+
+### Safety Guardrails
+
+The generation system enforces safety constraints:
+- Generated agents cannot have broader permissions than the agent that created them
+- The meta-agent explains each permission choice, making the ruleset transparent
+- Generated prompts are sanitized — they cannot contain injection attempts or override core system behavior
+- Users must explicitly approve before the definition is saved
+
+## Supporting Structures
+
+- **Multi-Agent System (RISE-009)** provides the architecture generated agents plug into
+- **Agent Definition Config (RISE-010)** defines the output format for generated definitions
+- **Agent Permission Rulesets (RISE-011)** provides the permission vocabulary the generator uses
+- **Agent Prompt Templates (RISE-012)** supplies the template structure generated prompts follow
+- **Zod Schema Validation (RISE-005)** validates generated definitions before saving
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — First-Time Agent Creation:**
+A developer types: "create an agent that helps me write unit tests for React components." The system generates a "test-writer" agent with file write permissions scoped to `**/*.test.tsx`, a prompt focused on React Testing Library patterns, and a recommendation for Claude Sonnet. The developer tests it, asks for Jest instead of Vitest conventions, and the system adjusts the prompt. Three minutes from idea to working agent.
+
+**Scenario 2 — Non-Technical User:**
+A project manager types: "I need an agent that can read the codebase and answer questions about architecture but cannot change anything." The system generates a read-only "architecture-guide" agent with all write/edit/bash permissions denied. No JSON knowledge required — the PM describes what they want in plain English.
+
+**Scenario 3 — Agent from Existing Agent:**
+A developer says: "create an agent like the build agent but that only works in the backend/ directory." The system clones the build agent's definition, adds path-scoped permissions restricting all operations to `backend/**`, and adjusts the prompt to focus on backend concerns. Inheritance through conversation.
+
+**Scenario 4 — Iterative Prompt Refinement:**
+A developer creates a documentation agent. First test: the agent writes docs in a style they don't like. They say: "use NumPy-style docstrings, not Google style." The system updates only the prompt, preserving all other settings. Second test: the agent tries to run `mkdocs build` without permission. They say: "let it run mkdocs commands." The system adds a bash permission with a pattern. Each iteration is surgical.

package/rispecs/borrowed_from_opencode/014-plan-build-mode-toggle.rispec.md

@@ -0,0 +1,155 @@
+# RISE-014: Plan/Build Mode Toggle
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/014-plan-build-mode-toggle.rispec.md
+
+## Creative Intent
+
+mia-code enables developers to fluidly switch between thinking and doing — between analyzing a problem and executing a solution. Plan mode is the agent with its hands behind its back: it reads, searches, reasons, and suggests, but never modifies. Build mode is the agent with full agency: it edits files, runs commands, creates code, and delivers results. The toggle between them is a single keypress (Tab), preserving full session context. This separation prevents accidental mutations during exploration and encourages a disciplined think-then-act workflow.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has a single operational mode — every prompt can trigger file modifications, command execution, or code generation
+- There is no "safe exploration" mode for reading and analyzing without risk of mutation
+- Developers who want to explore a codebase before making changes must mentally restrain the agent ("don't edit anything, just tell me about...")
+- This restraint is fragile — the agent may still attempt edits if its interpretation suggests them
+- The unifier treats exploration and execution responses identically, missing the opportunity for mode-appropriate commentary
+- Switching between analysis and execution requires changing one's prompting style, not the system's capabilities
+
+**Desired State:**
+- Two primary modes are available: Plan (read-only analysis) and Build (full execution)
+- Each mode is implemented as a distinct agent (see RISE-009) with its own permission ruleset and system prompt
+- Switching between modes is instantaneous via the Tab key — same session, same conversation history
+- A clear visual indicator shows which mode is active at all times
+- The unifier adapts its 🧠/🌸 dual perspective based on the active mode
+- Mode state persists within the session — the system remembers which mode was last active
+
+## Desired Outcome Definition
+
+A developer presses Tab to toggle between Plan and Build modes. Plan mode prevents all file modifications and gates bash execution behind confirmation. Build mode enables full tool access. The switch is instant, contextual, and visually indicated. The conversation flows uninterrupted across mode switches.
+
+## Natural Language Functional Description
+
+### Mode Definitions
+
+**Plan Mode (🔍):**
+- Permission ruleset: read (allow), glob (allow), grep (allow), write (deny), edit (deny), bash (ask), * (deny)
+- System prompt emphasis: analysis, architecture review, dependency mapping, impact assessment, planning
+- Unifier adaptation: 🧠 Mia focuses on structural observations and technical implications; 🌸 Miette reflects on discovery and understanding
+- Default model: same as session default (or configurable to a faster model for rapid exploration)
+- Visual indicator: mode label `[PLAN]` in the prompt area, with a distinct color (e.g., blue)
+
+**Build Mode (🔨):**
+- Permission ruleset: * (allow) — full access to all tools
+- System prompt emphasis: implementation, execution, code generation, testing, delivery
+- Unifier adaptation: 🧠 Mia focuses on execution quality and correctness; 🌸 Miette reflects on creation and progress
+- Default model: session default
+- Visual indicator: mode label `[BUILD]` in the prompt area, with a distinct color (e.g., green)
+
+### Switching Mechanism
+
+The Tab key triggers a mode switch. The process:
+
+1. User presses Tab — the mode switcher UI appears
+2. The switcher shows available primary agents (at minimum: Plan and Build)
+3. User selects the desired mode (or Tab again for instant toggle between the two)
+4. The active agent changes: permission ruleset, system prompt, and visual indicator update
+5. The next message the user sends is processed by the newly active agent
+6. All session context — message history, file state, working directory — remains intact
+
+If only two primary agents exist (Plan and Build), Tab acts as an instant toggle without showing a selection menu. With three or more primary agents, Tab opens the selection menu.
+
+### Context Continuity
+
+Switching modes does not:
+- Clear the message history — the new agent sees everything the previous one discussed
+- Reset file state — changes made in Build mode are visible in Plan mode
+- Change the working directory
+- Interrupt a running operation — mode switches are queued until the current operation completes
+
+Switching modes does:
+- Change the active permission ruleset — immediately enforced on the next tool invocation
+- Change the system prompt — the agent's personality and guidelines shift
+- Update the visual indicator
+- Log the mode switch event (see RISE-007)
+
+### Visual Indicator
+
+The current mode is displayed prominently in the terminal UI:
+
+```
+┌─────────────────────────────────────────┐
+│  mia-code  [BUILD 🔨]  session: abc123  │
+│─────────────────────────────────────────│
+│  > Your prompt here...                  │
+└─────────────────────────────────────────┘
+```
+
+When in Plan mode:
+```
+┌─────────────────────────────────────────┐
+│  mia-code  [PLAN 🔍]  session: abc123   │
+│─────────────────────────────────────────│
+│  > Your prompt here...                  │
+└─────────────────────────────────────────┘
+```
+
+The indicator uses color coding: blue for Plan, green for Build. This provides instant visual feedback about the current operational mode.
+
+### Unifier Adaptation
+
+The unifier's dual 🧠/🌸 interpretation calibrates to the active mode:
+
+**In Plan mode**, after the agent analyzes code:
+```
+🧠 Mia: The authentication module uses a middleware chain pattern with three 
+   layers — rate limiting, token validation, and role checking. The token 
+   validation has no expiry check, which is a gap worth addressing.
+🌸 Miette: We've mapped the territory. The authentication flow is clearer now — 
+   like tracing a river to find where it branches. That missing expiry check 
+   is a quiet risk waiting in the current.
+```
+
+**In Build mode**, after the agent modifies code:
+```
+🧠 Mia: Added JWT expiry validation to the token middleware. The check 
+   throws a 401 with a descriptive error message. Three tests added covering 
+   valid, expired, and missing-expiry scenarios.
+🌸 Miette: That gap we found is sealed now. The code moved from analysis 
+   to action — three tests standing guard where none stood before.
+```
+
+### Default Mode
+
+The session starts in Build mode by default. Users can configure their preferred starting mode in `mia-code.json`:
+
+```json
+{
+  "defaultAgent": "plan"
+}
+```
+
+This is particularly useful for read-only workflows (code review, onboarding) where Plan mode is the natural starting point.
+
+## Supporting Structures
+
+- **Multi-Agent System (RISE-009)** provides the agent architecture that Plan and Build modes are built on
+- **Agent Permission Rulesets (RISE-011)** enforces the read-only constraint in Plan mode
+- **Agent Prompt Templates (RISE-012)** provides mode-specific system prompts
+- **Agent Definition Config (RISE-010)** enables user customization of mode behavior
+- **Event Bus (RISE-002)** broadcasts mode switch events to the UI layer
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Explore Then Execute:**
+A developer is tasked with fixing a bug in an unfamiliar service. They start in Plan mode, asking: "What does the payment processing pipeline look like?" The plan agent reads files, traces imports, and maps the architecture. After understanding the flow, the developer presses Tab to switch to Build mode and says: "Fix the race condition in the payment queue we identified." Build mode has full context from the Plan conversation and executes the fix immediately.
+
+**Scenario 2 — Code Review Workflow:**
+A team lead reviews a PR by starting mia-code in Plan mode. They ask: "What changed in the last 5 commits and what are the risks?" The plan agent analyzes diffs, identifies potential issues, and suggests improvements — all without touching the code. The lead copies the analysis into a review comment. Plan mode ensures the review process is purely observational.
+
+**Scenario 3 — Teaching and Learning:**
+A senior developer mentors a junior by working in Plan mode together. They explore the codebase, discuss patterns, and analyze design decisions. When the junior feels ready, they switch to Build mode to implement what they learned. The mode boundary creates a natural "study then practice" rhythm.
+
+**Scenario 4 — Safe Experimentation:**
+A developer wants to understand what changes an agent would suggest before committing to them. In Plan mode, they ask: "How would you refactor this module to use dependency injection?" The plan agent describes the changes in detail without making them. Satisfied with the approach, the developer switches to Build mode: "Do the refactoring you just described." The agent executes with full context of the planned approach.