@jaimevalasek/aioson 1.8.0 → 1.9.0

package/template/.aioson/docs/squad/research-loop.md

@@ -1,59 +1,59 @@
----
-description: "Squad research loop — extract short domain phrases, consult research cache, and use fresh findings to improve executors, workflows, and output quality."
----
-
-# Squad Research Loop
-
-Load this module before creating, extending, planning, repairing, or materially reworking a squad package.
-
-## Goal
-
-Prevent `@squad` from generating interchangeable squads. Use a small fresh-research pass to ground the package in current domain language, operating patterns, and quality expectations.
-
-## Mandatory keyword extraction
-
-Derive `3-7` short keyword phrases from the current squad ask, such as:
-
-- domain or niche name
-- deliverable type
-- workflow style
-- review or approval pattern
-- audience or buyer language
-- compliance or trust constraint
-- output medium or channel
-
-Keep phrases concrete and searchable. Favor `2-6` words.
-
-## Mandatory scouting pass
-
-1. Load `.aioson/skills/static/web-research-cache.md`
-2. Rank phrases by:
-   - chance of changing executor design
-   - chance of changing workflow or output structure
-   - freshness sensitivity
-3. Check `researchs/` first
-4. Search only the top `1-4` stale or missing phrases
-5. Save every result before using it
-
-At least one phrase must be validated through cache or fresh research whenever the squad serves an external domain, recurring workflow, content system, regulated environment, or specialized audience.
-
-For regulated domains, this lightweight loop does not replace mandatory `@orache` investigation.
-If an `investigation` report already exists, use it as the primary evidence source and run fresh scouting only to fill missing gaps.
-
-## How to use the findings
-
-Use research to improve:
-
-- executor vocabulary and mission boundaries
-- workflow stages and review loops
-- checklists and quality gates
-- anti-patterns that should become hard constraints
-- output blueprints and deliverable structure
-
-If the domain is broad, unfamiliar, or strategically important, use this lightweight loop first and then offer `@orache` for deeper investigation.
-
-## Output discipline
-
-- `researchs/` is a temporary shared evidence layer for reusable references
-- keep only the findings that materially change the squad package
-- do not let research inflate the squad with unnecessary executors or boilerplate
+---
+description: "Squad research loop — extract short domain phrases, consult research cache, and use fresh findings to improve executors, workflows, and output quality."
+---
+
+# Squad Research Loop
+
+Load this module before creating, extending, planning, repairing, or materially reworking a squad package.
+
+## Goal
+
+Prevent `@squad` from generating interchangeable squads. Use a small fresh-research pass to ground the package in current domain language, operating patterns, and quality expectations.
+
+## Mandatory keyword extraction
+
+Derive `3-7` short keyword phrases from the current squad ask, such as:
+
+- domain or niche name
+- deliverable type
+- workflow style
+- review or approval pattern
+- audience or buyer language
+- compliance or trust constraint
+- output medium or channel
+
+Keep phrases concrete and searchable. Favor `2-6` words.
+
+## Mandatory scouting pass
+
+1. Load `.aioson/skills/static/web-research-cache.md`
+2. Rank phrases by:
+   - chance of changing executor design
+   - chance of changing workflow or output structure
+   - freshness sensitivity
+3. Check `researchs/` first
+4. Search only the top `1-4` stale or missing phrases
+5. Save every result before using it
+
+At least one phrase must be validated through cache or fresh research whenever the squad serves an external domain, recurring workflow, content system, regulated environment, or specialized audience.
+
+For regulated domains, this lightweight loop does not replace mandatory `@orache` investigation.
+If an `investigation` report already exists, use it as the primary evidence source and run fresh scouting only to fill missing gaps.
+
+## How to use the findings
+
+Use research to improve:
+
+- executor vocabulary and mission boundaries
+- workflow stages and review loops
+- checklists and quality gates
+- anti-patterns that should become hard constraints
+- output blueprints and deliverable structure
+
+If the domain is broad, unfamiliar, or strategically important, use this lightweight loop first and then offer `@orache` for deeper investigation.
+
+## Output discipline
+
+- `researchs/` is a temporary shared evidence layer for reusable references
+- keep only the findings that materially change the squad package
+- do not let research inflate the squad with unnecessary executors or boilerplate

package/template/.aioson/docs/squad/session-operations.md

@@ -1,117 +1,117 @@
----
-description: "Squad session operations — ephemeral squads, investigation, inter-squad routing, learnings, dashboard guidance, and recurring tasks."
----
-
-# Squad Session Operations
-
-Use this module for ongoing orchestration and maintenance concerns around the squad.
-
-## Ephemeral squads
-
-Trigger on:
-
-- `@squad --ephemeral`
-- "quick squad"
-- "temporary squad"
-- "session-only squad"
-
-Rules:
-
-- set `"ephemeral": true` in the manifest
-- optionally set `"ttl": "24h"`
-- skip deep design-doc/readiness work
-- keep the package in `.aioson/squads/{slug}/`
-- keep output in `output/{slug}/`
-- do not register ephemeral squads in `CLAUDE.md` or `AGENTS.md`
-
-## Investigation via `@orache`
-
-Offer investigation when:
-
-- the domain is unfamiliar or specialized
-- the user did not provide deep context
-- the squad will be reused repeatedly
-- richer domain vocabulary and benchmarks would materially help
-
-If the domain-classification gate marked the domain as regulated, investigation is mandatory and blocks final squad generation.
-
-If investigation is accepted or required:
-
-1. invoke `@orache`
-2. read the `squad-searches/` report
-3. persist an `investigation` object in the blueprint and final manifest
-4. use it to refine executors, vocabulary, blueprints, quality checks, and anti-patterns
-5. translate regulations into hard constraints, human gates, or review criteria
-6. translate anti-patterns into checklist items and `vetoConditions`
-7. translate benchmarks into workflow quality bars and warm-up expectations
-
-If the report covers fewer than 4 of the 7 investigation dimensions, ask whether the user wants a deeper pass before finalizing the squad.
-
-## Inter-squad routing
-
-When multiple squads exist:
-
-1. scan `.aioson/squads/`
-2. read sibling `squad.md` files
-3. if a request belongs to a sibling squad, route explicitly
-4. if collaboration is required, coordinate a handoff instead of absorbing the work silently
-
-Never duplicate an existing squad's responsibility without an explicit user request.
-
-## Squad learnings
-
-At session start:
-
-- read `learnings/index.md` if present
-- load only the learnings relevant to the current topic
-
-During session:
-
-- capture corrections, rejections, and quality signals internally
-- do not interrupt productive work to discuss learning capture
-
-At session end:
-
-- list the main detected learnings
-- show them briefly to the user
-- save approved ones under `learnings/`
-- update `learnings/index.md`
-
-Promotion checks:
-
-- repeated quality learning → offer promotion to a rule
-- accumulated domain learnings → offer domain skill creation
-- stable preference over many sessions → mark established
-
-## Dashboard guidance
-
-If the user asks for a dashboard or panel:
-
-- explain that the dashboard app is installed separately from the CLI
-- do not assume a dashboard project exists in this repository
-- tell the user to open the installed dashboard app and select the project folder containing `.aioson/`
-
-## Session facilitation
-
-When the user brings a challenge:
-
-- present each relevant specialist in sequence
-- require concrete reasoning, tradeoffs, and next steps
-- synthesize convergences and tensions at the end
-- ask which specialist the user wants to push further
-
-If a specialist produces a final artifact:
-
-- save a draft `.md` in `output/{squad-slug}/`
-- then let the orchestrator fold it into the session HTML
-
-## Recurring tasks
-
-If the environment supports them and the use case is justified:
-
-- `CronCreate`
-- `CronList`
-- `CronDelete`
-
-Use cases include polling external APIs during research and scheduled health checks across executors.
-Always clean recurring tasks up before the session ends.
+---
+description: "Squad session operations — ephemeral squads, investigation, inter-squad routing, learnings, dashboard guidance, and recurring tasks."
+---
+
+# Squad Session Operations
+
+Use this module for ongoing orchestration and maintenance concerns around the squad.
+
+## Ephemeral squads
+
+Trigger on:
+
+- `@squad --ephemeral`
+- "quick squad"
+- "temporary squad"
+- "session-only squad"
+
+Rules:
+
+- set `"ephemeral": true` in the manifest
+- optionally set `"ttl": "24h"`
+- skip deep design-doc/readiness work
+- keep the package in `.aioson/squads/{slug}/`
+- keep output in `output/{slug}/`
+- do not register ephemeral squads in `CLAUDE.md` or `AGENTS.md`
+
+## Investigation via `@orache`
+
+Offer investigation when:
+
+- the domain is unfamiliar or specialized
+- the user did not provide deep context
+- the squad will be reused repeatedly
+- richer domain vocabulary and benchmarks would materially help
+
+If the domain-classification gate marked the domain as regulated, investigation is mandatory and blocks final squad generation.
+
+If investigation is accepted or required:
+
+1. invoke `@orache`
+2. read the `squad-searches/` report
+3. persist an `investigation` object in the blueprint and final manifest
+4. use it to refine executors, vocabulary, blueprints, quality checks, and anti-patterns
+5. translate regulations into hard constraints, human gates, or review criteria
+6. translate anti-patterns into checklist items and `vetoConditions`
+7. translate benchmarks into workflow quality bars and warm-up expectations
+
+If the report covers fewer than 4 of the 7 investigation dimensions, ask whether the user wants a deeper pass before finalizing the squad.
+
+## Inter-squad routing
+
+When multiple squads exist:
+
+1. scan `.aioson/squads/`
+2. read sibling `squad.md` files
+3. if a request belongs to a sibling squad, route explicitly
+4. if collaboration is required, coordinate a handoff instead of absorbing the work silently
+
+Never duplicate an existing squad's responsibility without an explicit user request.
+
+## Squad learnings
+
+At session start:
+
+- read `learnings/index.md` if present
+- load only the learnings relevant to the current topic
+
+During session:
+
+- capture corrections, rejections, and quality signals internally
+- do not interrupt productive work to discuss learning capture
+
+At session end:
+
+- list the main detected learnings
+- show them briefly to the user
+- save approved ones under `learnings/`
+- update `learnings/index.md`
+
+Promotion checks:
+
+- repeated quality learning → offer promotion to a rule
+- accumulated domain learnings → offer domain skill creation
+- stable preference over many sessions → mark established
+
+## Dashboard guidance
+
+If the user asks for a dashboard or panel:
+
+- explain that the dashboard app is installed separately from the CLI
+- do not assume a dashboard project exists in this repository
+- tell the user to open the installed dashboard app and select the project folder containing `.aioson/`
+
+## Session facilitation
+
+When the user brings a challenge:
+
+- present each relevant specialist in sequence
+- require concrete reasoning, tradeoffs, and next steps
+- synthesize convergences and tensions at the end
+- ask which specialist the user wants to push further
+
+If a specialist produces a final artifact:
+
+- save a draft `.md` in `output/{squad-slug}/`
+- then let the orchestrator fold it into the session HTML
+
+## Recurring tasks
+
+If the environment supports them and the use case is justified:
+
+- `CronCreate`
+- `CronList`
+- `CronDelete`
+
+Use cases include polling external APIs during research and scheduled health checks across executors.
+Always clean recurring tasks up before the session ends.

package/template/.aioson/docs/squad/workflow-quality.md

@@ -1,165 +1,165 @@
----
-description: "Squad workflow and quality rules — workflow generation, review loops, model tiering, plans, checklists, coverage score, and warm-up."
----
-
-# Squad Workflow And Quality
-
-Use this module whenever the squad has phases, quality gates, review loops, plans, or coverage scoring.
-
-## When to generate a workflow
-
-Generate `.aioson/squads/{squad-slug}/workflows/main.md` when:
-
-- the squad has 3 or more distinct phases
-- later phases depend on earlier outputs
-- deterministic workers mix with LLM executors
-- human approval points exist
-- the squad will run as a repeatable pipeline
-
-Skip only for purely conversational or exploratory squads.
-
-## Workflow registration
-
-Register the workflow in `squad.manifest.json` with:
-
-- `slug`
-- `title`
-- `trigger`
-- `executionMode`
-- `estimatedDuration`
-- `file`
-- `phases`
-
-Each phase should declare:
-
-- `id`
-- `title`
-- `executor`
-- `executorType`
-- `dependsOn`
-- `output`
-- optional `humanGate`
-- optional `review`
-- optional `vetoConditions`
-
-## Execution modes
-
-- `sequential`
-- `parallel`
-- `mixed`
-
-## Human gates
-
-Use `humanGate` when a phase requires explicit human approval or risk review.
-
-Action levels:
-
-- `auto`
-- `consult`
-- `approve`
-- `block`
-
-## Review loops
-
-Add review when:
-
-- the phase produces a final deliverable
-- the domain is high-risk
-- the pipeline is repeatable and quality drift matters
-
-Review should normally be done by an executor other than the creator.
-
-Include:
-
-- reviewer
-- criteria
-- `onReject`
-- `maxRetries`
-- `retryStrategy`
-- `escalateOnMaxRetries`
-
-Supported retry strategies:
-
-- `feedback`
-- `fresh`
-- `alternative`
-
-## Model tiering
-
-Assign `modelTier` to every executor:
-
-- `none` for deterministic workers
-- `powerful` for orchestration, synthesis, creative generation, or reviewer roles
-- `fast` for research, analysis at scale, or formatting-heavy work
-- `balanced` for mixed/default cases
-
-Show `modelTier` together with type classification in the confirmation output.
-
-## Task decomposition
-
-If an executor has a recurrent multi-step process:
-
-- keep identity in the main agent file
-- move procedure to `.aioson/squads/{squad-slug}/agents/{executor-slug}/tasks/`
-- register the tasks in the manifest
-
-## Quality checklists
-
-Always generate `.aioson/squads/{squad-slug}/checklists/quality.md`.
-
-The checklist must validate:
-
-- domain-specific output quality
-- output integrity
-- executor coverage
-- worker completion when present
-- human gate resolution when present
-
-Add phase-specific checklists if the workflow needs them.
-
-## Execution plan
-
-Generate `.aioson/squads/{squad-slug}/docs/execution-plan.md` when:
-
-- the squad has 4 or more executors
-- workflows are present
-- the squad came from investigation
-- the squad mode is `software` or `mixed`
-
-Offer but do not force for:
-
-- 3-executor squads with moderate complexity
-- content squads with multi-step pipelines
-
-Skip for:
-
-- ephemeral squads
-- tiny obvious linear flows
-- explicit user refusal
-
-## Confirmation, coverage, and warm-up
-
-After generation:
-
-1. list created executors
-2. show classification review
-3. show coverage score
-4. suggest `aioson squad:score . --squad={slug}`
-5. run the warm-up round immediately
-
-Coverage score dimensions:
-
-- executors typed
-- workflow defined
-- checklists present
-- tasks defined
-- workers present
-
-Warm-up output should show, for each specialist:
-
-- problem reading
-- initial recommendation
-- main risk or tension
-- next practical step
-
-Do not skip the warm-up round.
+---
+description: "Squad workflow and quality rules — workflow generation, review loops, model tiering, plans, checklists, coverage score, and warm-up."
+---
+
+# Squad Workflow And Quality
+
+Use this module whenever the squad has phases, quality gates, review loops, plans, or coverage scoring.
+
+## When to generate a workflow
+
+Generate `.aioson/squads/{squad-slug}/workflows/main.md` when:
+
+- the squad has 3 or more distinct phases
+- later phases depend on earlier outputs
+- deterministic workers mix with LLM executors
+- human approval points exist
+- the squad will run as a repeatable pipeline
+
+Skip only for purely conversational or exploratory squads.
+
+## Workflow registration
+
+Register the workflow in `squad.manifest.json` with:
+
+- `slug`
+- `title`
+- `trigger`
+- `executionMode`
+- `estimatedDuration`
+- `file`
+- `phases`
+
+Each phase should declare:
+
+- `id`
+- `title`
+- `executor`
+- `executorType`
+- `dependsOn`
+- `output`
+- optional `humanGate`
+- optional `review`
+- optional `vetoConditions`
+
+## Execution modes
+
+- `sequential`
+- `parallel`
+- `mixed`
+
+## Human gates
+
+Use `humanGate` when a phase requires explicit human approval or risk review.
+
+Action levels:
+
+- `auto`
+- `consult`
+- `approve`
+- `block`
+
+## Review loops
+
+Add review when:
+
+- the phase produces a final deliverable
+- the domain is high-risk
+- the pipeline is repeatable and quality drift matters
+
+Review should normally be done by an executor other than the creator.
+
+Include:
+
+- reviewer
+- criteria
+- `onReject`
+- `maxRetries`
+- `retryStrategy`
+- `escalateOnMaxRetries`
+
+Supported retry strategies:
+
+- `feedback`
+- `fresh`
+- `alternative`
+
+## Model tiering
+
+Assign `modelTier` to every executor:
+
+- `none` for deterministic workers
+- `powerful` for orchestration, synthesis, creative generation, or reviewer roles
+- `fast` for research, analysis at scale, or formatting-heavy work
+- `balanced` for mixed/default cases
+
+Show `modelTier` together with type classification in the confirmation output.
+
+## Task decomposition
+
+If an executor has a recurrent multi-step process:
+
+- keep identity in the main agent file
+- move procedure to `.aioson/squads/{squad-slug}/agents/{executor-slug}/tasks/`
+- register the tasks in the manifest
+
+## Quality checklists
+
+Always generate `.aioson/squads/{squad-slug}/checklists/quality.md`.
+
+The checklist must validate:
+
+- domain-specific output quality
+- output integrity
+- executor coverage
+- worker completion when present
+- human gate resolution when present
+
+Add phase-specific checklists if the workflow needs them.
+
+## Execution plan
+
+Generate `.aioson/squads/{squad-slug}/docs/execution-plan.md` when:
+
+- the squad has 4 or more executors
+- workflows are present
+- the squad came from investigation
+- the squad mode is `software` or `mixed`
+
+Offer but do not force for:
+
+- 3-executor squads with moderate complexity
+- content squads with multi-step pipelines
+
+Skip for:
+
+- ephemeral squads
+- tiny obvious linear flows
+- explicit user refusal
+
+## Confirmation, coverage, and warm-up
+
+After generation:
+
+1. list created executors
+2. show classification review
+3. show coverage score
+4. suggest `aioson squad:score . --squad={slug}`
+5. run the warm-up round immediately
+
+Coverage score dimensions:
+
+- executors typed
+- workflow defined
+- checklists present
+- tasks defined
+- workers present
+
+Warm-up output should show, for each specialist:
+
+- problem reading
+- initial recommendation
+- main risk or tension
+- next practical step
+
+Do not skip the warm-up round.