@plazmodium/odin 0.3.2-beta → 0.3.4-beta

package/README.md

@@ -6,13 +6,13 @@ A single-install MCP server that gives your AI coding agent an 11-phase developm
 
 ### 1. Install
 
-Preferred published-package flow after the first npm publish:
+Preferred published-package flow:
 
 ```bash
 npx -y @plazmodium/odin init --project-root /path/to/your/project --tool opencode --write-mcp
 ```
 
-Current repo-checkout flow that works today:
+Maintainer repo-checkout flow:
 
 ```bash
 cd runtime
@@ -23,26 +23,82 @@ npm run build
 ### 2. Bootstrap your project
 
 ```bash
-# Published-package MCP command snippets after the first npm publish
+# Published-package MCP command snippets
 npx -y @plazmodium/odin init --project-root /path/to/your/project --tool amp --write-mcp
 npx -y @plazmodium/odin init --project-root /path/to/your/project --tool opencode --write-mcp
 
-# Source-checkout snippets while working from odin-workflow today
+# Source-checkout snippets while working on Odin from this repo
 npm run init:project -- --project-root /path/to/your/project --tool amp --distribution source --write-mcp
 npm run init:project -- --project-root /path/to/your/project --tool codex --distribution source --write-mcp
 ```
 
 This creates:
 - `.odin/config.yaml` — runtime configuration (commit this)
+- `.odin/ODIN.md` — bundled Odin framework guide for the harness to read locally
+- `.odin/agents/definitions/` — bundled phase agent definitions and shared context
 - `.odin/skills/` — project-local skill overrides (commit this)
 - `.env.example` — required environment variables (commit this)
 - Your harness config file (`opencode.json`, `.mcp.json`, or `.codex/config.toml`, depending on tool)
 
 Important: Odin bootstraps with `runtime.mode: in_memory` by default so MCP wiring can work without external services. Switch `.odin/config.yaml` to `runtime.mode: supabase` when you are ready for persistent workflow state.
 
-Until `@plazmodium/odin` is actually published, use the repo-checkout `--distribution source` flow shown above.
+If you are developing Odin from this repo, use the repo-checkout `--distribution source` flow shown above.
 
-If you are the maintainer preparing that publish, use [`../docs/guides/NPM-PUBLISH.md`](../docs/guides/NPM-PUBLISH.md).
+If you are the maintainer preparing that publish, use [the npm publish guide](https://github.com/Plazmodium/odin-workflow/blob/dev/docs/guides/NPM-PUBLISH.md).
+
+### Manual MCP wiring
+
+If you do not want Odin to write your harness config for you, add the MCP server manually.
+
+For Claude Code / Amp:
+
+```json
+{
+  "mcpServers": {
+    "odin": {
+      "command": "npx",
+      "args": ["-y", "@plazmodium/odin", "mcp"],
+      "env": {
+        "ODIN_PROJECT_ROOT": "/absolute/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+For OpenCode:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "odin": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "@plazmodium/odin",
+        "mcp"
+      ],
+      "enabled": true,
+      "environment": {
+        "ODIN_PROJECT_ROOT": "/absolute/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+For Codex:
+
+```toml
+[mcp_servers.odin]
+command = "npx"
+args = ["-y", "@plazmodium/odin", "mcp"]
+env = { ODIN_PROJECT_ROOT = "/absolute/path/to/your/project" }
+```
+
+For Cursor, use the same command, args, and env values in the MCP Servers settings UI.
 
 ### 3. Add your database credentials
 
@@ -102,6 +158,17 @@ Your AI agent now has these tools available:
 | `odin.explore_knowledge` | Explore knowledge clusters, cross-domain bridges, and domain stats |
 | `odin.apply_migrations` | Apply pending database migrations (auto-detects existing schema) |
 
+## Dashboard
+
+`@plazmodium/odin` ships the MCP runtime only. It does **not** bundle the Next.js dashboard.
+
+If you want the dashboard UI for feature health, learnings, claims, and eval visibility, use the full Odin repository:
+
+- Repo: https://github.com/Plazmodium/odin-workflow
+- Dashboard app: https://github.com/Plazmodium/odin-workflow/tree/dev/dashboard
+
+The dashboard is a separate app and is not included in the npm tarball.
+
 ## Configuration
 
 Odin uses two files:
@@ -208,8 +275,10 @@ Recommended harness behavior:
 ```text
 1. Call odin.prepare_phase_context(...)
 2. Build the agent prompt from:
+   - .odin/ODIN.md (framework-level rules)
    - context.agent.role_summary
    - context.agent.constraints
+   - context.agent.definition_markdown
    - context.development_evals.harness_prompt_block
 3. Keep context.development_evals.status_summary visible to the operator
 4. Do not treat eval instructions as a replacement for formal verification, Semgrep, tests, runtime checks, or watcher checks
@@ -219,14 +288,16 @@ Canonical eval-aware orchestration snippet:
 
 ```text
 When orchestrating Odin phases:
-1. Call odin.prepare_phase_context({ feature_id, phase, agent_name }).
-2. Build the active agent prompt from:
+1. Read `.odin/ODIN.md` once so the harness has the framework-level rules in project context.
+2. Call odin.prepare_phase_context({ feature_id, phase, agent_name }).
+3. Build the active agent prompt from:
    - context.agent.role_summary
    - context.agent.constraints
+   - context.agent.definition_markdown
    - context.development_evals.harness_prompt_block
-3. Use odin.get_development_eval_status({ feature_id }) when you need focused eval state.
-4. Record eval artifacts/gates with odin.record_eval_plan, odin.record_eval_run, and odin.record_quality_gate.
-5. Never let Development Evals override odin.verify_design, odin.run_review_checks, tests, runtime verification, or watcher checks.
+4. Use odin.get_development_eval_status({ feature_id }) when you need focused eval state.
+5. Record eval artifacts/gates with odin.record_eval_plan, odin.record_eval_run, and odin.record_quality_gate.
+6. Never let Development Evals override odin.verify_design, odin.run_review_checks, tests, runtime verification, or watcher checks.
 ```
 
 If the harness wants a focused eval-only read path instead of parsing `odin.get_feature_status`, call: