@jaimevalasek/aioson 1.23.3 → 1.28.0

package/template/.aioson/agents/sheldon.md

@@ -272,7 +272,7 @@ Run after writing `sheldon-enrichment-{slug}.md` only when `classification: MEDI
 
 Goal: convert binary ACs from the enriched PRD into a machine-checkable contract consumed by `@validator`. Implements AC-HD-06 of `harness-driven-aioson`.
 
-Load `.aioson/docs/sheldon/harness-contract.md` for the full procedure: init via `aioson harness:init`, criteria population (binary vs advisory), `contract_mode`/governor selection by risk, and canonical schemas. Mention the contract path in the post-enrichment handoff; the user approves before the contract is final.
+Load `.aioson/docs/sheldon/harness-contract.md` for the full procedure: init via `aioson harness:init`, criteria population (binary vs advisory), `verification` command authoring (every `binary: true` criterion carries an executable check when mechanically possible — exit 0 = pass, run via `aioson harness:check`), `contract_mode`/governor selection by risk, and canonical schemas. Mention the contract path in the post-enrichment handoff; the user approves before the contract is final.
 
 ## Retro dossier analysis (on-demand)
 

package/template/.aioson/agents/validator.md

@@ -25,6 +25,7 @@ Rules and governance docs may *add* binary criteria but never override the expli
 - `.aioson/plans/{slug}/progress.json` — current state and `completed_steps`
 - Files listed in `progress.json.completed_steps` — the only delivered artifacts in scope
 - Diagnostic tool output — linters, test runners, compilers for deterministic verification
+- `.aioson/plans/{slug}/validator-prompt.txt` (when generated by `aioson harness:validate`) — self-contained review payload: deterministic check results, changed-file list, and unified diff vs base. **Preferred activation: run from this prompt in a fresh, isolated context** (subagent or separate session) — never inline in the session that implemented the feature.
 > Strict sandbox: read ONLY the above. Never read other agents' history, PRDs/requirements/architecture, or unrelated code — see **Context restrictions (mandatory)** below.
 
 ## Context restrictions (mandatory)
@@ -50,13 +51,23 @@ To preserve impartiality and avoid continuity hallucinations, you operate in a *
 Locate `harness-contract.json` for the current feature. Identify criteria with `binary: true`.
 
 ### Step 2 — Deterministic verification
-Run (or request execution of) local tools for each criterion:
+First, run the executable checks declared in the contract:
+
+```bash
+aioson harness:check . --slug={slug} --json
+```
+
+For every criterion that has a `verification` command, the check's exit code **is** the verdict — copy `ok` into `passed` verbatim (reason = the check's stderr first line on failure). Never override a deterministic result with judgment. The report is also persisted at `.aioson/plans/{slug}/last-check-output.json` (allowed reading — it is diagnostic tool output).
+
+For criteria **without** `verification` that are still mechanically checkable, run (or request execution of) local tools yourself:
 - `ls -l {path}` to check file existence.
 - `cat {path}` to validate patterns or content.
 - `npm test` or equivalent for execution criteria.
 
+If the `aioson` CLI is unavailable, fall back to running each criterion's `verification` command directly and use its exit code.
+
 ### Step 3 — Semantic verification
-For criteria that require understanding (e.g., "API follows REST conventions"), analyze the delivered code strictly against what the contract requires — nothing more.
+Only for criteria with no `verification` command that require understanding (e.g., "API follows REST conventions"): analyze the delivered code strictly against what the contract requires — nothing more.
 
 ### Step 4 — Verdict generation
 Your output must be **EXCLUSIVELY** a structured JSON object designed to be parsed by a machine. Do not add preambles or explanations outside the JSON.
@@ -100,12 +111,12 @@ aioson dossier:add-finding . --slug={slug} --agent=validator --section="Agent Tr
 
 Skip silently when the dossier is absent — `progress.json` remains the canonical machine output.
 
-## Observability
-At session end, register: `aioson agent:epilogue . --agent=validator --feature=<slug> --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" --no-dossier 2>/dev/null || aioson agent:done . --agent=validator --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" 2>/dev/null || true`
+## Observability
+At session end, register: `aioson agent:epilogue . --agent=validator --feature=<slug> --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" --no-dossier 2>/dev/null || aioson agent:done . --agent=validator --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" 2>/dev/null || true`
 
 ## Autopilot handoff (post-dev cycle)
 
-When `auto_handoff: true` is set in `project.context.md`, after the verdict and `agent:epilogue`/`agent:done` (`.aioson/docs/autopilot-handoff.md`):
+When `auto_handoff: true` is set in `project.context.md`, after the verdict and `agent:epilogue`/`agent:done` (`.aioson/docs/autopilot-handoff.md`):
 - Score 0 / FAIL → `Skill(aioson:agent:dev)` with `"fix @validator findings — autopilot handoff"`.
 - Score 1 / PASS → **STOP**. The feature is verification-clean; recommend the human run `aioson feature:close . --feature={slug}`. **Never auto-run `feature:close`** — the close is the human gate.
 

package/template/.aioson/docs/autopilot-handoff.md

@@ -9,21 +9,21 @@ Opt-in protocol that removes manual handoff confirmations in the deterministic s
 1. **Pre-dev chain (`@analyst` → `@dev`):** `@analyst`, `@scope-check`, `@architect`, `@discovery-design-doc`, and `@pm` (MEDIUM only). Upstream agents (`@briefing`, `@product`, `@sheldon`) always stay manual — they end on genuine human decisions.
 2. **Post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` → `@validator`):** once a human starts `@dev`, the implementation and review agents chain automatically until the feature is ready to close. `@qa` is the hub: it owns the routing to the specialized agents and the corrections loop.
 
-## Activation
-
-Autopilot is active only when ALL are true:
-
-1. `project.context.md` frontmatter has `auto_handoff: true` (absent or `false` = manual handoffs, current behavior).
-2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
-3. The current agent's own gate/verdict passed (see stop conditions).
-
-Preferred runtime entrypoint:
-
-```bash
-aioson workflow:execute . --feature={slug} --tool=<tool> --agentic
-```
-
-`workflow:execute --agentic` is the central orchestration contract. It writes `.aioson/context/workflow-execute.json` with `agentic_policy`, including the review-loop caps, sidecar/scout policy, lane guard, current checkpoint, and resumable command. Prompt-level `Skill(aioson:agent:<next>)` chaining remains a compatibility fallback for clients that cannot let the gateway consume this checkpoint.
+## Activation
+
+Autopilot is active only when ALL are true:
+
+1. `project.context.md` frontmatter has `auto_handoff: true` (absent or `false` = manual handoffs, current behavior).
+2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
+3. The current agent's own gate/verdict passed (see stop conditions).
+
+Preferred runtime entrypoint:
+
+```bash
+aioson workflow:execute . --feature={slug} --tool=<tool> --agentic
+```
+
+`workflow:execute --agentic` is the central orchestration contract. It writes `.aioson/context/workflow-execute.json` with `agentic_policy`, including the review-loop caps, sidecar/scout policy, lane guard, current checkpoint, and resumable command. Prompt-level `Skill(aioson:agent:<next>)` chaining remains a compatibility fallback for clients that cannot let the gateway consume this checkpoint.
 
 ## Routing — deterministic, never LLM-chosen
 
@@ -34,22 +34,22 @@ The next agent comes from the workflow state machine and on-disk evidence, not f
 
 Never skip a stage, reorder, or pick an agent the state machine / routing table did not name.
 
-## Auto-invoke pattern
-
-When autopilot is active and no stop condition applies:
-
-1. Finish your own closing duties first (artifacts on disk, gate registration, dossier/spec updates, `agent:epilogue`; `agent:done` remains the fallback).
-2. If the runtime checkpoint contains `agentic_policy.enabled=true`, let the gateway continue from `.aioson/context/workflow-execute.json`; do not ask the user to confirm the next deterministic stage.
-3. If no runtime gateway is available, emit a one-line transition notice: `Autopilot: @<current> done → invoking @<next> (Ctrl+C to interrupt)`.
-4. Invoke `Skill(aioson:agent:<next>)` with the task `"continue feature {slug} — autopilot handoff from @<current>"`. No user prompt — Ctrl+C interrupts.
+## Auto-invoke pattern
+
+When autopilot is active and no stop condition applies:
+
+1. Finish your own closing duties first (artifacts on disk, gate registration, dossier/spec updates, `agent:epilogue`; `agent:done` remains the fallback).
+2. If the runtime checkpoint contains `agentic_policy.enabled=true`, let the gateway continue from `.aioson/context/workflow-execute.json`; do not ask the user to confirm the next deterministic stage.
+3. If no runtime gateway is available, emit a one-line transition notice: `Autopilot: @<current> done → invoking @<next> (Ctrl+C to interrupt)`.
+4. Invoke `Skill(aioson:agent:<next>)` with the task `"continue feature {slug} — autopilot handoff from @<current>"`. No user prompt — Ctrl+C interrupts.
 
 ## Segment 1 — pre-dev chain (`@analyst` → `@dev`)
 
-SMALL feature: `@analyst` → `@scope-check` → `@architect` → `@discovery-design-doc` → `@dev`.
-
-MEDIUM feature: `@analyst` → `@architect` → `@discovery-design-doc` → `@pm` → `@scope-check` → `@dev`.
-
-The prompt-only fallback still stops before the FIRST `@dev` activation because `@dev` is a heavy phase and benefits from a fresh context window. Runtime agentic mode may cross this boundary only by starting a fresh `@dev` activation from the checkpoint/context package, not by carrying the upstream chat context forward. If the gateway cannot start that fresh activation, stop with the normal `/clear` + `/dev` recommendation.
+SMALL feature: `@analyst` → `@scope-check` → `@architect` → `@discovery-design-doc` → `@dev`.
+
+MEDIUM feature: `@analyst` → `@architect` → `@discovery-design-doc` → `@pm` → `@scope-check` → `@dev`.
+
+The prompt-only fallback still stops before the FIRST `@dev` activation because `@dev` is a heavy phase and benefits from a fresh context window. Runtime agentic mode may cross this boundary only by starting a fresh `@dev` activation from the checkpoint/context package, not by carrying the upstream chat context forward. If the gateway cannot start that fresh activation, stop with the normal `/clear` + `/dev` recommendation.
 
 ## Segment 2 — post-dev review cycle (hub = `@qa`)
 
@@ -60,8 +60,8 @@ Routing table (each row is followed only when autopilot is active and no stop co
 | Current | Condition | Auto-invoke |
 |---|---|---|
 | `@dev` (first pass) | tests green, gates clear, no open corrections cycle | `@qa` |
-| `@dev` (corrections) | corrections applied, tests green (`review-cycle:status` active; `qa-dev-cycle.json` is legacy QA compatibility) | `@qa` (re-verify) |
-| `@qa` | verdict **FAIL** (Critical/High) | `@dev` via the corrections auto-cycle (cap 3, security gate) |
+| `@dev` (corrections) | corrections applied, tests green (`review-cycle:status` active; `qa-dev-cycle.json` is legacy QA compatibility) | `@qa` (re-verify) |
+| `@qa` | verdict **FAIL** (Critical/High) | `@dev` via the corrections auto-cycle (cap 3, security gate) |
 | `@qa` | verdict **PASS** + `@tester` trigger fires AND `@tester` not yet run clean | `@tester` |
 | `@qa` | verdict **PASS** + `@pentester` trigger fires AND `@pentester` not yet run clean | `@pentester` |
 | `@qa` | verdict **PASS** + harness contract present AND `@validator` not yet PASS | `@validator` |
@@ -77,11 +77,13 @@ Routing table (each row is followed only when autopilot is active and no stop co
 
 **Re-entry guard (no infinite loops):** before auto-invoking a specialized agent, `@qa` checks on-disk evidence that it already ran clean this cycle (e.g. `security-findings-{slug}.json` clean → `@pentester` done; a tester coverage artifact present with no new gap → `@tester` done; `progress.json.ready_for_done_gate` / validator PASS recorded → `@validator` done). An agent that already returned clean is not re-invoked.
 
+**`@validator` runs fresh-context:** when routing to `@validator` with a harness contract present, do not run it inline in the current session — the implementation history biases the verdict. Instead: (1) `aioson harness:check . --slug={slug}` (deterministic checks), (2) `aioson harness:validate . --slug={slug}` — the generated `validator-prompt.txt` is self-contained (criteria + check results + diff vs base), (3) execute that prompt in an **isolated subagent** (Task tool, no conversation context) that writes its JSON verdict to `last-validator-output.json`, (4) re-run `aioson harness:validate` to consume the verdict through the circuit breaker. Clients without subagent support fall back to `Skill(aioson:agent:validator)` in a fresh session, as before.
+
 ## Stop conditions — break the chain and emit the normal manual handoff
 
 1. **`feature:close` / publish** — ALWAYS the human gate. When `@qa` (PASS, nothing pending) or `@validator` (PASS) is the last clean step, STOP and recommend `aioson feature:close . --feature={slug}`. Never auto-run `feature:close`, `feature:archive`, `npm publish`, or any publish/close action.
-2. **First `@dev` entry without runtime gateway** — prompt-only clients stop here (Segment 1). Runtime agentic mode may continue only through a fresh checkpointed `@dev` activation.
-3. **Corrections cap reached** — review cycles are bounded by `agentic_policy.review_cycle` (default 3); when `review-cycle:advance` returns `stop_cycle_limit`, stop and escalate to the human.
+2. **First `@dev` entry without runtime gateway** — prompt-only clients stop here (Segment 1). Runtime agentic mode may continue only through a fresh checkpointed `@dev` activation.
+3. **Corrections cap reached** — review cycles are bounded by `agentic_policy.review_cycle` (default 3); when `review-cycle:advance` returns `stop_cycle_limit`, stop and escalate to the human.
 4. **Critical security finding** — the `@qa` corrections security gate (auth/secret/credential/session/password/token/PII/encryption keywords) blocks the auto-loop; stop and require human intervention.
 5. **Verdict not clean / gate or readiness blocked** — `@scope-check` not `approved`/`patched`, `@architect` Gate B blocked, `@discovery-design-doc` readiness `blocked`, `@pm` Gate C blocked, `@validator` FAIL with no safe corrections path: stop and route to the owner manually.
 6. **Context budget** — estimated usage ≥ `context_warning_threshold` (`.aioson/config.md`): write the compaction checkpoint to `.aioson/context/last-handoff.json`, stop, and recommend `/clear`. The workflow resumes from `workflow.state.json` — the next session re-enters autopilot automatically.

package/template/.aioson/docs/sheldon/harness-contract.md

@@ -37,7 +37,8 @@ For every AC in the enriched PRD with an objective, mechanically verifiable asse
   "id": "C1",
   "description": "<AC text — human-readable for PR review>",
   "assertion": "<machine-verifiable expression — e.g. 'tests/foo.test.js passes' or 'src/x/y.js exports parseX'>",
-  "binary": true
+  "binary": true,
+  "verification": "<shell command whose exit code 0 = pass — e.g. 'node --test tests/foo.test.js'>"
 }
 ```
 
@@ -45,6 +46,19 @@ ACs that are subjective (UX feel, code style preference) get `binary: false` and
 
 **Rule of thumb:** if the assertion can be answered by a single shell command exit code or a single test, it qualifies as `binary: true`. Otherwise mark it advisory and let `@qa` cover it.
 
+### 2b. Author `verification` commands
+
+Every `binary: true` criterion **must** carry a `verification` shell command whenever one is mechanically possible. Exit code 0 = pass; anything else = fail. These commands are executed deterministically by `aioson harness:check . --slug={slug}` (and by `self:loop`) — `@validator` only LLM-judges criteria that have no `verification`.
+
+Authoring rules for `verification`:
+
+- **Prefer the project's own test runner** (`node --test tests/x.test.js`, `npm test -- --grep "..."`, `pytest tests/test_x.py`). A criterion backed by a real test is the gold standard.
+- **One-liner assertions** when no test exists yet: `node -e "const m = require('./src/x'); process.exit(typeof m.parseX === 'function' ? 0 : 1)"`.
+- **Deterministic only**: no network calls, no wall-clock dependence, no interactive prompts.
+- **Cross-platform**: single commands or npm scripts — avoid shell chaining (`&&`, `||`) and POSIX-only utilities (`grep`, `test -f`) on Windows-first projects; use `node -e` for file/shape assertions instead.
+- **Self-contained**: the command must pass/fail on a clean checkout after install — no hidden setup steps.
+- A `binary: true` criterion **without** `verification` remains valid (judged by `@validator`, as before), but the contract schema emits a coverage warning — treat each one as debt and justify it in the enrichment log.
+
 ### 3. Set `contract_mode`
 
 By classification and risk surface:
@@ -90,12 +104,15 @@ Safe defaults for `BALANCED`:
       "id": "C1",
       "description": "...",
       "assertion": "...",
-      "binary": true
+      "binary": true,
+      "verification": "node --test tests/foo.test.js"
     }
   ]
 }
 ```
 
+`verification` is optional per criterion (legacy contracts remain valid), executed via `aioson harness:check` with exit code 0 = pass.
+
 ### `progress.json`
 
 ```json

package/template/.claude/commands/aioson/agent/forge-run.md

@@ -0,0 +1,17 @@
+---
+description: "AIOSON — Compile and run the Lane B workflow harness for a MEDIUM feature"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@forge-run — Compile specs into a workflow harness and execute it (Lane B)
+Usage: /aioson:agent:forge-run [feature slug]
+Requires:
+  .aioson/plans/{slug}/harness-contract.json (with verification commands)
+  .aioson/context/implementation-plan-{slug}.md (with Wave column)
+Produces: .aioson/plans/{slug}/forge-run.workflow.js + a workflow run ending before feature:close
+Instruction file: .aioson/agents/forge-run.md
+CLI help: aioson agent:help forge-run
+
+Otherwise: Read `.aioson/agents/forge-run.md` and follow all instructions. $ARGUMENTS

package/template/AGENTS.md

@@ -2,12 +2,12 @@
 
 You operate as AIOSON — an AI development squad with specialized agents.
 
-## Mandatory first action
-1. Check whether `.aioson/context/project.context.md` exists
-   - If missing: activate @setup agent immediately
-   - If present: read it before any action
-2. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details.
-3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
+## Mandatory first action
+1. Check whether `.aioson/context/project.context.md` exists
+   - If missing: activate @setup agent immediately
+   - If present: read it before any action
+2. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details.
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
 
 ## Project knowledge
 
@@ -88,6 +88,7 @@ Describe your intent. The agent system will match and execute.
 | @design-hybrid-forge | "create hybrid design skill", "combine two design skills", "use the design-hybrid-forge agent" |
 | @site-forge | "clone this site with [skill]", "rebuild [url] using [skill]", "[url] in the style of [skill]", "extract the design from [url] as a skill", "use the site-forge agent" |
 | @discover | "discover the system", "scan and understand the project", "build semantic knowledge cache", "refresh bootstrap", "use the discover agent" |
+| @forge-run | "compile the workflow harness for [slug]", "run lane B for [slug]", "execute the compiled harness", "use the forge-run agent" |
 
 When an agent file is included via @ or described via natural language, read the corresponding file and execute its instructions immediately from the first step.
 Do not answer with "I will open/read/show the file" unless the user explicitly asked to inspect that file.
@@ -148,6 +149,7 @@ When running Codex directly (without `aioson workflow:next`), these rules apply:
 - @orache → `.aioson/agents/orache.md`
 - @design-hybrid-forge → `.aioson/agents/design-hybrid-forge.md`
 - @site-forge → `.aioson/agents/site-forge.md`
+- @forge-run → `.aioson/agents/forge-run.md`
 
 ## Spec-Driven Development (SDD)
 
@@ -167,8 +169,8 @@ AIOSON uses the `aioson-spec-driven` process skill to enforce specification-firs
 
 Gates are blocking in MEDIUM, informational in MICRO/SMALL.
 
-### How agents load SDD
-For concrete spec/workflow work, the active agent checks for `aioson-spec-driven` in `.aioson/installed-skills/` or `.aioson/skills/process/` and loads only its role-specific reference file (e.g., `references/dev.md`, `references/qa.md`). A bare `@deyvin` activation is not spec work: follow Deyvin's activation-only fast path and do not open this skill.
+### How agents load SDD
+For concrete spec/workflow work, the active agent checks for `aioson-spec-driven` in `.aioson/installed-skills/` or `.aioson/skills/process/` and loads only its role-specific reference file (e.g., `references/dev.md`, `references/qa.md`). A bare `@deyvin` activation is not spec work: follow Deyvin's activation-only fast path and do not open this skill.
 
 ### Project pulse convention
 Every agent updates `project-pulse.md` at session end with: last_agent, last_gate, active features, blockers, and next recommended action. This enables crash recovery — any agent can read project-pulse.md and know where to resume.
@@ -179,9 +181,9 @@ Located at: `.aioson/skills/process/aioson-spec-driven/SKILL.md`
 
 This is a first-party process skill. It teaches agents how phases connect, when to apply which depth, and how to prepare clean handoffs.
 
-Agents that load it: @product, @analyst, @scope-check, @architect, @sheldon, @dev, @deyvin, @qa, @tester, @orchestrator, @pm
-When to load: at the start of concrete spec work (PRD, requirements, architecture, implementation, testing); not during `@deyvin` activation-only recovery
-What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
+Agents that load it: @product, @analyst, @scope-check, @architect, @sheldon, @dev, @deyvin, @qa, @tester, @orchestrator, @pm
+When to load: at the start of concrete spec work (PRD, requirements, architecture, implementation, testing); not during `@deyvin` activation-only recovery
+What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
 
 ## Process skill: design-hybrid-forge
 
@@ -225,8 +227,8 @@ researchs/
 Primary recurring writers here: @product, @sheldon, and @squad
 All agents may read from here to avoid redundant searches.
 
-## Session protocol
-Do not read `.aioson/context/spec.md` globally at session start. Agents load `spec*.md` only when `context:select`, their SDD reference, or a concrete task selects it; update it at session end only if the active agent loaded and changed that spec context.
+## Session protocol
+Do not read `.aioson/context/spec.md` globally at session start. Agents load `spec*.md` only when `context:select`, their SDD reference, or a concrete task selects it; update it at session end only if the active agent loaded and changed that spec context.
 
 ## Golden rule
 Small project, small solution.

package/template/CLAUDE.md

@@ -2,12 +2,12 @@
 
 You operate as AIOSON.
 
-## Mandatory first action
-1. Check whether `.aioson/context/project.context.md` exists
-   - If missing: run `/setup`
-   - If present: read it before any action
-2. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details.
-3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
+## Mandatory first action
+1. Check whether `.aioson/context/project.context.md` exists
+   - If missing: run `/setup`
+   - If present: read it before any action
+2. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details.
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
 
 ## Project knowledge
 
@@ -78,14 +78,15 @@ Capture is best-effort — do not crash, retry, or surface failures to the user.
 - /design-hybrid-forge -> `.aioson/agents/design-hybrid-forge.md`
 - /site-forge -> `.aioson/agents/site-forge.md`
 - /discover -> `.aioson/agents/discover.md`
+- /forge-run -> `.aioson/agents/forge-run.md`
 
 ## Spec-Driven Development framework
 
 AIOSON follows a Spec-Driven Development (SDD) methodology. Key governance files:
 
-- **`.aioson/constitution.md`** — 6 governing principles all agents must respect
-- **`.aioson/context/project-pulse.md`** — global project state; read at session start, update at session end
-- **`.aioson/skills/process/aioson-spec-driven/SKILL.md`** — process methodology; agents load this on demand for concrete spec/workflow work. `/deyvin` activation-only recovery must not load it.
+- **`.aioson/constitution.md`** — 6 governing principles all agents must respect
+- **`.aioson/context/project-pulse.md`** — global project state; read at session start, update at session end
+- **`.aioson/skills/process/aioson-spec-driven/SKILL.md`** — process methodology; agents load this on demand for concrete spec/workflow work. `/deyvin` activation-only recovery must not load it.
 
 The process depth scales with project classification:
 - **MICRO** (0-1): lightweight — @product → @dev

package/template/OPENCODE.md

@@ -1,31 +1,31 @@
 # AIOSON - OpenCode
 
-## Boot
-1. Check `.aioson/context/project.context.md`
-2. If present, read it before any action
-3. If missing, start with `setup`
-4. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details
-
-## No agent selected
-
-After boot, if the user started the chat without naming an agent and has not given a concrete task yet, do not start implementation or workflow routing. First offer these starting lanes:
-
-- Simple Plan with `dev` for bounded technical work, small fixes, refactors, or directly verifiable implementation.
-- Pair programming with `deyvin` for continuity, debugging together, or a small validated slice with known context.
-- Briefing with `briefing` to frame and evaluate an early feature idea before committing to a PRD.
-- Product with `product` to start a full feature definition when the user already wants to build a product/feature.
-
-## Project knowledge
-
-Read `.aioson/learnings/INDEX.md` if it exists. Each line is a project gotcha or recipe with its file path and a one-line summary. Lazy-load individual files only when title/scope matches your current task or files being touched.
-
-## Available agents
+## Boot
+1. Check `.aioson/context/project.context.md`
+2. If present, read it before any action
+3. If missing, start with `setup`
+4. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details
+
+## No agent selected
+
+After boot, if the user started the chat without naming an agent and has not given a concrete task yet, do not start implementation or workflow routing. First offer these starting lanes:
+
+- Simple Plan with `dev` for bounded technical work, small fixes, refactors, or directly verifiable implementation.
+- Pair programming with `deyvin` for continuity, debugging together, or a small validated slice with known context.
+- Briefing with `briefing` to frame and evaluate an early feature idea before committing to a PRD.
+- Product with `product` to start a full feature definition when the user already wants to build a product/feature.
+
+## Project knowledge
+
+Read `.aioson/learnings/INDEX.md` if it exists. Each line is a project gotcha or recipe with its file path and a one-line summary. Lazy-load individual files only when title/scope matches your current task or files being touched.
+
+## Available agents
 - setup -> `.aioson/agents/setup.md`
 - discovery-design-doc -> `.aioson/agents/discovery-design-doc.md`
 - discover -> `.aioson/agents/discover.md`
-- analyst -> `.aioson/agents/analyst.md`
-- scope-check -> `.aioson/agents/scope-check.md`
-- architect -> `.aioson/agents/architect.md`
+- analyst -> `.aioson/agents/analyst.md`
+- scope-check -> `.aioson/agents/scope-check.md`
+- architect -> `.aioson/agents/architect.md`
 - ux-ui (UI/UX) -> `.aioson/agents/ux-ui.md`
 - product -> `.aioson/agents/product.md`
 - sheldon -> `.aioson/agents/sheldon.md`
@@ -45,6 +45,7 @@ Read `.aioson/learnings/INDEX.md` if it exists. Each line is a project gotcha or
 - orache -> `.aioson/agents/orache.md`
 - design-hybrid-forge -> `.aioson/agents/design-hybrid-forge.md`
 - site-forge -> `.aioson/agents/site-forge.md`
+- forge-run -> `.aioson/agents/forge-run.md`
 
 ## Rule
 Do not duplicate rules outside `.aioson/`.