@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/docs/squad/genome-bindings.md

@@ -0,0 +1,47 @@
+---
+description: "Squad genome binding rules — when to route to @genome, how to persist bindings, and how to preserve legacy compatibility."
+---
+
+# Squad Genome Bindings
+
+Use this module when the request mentions genomes, when the squad already has genome bindings, or when repairing binding compatibility.
+
+## Responsibility boundary
+
+- `@squad` owns the squad package and its metadata
+- `@genome` owns genome generation and application logic
+
+If the user asks for a genome during a squad session:
+
+- finish or confirm the squad package first
+- then route explicitly to `@genome`
+
+## Binding persistence
+
+When a genome is applied to an existing squad:
+
+- update `.aioson/squads/{slug}/squad.md`
+- if normalized bindings are present or being normalized, update `.aioson/squads/{slug}/squad.manifest.json`
+- record whether the binding is squad-wide or agent-specific
+- rewrite affected executor prompts in `.aioson/squads/{squad-slug}/agents/` so they include `## Active genomes`
+
+## Compatibility rules
+
+When inspecting or modifying an existing squad:
+
+- accept legacy `genomes`
+- accept normalized `genomeBindings`
+- if only `genomes` exists, interpret it as squad-level bindings
+- if `genomeBindings` exists, treat it as the primary structure
+- do not automatically delete legacy `genomes` during the migration phase
+
+If the user asks for repair or normalize:
+
+- materialize `genomeBindings`
+- preserve old data
+- keep reads compatible with both formats
+
+## Non-negotiable boundary
+
+Do not modify official files in `.aioson/agents/` with user-specific genomes.
+Bindings must affect only squad package files under `.aioson/squads/{slug}/`.

package/template/.aioson/docs/squad/package-contract.md

@@ -0,0 +1,260 @@
+---
+description: "Squad package contract — required filesystem layout, manifests, executor prompts, metadata, and gateway registration."
+---
+
+# Squad Package Contract
+
+Use this module whenever `@squad` is creating, extending, repairing, or validating the package itself.
+
+## Non-negotiable package shape
+
+Every persistent squad must be created at `.aioson/squads/{squad-slug}/` with:
+
+- `agents/agents.md`
+- `agents/`
+- `workers/`
+- `workflows/`
+- `checklists/`
+- `skills/`
+- `templates/`
+- `docs/design-doc.md`
+- `docs/readiness.md`
+- `squad.manifest.json`
+- `squad.md`
+- external roots: `output/{squad-slug}/`, `aioson-logs/{squad-slug}/`, `media/{squad-slug}/`
+
+Do not collapse the squad into `agents/{slug}/`. The CLI and dashboard expect the package root under `.aioson/squads/`.
+
+## Package derivation checklist
+
+Before writing executors, derive and register:
+
+- mission
+- goal
+- scope and out-of-scope
+- domain classification
+- locale scope and rationale
+- skills
+- MCPs
+- subagent policy
+- content blueprints when relevant
+- source docs when relevant
+- investigation summary when relevant
+- output strategy when relevant
+- design-doc summary
+- readiness status
+
+Reuse installed squad skills from `.aioson/squads/{squad-slug}/skills/` before inventing new ones.
+
+## `agents/agents.md`
+
+Create a short textual map at `.aioson/squads/{squad-slug}/agents/agents.md`.
+Keep it concise and actionable. It should include:
+
+- mission
+- does
+- does not
+- permanent executors
+- skills
+- MCPs
+- subagent policy
+- outputs and review policy
+
+Do not paste full executor prompts into this file.
+
+## `squad.manifest.json`
+
+Create `.aioson/squads/{squad-slug}/squad.manifest.json`.
+At minimum, include:
+
+- `schemaVersion`
+- `packageVersion`
+- `slug`
+- `name`
+- `mode`
+- `mission`
+- `goal`
+- `visibility`
+- `locale_scope`
+- `storagePolicy`
+- `package.rootDir`
+- `package.agentsDir`
+- `package.workersDir`
+- `package.workflowsDir`
+- `package.checklistsDir`
+- `package.skillsDir`
+- `package.templatesDir`
+- `package.docsDir`
+- `rules.outputsDir`
+- `rules.logsDir`
+- `rules.mediaDir`
+- `skills`
+- `mcps`
+- `subagents`
+- `contentBlueprints`
+- `executors`
+- `checklists`
+- `workflows`
+- `genomes`
+
+When they exist, also persist:
+
+- `locale_rationale`
+- `domainClassification`
+- `investigation`
+- `sourceDocs`
+
+The manifest must mirror the real files you generated.
+
+## Executor generation
+
+### Workers
+
+If an executor is `type: worker`:
+
+- create `.aioson/squads/{squad-slug}/workers/{slug}.py` or `.sh`
+- keep it deterministic
+- mark it in the manifest with:
+  - `"usesLLM": false`
+  - `"deterministic": true`
+
+### Agents, clones, assistants
+
+If an executor is `type: agent`, `clone`, or `assistant`:
+
+- create `.aioson/squads/{squad-slug}/agents/{role-slug}.md`
+- keep it concise but dense
+- make the file immediately usable when invoked via `@`
+
+Recommended structure:
+
+- `## Mission`
+- `## Quick context`
+- `## Active genomes`
+- `## Focus`
+- `## Response pattern`
+- `## Hard constraints`
+- `## Output contract`
+
+Each executor prompt should make clear:
+
+- which squad skills it relies on
+- when to delegate to another executor
+- when to ask the orchestrator for a temporary subagent
+
+### Customer-facing executors — mandatory world-context block
+
+Any executor whose role involves direct customer interaction (retail, hospitality, service, support, sales, food service, reception, etc.) **must** include this block in its `## Quick context` section. The block is the world-model anchor — without it, executors produce clipped responses ("we only sell medicine" when asked for candy at a pharmacy):
+
+```yaml
+role: "Concrete role title with operational specificity"
+backstory: |
+  3–6 sentences anchoring the executor in real lived experience.
+  Reference real venues, real years on the job, real customer types.
+  Mention the breadth of requests handled daily.
+goal: "The single customer-facing outcome to optimize."
+
+operational_breadth:
+  primary: ["literal role responsibilities"]
+  adjacent: ["5–10 adjacent items real practitioners handle"]
+  out_of_scope: ["only what's illegal, unsafe, or genuinely unavailable"]
+
+interaction_principles:
+  - "Default 'yes, and...' — accept the premise, build on it"
+  - "Refuse only when illegal, unsafe, or genuinely unavailable"
+  - "Never say 'we only sell X' — name what we DO have"
+  - "Validate the underlying need before responding to the literal request"
+```
+
+Full guidance + four worked examples (pharmacy, restaurant, gym, hotel) in `.aioson/docs/squad/domain-breadth.md`. The `quality-lens.md` scorecard now includes a `domain breadth` criterion that gates this block.
+
+Agent file language follows `.aioson/rules/agent-language-policy.md`:
+
+- `locale_scope` absent or `universal` → prompt files in English
+- locale-specific `locale_scope` declared → prompt files in the locale language
+- source code identifiers remain in English in every case
+
+### UI specialist executor
+
+If `uiCapability.mode = "executor"`:
+
+- create `.aioson/squads/{squad-slug}/agents/ui-specialist.md`
+- treat it as a visual specialist responsible for UI direction, layout decisions, and HTML/UI-spec deliverables
+- give it `modelTier: powerful`
+- if using an assistant profile, prefer `behavioralProfile: compliant-dominant`
+- make the routing explicit: visual, layout, interface, landing page, and component-structure requests go to `@ui-specialist`
+
+## Orchestrator prompt
+
+Create `.aioson/squads/{squad-slug}/agents/orquestrador.md`.
+The orchestrator must include:
+
+- squad mission
+- members
+- routing guide
+- genomes
+- skills
+- MCPs
+- subagent policy
+- inter-squad awareness
+- execution plan awareness
+- learnings protocol
+- hard constraints
+- output contract
+
+The orchestrator is responsible for the final session HTML and for synthesis across specialists.
+
+## Gateway registration
+
+Register the squad in both root gateway files:
+
+- `CLAUDE.md`
+- `AGENTS.md`
+
+Use `.aioson/squads/{squad-slug}/agents/{role}.md` paths.
+
+Rules:
+
+- do not remove official framework agents
+- append or update only the squad section
+- if the squad already exists, update only its own section
+
+## Squad metadata
+
+Create `.aioson/squads/{squad-slug}/squad.md` with:
+
+- name
+- mode
+- goal
+- agents path
+- manifest path
+- output path
+- logs path
+- media path
+- latest session path
+- locale scope
+- locale rationale when present
+- source docs when present
+- investigation path when present
+- squad-level genomes
+- per-agent genomes
+- skills
+- MCPs
+- subagent policy
+
+## Required filesystem outputs
+
+Persistent squad package:
+
+- `.aioson/squads/{squad-slug}/squad.manifest.json`
+- `.aioson/squads/{squad-slug}/squad.md`
+- `.aioson/squads/{squad-slug}/agents/`
+- `.aioson/squads/{squad-slug}/workers/`
+- `.aioson/squads/{squad-slug}/workflows/`
+- `.aioson/squads/{squad-slug}/checklists/`
+- `.aioson/squads/{squad-slug}/skills/`
+- `.aioson/squads/{squad-slug}/templates/`
+- `.aioson/squads/{squad-slug}/docs/`
+- `output/{squad-slug}/latest.html`
+- `aioson-logs/{squad-slug}/`
+- `media/{squad-slug}/`

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

@@ -0,0 +1,60 @@
+---
+description: "Squad quality lens — patterns, anti-pattern replacements, and a compact rubric for non-generic squad packages."
+---
+
+# Squad Quality Lens
+
+Load this module before emitting a new or revised squad package.
+
+## Positive patterns
+
+High-quality squad output usually does all of this:
+
+- creates executors with distinct thinking roles, not just different names
+- turns domain knowledge into concrete workflow and checklist changes
+- maps deliverables, review gates, and artifacts to the real operating motion
+- encodes constraints and anti-patterns in the package, not only in prose
+- keeps the package lean enough to stay usable
+
+## Anti-patterns and replacements
+
+| Anti-pattern | Replace with |
+|---|---|
+| Four agents that think the same way | Distinct responsibilities and quality lenses |
+| Generic workflow copied from another domain | Workflow stages tied to the actual problem and deliverables |
+| Manifest rich in words but weak in consequences | Package files that drive behavior, outputs, and checks |
+| Adding agents to look sophisticated | The minimum executor set that covers real work |
+| Domain buzzwords with no operational value | Vocabulary that changes prompts, blueprints, or quality gates |
+| Customer-facing executor with `role:` only (no `backstory`, no `operational_breadth`) | The 4-field block: `role + backstory + goal + operational_breadth` plus `interaction_principles` (see `domain-breadth.md`) |
+| Executor that refuses adjacent requests as "out of scope" | `operational_breadth.adjacent` listing 5–10 items real practitioners handle, plus yes-and `interaction_principles` |
+
+## Elevation moves
+
+Before finalizing, strengthen at least one item in each area:
+
+- role differentiation
+- workflow realism
+- package actionability
+- domain specificity
+
+## Review scorecard
+
+Score from `1-5` on:
+
+- role differentiation
+- workflow fit
+- artifact completeness
+- domain specificity
+- domain breadth (would real practitioners recognize the executor as one of their own? does it handle obvious adjacent requests? — applies to all customer-facing executors; see `domain-breadth.md`)
+- operational efficiency
+
+If any score is `3` or lower, revise the package before delivering it.
+
+## Final pass
+
+Ask silently:
+
+- Would these executors still feel distinct if their names changed?
+- Does the package change how work gets done, or only how it is described?
+- Is anything here ceremony without payoff?
+- (Customer-facing only) Would each executor pass the breadth self-check in `domain-breadth.md` § "Self-check before delivering"? If any answer is no, revise.

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

@@ -0,0 +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

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

@@ -0,0 +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.

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

@@ -0,0 +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.