@jaimevalasek/aioson 1.23.1 → 1.28.0

package/template/.aioson/skills/process/aioson-spec-driven/references/deyvin.md

@@ -2,17 +2,21 @@
 
 > Router file. Do not duplicate logic from the generic references — load those directly.
 
-## Which references to load for continuation and resume flows
-
-### Always load when this skill is active
-
-- `maintenance-and-state.md` — @deyvin's primary job is resumption; use this to read `phase_gates`, `last_checkpoint`, and `pending_review` correctly before any action
-- `approval-gates.md` — use to check which gates are already approved before proceeding; never advance past a gate that is not yet passed
-
-### Load when the continuation context is unclear
-
-- `artifact-map.md` — use to quickly orient which artifacts exist and which are missing when resuming a session with incomplete context
-
+## Which references to load for continuation and resume flows
+
+### Activation-only sessions
+
+If the user only activates `@deyvin` without a concrete task, stop after the lightweight context summary from `context:select`. Do not load this reference's downstream files.
+
+### Load only for concrete continuation
+
+- `maintenance-and-state.md` — load when the concrete task requires reading or writing `spec*.md`, `last_checkpoint`, or `pending_review`
+- `approval-gates.md` — load when the next action could cross a phase gate, approve/deny readiness, or continue implementation past Gate C/D
+
+### Load when the continuation context is unclear
+
+- `artifact-map.md` — use to quickly orient which artifacts exist and which are missing after a concrete continuation task names a feature but the selected artifacts contradict each other
+
 ### Do not load for @deyvin
 
 - `hardening-lane.md` — by the time @deyvin is active, the spec pack should already be hardened
@@ -21,7 +25,7 @@
 
 ## Behavioral notes
 
-- `last_checkpoint` in `spec-{slug}.md` is the first thing @deyvin reads — see `maintenance-and-state.md` for format
-- Do not re-read the full spec pack unless `last_checkpoint` is null or contradictory
-- `phase_gates` from `approval-gates.md` defines what is locked — @deyvin does not re-open locked decisions
-- `pending_review` items must be surfaced to the user before proceeding past them
+- `last_checkpoint` in `spec-{slug}.md` is the first thing @deyvin reads only after a concrete continuation task selects that spec — see `maintenance-and-state.md` for format
+- Do not re-read the full spec pack unless `last_checkpoint` is null or contradictory
+- `phase_gates` from `approval-gates.md` defines what is locked — @deyvin does not re-open locked decisions
+- `pending_review` items must be surfaced to the user before proceeding past them

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

@@ -3,10 +3,10 @@
 You operate as AIOSON — an AI development squad with specialized agents.
 
 ## Mandatory first action
-1. Read `.aioson/config.md`
-2. Check whether `.aioson/context/project.context.md` exists
+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)
 
@@ -168,7 +170,7 @@ 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
-Each agent checks for `aioson-spec-driven` in `.aioson/installed-skills/` or `.aioson/skills/process/` and loads its role-specific reference file (e.g., `references/dev.md`, `references/qa.md`).
+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.
@@ -180,7 +182,7 @@ 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 any spec work (PRD, requirements, architecture, implementation, testing)
+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
@@ -226,7 +228,7 @@ Primary recurring writers here: @product, @sheldon, and @squad
 All agents may read from here to avoid redundant searches.
 
 ## Session protocol
-If `.aioson/context/spec.md` exists, read it at session start and update it at session end.
+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

@@ -3,10 +3,10 @@
 You operate as AIOSON.
 
 ## Mandatory first action
-1. Read `.aioson/config.md`
-2. Check whether `.aioson/context/project.context.md` exists
+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,6 +78,7 @@ 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
 
@@ -85,7 +86,7 @@ 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 automatically
+- **`.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,30 +1,31 @@
 # AIOSON - OpenCode
 
-## Boot
-1. Read `.aioson/config.md`
-2. Check `.aioson/context/project.context.md`
-3. If missing, start with `setup`
-
-## 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`
@@ -44,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/`.