dino-spec 19.5.0 → 20.4.0

package/.claude/rules/dino/change-categories.md

@@ -6,11 +6,7 @@ Files are classified into categories based on path and name:
 
 ### dependency (High Significance)
 Files that affect project dependencies:
-- `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
-- `requirements.txt`, `Pipfile`, `pyproject.toml`
-- `Cargo.toml`, `Cargo.lock`
-- `go.mod`, `go.sum`
-- `Gemfile`, `Gemfile.lock`
+- `package.json`, `bun.lockb`, `package-lock.json`
 
 **Pending Action:** Run package manager install command
 

package/.claude/rules/dino/fork-recovery.md

@@ -1,58 +1,3 @@
 # Fork Context Recovery
 
-**CRITICAL**: Skills with `context: fork` start with NO conversation history. They MUST recover context before doing anything.
-
----
-
-## Canonical Recovery Pattern
-
-Every forked skill MUST implement Step 0 using this priority order:
-
-### Source Priority
-
-| Priority | Source | Check For |
-|----------|--------|-----------|
-| 1 | `$ARGUMENTS` | Direct input from user |
-| 2 | `.dino/session.md` | `### Discovery:` in `## Notes` (use most recent) |
-| 3 | Skill-specific source | See table below |
-| 4 | `.dino/handoff/latest.md` | Previous session context |
-| 5 | `AskUserQuestion` | Last resort only |
-
-**Stop at the first source that provides actionable context.**
-
-### Skill-Specific Sources (Priority 3)
-
-| Skill | Source | Check For |
-|-------|--------|-----------|
-| ralph-gate | `.dino/ralph-gate/status.md` | "IN PROGRESS" with user request |
-| ralph | `.dino/ralph-state.json` | `phase === 'executing'`, pending stories |
-| team | `.dino/team.md` | `## Mission` with content |
-| refactor | `.dino/plans/refactor-customer-review.md` | Incomplete/complete review |
-| analyze-codebase | `CLAUDE.md` | Project architecture context |
-| scout | `.dino/ralph-gate/status.md` | Research needs for in-progress work |
-
----
-
-## Implementation in Skills
-
-Each forked skill should reference this rule briefly, not duplicate it:
-
-```markdown
-## Step 0: Recover Context
-
-Follow `.claude/rules/dino/fork-recovery.md` recovery pattern.
-
-**Skill-specific source**: `.dino/ralph-state.json` (check for pending stories)
-
-If no context found, ask: "What would you like me to [skill action]?"
-```
-
----
-
-## Rules
-
-- **NEVER** ask user if context exists in files — check files first
-- **NEVER** proceed to main work without context
-- **ALWAYS** read sources in priority order
-- **STOP** at first actionable match
-- If all file sources are empty/missing, use `AskUserQuestion` with proper format (options, not plain text)
+Fork-context skills must recover context before doing work. See each skill's Step 0 for the recovery pattern. Priority: $ARGUMENTS → session.md Discovery → skill-specific source → handoff/latest.md → AskUserQuestion.

package/.claude/rules/dino/quality.md

@@ -68,49 +68,7 @@ Documentation only → SKIP
 
 ## Mandatory Review
 
-Optional review gate for code changes.
-
-### Enabling
-
-```bash
-DINO_MANDATORY_REVIEW=true
-```
-
-Or in `.dino/config.json`:
-```json
-{"mandatoryReview": true}
-```
-
-### Review Flow
-
-```
-Edit/Write → [review enabled?] → Spawn reviewer → [critical?] → Block/Continue
-```
-
-### Review Categories
-
-| Category | Checks | Severity |
-|----------|--------|----------|
-| Security | Secrets, injection, auth | Critical/Major |
-| Quality | Patterns, errors, complexity | Major/Minor |
-| Style | Formatting, naming | Minor/Info |
-| Performance | N+1, inefficient patterns | Major/Minor |
-
-### Blocking Rules
-
-| Condition | Action |
-|-----------|--------|
-| Critical security | BLOCK |
-| Critical quality | BLOCK |
-| Major (if configured) | BLOCK |
-| Minor/Info | Warn only |
-
-### Environment Variables
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `DINO_MANDATORY_REVIEW` | false | Enable review |
-| `DINO_REVIEW_BLOCK_MAJOR` | false | Block on major |
+Set `DINO_MANDATORY_REVIEW=true` to enable code review gate. Disabled by default.
 
 ---
 

package/.claude/skills/dino.mcp-setup/SKILL.md

@@ -0,0 +1,383 @@
+---
+description: Configure MCP server for Claude Code
+metadata:
+  model: haiku
+  context: inherit
+  effort: low
+  allowed-tools:
+    - Read
+    - Bash
+    - Glob
+    - WebSearch
+---
+
+# MCP Setup
+
+Configure Model Context Protocol (MCP) servers for Claude Code.
+
+## What is MCP
+
+MCP is an open protocol (JSON-RPC 2.0) that standardizes how AI assistants connect to external tools and data sources. Claude Code uses MCP to extend its capabilities through custom servers.
+
+**Official Spec**: https://modelcontextprotocol.io/specification/2025-11-25
+
+## Transport Types
+
+| Transport | Use Case | Config Key |
+|-----------|----------|------------|
+| **stdio** | Local CLI tools (recommended) | `command`, `args`, `env` |
+| **SSE** | Server-Sent Events over HTTP | `url`, `headers` |
+| **HTTP** | Direct HTTP endpoints | `url`, `headers` |
+
+## Configuration Scopes
+
+| Scope | Location | Usage |
+|-------|----------|-------|
+| **Project** | `.mcp.json` (project root) | Shared with team, version controlled |
+| **Local** | `~/.claude.json` (local object) | Machine-specific, not synced |
+| **User** | `~/.claude.json` (user object) | Personal, applies to all projects |
+
+### Priority Order
+
+Project > Local > User (project scope overrides others)
+
+## Configuration Files
+
+### Project Scope (`.mcp.json`)
+
+Place at project root:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["server.js"],
+      "env": {
+        "API_KEY": "${API_KEY:-default}"
+      }
+    }
+  }
+}
+```
+
+### Local/User Scope (`~/.claude.json`)
+
+```json
+{
+  "mcpServers": {
+    "local-server": {
+      "type": "stdio",
+      "command": "/path/to/server"
+    }
+  }
+}
+```
+
+### With `.claude/settings.json`
+
+Hooks and status line configuration (dino-specific):
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "dino-hud",
+    "padding": 0
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          { "type": "command", "command": "bun tsc --noEmit --incremental" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## CLI Commands
+
+```bash
+# Add MCP server (interactive)
+claude mcp add <server-name>
+
+# Add with specific scope
+claude mcp add <server-name> --scope project
+claude mcp add <server-name> --scope local
+claude mcp add <server-name> --scope user
+
+# List configured servers
+claude mcp list
+
+# Remove server
+claude mcp remove <server-name>
+
+# Get server details
+claude mcp get <server-name>
+```
+
+## Server Configuration Formats
+
+### stdio Transport (Most Common)
+
+```json
+{
+  "mcpServers": {
+    "my-tool": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["--experimental-specifier-resolution=node", "dist/server.js"],
+      "env": {
+        "NODE_ENV": "production",
+        "API_KEY": "${MY_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### HTTP/SSE Transport
+
+```json
+{
+  "mcpServers": {
+    "remote-tool": {
+      "type": "http",
+      "url": "https://api.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${API_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### With Bun
+
+```json
+{
+  "mcpServers": {
+    "bun-server": {
+      "type": "stdio",
+      "command": "bun",
+      "args": ["run", "server.ts"],
+      "env": {
+        "BUN_NO_WARNINGS": "1"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+MCP supports environment variable expansion:
+
+| Syntax | Behavior |
+|--------|----------|
+| `${VAR}` | Required - errors if unset |
+| `${VAR:-default}` | Optional - uses default if unset |
+| `${VAR:=default}` | Sets variable if unset |
+
+### Security Note
+
+Never hardcode secrets. Use environment variables:
+
+```json
+{
+  "env": {
+    "API_KEY": "${ANTHROPIC_API_KEY}",
+    "DB_URL": "${DATABASE_URL:-localhost:5432}"
+  }
+}
+```
+
+## Dino MCP Server
+
+Dino includes a built-in MCP server with 22 tools.
+
+### Check Current Config
+
+```bash
+dino mcp doctor
+```
+
+### Manual Configuration
+
+Add to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "dino": {
+      "type": "stdio",
+      "command": "dino",
+      "args": ["mcp", "serve"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Protocol Details
+
+- **Protocol Version**: `2024-11-05`
+- **Server Name**: `dino`
+- **Capabilities**: `tools: { listChanged: true }`
+
+### Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `dino_status` | Session state display |
+| `dino_budget` | Token budget tracking |
+| `dino_context` | Context management |
+| `dino_defer` | Lazy file loading |
+| `dino_focus_set` | Set focus area |
+| `dino_memory_save` | Save memories |
+| `dino_memory_recall` | Recall memories |
+| `dino_retrieve` | Hybrid context retrieval |
+| `dino_spec` | Prompt analysis |
+| `dino_validate` | Package validation |
+| `dino_tasks` | Task management |
+| `dino_plans` | Plan management |
+| `dino_agents` | Agent coordination |
+
+Run `dino mcp serve --help` for full tool list.
+
+## Common Mistakes
+
+### Missing `mcpServers` Wrapper
+
+```json
+// WRONG - Missing wrapper
+{
+  "my-server": { "command": "node" }
+}
+
+// CORRECT
+{
+  "mcpServers": {
+    "my-server": { "command": "node" }
+  }
+}
+```
+
+### Wrong Transport for Remote
+
+```json
+// WRONG - stdio for remote
+{
+  "type": "stdio",
+  "url": "https://api.example.com"
+}
+
+// CORRECT
+{
+  "type": "http",
+  "url": "https://api.example.com/mcp"
+}
+```
+
+### Tildef/Home in Paths (Bun/Node Issue)
+
+```json
+// WRONG - Causes Bun segfault
+{
+  "command": "~/bin/server"
+}
+
+// CORRECT - Use absolute paths
+{
+  "command": "/Users/username/bin/server"
+}
+
+// CORRECT - Or expand via env
+{
+  "command": "${HOME}/bin/server"
+}
+```
+
+### Missing args Array
+
+```json
+// WRONG - args as string
+{
+  "command": "node",
+  "args": "server.js --port 3000"
+}
+
+// CORRECT - args as array
+{
+  "command": "node",
+  "args": ["server.js", "--port", "3000"]
+}
+```
+
+## Troubleshooting
+
+### Server Not Appearing
+
+1. Check JSON syntax: `cat .mcp.json | jq .`
+2. Verify scope: `claude mcp list`
+3. Check command path is absolute or in PATH
+
+### Connection Drops
+
+1. Check server logs: `dino mcp serve --verbose`
+2. Verify protocol version matches
+3. Run `dino mcp doctor` for diagnostics
+
+### Bun Segmentation Fault
+
+**CAUSE**: Usually incorrect config or path issues.
+
+**CHECK**:
+1. All paths are absolute (no `~` or `$HOME`)
+2. `args` is an array, not a string
+3. Environment variables use `${VAR}` syntax
+4. JSON is valid (no trailing commas)
+
+**FIX**:
+```bash
+# Validate JSON
+cat .mcp.json | jq .
+
+# Test server directly
+dino mcp serve
+
+# Run diagnostics
+dino mcp doctor
+```
+
+## Workflow
+
+1. Check current configuration:
+   ```bash
+   claude mcp list
+   dino mcp doctor
+   ```
+
+2. Add or update server configuration in `.mcp.json`
+
+3. Validate configuration:
+   ```bash
+   cat .mcp.json | jq .
+   ```
+
+4. Restart Claude Code to load new servers
+
+5. Verify server is running:
+   ```bash
+   claude mcp get dino
+   ```
+
+## Resources
+
+- [MCP Specification](https://modelcontextprotocol.io/specification/2025-11-25)
+- [Claude Code MCP Docs](https://docs.anthropic.com/en/docs/claude-code/mcp)
+- [Anthropic MCP Blog](https://www.anthropic.com/engineering/claude-mcp-code-execution)

package/.claude/skills/dino.release/SKILL.md

@@ -127,7 +127,7 @@ Apply all confirmed documentation changes before build/publish.
 ### 6. Build and Test
 
 ```bash
-bun run build.js          # Build
+node build.js             # Build (NOT bun — segfaults under pipe stdio)
 bun run vitest run        # Test (must pass)
 ```