@plazmodium/odin 0.3.3-beta → 0.3.4-beta

package/builtin/agent-definitions/README.md

@@ -0,0 +1,170 @@
+# Odin Agent Definitions
+
+This directory contains the prompt definitions for all Odin agents. Each agent is a specialized prompt that handles a specific phase of the 11-phase SDD workflow.
+
+## Agent Overview (v2)
+
+| Agent | Phase | File | Description |
+|-------|-------|------|-------------|
+| Planning | 0 | `planning.md` | Epic decomposition into features (L3 only) |
+| **Product** | 1 | `product.md` | PRD generation with complexity-gated templates (NEW in v2) |
+| Discovery | 2 | `discovery.md` | Requirements gathering via stakeholder interviews |
+| Architect | 3 | `architect.md` | Technical specification drafting + opt-in formal design verification |
+| Guardian | 4 | `guardian.md` | Multi-perspective review of PRD + spec + proof results |
+| Builder | 5 | `builder.md` | Code implementation (emits claims, watched) |
+| **Reviewer** | 6 | `reviewer.md` | SAST/security scanning via Semgrep (NEW in v2) |
+| Integrator | 7 | `integrator.md` | Build verification and integration (emits claims, watched) |
+| Documenter | 8 | `documenter.md` | Documentation updates |
+| Release | 9 | `release.md` | PR creation and archival (emits claims, watched) |
+
+### Support Agents
+
+| Agent | File | Description |
+|-------|------|-------------|
+| **Watcher** | `watcher.md` | LLM escalation for claim verification (NEW in v2) |
+| Shared Context | `_shared-context.md` | Common context injected into all agents |
+
+### Development Agents (Not Part of Workflow)
+
+| Agent | File | Description |
+|-------|------|-------------|
+| Consultant | `spec-driven-dev-consultant.md` | For analyzing/improving Odin itself |
+| MCP Test | `mcp-test.md` | For testing MCP server functionality |
+
+## Workflow Diagram (v2)
+
+```
+                              ┌─────────────────────────────────────────────────────┐
+                              │                  11-PHASE WORKFLOW                  │
+                              └─────────────────────────────────────────────────────┘
+
+   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+   │ PLANNING │───▶│ PRODUCT  │───▶│ DISCOVERY│───▶│ ARCHITECT│───▶│ GUARDIAN │
+   │  (0)     │    │  (1) NEW │    │   (2)    │    │   (3)    │    │   (4)    │
+   │ L3 only  │    │   PRD    │    │   Reqs   │    │   Spec   │    │  Review  │
+   └──────────┘    └──────────┘    └──────────┘    └──────────┘    └────┬─────┘
+                                                                        │
+        ┌───────────────────────────────────────────────────────────────┘
+        │
+        ▼
+   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+   │ BUILDER  │───▶│ REVIEWER │───▶│INTEGRATOR│───▶│DOCUMENTER│───▶│ RELEASE  │
+   │  (5)     │    │  (6) NEW │    │   (7)    │    │   (8)    │    │   (9)    │
+   │ WATCHED  │    │   SAST   │    │ WATCHED  │    │   Docs   │    │ WATCHED  │
+   └──────────┘    └──────────┘    └──────────┘    └──────────┘    └────┬─────┘
+                                                                        │
+                                                                        ▼
+                                                                   ┌──────────┐
+                                                                   │ COMPLETE │
+                                                                   │   (10)   │
+                                                                   └──────────┘
+```
+
+## New Agents in v2
+
+### Product Agent (Phase 1)
+
+The Product agent generates a Product Requirements Document (PRD) **before** the technical spec. This ensures business requirements are captured before diving into technical details.
+
+**Key Features:**
+- **Complexity-gated templates:**
+  - L1 (Bug Fix): PRD_EXEMPTION — 8-line template
+  - L2 (Feature): PRD_LITE — 1-page template
+  - L3 (Epic): PRD_FULL — Complete PRD with user journeys, NFRs, rollout plan
+- **Max 1 clarification round** — if unresolved, creates blocker
+- **No implementation details** — PRD focuses on "what", not "how"
+
+### Reviewer Agent (Phase 6)
+
+The Reviewer agent runs SAST (Static Application Security Testing) using Semgrep after the Builder completes implementation.
+
+**Key Features:**
+- **Default scan:** `semgrep scan --config=auto`
+- **Severity-based gating:** HIGH/CRITICAL must be resolved or deferred with justification
+- **Findings recorded** to `security_findings` table
+- **Output format:** Summary table with blocking/deferred sections
+
+### Watcher Agent (Support)
+
+The Watcher agent is called via LLM escalation when the Policy Engine cannot make a deterministic decision.
+
+**Key Features:**
+- **Only invoked for:**
+  - HIGH risk claims
+  - Claims with missing evidence
+  - Policy Engine inconclusive results
+- **Returns:** PASS/FAIL/NEEDS_REVIEW with reasoning and confidence
+- **Not a phase agent** — runs as a sub-agent when needed
+
+## Watched Agents (v2)
+
+Three agents emit structured **claims** that are verified by the Hybrid Watcher Architecture:
+
+| Agent | Claims Emitted |
+|-------|---------------|
+| Builder | CODE_ADDED, CODE_MODIFIED, TEST_PASSED, BUILD_SUCCEEDED |
+| Integrator | INTEGRATION_VERIFIED |
+| Release | PR_CREATED, ARCHIVE_CREATED |
+
+### Verification Flow
+
+```
+Agent emits claim
+       │
+       ▼
+┌─────────────────┐
+│  agent_claims   │ ─────────────────────────────────┐
+│    (Supabase)   │                                  │
+└────────┬────────┘                                  │
+         │                                           │
+         ▼                                           ▼
+┌─────────────────┐                        ┌─────────────────┐
+│  Policy Engine  │   NEEDS_REVIEW ──────▶ │   LLM Watcher   │
+│ (SQL Functions) │                        │   (Sub-Agent)   │
+└────────┬────────┘                        └────────┬────────┘
+         │                                          │
+         │ PASS/FAIL                                │ PASS/FAIL
+         │                                          │
+         ▼                                          ▼
+┌─────────────────┐                        ┌─────────────────┐
+│ policy_verdicts │                        │ watcher_reviews │
+│    (Supabase)   │                        │    (Supabase)   │
+└─────────────────┘                        └─────────────────┘
+```
+
+## Shared Context
+
+All agents receive the `_shared-context.md` file which includes:
+- 11-phase workflow table
+- Critical workflow rules (spec-first, never skip phases, agents never merge)
+- Watcher verification protocol
+- Skills injection block
+- Recovery mechanisms
+
+## Usage
+
+Agents are invoked via the Task tool in the main orchestrator session:
+
+```typescript
+// Example: Invoke the Product agent
+Task({
+  subagent_type: "product",
+  prompt: "Generate PRD for FEAT-001: User authentication flow",
+  description: "Generate PRD"
+});
+```
+
+The orchestrator is responsible for:
+1. Reading agent definitions before each phase
+2. Injecting relevant skills
+3. Executing MCP calls (agents can't access MCP directly)
+4. Submitting claims and running policy checks
+5. Recording phase transitions
+
+## Version History
+
+- **v2.1** (2026-03-18): Added TLA+ formal design verification (Architect Step A3a + Guardian proof review); fixed all agent phase headers to v2 numbering
+- **v2.0** (2026-03-06): Added Product, Reviewer, Watcher agents; 11-phase workflow; claim verification
+- **v1.4** (2026-02-17): Added step-level enforcement checklists
+- **v1.3** (2026-02-09): Added git branch tracking
+- **v1.0** (2026-02-04): Initial 8-agent system

package/builtin/agent-definitions/_shared-context.md

@@ -0,0 +1,377 @@
+# Shared Agent Context
+
+This file contains common patterns and references shared across all SDD agents. Each agent definition references this file rather than duplicating the content.
+
+---
+
+## The 11-Phase Workflow (Odin v2)
+
+| Phase | Name | Agent | Watched? | Description |
+|-------|------|-------|----------|-------------|
+| 0 | Planning | Planner | No | Epic decomposition (L3 only) |
+| 1 | Product | Product | No | PRD generation (complexity-gated) |
+| 2 | Discovery | Discovery | No | Requirements gathering |
+| 3 | Architect | Architect | No | Specification drafting |
+| 4 | Guardian | Guardian | No | PRD + Spec review |
+| 5 | Builder | Builder | **YES** | Implementation |
+| 6 | Reviewer | Reviewer | No | SAST/security scan |
+| 7 | Integrator | Integrator | **YES** | Build verification |
+| 8 | Documenter | Documenter | No | Documentation |
+| 9 | Release | Release | **YES** | PR creation + archival |
+| 10 | Complete | - | No | Feature done |
+
+**Watched agents** (Builder, Integrator, Release) emit structured claims that are verified by the Policy Engine and optionally the LLM Watcher.
+
+---
+
+## Hybrid Orchestration Model
+
+Odin uses a **hybrid orchestration** model:
+- **You (Agent)**: Create artifacts (specs, reviews, code, docs) + document state changes needed
+- **Main Session (Orchestrator)**: Manages workflow state via MCP
+
+**Why**: Sub-agents spawned via task/agent tools cannot access MCP servers. Only the main orchestrator session can call MCP tools.
+
+**Your responsibility**: At the end of your artifact, include a `## State Changes Required` section listing all state changes the orchestrator should make.
+
+---
+
+## State Changes Required — Template
+
+Every agent artifact must end with this section:
+
+```markdown
+---
+## State Changes Required
+
+### 1. Submit Claims (if watched agent: Builder, Integrator, Release)
+[Include structured claims with type, description, risk level, evidence refs]
+
+### 2. Track Duration
+- **Phase**: [0-10]
+- **Agent**: [Your agent name]
+- **Operation**: [Brief description]
+
+### 3. Record Development Eval Artifact (if applicable)
+- **Feature ID**: [ID]
+- **Phase**: [N]
+- **Output Type**: `eval_plan` | `eval_run`
+- **Created By**: [Agent name]
+
+### 4. Record Quality Gate (if applicable)
+- **Feature ID**: [ID]
+- **Gate Name**: `eval_readiness` | [other gate]
+- **Status**: `APPROVED` | `REJECTED`
+- **Approver**: [Agent name]
+- **Notes**: [Why]
+
+### 5. Transition Phase (if applicable)
+- **Feature ID**: [ID]
+- **From Phase**: [N]
+- **To Phase**: [N+1]
+- **Transitioned By**: [Agent name]
+
+### 6. Create Blocker (if applicable)
+- **Blocker Type**: [SPEC_AMBIGUITY | MISSING_CONTEXT | TECHNICAL_IMPOSSIBILITY | EXTERNAL_DEPENDENCY | INTEGRATION_CONFLICT | DURATION_EXCEEDED | ITERATION_LIMIT_EXCEEDED | QUALITY_GATE_REJECTED | OTHER]
+- **Phase**: [N]
+- **Severity**: [LOW | MEDIUM | HIGH | CRITICAL]
+- **Title**: [Short description]
+- **Description**: [Details + what's needed to resolve]
+- **Created By**: [Agent name]
+```
+
+---
+
+## Duration Tracking
+
+Agent work duration is tracked automatically by the orchestrator using `start_agent_invocation` and `end_agent_invocation`. You do not need to self-report duration or token usage.
+
+**If an operation is taking excessively long** (e.g., unbounded iteration, runaway complexity):
+- Stop and document a `DURATION_EXCEEDED` blocker
+- Include what was completed and what remains
+
+---
+
+## Watcher Verification (Builder, Integrator, Release Only)
+
+**Builder, Integrator, and Release are watched agents.** They must emit structured claims for verification.
+
+### How Verification Works
+
+1. **Agent emits claim** (in State Changes Required section)
+2. **Policy Engine** (SQL) performs deterministic checks:
+   - Evidence refs present?
+   - Phase order correct?
+   - Required gates approved?
+3. **If PASS**: Claim verified, workflow continues
+4. **If NEEDS_REVIEW**: Escalated to LLM Watcher for semantic verification
+
+### Escalation Triggers (Any One Triggers LLM Watcher)
+
+- Claim marked `HIGH` risk
+- Evidence refs missing or empty
+- Policy check inconclusive
+
+### Claim Format
+
+```markdown
+### Claim: [CLAIM_TYPE]
+
+- **Claim Type**: CODE_ADDED | CODE_MODIFIED | CODE_DELETED | TEST_ADDED | TEST_PASSED | BUILD_SUCCEEDED | INTEGRATION_VERIFIED | PR_CREATED | ARCHIVE_CREATED
+- **Description**: What was done
+- **Risk Level**: LOW | MEDIUM | HIGH
+- **Evidence Refs**:
+  ```json
+  {
+    "commit_sha": "abc123",
+    "file_paths": ["src/file.ts"],
+    "spec_sections": ["4.2"],
+    "test_output_hash": "sha256:...",
+    ...
+  }
+  ```
+```
+
+### Risk Level Guidelines
+
+| Risk Level | When to Use |
+|------------|-------------|
+| **LOW** | Tests, docs, styling, non-critical code |
+| **MEDIUM** | Business logic, API endpoints, data transformations |
+| **HIGH** | Authentication, authorization, payments, PII, security, deletions |
+
+**HIGH risk claims ALWAYS escalate to LLM Watcher.**
+
+---
+
+## Memory Candidates
+
+Document project knowledge discovered during your work. The orchestrator will prompt the user to save these as permanent memories.
+
+**When to document**: Architecture insights, integration patterns, tech stack decisions, performance baselines, security requirements, gotchas found.
+
+```markdown
+### Memory Candidates
+
+**ARCHITECTURE**: [Insight about system architecture]
+**Tags**: [relevant, tags]
+
+**PATTERN**: [Reusable pattern discovered]
+**Tags**: [pattern, category]
+```
+
+---
+
+## Skills — Mandatory
+
+Skills are **mandatory** for all agents. The orchestrator injects domain-specific skills into your context under `## Active Skills`. If no specific tech stack skills match, the `generic-dev` fallback skill is injected.
+
+Some phases also require workflow skills:
+
+- **Builder** must receive `testing/unit-tests-sdd`
+- **Reviewer** must receive `testing/unit-tests-eval-sdd`
+
+Always follow patterns, conventions, and best practices from your injected skills.
+
+---
+
+## Development Evals — Additive Verification
+
+Development Evals are a workflow track for defining and checking behavior before and after implementation. They are **not** the same as Odin's operational **EVALS** health scoring.
+
+### Core Objects
+
+- **`eval_plan`** — Architect-owned pre-build artifact describing capability/regression cases and grading strategy
+- **`eval_readiness`** — Guardian gate before Builder begins
+- **`eval_run`** — Reviewer-owned post-build proof artifact, optionally extended by Integrator for runtime validation
+
+### Phase Responsibilities
+
+- **Product**: define success, non-goals, and failure shape
+- **Discovery**: collect happy-path, edge, failure, and should-not-trigger scenarios
+- **Architect**: record `eval_plan` when required
+- **Guardian**: decide `eval_readiness`
+- **Builder**: keep regression/acceptance coverage in sync with the work
+- **Reviewer**: run development evals and record `eval_run`
+- **Integrator**: resolve any `partial` eval state with runtime/end-state verification
+
+### Non-Interference Rule
+
+Development Evals are additive. They MUST NOT replace, bypass, or weaken:
+
+- formal verification (`odin.verify_design`) when applicable
+- Builder/Integrator test and build verification
+- Reviewer security review via `odin.run_review_checks`
+- runtime spot-checks and integration validation
+- watched-claim Policy Engine / Watcher verification
+
+If Development Evals pass but one of the existing review steps fails, the feature is still blocked.
+
+### Runtime Recording Convention
+
+Only the main orchestrator session can call Odin MCP tools. Agents should document these state changes when relevant:
+
+- `odin.record_phase_artifact({ output_type: "eval_plan", ... })`
+- `odin.record_quality_gate({ gate_name: "eval_readiness", ... })`
+- `odin.record_phase_artifact({ output_type: "eval_run", ... })`
+
+---
+
+## Build Verification — Dual-Check Convention
+
+Both the **Builder** and **Integrator** agents must verify the build passes. This provides defense-in-depth:
+
+1. **Builder (Step 5a)**: Runs `npm run build` after completing all code changes. Catches TypeScript errors, import issues, and configuration problems before handoff. If the build fails, the Builder fixes the issue — no phase transition until the build passes.
+
+2. **Integrator (Step 6)**: Runs the build again as a second verification. Also performs runtime verification (Step 6b) to catch issues that pass the build but fail at runtime (e.g., stale data, caching, missing env vars).
+
+**Why both?** A build failure caught by the Builder saves a full phase transition round-trip. The Integrator's second check catches regressions or environment-specific issues.
+
+---
+
+## Git Branch Management
+
+Odin tracks git branches per feature. When a feature is created, a branch name is generated:
+- **With dev initials**: `{initials}/feature/{FEATURE-ID}` (e.g., `jd/feature/AUTH-001`)
+- **Without initials**: `feature/{FEATURE-ID}` (e.g., `feature/AUTH-001`)
+
+The orchestrator creates the git branch **BEFORE calling `create_feature()`**. The branch must exist before the DB record is created:
+```
+# 1. Create branch FIRST
+git checkout -b {dev_initials}/feature/{FEATURE-ID}
+
+# 2. Only after branch exists, create the DB record
+SELECT * FROM create_feature(...);
+```
+
+> **CRITICAL**: If branch creation fails, do NOT call `create_feature()`. A dead DB record with no branch is worse than no record at all.
+
+Agents that interact with git should:
+1. **Orchestrator**: Create the feature branch FIRST, then call `create_feature()` — do NOT defer branch creation to Builder
+2. **Builder**: Commit after each task, include commit tracking in State Changes
+3. **Integrator**: Verify build and runtime on the feature branch
+4. **Release**: Create PR via `gh pr create`, request human review — **NEVER merge PRs**
+
+### Developer Identity
+
+The `dev_initials` and `author` parameters must identify the real human developer. **Never guess or use placeholders.** To obtain them:
+1. Check `git config user.name` and derive initials
+2. Check recent features: `SELECT dev_initials, author FROM features WHERE dev_initials IS NOT NULL ORDER BY created_at DESC LIMIT 1`
+3. Ask the developer if neither source is available
+
+### Commit Tracking
+
+After each commit, document it in State Changes Required:
+
+```markdown
+### Record Commit
+- **Feature ID**: AUTH-001
+- **Commit Hash**: abc123
+- **Phase**: 4 (Builder)
+- **Message**: feat(AUTH-001): implement login endpoint
+- **Files Changed**: 5
+- **Insertions**: 120
+- **Deletions**: 30
+```
+
+The orchestrator records commits via `record_commit()` in Supabase.
+
+---
+
+## CRITICAL: NEVER Auto-Merge Pull Requests
+
+**Agents can CREATE pull requests but NEVER merge them.**
+
+PR merging is ALWAYS a human decision. This applies to ALL agents with git/gh access. No exceptions. No "auto-merge if tests pass." No "merge if approved." NEVER.
+
+- **Release agent**: Creates PR via `gh pr create`, records PR URL via `record_pr()`, then STOPS
+- **Human**: Reviews, approves, and merges the PR
+- **After merge**: Human (or agent on instruction) calls `record_merge()` to update tracking
+
+---
+
+## Learning Creation — Mandatory for Bug Fixes
+
+**Every bug fix MUST create a learning.** Before closing any fix, ask yourself:
+
+> *Is this a learning? If the fix involved a non-obvious cause, a gotcha, or a pattern others would hit — create a learning and declare propagation targets.*
+
+Include in your artifact's Memory Candidates section:
+- **Category**: GOTCHA, PATTERN, CONVENTION, etc.
+- **Title**: Concise description of the insight
+- **Content**: What happened, why, and how to avoid it
+- **Propagation targets**: Which skills, agent definitions, or AGENTS.md should receive this
+
+**When in doubt, create the learning.** It's better to have a low-importance learning than to lose a hard-won insight.
+
+---
+
+## Post-Release Verification
+
+After the Release phase completes, the orchestrator should verify the deployed/running application shows correct data. This includes:
+
+1. **Spot-check a known DB value** against the rendered output (e.g., a feature's status in Supabase vs. what the dashboard shows)
+2. **Verify key pages render** without errors
+3. **Check data freshness** — ensure the UI reflects recent changes, not cached stale data
+
+If bugs are found post-release:
+1. Create a **new L1 feature** to track the fix (don't fix ad-hoc without tracking)
+2. The fix feature MUST create a learning before completion
+3. The learning MUST declare propagation targets
+
+---
+
+## CRITICAL: NEVER Skip Phases OR Steps
+
+**All 11 phases must be executed for every feature.** This is enforced at the database level — `transition_phase()` will reject any attempt to skip a phase.
+
+**All steps within each phase must also be executed.** Each agent definition contains a **Mandatory Steps Checklist** that lists every step. No step may be silently skipped.
+
+- Forward transitions must be sequential: 0→1→2→3→4→5→6→7→8→9
+- Complexity level (L1/L2/L3) affects **depth** within each phase and step, not which phases or steps run
+- An L1 phase can be a single sentence, but it must still be recorded
+- An L1 step can produce minimal output, but it must still execute
+- When documenting State Changes, always use `To Phase: [current + 1]`
+- Phase 10 (Complete) is set by `complete_feature()`, not by `transition_phase()`
+
+**If you think a phase or step is unnecessary**: You're wrong. Execute it briefly. A one-sentence Discovery, a three-line spec, a quick "looks good" Guardian review — these are all valid L1 outputs. If a step truly does not apply (e.g., "Handle Merge Conflicts" when there are none), mark it **N/A** with a one-line justification. Never silently skip it.
+
+---
+
+## Step Execution Protocol
+
+Before each phase, the orchestrator MUST:
+
+1. **Read the agent definition** for the upcoming phase
+2. **Identify the Mandatory Steps Checklist** at the top of the agent's process section
+3. **Execute every step** in order, or mark it N/A with justification
+4. **Never silently skip a step** — if a step seems unnecessary, state why and mark N/A
+
+**Enforcement levels**:
+| Level | What | Enforced By | Mechanism |
+|-------|------|-------------|-----------|
+| Phase | All 11 phases run (0-10) | Database | `transition_phase()` rejects skips |
+| Step | All steps within a phase run | Agent checklist | Orchestrator verifies each step |
+
+**Complexity affects depth, not coverage**:
+| Complexity | Phase Depth | Step Depth |
+|------------|-------------|------------|
+| L1 | 1-3 sentences | Minimal output per step |
+| L2 | Full paragraphs | Standard output per step |
+| L3 | Comprehensive sections | Detailed output per step |
+
+---
+
+## What ALL Agents Must NOT Do
+
+- Try to call MCP tools directly (you don't have access)
+- Skip documenting State Changes Required
+- Proceed without skills loaded
+- **Skip phases** — all 11 phases must execute, even for L1 tasks (see above)
+- **Skip steps** — all steps within your phase must execute, even for L1 tasks (see above)
+- Continue past reasonable duration for your phase (document DURATION_EXCEEDED blocker and stop)
+- Make up file paths or code patterns — use only what you can verify from context
+- Override decisions made in earlier phases
+- **Merge pull requests** — PR merging is ALWAYS a human decision (see above)
+- **Skip learning creation after bug fixes** — every fix is a potential learning (see above)
+- **Continue work after PR creation** — When a feature is complete and a PR has been created, ALL work MUST stop. Do NOT switch branches, start the next task, stash changes, or begin planning. Report the PR URL and EVAL score, then STOP and wait for the developer to review and merge. The ONLY exception is if the developer explicitly says "continue."