@jaimevalasek/aioson 1.33.1 → 1.37.0

package/template/AGENTS.md

@@ -7,15 +7,15 @@ You operate as AIOSON — an AI development squad with specialized agents.
    - 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 — concrete code/review agents use `context:brief` for precision selection, broad recall, and constraints. Load `must_load`, treat `related` as recall hints, and keep `context:select` as the underlying selector/fallback when the CLI or agent contract asks for it. Do not alarm if the directory is absent or empty.
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — concrete code/review agents use `context:brief` for precision selection, broad recall, and constraints. Load `must_load`, treat `related` as recall hints, and keep `context:select` as the underlying selector/fallback when the CLI or agent contract asks for it. Do not alarm if the directory is absent or empty.
 
-## 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.
-
-## Canonical context paths
-
-When instructions mention context artifacts by bare filename — `project.context.md`, `project-pulse.md`, `features.md`, `dev-state.md`, `workflow.state.json`, `last-handoff.json`, or `handoff-protocol.json` — resolve them to `.aioson/context/<filename>`. Never probe the project root or `.aioson/` root for these files.
+## 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.
+
+## Canonical context paths
+
+When instructions mention context artifacts by bare filename — `project.context.md`, `project-pulse.md`, `features.md`, `dev-state.md`, `workflow.state.json`, `last-handoff.json`, or `handoff-protocol.json` — resolve them to `.aioson/context/<filename>`. Never probe the project root or `.aioson/` root for these files.
 
 ## No agent selected
 
@@ -107,8 +107,8 @@ When running Codex directly (without `aioson workflow:next`), these rules apply:
 - For implementation requests (code changes, feature build, refactor, bugfix), default to workflow routing and execute via the next workflow stage agent (typically `@dev` after required upstream stages).
 - Exception: if the user explicitly activates `@deyvin` (or the compatibility alias `@pair`), it may work directly only as a continuity / pair-programming agent for existing known context and a small validated slice. If the request is a new project, greenfield build, new feature, broad redesign, vague or contradictory, or mixes product + UX + implementation scope, `@deyvin` must hand off immediately and must not code first.
 - Official workflow agents (`@setup`, `@product`, `@analyst`, `@scope-check`, `@architect`, `@ux-ui`, `@pm`, `@orchestrator`, `@dev`, `@qa`) must stay inside the workflow. Do not answer requests outside the current agent's scope.
-- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `.aioson/context/project.context.md`, the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping. That chain stops before the first `@dev` activation (the human clears context and starts implementation) and resumes through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their `@qa` triggers fire → `@validator`); it never auto-runs `feature:close`/publish — those require explicit human approval.
-- If `.aioson/context/project.context.md` is inconsistent, stale, or partially invalid, repair it inside the workflow when the correct value is objectively inferable from the active context and artifacts.
+- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `.aioson/context/project.context.md` (or a seeded `.aioson/context/workflow-execute.json` with `agentic_policy.enabled` is present), the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping. That chain runs the whole feature — the spec authority (`@sheldon`/`@orchestrator`) seeds the agentic scheme and crosses into `@dev` via the `dev-state.md` cold-start packet, `@dev` runs all phases in one continuous drive, and the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their `@qa` triggers fire → `@validator`) follows automatically. It stops only for a genuine human decision (product scope/sizing still open) and never auto-runs `feature:close`/publish — those require explicit human approval.
+- If `.aioson/context/project.context.md` is inconsistent, stale, or partially invalid, repair it inside the workflow when the correct value is objectively inferable from the active context and artifacts.
 - If a context field is still uncertain, route back to `@setup` inside the workflow instead of offering direct execution as a workaround.
 - Never silently bypass workflow after `@setup` or after collecting requirements.
 
@@ -161,7 +161,7 @@ AIOSON uses the `aioson-spec-driven` process skill to enforce specification-firs
 
 ### Core artifacts
 - `constitution.md` — governs all agents with 6 articles
-- `.aioson/context/project-pulse.md` — global heartbeat, max 30 lines, updated by every agent at session end
+- `.aioson/context/project-pulse.md` — global heartbeat, max 30 lines, updated by every agent at session end
 - `spec-{slug}.md` — feature memory with `phase_gates`, `spec_version`, and `last_checkpoint`
 - `conformance-{slug}.yaml` — machine-readable AC definitions (MEDIUM projects only)
 
@@ -177,7 +177,7 @@ Gates are blocking in MEDIUM, informational in MICRO/SMALL.
 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 `.aioson/context/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 `.aioson/context/project-pulse.md` and know where to resume.
+Every agent updates `.aioson/context/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 `.aioson/context/project-pulse.md` and know where to resume.
 
 ## Process skill: aioson-spec-driven
 
@@ -199,29 +199,29 @@ Activated by: @design-hybrid-forge
 Default output: `.aioson/installed-skills/{hybrid-name}/`
 What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
 
-## Process skill: prompt-sharpener
-
-Located at: `.aioson/skills/process/prompt-sharpener/SKILL.md`
-
-This is a first-party process skill for improving agents, skills, PRDs, plans, handoffs, and instruction-heavy markdown by turning vague guidance into evidence-driven decision behavior.
-
-Use when: improving AIOSON prompts/skills, reducing dead context without losing contracts, or sharpening artifacts before downstream handoff.
-What to load: `SKILL.md` first; load `references/prompt-diagnostics.md` only for multi-prompt audits or adoption planning.
-
-## Process skills: feature expansion
-
-Located at:
-- `.aioson/skills/process/briefing-expansion-scout/SKILL.md`
-- `.aioson/skills/process/product-scope-expansion/SKILL.md`
-- `.aioson/skills/process/sheldon-expansion-audit/SKILL.md`
-
-These are first-party process skills for richer feature thinking without uncontrolled MVP inflation.
-
-Agents that load them: @briefing, @briefing-refiner, @product, @sheldon
-When to load: only when the active idea/PRD has a rich surface, a prior expansion artifact exists, or the user asks for richer options.
-Shared taxonomy: `.aioson/docs/feature-expansion-taxonomy.md`
-
-## Shared research cache: researchs/
+## Process skill: prompt-sharpener
+
+Located at: `.aioson/skills/process/prompt-sharpener/SKILL.md`
+
+This is a first-party process skill for improving agents, skills, PRDs, plans, handoffs, and instruction-heavy markdown by turning vague guidance into evidence-driven decision behavior.
+
+Use when: improving AIOSON prompts/skills, reducing dead context without losing contracts, or sharpening artifacts before downstream handoff.
+What to load: `SKILL.md` first; load `references/prompt-diagnostics.md` only for multi-prompt audits or adoption planning.
+
+## Process skills: feature expansion
+
+Located at:
+- `.aioson/skills/process/briefing-expansion-scout/SKILL.md`
+- `.aioson/skills/process/product-scope-expansion/SKILL.md`
+- `.aioson/skills/process/sheldon-expansion-audit/SKILL.md`
+
+These are first-party process skills for richer feature thinking without uncontrolled MVP inflation.
+
+Agents that load them: @briefing, @briefing-refiner, @product, @sheldon
+When to load: only when the active idea/PRD has a rich surface, a prior expansion artifact exists, or the user asks for richer options.
+Shared taxonomy: `.aioson/docs/feature-expansion-taxonomy.md`
+
+## Shared research cache: researchs/
 
 Located at: `researchs/` (project root)
 
@@ -245,7 +245,7 @@ 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:brief`/`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.
+Do not read `.aioson/context/spec.md` globally at session start. Agents load `spec*.md` only when `context:brief`/`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

@@ -7,15 +7,15 @@ You operate as AIOSON.
    - 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 — concrete code/review agents use `context:brief` for precision selection, broad recall, and constraints. Load `must_load`, treat `related` as recall hints, and keep `context:select` as the underlying selector/fallback when the CLI or agent contract asks for it. Do not alarm if the directory is absent or empty.
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — concrete code/review agents use `context:brief` for precision selection, broad recall, and constraints. Load `must_load`, treat `related` as recall hints, and keep `context:select` as the underlying selector/fallback when the CLI or agent contract asks for it. Do not alarm if the directory is absent or empty.
 
-## 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.
-
-## Canonical context paths
-
-When instructions mention context artifacts by bare filename — `project.context.md`, `project-pulse.md`, `features.md`, `dev-state.md`, `workflow.state.json`, `last-handoff.json`, or `handoff-protocol.json` — resolve them to `.aioson/context/<filename>`. Never probe the project root or `.aioson/` root for these files.
+## 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.
+
+## Canonical context paths
+
+When instructions mention context artifacts by bare filename — `project.context.md`, `project-pulse.md`, `features.md`, `dev-state.md`, `workflow.state.json`, `last-handoff.json`, or `handoff-protocol.json` — resolve them to `.aioson/context/<filename>`. Never probe the project root or `.aioson/` root for these files.
 
 ## No agent selected
 
@@ -94,8 +94,12 @@ AIOSON follows a Spec-Driven Development (SDD) methodology. Key governance files
 
 The process depth scales with project classification:
 - **MICRO** (0-1): lightweight — @product → @dev
-- **SMALL** (2-3): standard — @product → @analyst → @scope-check(pre-dev) → @architect → @discovery-design-doc → @dev, with optional @scope-check(post-dev) before @qa when implementation drift is likely
-- **MEDIUM** (4-6): full — all agents, all gates, all artifacts
+- **SMALL** (2-3): lean by default — @product → @sheldon → @dev → @qa (@sheldon is the single spec authority)
+- **MEDIUM** (4-6): @orchestrator maestro — feature: @product → @orchestrator → @dev → @pentester → @qa; project: @setup → @product → @orchestrator → @dev → @qa. @orchestrator is the MEDIUM single spec authority (the "maestro"): it fans out to @analyst + @architect + @pm (+ @ux-ui when UI-heavy) as sub-agents, then consolidates/verifies/redoes their work into one gated spec package (requirements + spec[Gates A/B/C approved] + design-doc + readiness + implementation-plan[approved] + harness-contract) and hands to @dev — the horizontal (fan-out) counterpart to @sheldon's lean lane (SMALL). @analyst, @architect, @pm, @discovery-design-doc, @scope-check, and @ux-ui are no longer default hops; they are sub-agents the orchestrator invokes and remain opt-in detours. @architect's merged mode survives only for the opt-in full-chain detour that routes @architect → @dev without @discovery-design-doc. The deterministic drift check runs at the @dev/@qa done gate.
+
+**Lean lane (default for SMALL):** collapse the spec hops into @sheldon as the single spec authority — @product → @sheldon → @dev → @qa (@validator detour when a harness contract exists). Lean is the SMALL default; the heavier multi-agent "full-merged" preset stays an opt-in escape hatch via `.aioson/context/workflow.config.json`. See `.aioson/docs/workflow-lean-lane.md`.
+
+**Runtime smoke gate (all lanes):** a feature with a backend, a database, or a clickable prototype does not close until its build + migrations (applied to a real DB) + boot + Core happy-path run on the **real stack** — not just unit tests. Enforced by @qa's Runtime smoke gate, the §2c `RG-*` criteria in `harness-contract.json`, and @validator's contract-integrity precheck. Passing unit tests + `tsc` is the floor, not "done".
 
 Classification is determined by @analyst during discovery. See `aioson-spec-driven` skill for details.
 
@@ -108,7 +112,7 @@ When running Claude Code directly (without `aioson workflow:next`), these rules
 **Hard constraints — no exceptions:**
 - You MUST NEVER implement code, produce UI specs, write PRDs, or answer technical tasks outside an activated agent.
 - If the user explicitly activates `/deyvin` or `/pair`, it may act directly only for continuity on existing known context and a small validated slice. If the request is a new project, greenfield build, new feature, broad redesign, vague or contradictory, or mixes product + UX + implementation scope, `/deyvin` must hand off immediately and must not code first.
-- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `.aioson/context/project.context.md`, the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping. That chain stops before the first `@dev` activation (the human clears context and starts implementation) and resumes through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their `@qa` triggers fire → `@validator`); it never auto-runs `feature:close`/publish — those require explicit human approval.
+- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `.aioson/context/project.context.md` (or a seeded `.aioson/context/workflow-execute.json` with `agentic_policy.enabled` is present), the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping. That chain runs the whole feature — the spec authority (`@sheldon`/`@orchestrator`) seeds the agentic scheme and crosses into `@dev` via the `dev-state.md` cold-start packet, `@dev` runs all phases in one continuous drive, and the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their `@qa` triggers fire → `@validator`) follows automatically. It stops only for a genuine human decision (product scope/sizing still open) and never auto-runs `feature:close`/publish — those require explicit human approval.
 - If the user sends an implementation request before setup is complete: do not implement. Tell them to activate `/setup` first.
 - If the user insists on bypassing an agent stage: refuse and redirect. Urgency or complexity do not override this rule.