mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/094-skill-system.rispec.md

@@ -0,0 +1,187 @@
+# RISE-094: Skill System
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/094-skill-system.rispec.md
+
+## Creative Intent
+
+mia-code enables developers to define custom reusable skills as simple markdown files. A skill is a prompt template — structured instructions that inject specialized knowledge into the agent's context for a specific task. A "code-review" skill teaches the agent a team's review checklist. A "commit-message" skill enforces a commit format. A "test-writer" skill carries testing patterns. Skills are the mechanism by which teams encode their craft knowledge into something an AI agent can follow consistently. They are not code — they are written wisdom.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no mechanism for users to define reusable specialized instructions
+- The agent's behavior is governed by the system prompt and CLAUDE.md — both are monolithic
+- Developers repeat the same instructions across sessions: "use this commit format," "follow this review checklist"
+- No way to share specialized instructions across projects or team members
+- Agent behavior cannot be customized per-task without rewriting the entire system prompt
+
+**Desired State:**
+- Skills are markdown files with YAML frontmatter (name, description) and a markdown body (instructions)
+- Skills live in `.mia-code/skills/` (project-local) or `~/.mia-code/skills/` (global)
+- The agent invokes a skill by name, receiving its content as additional context
+- Skills are prompt templates — they inject structured instructions, not executable code
+- Skills are discoverable via `/skills` command listing all available skills
+- Skills are composable — one skill can reference others for layered instructions
+
+## Desired Outcome Definition
+
+A developer creates a markdown file in `.mia-code/skills/code-review.md` with a name, description, and review instructions. When the agent needs to perform a code review, it invokes the "code-review" skill and receives those instructions as context. The skill shapes the agent's behavior for that specific task without altering its general capabilities.
+
+## Natural Language Functional Description
+
+### Skill File Format
+
+A skill is a markdown file with YAML frontmatter:
+
+```markdown
+---
+name: code-review
+description: Perform a thorough code review following team standards
+---
+
+# Code Review Skill
+
+When reviewing code, follow these steps:
+
+## 1. Security Check
+- Look for SQL injection, XSS, and CSRF vulnerabilities
+- Check that user input is validated and sanitized
+- Verify authentication and authorization on all endpoints
+
+## 2. Logic Review
+- Verify edge cases are handled (null, empty, overflow)
+- Check error handling is comprehensive
+- Ensure no infinite loops or unbounded recursion
+
+## 3. Style Compliance
+- Verify naming conventions match the project
+- Check for consistent formatting
+- Ensure comments explain "why" not "what"
+
+## 4. Output Format
+Provide your review as a list of findings:
+- 🔴 Critical: must fix before merge
+- 🟡 Warning: should fix, not blocking
+- 🟢 Suggestion: optional improvement
+```
+
+### Frontmatter Fields
+
+| Field         | Required | Description                              |
+|---------------|----------|------------------------------------------|
+| `name`        | Yes      | Unique skill identifier (kebab-case)     |
+| `description` | Yes      | One-line description shown in skill list |
+| `tags`        | No       | Categorization tags for filtering        |
+| `author`      | No       | Skill author for attribution             |
+| `version`     | No       | Skill version for tracking changes       |
+
+### Skill Storage Locations
+
+- **Project skills**: `.mia-code/skills/` — available only in this project
+- **Global skills**: `~/.mia-code/skills/` — available in all projects
+- Project skills override global skills with the same name
+
+### Skill Invocation
+
+The agent invokes a skill through the skill tool:
+
+```typescript
+// Agent calls the skill tool
+const skillContent = await tools.skill({ name: "code-review" })
+// skillContent contains the full markdown body of the skill
+// Agent uses this content as additional instructions for the current task
+```
+
+The skill content is injected into the agent's context as a system-level instruction. The agent follows the skill's instructions while processing the current task.
+
+### Skill Listing
+
+The `/skills` command lists all available skills:
+
+```
+Available Skills:
+  code-review     Perform a thorough code review following team standards       [project]
+  commit-message  Write commit messages in conventional format                  [project]
+  test-writer     Generate unit tests with coverage targets                     [global]
+  refactor        Refactor code following SOLID principles                      [global]
+```
+
+### Skill Composability
+
+A skill can reference other skills in its instructions:
+
+```markdown
+---
+name: pr-review
+description: Complete PR review combining code review and test verification
+---
+
+# PR Review
+
+1. First, invoke the `code-review` skill and apply it to all changed files
+2. Then, invoke the `test-writer` skill to verify test coverage for changes
+3. Finally, summarize findings in a PR comment format
+```
+
+The agent interprets these references and invokes the referenced skills as needed.
+
+### Example Skills
+
+**commit-message.md:**
+```markdown
+---
+name: commit-message
+description: Write commit messages in conventional format
+---
+Format: <type>(<scope>): <description>
+Types: feat, fix, docs, style, refactor, test, chore
+Scope: optional, describes the area of change
+Description: imperative mood, lowercase, no period
+Body: explain what and why, not how
+Footer: reference issues with "Closes #123"
+```
+
+**test-writer.md:**
+```markdown
+---
+name: test-writer
+description: Generate unit tests following project patterns
+---
+Use the existing test files as examples for style and structure.
+Each test should: describe behavior, not implementation.
+Coverage targets: branches > 80%, lines > 90%.
+Use describe/it blocks with clear names.
+Mock external dependencies, never mock the unit under test.
+```
+
+### Skills Are Not Code
+
+Skills do not execute. They are text — structured instructions that guide the agent's behavior. This distinction matters:
+
+- Skills cannot access the filesystem directly
+- Skills cannot call APIs or run commands
+- Skills cannot modify the agent's capabilities
+- Skills only influence what the agent does through natural language guidance
+- The agent interprets and follows skill instructions using its own judgment
+
+## Supporting Structures
+
+- **Skill Discovery (RISE-095)** defines how skills are found across multiple locations
+- **Agent Prompt Templates (RISE-012)** provides the template system skills extend
+- **Agent Definition Config (RISE-010)** can reference default skills for an agent
+- **Namespace Module Pattern (RISE-004)** organizes skill loading under a skills namespace
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Team Review Standards:**
+A tech lead creates `code-review.md` in the project's `.mia-code/skills/`. Every developer on the team gets consistent code reviews from the agent — same checklist, same severity levels, same output format. The skill encodes the team's review culture.
+
+**Scenario 2 — Personal Workflow:**
+A developer creates global skills for their personal habits: `commit-message.md` with their preferred format, `documentation.md` with their JSDoc style, `refactor.md` with their preferred patterns. These skills follow them across all projects.
+
+**Scenario 3 — Onboarding Acceleration:**
+A new team member clones the project and finds skills for every common task: code review, testing, deployment, documentation. The agent follows these skills and produces output that matches team standards from day one. The skills are living onboarding documents.
+
+**Scenario 4 — Skill Sharing:**
+A developer publishes their best skills as a GitHub repository. Other developers copy them into their global skills directory. The community builds a library of reusable agent instructions — crowd-sourced craft wisdom.

package/rispecs/borrowed_from_opencode/095-skill-discovery.rispec.md

@@ -0,0 +1,182 @@
+# RISE-095: Skill Discovery
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/095-skill-discovery.rispec.md
+
+## Creative Intent
+
+mia-code automatically discovers and loads skills from multiple sources — project directories, global user directories, custom paths, and remote URLs. Discovery is the mechanism that makes skills composable across contexts. A developer drops a skill file into `.mia-code/skills/` and it is immediately available. A team publishes skills at a URL and every developer's agent fetches them. Discovery runs at startup and can be refreshed on demand, ensuring the agent always knows what skills are available without manual registration.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no skill system — there is nothing to discover
+- Configuration is loaded from fixed locations (`.mia-code/config.json`, `~/.mia-code/config.json`)
+- No mechanism exists to load content from remote URLs with caching
+- No file-type validation ensures discovered files meet a required format
+- No precedence rules govern conflicts between files with the same name from different sources
+
+**Desired State:**
+- Skills are discovered from five sources in a defined precedence order
+- Project skills override global skills — local customization wins
+- Remote skills are downloaded, cached, and refreshed on a configurable TTL
+- Duplicate skill names trigger a warning with source attribution
+- Skill format is validated: frontmatter must include `name` and `description`
+- Discovery runs at startup and on-demand via `/skills refresh`
+- The agent's system prompt includes the count of available skills
+
+## Desired Outcome Definition
+
+When mia-code starts, it scans multiple directories and remote URLs for skill files. Valid skills are loaded into a registry keyed by name. The agent is informed of available skills and can invoke any of them by name. Discovery is fast, cached, and conflict-aware.
+
+## Natural Language Functional Description
+
+### Discovery Sources (Precedence Order)
+
+Skills are discovered from five sources, listed from highest to lowest precedence:
+
+| Priority | Source                             | Location                            |
+|----------|------------------------------------|-------------------------------------|
+| 1        | Project `.mia-code/skills/`        | `{projectRoot}/.mia-code/skills/`   |
+| 2        | Project `.agents/skills/`          | `{projectRoot}/.agents/skills/`     |
+| 3        | Global `~/.mia-code/skills/`       | `~/.mia-code/skills/`               |
+| 4        | Custom paths from config           | `{"skill": {"paths": ["./my-skills"]}}` |
+| 5        | Remote URLs from config            | `{"skill": {"urls": ["https://..."]}}` |
+
+Source 2 (`.agents/skills/`) exists for compatibility with other tools that use the `.agents` convention.
+
+### Discovery Algorithm
+
+1. **Scan directories**: for each source (1-4), glob for `*.md` files in the directory
+2. **Fetch remote**: for each URL in source 5, download the markdown file
+3. **Parse frontmatter**: extract YAML frontmatter from each file
+4. **Validate format**: ensure `name` and `description` fields exist
+5. **Register skills**: add to registry keyed by `name`
+6. **Handle duplicates**: higher-precedence source wins; log warning for conflicts
+7. **Report**: log total skill count and any warnings
+
+### File Discovery Pattern
+
+```
+.mia-code/skills/
+├── code-review.md        → skill "code-review"
+├── commit-message.md     → skill "commit-message"
+├── testing/
+│   ├── unit-test.md      → skill "unit-test"
+│   └── e2e-test.md       → skill "e2e-test"
+└── README.md             → skipped (no valid frontmatter)
+```
+
+Subdirectories are scanned recursively. Files without valid YAML frontmatter containing `name` and `description` are silently skipped.
+
+### Remote Skills
+
+Remote skills are fetched from URLs specified in configuration:
+
+```json
+{
+  "skill": {
+    "urls": [
+      "https://raw.githubusercontent.com/team/skills/main/code-review.md",
+      "https://example.com/skills/testing.md"
+    ]
+  }
+}
+```
+
+**Caching**: remote skills are cached in `~/.mia-code/cache/skills/` after first download.
+
+**TTL (Time-To-Live)**: cached skills are refreshed after 7 days by default. Configure:
+```json
+{
+  "skill": {
+    "cacheTTL": 604800   // seconds (7 days)
+  }
+}
+```
+
+**Offline**: if a remote URL is unreachable, the cached version is used. If no cache exists, the skill is skipped with a warning.
+
+**Security**: remote skills are markdown only — they cannot execute code. The agent interprets them as instructions, not as executable content.
+
+### Duplicate Handling
+
+When multiple sources provide a skill with the same name:
+
+1. The highest-precedence source wins (project > global > custom > remote)
+2. A warning is logged: `Skill "code-review" from ~/.mia-code/skills/ overridden by .mia-code/skills/`
+3. The overridden skill is not loaded — only the winning source is registered
+4. `/skills` command shows the active source for each skill
+
+### Format Validation
+
+A valid skill file must have:
+
+1. YAML frontmatter delimited by `---` markers
+2. A `name` field (string, kebab-case, 1-50 characters)
+3. A `description` field (string, 1-200 characters)
+4. A non-empty markdown body after the frontmatter
+
+Invalid files are skipped with a warning:
+```
+Warning: skills/bad-skill.md skipped — missing required "description" in frontmatter
+```
+
+### Refresh Mechanism
+
+`/skills refresh` triggers a full re-discovery:
+
+1. Clear the current skill registry
+2. Re-scan all directory sources for new, changed, or removed files
+3. Re-fetch remote skills (ignoring cache TTL)
+4. Re-validate and re-register all skills
+5. Report changes: "2 skills added, 1 updated, 0 removed"
+
+### System Prompt Integration
+
+After discovery, the agent's system prompt includes:
+
+```
+You have X skills available. Use the skill tool to invoke them by name.
+Available skills: code-review, commit-message, test-writer, ...
+```
+
+This ensures the agent knows skills exist and can proactively use them when relevant.
+
+### Configuration
+
+Full skill configuration:
+
+```json
+{
+  "skill": {
+    "paths": ["./custom-skills", "../shared-skills"],
+    "urls": ["https://example.com/skills/review.md"],
+    "cacheTTL": 604800,
+    "enabled": true
+  }
+}
+```
+
+Setting `"enabled": false` disables skill discovery entirely.
+
+## Supporting Structures
+
+- **Skill System (RISE-094)** defines what skills are and how they work
+- **Agent Definition Config (RISE-010)** can specify default skills for an agent type
+- **Structured Logging (RISE-007)** logs discovery events, warnings, and conflicts
+- **Lazy Initialization (RISE-008)** defers skill loading until first access if startup time is critical
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Drop-In Customization:**
+A developer creates `.mia-code/skills/code-review.md` in their project. On the next `mia-code` start, the skill appears in `/skills`. The agent uses it automatically when asked to review code. No configuration needed — just drop the file and it works.
+
+**Scenario 2 — Team Skill Repository:**
+A team maintains a GitHub repo of shared skills. Each developer adds the raw URLs to their config. On startup, mia-code fetches and caches the skills. When the team updates a skill, everyone gets the new version within 7 days (or immediately via `/skills refresh`).
+
+**Scenario 3 — Project-Specific Override:**
+The global `code-review.md` skill has generic review criteria. A project adds its own `code-review.md` in `.mia-code/skills/` with project-specific rules. The project version wins by precedence. When the developer works on other projects, the global version applies.
+
+**Scenario 4 — Skill Inventory Audit:**
+A tech lead runs `/skills` across multiple projects to audit what skills are in use. They find inconsistencies — some projects have outdated review skills. They update the shared URL and run `/skills refresh` everywhere. Consistency restored in minutes.

package/rispecs/borrowed_from_opencode/096-desktop-remote-driving.rispec.md

@@ -0,0 +1,175 @@
+# RISE-096: Desktop Remote Driving
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/096-desktop-remote-driving.rispec.md
+
+## Creative Intent
+
+mia-code delivers a desktop application and remote driving capability that untethers the developer from the terminal. The desktop app wraps mia-code's web interface in a native window with system tray presence, global keyboard shortcuts, and OS integration. Remote driving separates where computation happens from where interaction happens — the agent runs on a powerful workstation while the developer drives from a phone, a tablet, or a lightweight laptop on a different network. Computation and interface become independent dimensions.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code runs only in a terminal — no native desktop presence, no system tray, no global shortcuts
+- Interacting with mia-code requires an active terminal window in focus
+- Using mia-code from a mobile device requires SSH and a terminal emulator
+- The agent's computation is bound to the device running the interface
+- No auto-update mechanism exists — users manually update via npm
+- Terminal rendering limits the richness of the interface (no images, no rich formatting, no drag-and-drop)
+
+**Desired State:**
+- A desktop app provides a native window with system tray icon and global keyboard shortcuts
+- The app wraps a web-based UI connected to the HTTP API server (RISE-088)
+- Remote driving: the server runs on a workstation, clients connect from any device on any network
+- mDNS (RISE-092) enables auto-discovery of local servers; URL/password for remote servers
+- The desktop app auto-updates: checks on launch, downloads delta updates
+- Native OS integration: file drag-and-drop, notifications, open-in-editor
+
+## Desired Outcome Definition
+
+A developer installs the mia-code desktop app. It launches a native window with the mia-code web interface, a system tray icon for background access, and a global keyboard shortcut for instant activation. The app connects to a local or remote mia-code server, enabling the developer to drive an agent running on any machine from any client device.
+
+## Natural Language Functional Description
+
+### Desktop Application
+
+**Framework**: Tauri (preferred for small binary size and Rust security) or Electron (if web technology integration demands it).
+
+**Window Features:**
+- Native window with title bar, minimize, maximize, close
+- System tray icon with menu: Show/Hide, Active Sessions, Quit
+- Global keyboard shortcut to toggle window visibility (configurable, default: `Cmd+Shift+M` / `Ctrl+Shift+M`)
+- Window position and size remembered across launches
+- Dark/light theme following OS preference
+- Multiple windows for multiple sessions (optional)
+
+**System Tray:**
+- Tray icon shows agent status: idle (gray), thinking (animated), error (red)
+- Right-click menu: Show Window, Active Sessions (submenu), Preferences, Quit
+- Left-click: toggle window visibility
+- Badge/notification dot when agent completes a task in the background
+
+**Native Notifications:**
+- Notify when agent completes a response (if window is not focused)
+- Notify on permission requests requiring attention
+- Notify on errors during agent execution
+- Notification preferences configurable: all, errors-only, none
+
+### Web UI
+
+The desktop app renders a web-based UI that communicates with the mia-code server:
+
+- Built with a modern framework (React, Svelte, or Solid)
+- Connects to the HTTP API (RISE-088) for operations
+- Uses WebSocket (RISE-090) or SSE (RISE-091) for real-time streaming
+- Renders markdown responses with syntax highlighting
+- Shows tool executions in collapsible panels
+- Displays permission prompts as modal dialogs
+- File drag-and-drop: drop files onto the window to attach as context
+
+### Remote Driving
+
+Remote driving separates the server (where the agent runs) from the client (where the developer interacts):
+
+**Setup Flow:**
+1. Start the server on the workstation: `mia-code serve --host 0.0.0.0 --port 4096 --password secret`
+2. Note the workstation's IP or hostname
+3. From the client device: open the desktop app or web browser
+4. Connect: enter `http://workstation:4096` and the password
+5. Drive the agent from the client — all computation happens on the workstation
+
+**Local Discovery:**
+- On the same network, mDNS (RISE-092) auto-discovers the workstation
+- The desktop app shows a "Connect" screen listing discovered instances
+- One click connects to the local server
+
+**Remote Access:**
+- For different networks, use SSH tunnel: `ssh -L 4096:localhost:4096 workstation`
+- Or use a reverse proxy (Cloudflare Tunnel, ngrok, tailscale) for public access
+- The desktop app stores recent connections for quick reconnection
+
+### Device-Specific Features
+
+**From Desktop (macOS/Windows/Linux):**
+- Full keyboard input with shortcuts
+- File drag-and-drop from Finder/Explorer
+- "Open in Editor" button for files the agent references
+- Copy code blocks to clipboard with one click
+
+**From Mobile (phone/tablet via web browser):**
+- Responsive web UI adapts to small screens
+- Touch-friendly message input and permission buttons
+- Swipe gestures for navigation (session list ↔ chat)
+- Permission prompts as native-feeling bottom sheets
+
+**From Terminal (fallback):**
+- `mia-code connect --url http://workstation:4096 --password secret`
+- Same TUI experience as local mia-code, but driving a remote server
+
+### Auto-Updates
+
+The desktop app checks for updates on launch:
+
+1. Query update server for latest version
+2. Compare with current version
+3. If update available, download delta update in background
+4. Prompt user to restart to apply (or auto-apply on next launch)
+5. Update mechanism: Tauri's built-in updater or Electron's autoUpdater
+
+### Desktop Configuration
+
+Desktop-specific config (separate from CLI config):
+
+```json
+{
+  "desktop": {
+    "globalShortcut": "CommandOrControl+Shift+M",
+    "startMinimized": false,
+    "showInTray": true,
+    "notifications": "all",
+    "theme": "system",
+    "window": {
+      "width": 1200,
+      "height": 800,
+      "x": 100,
+      "y": 100
+    },
+    "recentConnections": [
+      {"url": "http://workstation:4096", "name": "Work Desktop"}
+    ]
+  }
+}
+```
+
+### Session Continuity
+
+Remote driving enables seamless session continuity across devices:
+
+1. Start a session on the workstation terminal
+2. Switch to the desktop app — same session, same history
+3. Walk away and connect from phone — continue the conversation
+4. Return to the workstation — the session is still there
+5. The server is the source of truth; clients are interchangeable views
+
+## Supporting Structures
+
+- **HTTP API Server (RISE-088)** provides the API the desktop app connects to
+- **WebSocket Support (RISE-090)** provides real-time streaming to the app
+- **SSE Streaming (RISE-091)** provides an alternative streaming transport
+- **mDNS Discovery (RISE-092)** enables auto-discovery of local servers
+- **JavaScript SDK (RISE-093)** powers the web UI's API communication
+- **Client-Server Architecture (RISE-001)** defines the separation this feature realizes
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Couch-Driven Development:**
+A developer starts `mia-code serve` on their workstation with 64GB RAM and a fast GPU. They move to the couch, open the mobile web UI on their phone, and continue their refactoring session. The agent runs with full workstation power while the developer types on a phone keyboard.
+
+**Scenario 2 — Notification-Driven Workflow:**
+A developer sends a long-running prompt (refactor an entire module) and minimizes the desktop app. Five minutes later, a native notification appears: "Refactoring complete — 12 files modified." They click the notification, review the changes, and approve. The agent worked in the background while they did other things.
+
+**Scenario 3 — Multi-Device Session:**
+Morning: the developer starts a session on their workstation terminal. Commute: they connect from their phone and continue the conversation on the train. Office: they open the desktop app on their work laptop and pick up where they left off. The session follows the developer, not the device.
+
+**Scenario 4 — Team Demo:**
+A developer presents a live demo of mia-code. They share their screen showing the desktop app. They type a prompt and the team watches the agent stream its response, execute tools, and produce code — all rendered in a rich web UI that is more presentable than a terminal. The demo sells the tool to the entire team.