@jaimevalasek/aioson 1.28.1 → 1.30.0

package/template/.aioson/skills/process/sheldon-expansion-audit/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sheldon-expansion-audit
+description: "Sheldon process skill for auditing a PRD against prior feature expansion artifacts and expected product richness. Use in @sheldon when expansion-scout.md or scope-expansion.md exists, or when a PRD for a rich-surface feature looks too thin, too inflated, or lacks acceptance criteria for enriched capabilities."
+---
+
+# Sheldon Expansion Audit
+
+Use this skill to judge whether product expansion was handled well. Sheldon should not be the primary dreamer; it should protect the PRD from being too poor or too large.
+
+## Load
+
+Read `.aioson/docs/feature-expansion-taxonomy.md`.
+
+Read available inputs:
+
+- target `prd-{slug}.md`
+- `.aioson/briefings/{slug}/expansion-scout.md`
+- `.aioson/context/features/{slug}/scope-expansion.md`
+- prior `.aioson/context/features/{slug}/expansion-audit.md`
+
+If no prior expansion artifact exists, perform only a lightweight inferred expansion and label it clearly.
+
+## Output
+
+Write `.aioson/context/features/{slug}/expansion-audit.md`.
+
+Use this structure:
+
+```md
+# Expansion Audit - {Feature}
+
+## Inputs
+- PRD:
+- Prior expansion artifacts found:
+- Audit mode: prior-artifact / inferred-lightweight
+
+## Findings
+| Severity | Finding | Evidence | Recommendation |
+|---|---|---|---|
+
+## Too Thin Check
+- Missing Core/Recommended MVP items:
+- Missing user states/actions:
+- Missing acceptance criteria:
+
+## Too Large Check
+- V2 items pulled into MVP:
+- Optional items without approval:
+- Classification/timeline risk:
+
+## PRD Patch Recommendations
+- Add:
+- Move to V2:
+- Ask user:
+
+## Sheldon Decision
+Proceed / enrich PRD first / return to product for decision.
+```
+
+## Rules
+
+- Prefer evidence from prior expansion artifacts over inventing new ideas.
+- Flag when a rich-surface PRD has only generic fields or thin CRUD.
+- Flag when V2 ideas entered MVP without explicit rationale.
+- Convert accepted expansion items into acceptance-criteria gaps.
+- Do not rewrite Product-owned Vision, Problem, or Users.
+

package/template/.aioson/skills/static/context-budget-guide.md

@@ -11,7 +11,7 @@ Since agents cannot directly measure token count, use file-count proxy:
 | 1-3 | Light (< 20%) | Proceed normally |
 | 4-6 | Moderate (20-40%) | Be selective about additional reads |
 | 7-9 | Heavy (40-60%) | Stop reading, start producing |
-| 10+ | Critical (> 60%) | Finish current step, recommend /clear |
+| 10+ | Critical (> 60%) | Finish current step, recommend /compact; reserve /clear for hard reset |
 
 ## File size estimates
 

package/template/.aioson/skills/static/multi-agent-patterns.md

@@ -28,10 +28,11 @@ When Evaluator finds issues:
 
 ### Session isolation
 
-Each role should run in a fresh context window:
-- Planner sessions: produce artifacts, then /clear
-- Generator sessions: read spec pack + implement, then /clear
-- Evaluator sessions: read code + spec + verify, then /clear
+Each role should run from a compact operational handoff:
+- Planner sessions: produce artifacts, then /compact for same-feature continuation
+- Generator sessions: read spec pack + implement, then /compact for same-feature continuation
+- Evaluator sessions: read code + spec + verify, then /compact for same-feature continuation
+- Use /clear only for a hard reset, feature switch, polluted context, or security-sensitive reset
 
 Cross-role communication happens through artifacts on disk, not conversation history.
 

package/template/.aioson/tasks/squad-create.md

@@ -123,6 +123,17 @@ For each executor in the blueprint, create `.aioson/squads/<slug>/agents/<execut
 - Before moving to the next executor, apply this test: would a real senior person in this role recognize themselves in this prompt? If not, deepen before continuing.
 - If `locale_scope` is locale-specific, write user-facing behavior examples in that locale's language; code identifiers remain English.
 
+### Step 5.5 - Genome Pass (bind or queue genomes)
+
+Load `.aioson/docs/squad/genome-bindings.md`. Then, for each executor whose blueprint entry plans a genome — and for every `assistant`/`clone` in a tier-1/tier-2 domain even when the blueprint is silent:
+
+1. Check `.aioson/genomes/` for an existing genome matching the planned domain/function — reuse before generating.
+2. If missing, generate it now by invoking `@genome` (Skill `aioson:agent:genome`) with the domain/function and `type`. `persona` genomes are never auto-generated — queue them for the Profiler pipeline instead.
+3. Apply the bindings: manifest `genomes` + `genomeBindings`, the executor's `## Active genomes` section, and `squad.md` (squad-level and per-agent genomes).
+4. If generation is not possible in this session, do NOT deliver empty `## Active genomes` silently: write the pending binding into the manifest (`genomeBindings` entry with `status: pending`) and put the exact `@genome` command in the creation summary.
+
+Skip this step only for tier-3 squads whose executors are all `worker` / plain `agent` types with no specialized expertise.
+
 ### Step 6 - Generate Orchestrator
 Create `.aioson/squads/<slug>/agents/orquestrador.md` following `.aioson/docs/squad/package-contract.md`, section `Orchestrator prompt`.
 If `uiCapability.mode = executor`, include routing guidance that visual demands go to `@ui-specialist`.

package/template/.aioson/tasks/squad-design.md

@@ -59,8 +59,8 @@ If the user already supplied enough context (text, docs, images), infer the answ
 Before defining executors, classify the domain using `.aioson/docs/squad/domain-classification.md`:
 
 - **Tier 1 — regulated:** investigation via `@squad investigate` / `@orache` is mandatory. Do not finalize the blueprint without a report.
-- **Tier 2 — specialized:** strongly recommend investigation. If the user refuses, record the limitation in `assumptions` and `risks`.
-- **Tier 3 — common:** proceed without unnecessary friction.
+- **Tier 2 — specialized:** run investigation by default (opt-out). If the user declines, record the limitation in `assumptions` and `risks`.
+- **Tier 3 — common:** with no `sourceDocs`, default to an `@orache` Quick Scan (announce it, let the user skip); proceed directly only when relevant sources or cached investigation already exist.
 
 If relevant investigation already exists, reuse the report instead of requesting a new one.
 
@@ -108,7 +108,7 @@ Group `workflows` into distinct work modes (originate / transform / judge / orch
 - `traces` — which `workflows`/`entities` this executor owns; an executor tracing no workflow is ceremony, so cut it
 - `confidence` (0-1) — how well sources justify this role; low = investigate or cut, never fill with padding
 - skills it will use
-- genomes it inherits
+- genomes it should inherit — record planned genomes (`type: domain|function`) for assistants/clones and specialized-domain agents; the create phase generates and binds them (`squad-create` Step 5.5)
 
 Always include an `orquestrador`. Keep 3-5 unless decomposition proves the real work requires more; do not inflate to look complete.
 

package/template/AGENTS.md

@@ -7,11 +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 — 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.
+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.
+## 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
 
@@ -103,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 `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 `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`, 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.
 - 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.
 
@@ -157,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
-- `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)
 
@@ -173,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 `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.
+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
 
@@ -195,16 +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.
-
-## 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)
 
@@ -228,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: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,11 +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 — 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.
+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.
+## 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
 
@@ -104,7 +108,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 `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`, 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 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.