@kal-elsam/kairo-runtime 0.4.3 → 0.5.0

package/README.md

@@ -35,9 +35,10 @@ kairo
 **First run** (no `~/.harness/state.json`): interactive onboarding → safe diagnosis →
 setup with confirmation → full-screen operations cockpit.
 
-**Later runs** (state present): full-screen cockpit Home that explains what Kairo
-does, shows real readiness, and recommends a useful next action. Layout adapts to
-terminal size:
+**Later runs** (state present): full-screen Control Center that explains what Kairo
+does, shows coverage/integrity, evidence-backed proposals, and the next governance
+action (scan → evidence → preview → confirm → apply → re-scan → recovery). Runs stay
+secondary. Layout adapts to terminal size:
 
 | Mode | Size | Layout |
 |------|------|--------|
@@ -216,17 +217,30 @@ kairo uninstall
 kairo install --scope=workspace   # opt-in / legacy
 ```
 
-### Intelligence layer (0.2.0)
+### Intelligence layer
 
-Kairo owns **Harness Engineering** governance: compile relevant project context, route to a backend, and require human confirmation for cloud transmission. It does not store credentials.
+Kairo owns **Harness Engineering** governance: compile relevant project context, route to a backend, and require human confirmation for cloud transmission. It does not store credentials and never reads OpenCode `auth.json`.
 
 | Backend | Detection | Invoke |
 |---|---|---|
 | Ollama | `GET $OLLAMA_HOST/api/tags` (default `http://127.0.0.1:11434`) | Local chat |
+| OpenCode Go | `OPENCODE_API_KEY` → `https://opencode.ai/zen/go/v1` | Chat Completions (subscription labels; entitlement unverified from key alone) |
+| OpenCode Zen | `OPENCODE_API_KEY` → `https://opencode.ai/zen/v1` | Chat Completions + Responses (credits; never auto-spent from Go failures) |
+| OpenCode CLI (`opencode`) | CLI installed + `opencode auth list` providers | `opencode run --format json --model` with an analysis-only preamble (not a universal non-mutation guarantee) |
 | OpenRouter | `OPENROUTER_API_KEY` in env | `openrouter/free` after `--cloud-consent` + `--yes` |
 | Custom HTTP | Profile `customProviders` (`baseUrl`, `modelId`, optional local-only `apiKeyEnv`) | OpenAI-compatible `/chat/completions` |
 
-Routing order: user override → Ollama → OpenRouter free (consent) → diagnostics mode.
+Routing order: ephemeral CLI `--backend`/`--model` → profile override → Ollama → OpenCode Go → OpenCode Zen → OpenRouter free → diagnostics. OpenCode CLI runtime is override-only (not auto-routed).
+
+```bash
+export OPENCODE_API_KEY=...   # env only; never persisted by Kairo
+kairo intelligence status --json
+kairo intelligence models --backend opencode-go
+kairo intelligence route --backend opencode-go --model kimi-k2.7-code --cloud-consent
+kairo intelligence ask --prompt "Summarize risks" --backend opencode --model opencode/claude-haiku-4-5 --cloud-consent --yes
+```
+
+Detection states stay differentiated: configured ≠ authenticated ≠ entitlement ≠ balance. An API key means a credential is present, not that login, subscription, or spend was verified.
 
 Private paths (`.env`, secrets, keys) are excluded from context packs unless `--include-private`.
 Remote custom providers require explicit cloud consent and cannot receive an `apiKeyEnv` credential in 0.2.0; use a built-in provider or a local custom endpoint for env-backed authentication.
@@ -275,7 +289,15 @@ kairo setup --agents all
 kairo install --agents all
 ```
 
-Primary flow remains `kairo` → `status` → `sync` (or `kairo setup` explicitly).
+Primary governance flow:
+
+```txt
+scan (read-only) → evidence proposals → preview → confirm → apply → re-scan → recovery
+```
+
+Bare `kairo` opens the Control Center cockpit when the ecosystem is configured.
+Runs stay secondary until setup/repairs/verification are healthy. CLI equivalents
+remain `kairo status` / `kairo diff` / `kairo sync` (or `kairo setup` explicitly).
 
 ## Install scopes
 
@@ -303,8 +325,9 @@ kairo install --agents cursor,codex --yes
 ### `kairo status`
 
 Control panel for the local ecosystem: detected vs managed agents, installed
-components, check counts (ok/missing/stale), backups, overall status, and the
-recommended next action.
+components, check counts (ok/missing/stale/warning), backups, overall status, and the
+recommended next action. Installed components expose public health
+(`healthy` / `degraded` / `drifted` / `missing`).
 
 ```bash
 kairo status
@@ -312,8 +335,8 @@ kairo status --json
 ```
 
 `--json` prints a stable machine-readable envelope for CI, tooling, and debugging
-(`ok`, `overall`, `agents`, `components`, `checks`, `backups`, `nextAction`,
-`cliVersion`). Human text remains the default. Exit code is non-zero when
+(`ok`, `overall`, `agents`, `components`, `componentHealth`, `checks`, `backups`,
+`nextAction`, `cliVersion`). Human text remains the default. Exit code is non-zero when
 `overall` is not `ok`.
 
 ### `kairo sync`
@@ -465,8 +488,83 @@ deletes `~/.harness/state.json` and `~/.harness/core/`. Backups are preserved.
 ### Workspace components
 
 Opt-in custom components live in the current repo under `.harness/components/`.
-They never override bundled IDs (`orchestrator`, `sdd-core`) and install copies
-assets into `~/.harness/components/<id>/` only when you pass `--components`.
+They never override bundled IDs (`orchestrator`, `sdd-core`, `engram-memory`,
+`graphify-context`) and install copies assets into `~/.harness/components/<id>/`
+only when you pass `--components`.
+
+#### Component Manifest v2
+
+Catalogs are a validated contract. Bundled `catalog.json` uses `schemaVersion: 2`
+with `kind`, `capabilities`, `dependencies`, and `healthChecks`. Workspace v1
+catalogs (no `schemaVersion`) still load — fields normalize in memory; persisted
+`~/.harness/state.json` stays compatible and derives new metadata from the catalog.
+
+- Dependencies resolve topologically (deps first, no duplicates).
+- Public component health: `healthy` | `degraded` | `drifted` | `missing`.
+- Engram/Graphify integration warnings degrade that component; they do not fail
+  global `doctor` by themselves.
+- Workspace entries stay declarative JSON (no arbitrary code execution).
+- `engram-memory` may declare `integration.provider: "engram"`. Kairo detects the
+  Engram binary, plans official `engram setup <agent>`, and never installs Engram
+  silently or runs `engram doctor` (SQLite side effects).
+
+Configure Engram (requires `engram-memory` installed and Engram `>=1.19.0 <2.0.0`):
+
+```bash
+kairo components configure engram-memory --agents codex,opencode --dry-run
+kairo components configure engram-memory --agents codex,opencode --yes
+kairo components rollback engram-memory --receipt <id> --dry-run
+```
+
+Without `--agents`, Kairo uses the intersection of detected agents and
+Kairo-managed Engram agents (`cursor`, `codex`, `opencode`, `claude` → setup slug
+`claude-code`). After setup, status is `restart_required` — restart the agent to
+load MCP; configuration evidence is not runtime-active. Receipts live under
+`~/.harness/integrations/engram/`.
+
+### SDD Core skills
+
+`sdd-core` (default with setup/install) materializes nine phase skills:
+
+`sdd-init`, `sdd-explore`, `sdd-propose`, `sdd-spec`, `sdd-design`,
+`sdd-tasks`, `sdd-apply`, `sdd-verify`, `sdd-archive`.
+
+Each skill ships as a directory (`SKILL.md` + `references/contract.md`).
+
+**Auto-materialization.** When `sdd-core` is selected/installed,
+`install` / `setup` / `sync` / `upgrade` materialize (or repair) skills via the
+same `sdd-core` apply path. Lifecycle keeps persona frozen (`preservePersona`):
+it never auto-activates teaching. Explicit persona changes stay on
+`kairo components configure sdd-core`.
+
+**Destinations.** Cursor, Codex, and OpenCode share `~/.agents/skills/<id>/`.
+Claude uses `~/.claude/skills/<id>/`. One physical tree per root; consumers are
+recorded per destination.
+
+**Persona.** Defaults to `off`. `--persona teaching` activates per managed
+agent via `state.sdd.personaAgentIds` (managed-section gate only — explanations,
+never code/docs/commits/PRs). `--persona off` removes teaching only for the
+targeted agents.
+
+**Consent and conflicts.** Dry-run writes nothing. Non-interactive mutating
+configure/rollback without `--json` requires `--yes`, `--confirm`, or
+`--no-preflight`. `--json` selects machine-readable output and skips the
+prompt/consent gate (same apply-confirmation policy as setup/sync/upgrade).
+Conflicts and user-owned files are never overwritten, even with `--yes`.
+Receipts live under `~/.harness/integrations/sdd-core/` and may be `partial`
+when some actions succeed and others fail.
+
+**Session refresh.** After skill or managed-section changes, results report
+`session_refresh_required` — restart agents to load skills; Kairo does not claim
+existing sessions already loaded them. Verify health is
+`configured` | `missing` | `drifted` | `conflict`.
+
+```bash
+kairo components configure sdd-core --agents codex,opencode,cursor,claude --persona off --dry-run
+kairo components configure sdd-core --agents codex,opencode --persona teaching --yes
+kairo components verify sdd-core --json
+kairo components rollback sdd-core --receipt <id> --dry-run
+```
 
 Create, validate, and install:
 
@@ -858,19 +956,28 @@ gentle-ai doctor
 
 ## Engram/Graphify integration
 
-This pack does not assume a specific implementation. It defines integration points in:
+Engram and Graphify are **external** integrations. Kairo verifies configuration,
+version, and freshness evidence when present; it does not install them, read the
+Engram database, or traverse the Graphify graph at runtime, and never claims they
+are actively running.
+
+Integration points (repo docs / optional components):
 
 ```txt
 docs/ai/context-graph.md
 docs/ai/memory.md
 docs/skills/context-graph.md
+global-template/components/engram-memory/
+global-template/components/graphify-context/
 ```
 
 The rule:
 
-- The repo keeps the source of truth in Markdown.
-- Engram can index decisions, specs, memory, and conventions.
-- Graphify can build the architecture graph: modules, dependencies, features, and risks.
+- The repo keeps the source of truth in Markdown (`AGENTS.md`, `docs/ai/`, code).
+- Engram may index decisions, specs, memory, and conventions when configured separately.
+- Graphify may build an architecture graph when you run `graphify` yourself.
+- Control-plane proposals for Engram/Graphify appear only with verifiable
+  config/version/freshness checks — never from optional intelligence absence alone.
 - No external memory replaces `AGENTS.md`, `docs/ai/`, or the code.
 
 ## v2 — Universal-first, adapter-based

package/global-template/components/catalog.json

@@ -1,19 +1,59 @@
 {
+  "schemaVersion": 2,
   "components": [
     {
       "id": "orchestrator",
+      "kind": "component",
       "label": "Orchestrator",
       "version": "1.0.0",
       "defaultEnabled": true,
+      "capabilities": ["orchestration"],
+      "dependencies": [],
+      "healthChecks": [
+        { "id": "assets", "type": "assets" },
+        { "id": "drift", "type": "drift" }
+      ],
       "assetFiles": ["orchestrator.md"],
       "adapterHints": {}
     },
     {
       "id": "sdd-core",
+      "kind": "component",
       "label": "SDD Core",
-      "version": "1.0.0",
+      "version": "2.0.0",
       "defaultEnabled": true,
-      "assetFiles": ["workflow.md", "spec-sizing.md", "handoff.md"],
+      "capabilities": ["sdd.workflow", "sdd.skills", "sdd.persona"],
+      "dependencies": [],
+      "healthChecks": [
+        { "id": "assets", "type": "assets" },
+        { "id": "drift", "type": "drift" },
+        { "id": "integration", "type": "integration", "optional": true }
+      ],
+      "integration": { "provider": "sdd-core" },
+      "assetFiles": [
+        "workflow.md",
+        "spec-sizing.md",
+        "handoff.md",
+        "skills/sdd-init/SKILL.md",
+        "skills/sdd-init/references/contract.md",
+        "skills/sdd-explore/SKILL.md",
+        "skills/sdd-explore/references/contract.md",
+        "skills/sdd-propose/SKILL.md",
+        "skills/sdd-propose/references/contract.md",
+        "skills/sdd-spec/SKILL.md",
+        "skills/sdd-spec/references/contract.md",
+        "skills/sdd-design/SKILL.md",
+        "skills/sdd-design/references/contract.md",
+        "skills/sdd-tasks/SKILL.md",
+        "skills/sdd-tasks/references/contract.md",
+        "skills/sdd-apply/SKILL.md",
+        "skills/sdd-apply/references/contract.md",
+        "skills/sdd-verify/SKILL.md",
+        "skills/sdd-verify/references/contract.md",
+        "skills/sdd-archive/SKILL.md",
+        "skills/sdd-archive/references/contract.md",
+        "personas/teaching.md"
+      ],
       "adapterHints": {
         "cursor": "- In repos with workspace harness: also read `.cursor/rules/` and `docs/specs/`.",
         "codex": "- In repos with workspace harness: also read `.codex/skills/sdd/` when present.",
@@ -23,22 +63,39 @@
     },
     {
       "id": "engram-memory",
+      "kind": "component",
       "label": "Engram Memory",
       "version": "1.0.0",
       "defaultEnabled": false,
+      "capabilities": ["memory"],
+      "dependencies": [],
+      "healthChecks": [
+        { "id": "assets", "type": "assets" },
+        { "id": "drift", "type": "drift" },
+        { "id": "integration", "type": "integration", "optional": true }
+      ],
+      "integration": { "provider": "engram" },
       "assetFiles": ["memory.md"],
       "adapterHints": {
-        "cursor": "- Engram MCP (`mem_*` tools) is not auto-installed; configure in Cursor MCP settings when ready.",
-        "codex": "- Engram MCP is not auto-installed; add MCP server config when ready.",
-        "claude": "- Engram MCP is not auto-installed; add MCP server config when ready.",
-        "opencode": "- Engram MCP is not auto-installed; add MCP server config when ready."
+        "cursor": "- Configure Engram via `kairo components configure engram-memory` (official `engram setup cursor`).",
+        "codex": "- Configure Engram via `kairo components configure engram-memory` (official `engram setup codex`).",
+        "claude": "- Configure Engram via `kairo components configure engram-memory` (official `engram setup claude-code`).",
+        "opencode": "- Configure Engram via `kairo components configure engram-memory` (official `engram setup opencode`)."
       }
     },
     {
       "id": "graphify-context",
+      "kind": "component",
       "label": "Graphify Context",
       "version": "1.0.0",
       "defaultEnabled": false,
+      "capabilities": ["context.graph"],
+      "dependencies": [],
+      "healthChecks": [
+        { "id": "assets", "type": "assets" },
+        { "id": "drift", "type": "drift" },
+        { "id": "integration", "type": "integration", "optional": true }
+      ],
       "assetFiles": ["context-graph.md"],
       "adapterHints": {
         "cursor": "- Graphify CLI is not auto-installed; run `graphify update .` after code changes when graphify is in PATH.",

package/global-template/components/sdd-core/personas/teaching.md

@@ -0,0 +1,42 @@
+# Teaching Persona
+
+> Managed by `@kal-elsam/harness` component `sdd-core`.
+> Enabled only with `--persona teaching`. Default is `off`.
+
+## Purpose
+
+Explain SDD decisions and trade-offs to the user in clear language while the agent still follows repository authority and contracts.
+
+## Authority
+
+```txt
+system/current user
+→ repository AGENTS.md
+→ repository docs/ai and docs/skills
+→ repository adapter instructions
+→ optional teaching persona
+→ global SDD fallback
+→ memory/model defaults
+```
+
+## Scope
+
+Affects:
+
+- explanations of classification, plans, and verification
+- answers to the user about why a step exists
+
+Does not affect:
+
+- generated code
+- UI copy
+- documentation content
+- commits or pull requests
+- hidden solutions or forced verbosity
+
+## Rules
+
+- Never override higher-authority instructions.
+- Never hide a working solution behind teaching theater.
+- Prefer short clarifying questions when ambiguity blocks progress.
+- Keep SDD skill contracts as the source of workflow behavior.

package/global-template/components/sdd-core/skills/sdd-apply/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: sdd-apply
+description: "Implement the current SDD task with failing tests first."
+---
+
+# SDD Apply
+
+Use this skill to implement one approved task without expanding scope.
+
+## References
+- [Phase contract](references/contract.md)
+## Source of truth
+
+- `AGENTS.md`
+- `docs/ai/harness.md`
+- `docs/ai/test-driven-development.md`
+- `docs/ai/testing.md`
+
+## Workflow
+
+1. Confirm the active task and its acceptance criteria.
+2. Write or update the failing regression or behavior tests first.
+3. Implement the smallest change that satisfies the task.
+4. Stop when the task is complete; do not pull later tasks forward.
+
+## Output
+
+```txt
+Task:
+Tests added:
+Files changed:
+Validation:
+Remaining risks:
+```

package/global-template/components/sdd-core/skills/sdd-apply/references/contract.md

@@ -0,0 +1,4 @@
+# sdd-apply contract
+Activation: One approved task is active and ready to implement. Hard rules: Failing tests first; smallest change; do not pull later tasks forward.
+Gates: Task done → sdd-verify · blocked by design/spec → escalate, do not widen. Steps: Confirm task → write failing tests → implement minimum → stop at completion.
+Output: Task | Tests added | Files changed | Validation | Remaining risks

package/global-template/components/sdd-core/skills/sdd-archive/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: sdd-archive
+description: "Close the SDD cycle with durable notes and handoff evidence."
+---
+
+# SDD Archive
+
+Use this skill at the end of a completed SDD cycle to leave a recoverable trail for the next agent or reviewer.
+
+## References
+- [Phase contract](references/contract.md)
+## Source of truth
+
+- `AGENTS.md`
+- `docs/ai/agent-workflow.md`
+- `docs/ai/harness.md`
+- `docs/specs/`
+
+## Workflow
+
+1. Summarize what shipped and what was deferred.
+2. Point to the spec, tasks, and verification evidence.
+3. Capture open questions and follow-up risks.
+4. Leave the workspace ready for the next request.
+
+## Output
+
+```txt
+Shipped:
+Deferred:
+Evidence:
+Open questions:
+Suggested next action:
+```

package/global-template/components/sdd-core/skills/sdd-archive/references/contract.md

@@ -0,0 +1,4 @@
+# sdd-archive contract
+Activation: Verification evidence is complete for this SDD cycle. Hard rules: Durable shipped/deferred notes only; do not reopen scope or implement.
+Gates: Trail recoverable → stop · missing evidence → return to sdd-verify Steps: Summarize shipped/deferred → point to evidence → open questions → ready next.
+Output: Shipped | Deferred | Evidence | Open questions | Suggested next action

package/global-template/components/sdd-core/skills/sdd-design/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: sdd-design
+description: "Translate an accepted spec into technical design boundaries."
+---
+
+# SDD Design
+
+Use this skill to convert the approved spec into technical structure before task breakdown.
+
+## References
+- [Phase contract](references/contract.md)
+## Source of truth
+
+- `AGENTS.md`
+- `docs/ai/architecture.md`
+- `docs/ai/spec-driven-development.md`
+- `docs/ai/testing.md`
+
+## Workflow
+
+1. Map the affected modules and interfaces.
+2. Define invariants, error boundaries, and test seams.
+3. Capture trade-offs and non-goals.
+4. Prepare a clean handoff for task decomposition.
+
+## Output
+
+```txt
+Design boundary:
+Interfaces:
+Risks:
+Test seams:
+Next skill:
+```

package/global-template/components/sdd-core/skills/sdd-design/references/contract.md

@@ -0,0 +1,4 @@
+# sdd-design contract
+Activation: After an accepted spec, before task breakdown. Hard rules: Define interfaces/invariants/non-goals; do not start implementation tasks.
+Gates: Boundaries clear → sdd-tasks · spec gap found → return to sdd-spec Steps: Map modules → interfaces/error bounds → trade-offs → test seams → handoff.
+Output: Design boundary | Interfaces | Risks | Test seams | Next skill

package/global-template/components/sdd-core/skills/sdd-explore/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: sdd-explore
+description: "Gather focused repository context before proposing a spec."
+---
+
+# SDD Explore
+
+Use this skill to collect only the context needed to define scope, constraints, and affected files.
+
+## References
+- [Phase contract](references/contract.md)
+## Source of truth
+
+- `AGENTS.md`
+- `docs/ai/context-budget.md`
+- `docs/ai/architecture.md`
+- `docs/ai/spec-driven-development.md`
+
+## Workflow
+
+1. Read the minimum relevant code and docs.
+2. Identify affected modules, contracts, and existing tests.
+3. Capture unknowns, dependencies, and rollout or rollback constraints.
+4. Stop exploration once the next decision is clear.
+
+## Output
+
+```txt
+Context read:
+Files analyzed:
+Existing contract:
+Unknowns:
+Next skill:
+```

package/global-template/components/sdd-core/skills/sdd-explore/references/contract.md

@@ -0,0 +1,4 @@
+# sdd-explore contract
+Activation: After init when scope still needs evidence before propose/spec. Hard rules: Read only what unlocks the next decision; do not propose or implement.
+Gates: Enough context → sdd-propose · residual ambiguity/risk → sdd-spec Steps: Minimum relevant read → map modules/contracts/tests → capture unknowns → stop.
+Output: Context read | Files analyzed | Existing contract | Unknowns | Next skill

package/global-template/components/sdd-core/skills/sdd-init/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: sdd-init
+description: "Classify the request and open the right SDD path."
+---
+
+# SDD Init
+
+Use this skill at the start of non-trivial work to classify the request before planning or implementation.
+
+## References
+- [Phase contract](references/contract.md)
+## Source of truth
+
+- `AGENTS.md`
+- `docs/ai/harness.md`
+- `docs/ai/spec-driven-development.md`
+- `docs/ai/spec-sizing.md`
+
+## Workflow
+
+1. Read the current user request and repository constraints.
+2. Classify the work as `basic`, `standard`, or `complex`.
+3. State the main risk, the expected validation, and whether a spec is required.
+4. Route to `sdd-explore`, `sdd-propose`, or `sdd-spec` as the next skill.
+
+## Output
+
+```txt
+Classification:
+Why:
+Primary risk:
+Validation:
+Next skill:
+```

package/global-template/components/sdd-core/skills/sdd-init/references/contract.md

@@ -0,0 +1,4 @@
+# sdd-init contract
+Activation: Non-trivial request start — before explore, propose, or spec. Hard rules: Classify and route only; never implement; prefer local refs over missing paths.
+Gates: basic→sdd-propose · standard→sdd-explore · complex→sdd-spec Steps: Read request+constraints → classify → name risk/validation → hand off next skill.
+Output: Classification | Why | Primary risk | Validation | Next skill

package/global-template/components/sdd-core/skills/sdd-propose/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: sdd-propose
+description: "Turn explored context into a bounded implementation proposal."
+---
+
+# SDD Propose
+
+Use this skill after exploration to outline the smallest safe delivery slice.
+
+## References
+- [Phase contract](references/contract.md)
+## Source of truth
+
+- `AGENTS.md`
+- `docs/ai/harness.md`
+- `docs/ai/spec-driven-development.md`
+- `docs/ai/architecture.md`
+
+## Workflow
+
+1. Define the user-visible outcome.
+2. Bound the change to one reviewable unit.
+3. List included work, excluded work, and validation.
+4. Escalate to `sdd-spec` when ambiguity or risk is still high.
+
+## Output
+
+```txt
+Outcome:
+Included:
+Excluded:
+Validation:
+Open questions:
+Next skill:
+```

package/global-template/components/sdd-core/skills/sdd-propose/references/contract.md

@@ -0,0 +1,4 @@
+# sdd-propose contract
+Activation: After explore when a bounded delivery slice is visible. Hard rules: One reviewable unit; escalate remaining ambiguity to spec; no coding.
+Gates: Slice clear → sdd-design/tasks path · still ambiguous → sdd-spec Steps: Define outcome → bound include/exclude → list validation → open questions.
+Output: Outcome | Included | Excluded | Validation | Open questions | Next skill

package/global-template/components/sdd-core/skills/sdd-spec/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: sdd-spec
+description: "Write or update the implementation spec for significant work."
+---
+
+# SDD Spec
+
+Use this skill when the request needs a written spec before implementation.
+
+## References
+- [Phase contract](references/contract.md)
+## Source of truth
+
+- `AGENTS.md`
+- `docs/ai/spec-driven-development.md`
+- `docs/ai/harness.md`
+- `docs/specs/`
+
+## Workflow
+
+1. Create or update the spec in `docs/specs/`.
+2. Record scope, acceptance criteria, constraints, and rollback notes.
+3. Keep the spec aligned with the selected SDD level.
+4. Hand off to `sdd-design` or `sdd-tasks` once scope is stable.
+
+## Output
+
+```txt
+Spec path:
+Scope:
+Acceptance criteria:
+Validation plan:
+Next skill:
+```

package/global-template/components/sdd-core/skills/sdd-spec/references/contract.md

@@ -0,0 +1,4 @@
+# sdd-spec contract
+Activation: When risk or ambiguity requires a written implementation contract. Hard rules: Record scope/acceptance/rollback only; no design coding or task execution.
+Gates: Scope stable → sdd-design · needs more evidence → sdd-explore Steps: Create/update docs/specs → acceptance+constraints → align SDD level → handoff.
+Output: Spec path | Scope | Acceptance criteria | Validation plan | Next skill