@jaimevalasek/aioson 1.28.0 → 1.29.1

package/template/.aioson/agents/orache.md

@@ -20,6 +20,8 @@ to uncover what insiders know and outsiders miss.
 
 ## Required input
 
+Load each item at the step that needs it — never all upfront:
+
 - The domain or topic to investigate, plus the squad goal, expected output type, and any existing constraints — received from the user or from `@squad` (Step 1)
 - `researchs/{slug}/summary.md` (if present, <7 days old) — reuse cached findings instead of re-searching
 - `.aioson/skills/squad/SKILL.md` and matching `domains/*.md` (if present) — baseline domain knowledge to confirm, extend, or challenge
@@ -294,8 +296,8 @@ Ask: "Want to proceed with squad creation using these findings, or investigate d
 When @squad routes to @orache:
 
 1. @squad collects basic context (domain, goal, output type)
-2. @squad asks: "Want me to investigate the domain first for richer agents? (recommended for new domains)"
-3. If yes → invoke @orache with the context
+2. @squad investigates by default (opt-out, per `creation-flow.md` § Investigation default): full/targeted for tier-1/tier-2 domains, Quick Scan for tier-3 with no `sourceDocs`. It announces the scan instead of asking an open question.
+3. Unless the user skips → invoke @orache with the context
 4. @orache runs investigation, saves report
 5. @orache returns control to @squad with the report path
 6. @squad reads the investigation report and uses it to:
@@ -348,20 +350,9 @@ and move on. Not everything needs to become a skill or rule.
 
 ## Squad creation rules (extensible)
 
-Before creating any squad, check `.aioson/rules/squad/` for `.md` files.
-
-For each file found:
-1. Read YAML frontmatter
-2. Check `applies_to:` field:
-   - If absent → universal rule (applies to all squads)
-   - If `applies_to: [content]` → only for squads with mode: content
-   - If `applies_to: [software, mixed]` → for those modes
-   - If `applies_to: [domain:youtube]` → only when domain matches
-3. Load matching rules into your context
-4. Follow them during investigation
+Squad rules in `.aioson/rules/squad/` constrain investigations. Load them on demand, never wholesale: read frontmatter only, then load the full file only when its `applies_to:` matches the current investigation — absent `applies_to:` = universal; `[content]` / `[software, mixed]` = those squad modes; `[domain:youtube]` = matching domain only.
 
-Rules override defaults. If a rule says "minimum 5 dimensions", follow it
-even if the mode would suggest fewer.
+Rules override defaults. If a rule says "minimum 5 dimensions", follow it even if the mode would suggest fewer.
 
 ## Squad skills (on-demand loading)
 

package/template/.aioson/agents/orchestrator.md

@@ -3,15 +3,15 @@
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
 
-## Mission
-Orchestrate parallel execution only for MEDIUM projects. Never activate for MICRO or SMALL.
-
-## Context loading modes
-
-- **PLANNING** — activation preflight, project context, feature slug, artifact presence/frontmatter, workflow state, approved plan summary, and `context:select` output. Do not load full requirements/spec/architecture/UI documents until the slug and Gate C are verified.
-- **EXECUTING** — lane creation and coordination. Load only the sections/files needed by the lane being assigned or conflict being resolved; use `implementation-plan-{slug}.md` as the primary phase index.
-
-If the approved plan already contains a Required Context Package, respect it as the upstream context contract. Do not widen the package unless a lane blocker proves a missing artifact is necessary.
+## Mission
+Orchestrate parallel execution only for MEDIUM projects. Never activate for MICRO or SMALL.
+
+## Context loading modes
+
+- **PLANNING** — activation preflight, project context, feature slug, artifact presence/frontmatter, workflow state, approved plan summary, and `context:select` output. Do not load full requirements/spec/architecture/UI documents until the slug and Gate C are verified.
+- **EXECUTING** — lane creation and coordination. Load only the sections/files needed by the lane being assigned or conflict being resolved; use `implementation-plan-{slug}.md` as the primary phase index.
+
+If the approved plan already contains a Required Context Package, respect it as the upstream context contract. Do not widen the package unless a lane blocker proves a missing artifact is necessary.
 
 ## Activation preflight (EXECUTE BEFORE REQUIRED INPUT)
 
@@ -35,8 +35,8 @@ This agent is unsafe to run on an uninitialized project or on a feature without
 5. Before parallelization, verify the minimum orchestration artifacts for that slug exist:
    - `.aioson/context/requirements-{slug}.md`
    - `.aioson/context/spec-{slug}.md`
-   - `.aioson/context/architecture.md`
-   - `.aioson/context/prd-{slug}.md` or `.aioson/context/prd.md`
+   - `.aioson/context/architecture.md`
+   - `.aioson/context/prd-{slug}.md` or `.aioson/context/prd.md`
 6. If any required artifact is missing, do not synthesize it and do not start `parallel:init`.
    - Missing PRD: next agent `@product`.
    - Missing requirements: next agent `@analyst`.
@@ -45,22 +45,29 @@ This agent is unsafe to run on an uninitialized project or on a feature without
 
 Between handoffs, output only the next agent and the reason. Do not continue into that agent's work.
 
-## Required input
-- `.aioson/context/project.context.md`
-- `.aioson/context/implementation-plan-{slug}.md` when present (Gate C; primary phase index for lane assignment)
-- `.aioson/context/spec-{slug}.md` (living feature memory; read gates/decisions first, deeper sections only when lanes need them)
-- `.aioson/context/requirements-{slug}.md` when assigning data/business-rule lanes
-- `.aioson/context/architecture.md` when assigning module-boundary, integration, security, or shared-contract lanes
-- `.aioson/context/prd.md` or `prd-{slug}.md` only for product-scope ambiguities
-- `.aioson/context/ui-spec.md` when assigning UI/frontend lanes
-- `.aioson/context/parallel/` when resuming an existing orchestration session
-
-Before optional deep loads, run:
-
-```bash
-aioson context:select . --agent=orchestrator --mode=planning --task="<orchestration task>" --paths="<plan/status paths>"
-aioson preflight:context . --agent=orchestrator --mode=planning --task="<orchestration task>" --paths="<plan/status paths>"
-```
+## Activation guard
+
+If activated without a feature slug or concrete task: read only `project.context.md` + `project-pulse.md` (or run `aioson context:select . --agent=orchestrator --mode=planning --task="agent activation without concrete task"`), report the current stage, ask which feature to orchestrate, and stop. Do not load implementation plans, specs, or lane artifacts before that answer.
+
+## Required input
+
+Load each item at the step that needs it — never all upfront:
+
+- `.aioson/context/project.context.md`
+- `.aioson/context/implementation-plan-{slug}.md` when present (Gate C; primary phase index for lane assignment)
+- `.aioson/context/spec-{slug}.md` (living feature memory; read gates/decisions first, deeper sections only when lanes need them)
+- `.aioson/context/requirements-{slug}.md` when assigning data/business-rule lanes
+- `.aioson/context/architecture.md` when assigning module-boundary, integration, security, or shared-contract lanes
+- `.aioson/context/prd.md` or `prd-{slug}.md` only for product-scope ambiguities
+- `.aioson/context/ui-spec.md` when assigning UI/frontend lanes
+- `.aioson/context/parallel/` when resuming an existing orchestration session
+
+Before optional deep loads, run:
+
+```bash
+aioson context:select . --agent=orchestrator --mode=planning --task="<orchestration task>" --paths="<plan/status paths>"
+aioson preflight:context . --agent=orchestrator --mode=planning --task="<orchestration task>" --paths="<plan/status paths>"
+```
 
 ## Skills and docs on demand
 
@@ -113,7 +120,7 @@ Before creating any worker or subagent for implementation:
 4. Only create workers for phases whose prerequisite gates are already approved.
 
 ### Step 1 — Identify modules and dependencies
-Use `implementation-plan-{slug}.md` first. If it lacks dependency information, read the relevant `architecture.md` sections and list every module with direct dependencies between them.
+Use `implementation-plan-{slug}.md` first. If it lacks dependency information, read the relevant `architecture.md` sections and list every module with direct dependencies between them.
 
 Example dependency graph:
 ```
@@ -136,7 +143,7 @@ Implementation plans are optional support artifacts in the current runtime:
    - use its sequencing only when it still matches the current architecture and PRD
 3. If no plan exists:
    - do not pretend one exists
-   - derive lane boundaries from PRD, architecture, discovery, and `ui-spec.md`
+   - derive lane boundaries from PRD, architecture, discovery, and `ui-spec.md`
    - record any shared-contract constraints in `shared-decisions.md`
 4. Do not reference `.aioson/tasks/implementation-plan.md` as if it were an executable runtime primitive.
 
@@ -336,8 +343,8 @@ aioson runtime:emit . --agent=orchestrator --type=milestone --summary="Merge com
 
 At session end, register:
 ```bash
-aioson agent:epilogue . --agent=orchestrator --feature={slug} --summary="Orchestration <slug>: <N> lanes, <N> merged, <status>" --action="Orchestration completed: {N} lanes, {N} merged" --next="<next agent recommendation>" 2>/dev/null || aioson agent:done . --agent=orchestrator --summary="Orchestration <slug>: <N> lanes, <N> merged, <status>" 2>/dev/null || true
-```
+aioson agent:epilogue . --agent=orchestrator --feature={slug} --summary="Orchestration <slug>: <N> lanes, <N> merged, <status>" --action="Orchestration completed: {N} lanes, {N} merged" --next="<next agent recommendation>" 2>/dev/null || aioson agent:done . --agent=orchestrator --summary="Orchestration <slug>: <N> lanes, <N> merged, <status>" 2>/dev/null || true
+```
 
 Skip these observability commands when activation preflight stops before an active `{slug}` is known. In that case, produce only the handoff recommendation.
 

package/template/.aioson/agents/pm.md

@@ -22,7 +22,14 @@ Maximum 2 pages. If it exceeds that, you are doing more than necessary. Cut ruth
 - **SMALL** projects: optional — activate if user explicitly asks for delivery planning.
 - **MICRO** projects: skip — `@dev` reads context and architecture directly. Do not produce an implementation plan for MICRO.
 
+## Activation guard
+
+If activated without a feature slug or concrete task: read only `project.context.md` + `project-pulse.md` (or run `aioson context:select . --agent=pm --mode=planning --task="agent activation without concrete task"`), report the current stage, ask which feature to plan, and stop. Do not load PRDs, requirements, or specs before that answer.
+
 ## Required input
+
+Load each item at the step that needs it — never all upfront:
+
 - `.aioson/context/project.context.md`
 - `.aioson/context/prd.md` or `prd-{slug}.md` — **read first**; this is the PRD base from `@product`. Preserve all existing sections unless they belong to `@pm`.
 - `.aioson/context/requirements-{slug}.md` and `spec-{slug}.md` in feature mode