mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/040-code-search-tool.rispec.md

@@ -0,0 +1,143 @@
+# RISE-040: Code Search Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/040-code-search-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides a code search tool that reaches beyond the local filesystem to search across GitHub repositories, organizations, and the broader open-source ecosystem. When the agent needs to find usage patterns, discover implementations, or reference code outside the current project, it uses GitHub's code search API with its rich query syntax. For local searches, the tool falls back to ripgrep — ensuring fast, reliable results whether the target is remote or local. The agent gains the same code discovery capability a human developer has when searching on github.com.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- Code search is limited to the local project directory via the CLI's built-in grep/find tools
+- The agent cannot search across an organization's repositories to find usage patterns
+- Discovering how other projects solve a similar problem requires the developer to manually search and paste results
+- There is no integration with GitHub's search syntax (language filters, org scopes, path patterns)
+- Local search via grep is powerful but produces raw line matches without repository or file context
+- The agent cannot answer questions like "how does our auth library handle token refresh across all our services?"
+
+**Desired State:**
+- A `code_search` tool accepts queries in GitHub code search syntax
+- Remote search returns: matching files with code snippets, repository info, file paths, and match highlights
+- Pagination support for large result sets
+- GitHub authentication enables searching private repositories and organization code
+- Local fallback via ripgrep when GitHub is unavailable or when searching the current project
+- Results formatted as code blocks with file and repository context for clear presentation
+- Rate limiting handled transparently with automatic retry
+
+## Desired Outcome Definition
+
+The developer asks: "How do other services in our org handle rate limiting?" The agent issues a code search: `"rate limit" language:TypeScript org:myorg`. GitHub returns 23 matching files across 8 repositories. The agent presents the top results with code snippets, identifies common patterns, and recommends an approach consistent with the organization's existing code.
+
+## Natural Language Functional Description
+
+### Input Format
+
+```typescript
+interface CodeSearchInput {
+  query: string;              // GitHub search syntax query
+  scope?: "github" | "local"; // default: "github", falls back to "local" if unavailable
+  page?: number;              // pagination (default: 1)
+  perPage?: number;           // results per page (default: 20, max: 100)
+}
+```
+
+### GitHub Search Syntax
+
+The tool supports GitHub's full code search syntax:
+
+- `content:authenticate` — search for specific content
+- `language:TypeScript` — filter by programming language
+- `org:myorg` — scope to an organization
+- `repo:owner/name` — scope to a specific repository
+- `path:src/auth` — filter by file path
+- `extension:ts` — filter by file extension
+- Boolean operators: `AND`, `OR`, `NOT`
+
+Examples:
+- `"useEffect" language:TypeScript org:myorg` — find React hooks usage across org
+- `content:authenticate path:middleware extension:ts` — find auth middleware in TypeScript
+- `"TODO" repo:myorg/backend` — find TODOs in a specific repo
+
+### Remote Search (GitHub)
+
+When scope is "github" (default):
+
+1. Authenticate using the configured GitHub token (RISE-029)
+2. Send the query to GitHub's code search API
+3. Parse results into structured format with code snippets
+4. Handle rate limiting: if 403 with rate limit headers, wait and retry
+5. Return paginated results with metadata
+
+### Local Search (ripgrep fallback)
+
+When scope is "local" or GitHub is unavailable:
+
+1. Convert the query to ripgrep arguments (basic pattern extraction)
+2. Execute `rg --json` for structured output
+3. Format results to match the remote result structure
+4. No pagination needed — results stream directly
+
+The fallback is automatic: if the GitHub API returns a network error, the tool silently falls back to local search and notes this in the result metadata.
+
+### Output Format
+
+```json
+{
+  "source": "github",
+  "totalCount": 23,
+  "page": 1,
+  "results": [
+    {
+      "repository": "myorg/auth-service",
+      "path": "src/middleware/rateLimiter.ts",
+      "url": "https://github.com/myorg/auth-service/blob/main/src/middleware/rateLimiter.ts",
+      "snippet": "export function rateLimiter(limit: number, window: number) {\n  const tokens = new Map<string, number>();\n  ...\n}",
+      "matchLines": [12, 13, 14],
+      "language": "TypeScript"
+    }
+  ]
+}
+```
+
+### Rate Limit Management
+
+GitHub's search API has strict rate limits (30 requests/minute for authenticated users). The tool:
+
+- Tracks remaining requests from response headers
+- Waits automatically when rate limited (using `retry-after` or calculated backoff)
+- Reports rate limit status in result metadata
+- Suggests local search when rate limit is exhausted
+
+### Authentication
+
+The tool requires a GitHub token for:
+- Searching private repositories
+- Higher rate limits (30/min vs 10/min unauthenticated)
+- Organization-scoped searches
+
+If no token is configured, the tool searches only public repositories and warns about limited access.
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers the code_search tool with id `code_search`
+- **Tool Context Injection (RISE-035)** provides session context and cancellation signal
+- **Provider Authentication (RISE-029)** supplies GitHub authentication tokens
+- **Tool Output Truncation (RISE-036)** truncates large result sets to prevent context overflow
+- **Web Fetch Tool (RISE-041)** provides the HTTP client used for GitHub API requests
+- **Named Error System (RISE-006)** provides CodeSearchRateLimitError, CodeSearchAuthError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Cross-Org Pattern Discovery:**
+The developer asks "how do our services implement health checks?" The agent searches `path:health language:TypeScript org:ourcompany`. It finds 12 implementations across 8 services, identifies that 10 use the same pattern (express endpoint returning JSON status), and recommends following the established convention.
+
+**Scenario 2 — Open Source Reference:**
+The agent needs to implement a trie data structure. It searches `"class Trie" language:TypeScript stars:>100`. It finds well-tested implementations in popular repositories and adapts the approach for the current project, citing the source.
+
+**Scenario 3 — Automatic Local Fallback:**
+The developer is on a plane with no internet. The agent tries a GitHub search, gets a network error, automatically falls back to `rg` for local search, and notes "Searched locally (GitHub unavailable)." The workflow continues uninterrupted.
+
+**Scenario 4 — Usage Impact Analysis:**
+Before renaming a shared utility function, the agent searches `content:parseConfig repo:myorg/shared-utils` across all organization repos that import the shared library. It finds 34 consumers and estimates the impact of the rename. The developer now has data to decide whether to rename or deprecate.

package/rispecs/borrowed_from_opencode/041-web-fetch-tool.rispec.md

@@ -0,0 +1,131 @@
+# RISE-041: Web Fetch Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/041-web-fetch-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides a web fetch tool that retrieves content from URLs, transforming raw web responses into agent-friendly formats. HTML pages become readable markdown. JSON responses are formatted and navigable. Binary content is identified and handled gracefully. The agent can read documentation, inspect API endpoints, fetch configuration files, and access any publicly available web resource — extending its knowledge beyond the local filesystem and its training data. Security boundaries ensure the tool cannot be used to probe internal networks or access local files via URL schemes.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- The agent cannot access web content directly — it relies on training data and user-pasted content
+- When the agent needs to read documentation, the developer must manually copy-paste relevant sections
+- API responses cannot be inspected interactively — the developer runs curl and pastes output
+- There is no content transformation — raw HTML is unusable in a conversation context
+- No security boundaries exist for URL access — a tool with unrestricted fetch could probe internal services
+
+**Desired State:**
+- A `web_fetch` tool retrieves content from any URL with configurable method, headers, and body
+- HTML responses are automatically converted to clean markdown for readable consumption
+- JSON responses are pretty-formatted with optional path navigation
+- Binary content is detected and returns metadata (size, content-type) instead of raw bytes
+- Configurable response size limits prevent context overflow from large pages
+- URL allowlist/blocklist prevents access to internal networks and `file://` schemes
+- Timeout and streaming support for large or slow responses
+
+## Desired Outcome Definition
+
+The developer says "check what the Express.js middleware docs say about error handling." The agent fetches the Express error handling documentation URL, receives clean markdown conversion of the HTML page, extracts the relevant section, and presents a summary with a link to the source. The entire round-trip is one tool call.
+
+## Natural Language Functional Description
+
+### Input Format
+
+```typescript
+interface WebFetchInput {
+  url: string;
+  method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD";  // default: GET
+  headers?: Record<string, string>;
+  body?: string;
+  maxBytes?: number;           // max response size (default: 100KB)
+  timeout?: number;            // request timeout in ms (default: 30000)
+  format?: "auto" | "raw" | "markdown";  // output format (default: auto)
+}
+```
+
+### Content Processing Pipeline
+
+Responses pass through a format-specific processing pipeline:
+
+1. **Content-Type detection** — inspect the `Content-Type` response header
+2. **HTML → Markdown** — strip scripts/styles, convert semantic HTML to markdown, preserve code blocks, links, and headings. Uses a turndown-style converter.
+3. **JSON → Formatted JSON** — pretty-print with 2-space indentation. Large arrays are summarized.
+4. **Plain text** — pass through unchanged
+5. **Binary** — return metadata only: `{type: "binary", contentType: "image/png", size: 45312}`
+6. **Size limiting** — if processed content exceeds `maxBytes`, truncate with a note
+
+### Output Format
+
+```json
+{
+  "status": 200,
+  "contentType": "text/html",
+  "url": "https://expressjs.com/en/guide/error-handling.html",
+  "content": "# Error Handling\n\nExpress comes with a built-in error handler...",
+  "format": "markdown",
+  "fetchedBytes": 34567,
+  "truncated": false
+}
+```
+
+### Security Controls
+
+The tool enforces strict URL security:
+
+- **Blocked schemes** — `file://`, `ftp://`, `data:` (only `http://` and `https://` allowed)
+- **Blocked hosts** — `localhost`, `127.0.0.1`, `::1`, `0.0.0.0`, `169.254.*` (link-local), `10.*`, `172.16-31.*`, `192.168.*` (private ranges)
+- **Configurable allowlist** — projects can explicitly allow specific internal URLs via config
+- **Configurable blocklist** — organizations can block specific domains
+
+These defaults prevent the agent from being used to probe internal infrastructure. The allowlist enables intentional access to internal documentation servers or staging APIs.
+
+### User Agent and Identification
+
+Requests include a descriptive User-Agent header:
+
+```
+User-Agent: mia-code/1.0 (AI coding agent; +https://github.com/mia-code)
+```
+
+This enables web servers to identify requests from coding agents and serve appropriate content.
+
+### Timeout and Streaming
+
+- **Connection timeout** — 10 seconds to establish TCP connection
+- **Response timeout** — configurable total response time (default: 30 seconds)
+- **Streaming** — for responses larger than `maxBytes`, the tool reads only up to the limit and closes the connection, avoiding memory pressure from large downloads
+
+### Error Handling
+
+Common failure modes and their responses:
+
+- **DNS failure** — `{error: "DNS resolution failed for example.invalid"}`
+- **Connection refused** — `{error: "Connection refused at https://..."}`
+- **Timeout** — `{error: "Request timed out after 30000ms"}`
+- **HTTP errors** — returned as results with status code (4xx/5xx are not tool errors)
+- **Blocked URL** — `{error: "URL blocked by security policy: private network access denied"}`
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers the web_fetch tool with id `web_fetch`
+- **Tool Context Injection (RISE-035)** provides abort signal for cancellation
+- **Tool Output Truncation (RISE-036)** applies secondary truncation if content exceeds context limits
+- **Multi-Level Config (RISE-064)** provides URL allowlist/blocklist configuration
+- **Permission System (RISE-074)** gates web fetch behind the "network" permission
+- **Named Error System (RISE-006)** provides FetchSecurityError, FetchTimeoutError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Documentation Lookup:**
+The developer asks "what's the correct way to use Zod's `.transform()`?" The agent fetches the Zod documentation page, converts it to markdown, extracts the `.transform()` section, and presents a clear explanation with code examples — all from the latest docs, not training data.
+
+**Scenario 2 — API Endpoint Testing:**
+The developer says "check if the staging API health endpoint is responding." The agent fetches `https://staging.example.com/health` (allowed in the project's URL allowlist) and reports: "Status 200, response: `{status: 'ok', version: '2.1.3', uptime: '4d 3h'}`."
+
+**Scenario 3 — Security Boundary:**
+The agent attempts to fetch `http://169.254.169.254/latest/meta-data/` (AWS metadata endpoint). The tool blocks it: "URL blocked by security policy: private network access denied." The agent cannot exfiltrate cloud credentials even if instructed to do so.
+
+**Scenario 4 — Large Page Handling:**
+The agent fetches a lengthy API reference page (500KB HTML). The tool converts it to 200KB of markdown, which exceeds the 100KB default limit. The content is truncated with a note: "Content truncated at 100KB (full page: 200KB). Refine your query or increase maxBytes." The agent works with the first 100KB or asks a more specific question.

package/rispecs/borrowed_from_opencode/042-web-search-tool.rispec.md

@@ -0,0 +1,159 @@
+# RISE-042: Web Search Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/042-web-search-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides a web search tool that queries the internet for current information, returning ranked results with titles, URLs, and content snippets. The agent can answer questions about recent developments, find documentation for unfamiliar libraries, discover solutions to error messages, and access information beyond its training data cutoff. Search results include source citations, enabling the developer to verify claims and follow links for deeper reading. The tool transforms the agent from a static knowledge base into a research-capable assistant.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- The agent's knowledge is frozen at its training data cutoff — it cannot answer questions about recent releases, new APIs, or current best practices
+- When the developer encounters an unfamiliar error, they must search the web themselves and paste relevant results
+- The agent cannot discover documentation for newly released libraries or breaking changes in dependencies
+- There is no way to verify the agent's claims against current sources — hallucination risk increases for recent topics
+- Finding solutions to environment-specific issues (platform bugs, version conflicts) requires human research
+
+**Desired State:**
+- A `web_search` tool accepts natural language queries and returns search results
+- Results include: title, URL, relevance snippet, and optionally fetched-and-summarized content
+- The search provider is configurable (default: integrated search API)
+- Results are deduplicated and ranked by relevance
+- Source citations are included in every result for verifiability
+- Rate limiting is handled transparently with queued retries
+- The agent uses search proactively when it detects knowledge gaps
+
+## Desired Outcome Definition
+
+The developer asks "what changed in React 19?" The agent searches the web, finds the React 19 blog post, the migration guide, and three tutorial articles. It synthesizes the results into a concise summary of key changes — Server Components as default, new hooks, compiler — with citations linking to each source. The developer gets current, verified information without leaving their terminal.
+
+## Natural Language Functional Description
+
+### Input Format
+
+```typescript
+interface WebSearchInput {
+  query: string;                    // natural language search query
+  maxResults?: number;              // max results to return (default: 10)
+  fetchContent?: boolean;           // fetch and include page content (default: false)
+  contentMaxBytes?: number;         // max content per result when fetching (default: 10KB)
+}
+```
+
+### Search Execution
+
+1. **Query submission** — send the query to the configured search provider
+2. **Result parsing** — extract title, URL, and snippet from each result
+3. **Deduplication** — remove duplicate URLs and near-duplicate snippets
+4. **Optional content fetch** — if `fetchContent: true`, fetch the top N result URLs via the web fetch tool (RISE-041) and include processed content
+5. **Formatting** — structure results with clear titles, snippets, and source URLs
+
+### Output Format
+
+```json
+{
+  "query": "React 19 new features",
+  "resultCount": 8,
+  "results": [
+    {
+      "title": "React 19 — What's New",
+      "url": "https://react.dev/blog/2025/04/react-19",
+      "snippet": "React 19 introduces Server Components as a first-class feature, a new React Compiler, and simplified ref handling...",
+      "source": "react.dev"
+    },
+    {
+      "title": "Migrating to React 19 — Complete Guide",
+      "url": "https://example.com/react-19-migration",
+      "snippet": "This guide covers every breaking change in React 19 and how to update your codebase...",
+      "source": "example.com"
+    }
+  ],
+  "citations": [
+    "[1] https://react.dev/blog/2025/04/react-19",
+    "[2] https://example.com/react-19-migration"
+  ]
+}
+```
+
+### Content Fetching Mode
+
+When `fetchContent: true`, the tool uses the web fetch tool (RISE-041) to retrieve page content for the top results:
+
+```json
+{
+  "results": [
+    {
+      "title": "React 19 — What's New",
+      "url": "https://react.dev/blog/2025/04/react-19",
+      "snippet": "React 19 introduces Server Components...",
+      "content": "# React 19\n\n## Server Components\n\nServer Components are now...",
+      "contentTruncated": true
+    }
+  ]
+}
+```
+
+This enables the agent to provide detailed answers without the developer needing to read the source pages.
+
+### Search Provider Configuration
+
+The search provider is configurable in project or global configuration:
+
+```json
+{
+  "tools": {
+    "web_search": {
+      "provider": "default",
+      "apiKey": "${WEB_SEARCH_API_KEY}"
+    }
+  }
+}
+```
+
+The default provider uses an integrated search API. Custom providers can be configured for organizational search proxies or alternative search engines.
+
+### Rate Limiting
+
+Search APIs have strict rate limits. The tool handles them by:
+
+- Tracking request counts per time window
+- Queuing requests when approaching the limit
+- Displaying "⏳ Search rate limited, waiting..." when throttled
+- Returning cached results for identical queries within a short window (5 minutes)
+
+### Citation Format
+
+Every search result includes a numbered citation. When the agent uses search results in its response, it can reference sources:
+
+```
+React 19 introduces Server Components as a default feature [1] and includes a new
+compiler that automatically optimizes re-renders [2].
+
+[1] https://react.dev/blog/2025/04/react-19
+[2] https://react.dev/blog/2025/04/react-compiler
+```
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers the web_search tool with id `web_search`
+- **Tool Context Injection (RISE-035)** provides session context and cancellation
+- **Web Fetch Tool (RISE-041)** fetches page content for content-enriched results
+- **Tool Output Truncation (RISE-036)** truncates large result sets
+- **Multi-Level Config (RISE-064)** provides search provider configuration
+- **Permission System (RISE-074)** gates web search behind the "network" permission
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Error Message Research:**
+The developer encounters `ENOSPC: System limit for number of file watchers reached`. The agent searches this error message, finds the standard fix (increasing `fs.inotify.max_user_watches`), and provides the exact command with a citation to the relevant Node.js documentation.
+
+**Scenario 2 — Library Evaluation:**
+The developer asks "should I use Drizzle or Prisma for this project?" The agent searches for recent comparisons, finds benchmark data and community opinions from the last 3 months, and presents a balanced summary with citations — far more current than anything in training data.
+
+**Scenario 3 — Breaking Change Discovery:**
+During a dependency upgrade, tests fail with a cryptic error. The agent searches `"libraryX 3.0 breaking changes"`, finds the migration guide, identifies the specific change causing the failure, and applies the fix — all without the developer leaving the conversation.
+
+**Scenario 4 — Current Documentation:**
+The developer asks about a new cloud provider feature released last week. The agent searches, finds the announcement blog post and API documentation, and explains the feature with accurate, current details. Without web search, it would either hallucinate or admit ignorance.

package/rispecs/borrowed_from_opencode/043-todo-tool.rispec.md

@@ -0,0 +1,156 @@
+# RISE-043: Built-in Todo Tool
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/043-todo-tool.rispec.md
+
+## Creative Intent
+
+mia-code provides a built-in task tracking tool that lets the agent create, manage, and track todo items within a session. When the agent plans a multi-step implementation, it creates todos for each step, updates their status as it works, and marks them done on completion. The developer sees a living task list that reflects the agent's progress and intent. This is not a project management system — it is a lightweight, session-scoped scratchpad that makes the agent's plan visible and trackable. The developer can also interact with todos directly via a `/todos` slash command.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- The agent keeps its plan in free-form text within the conversation — there is no structured task tracking
+- Multi-step tasks are easy to lose track of — the agent may forget steps after context compaction
+- There is no visible indicator of progress through a plan — the developer must read conversation history
+- The developer cannot see what the agent intends to do next or what remains
+- Interrupted sessions lose all planning context — resuming requires re-explanation
+
+**Desired State:**
+- A `todo` tool with two operations: `read` (list/filter todos) and `write` (create/update/delete todos)
+- Todo items have: id, title, description, status (pending/in_progress/done/blocked), priority, timestamps
+- Todos persist per session in the database (RISE-080) — they survive compaction and session restarts
+- The agent creates todos during planning, updates status during execution, and marks done on completion
+- A `/todos` slash command lets the developer view, add, and manage todos directly
+- Todo status integrates with the UI to show progress indicators
+
+## Desired Outcome Definition
+
+The developer asks "refactor the auth module to use JWT." The agent creates 5 todos: install jsonwebtoken, create token utils, update auth middleware, update login handler, update tests. As it works through each step, the todo status updates from pending → in_progress → done. The developer sees a progress bar: "3/5 tasks complete." If the session is interrupted and resumed, the todo list persists with accurate status.
+
+## Natural Language Functional Description
+
+### Tool Operations
+
+The todo tool supports two operations via a single tool with mode parameter:
+
+**Read Operation:**
+```typescript
+interface TodoReadInput {
+  mode: "read";
+  filter?: {
+    status?: "pending" | "in_progress" | "done" | "blocked";
+    priority?: "low" | "medium" | "high";
+  };
+}
+```
+
+**Write Operation:**
+```typescript
+interface TodoWriteInput {
+  mode: "write";
+  action: "add" | "update" | "remove";
+  todo?: {
+    id?: string;          // required for update/remove
+    title?: string;       // required for add
+    description?: string;
+    status?: "pending" | "in_progress" | "done" | "blocked";
+    priority?: "low" | "medium" | "high";
+  };
+}
+```
+
+### Todo Data Model
+
+```typescript
+interface Todo {
+  id: string;                // auto-generated UUID or descriptive kebab-case
+  title: string;             // brief task description
+  description: string;       // detailed task description with context
+  status: TodoStatus;        // current state
+  priority: TodoPriority;    // urgency level
+  createdAt: string;         // ISO 8601 timestamp
+  updatedAt: string;         // ISO 8601 timestamp
+}
+
+type TodoStatus = "pending" | "in_progress" | "done" | "blocked";
+type TodoPriority = "low" | "medium" | "high";
+```
+
+### Persistence
+
+Todos are stored in the session's SQLite database (RISE-080):
+
+```sql
+CREATE TABLE todos (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  description TEXT DEFAULT '',
+  status TEXT DEFAULT 'pending',
+  priority TEXT DEFAULT 'medium',
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+```
+
+Todos are scoped to the current session — they do not leak across sessions. They persist through session compaction (RISE-019) because they are stored in the database, not in conversation history.
+
+### Output Formatting
+
+The read operation returns a formatted todo list:
+
+```
+📋 Todos (3/5 complete):
+
+  ✅ [done] Install jsonwebtoken package
+  ✅ [done] Create src/utils/token.ts with sign/verify functions
+  ✅ [done] Update auth middleware to validate JWT
+  🔄 [in_progress] Update login handler to return JWT
+  ⬜ [pending] Update auth tests for JWT flow
+```
+
+Status icons: ⬜ pending, 🔄 in_progress, ✅ done, 🚫 blocked
+
+### Agent Integration Pattern
+
+The agent follows a consistent pattern with todos:
+
+1. **Planning phase** — create todos for each identified step, ordered by dependency
+2. **Execution phase** — before starting a step, update its todo to `in_progress`; after completing, update to `done`
+3. **Blocked handling** — if a step cannot proceed, update to `blocked` with a description of why
+4. **Completion** — after all todos are done, summarize the completed work
+
+### Slash Command: `/todos`
+
+The developer can interact with todos directly:
+
+- `/todos` — list all todos with status
+- `/todos add <title>` — add a new todo
+- `/todos done <id>` — mark a todo as done
+- `/todos clear` — remove all completed todos
+
+This gives the developer direct control alongside the agent's automated management.
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** registers the todo tool with id `todo`
+- **Tool Context Injection (RISE-035)** provides session ID for scoping
+- **SQLite Storage (RISE-080)** persists todos in the session database
+- **Session Persistence (RISE-018)** ensures todos survive session restarts
+- **Session Compaction (RISE-019)** preserves todos during context compaction
+- **Keybinding System (RISE-063)** can bind a key to show todos
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Visible Progress:**
+The developer asks for a complex refactoring. The agent creates 8 todos. As it works, the TUI shows a progress bar updating in real-time: "3/8 ▓▓▓░░░░░". The developer knows exactly where things stand without reading the full conversation.
+
+**Scenario 2 — Session Resumption:**
+The developer stops mid-refactoring and resumes the session later. The agent reads the todo list: 4 done, 1 in_progress, 3 pending. It picks up exactly where it left off — "Resuming from step 5: update the API routes" — without the developer needing to re-explain the plan.
+
+**Scenario 3 — Developer Adds Context:**
+While the agent works on auth refactoring, the developer types `/todos add "also update the logout endpoint"`. The agent sees the new todo on its next read and incorporates it into the plan naturally.
+
+**Scenario 4 — Blocked Task Handling:**
+The agent marks "deploy to staging" as `blocked` with description: "Requires CI pipeline access — cannot proceed without deploy token." The developer sees the blocked item, provides the token, and the agent unblocks and continues.