@jaimevalasek/aioson 1.7.2 → 1.8.0

package/template/.aioson/docs/squad/content-output.md

@@ -0,0 +1,91 @@
+---
+description: "Squad content and output rules — content blueprints, output strategy, HTML deliverables, and dashboard-facing artifact structure."
+---
+
+# Squad Content And Output
+
+Use this module when the squad produces recurring content packages, structured outputs, or session HTML.
+
+## Content blueprints
+
+For content-heavy squads, define `contentBlueprints` in `squad.manifest.json`.
+They should describe:
+
+- `contentType`
+- `layoutType`
+- blueprint `sections`
+- the dynamic contract of recurring deliverables
+
+Do not hardcode domain-specific fields as framework-wide rules. The shell is fixed; the blueprint is domain-derived.
+
+## Preferred structured output layout
+
+When a deliverable is more than a one-off text file:
+
+- create a `content_key`
+- save under `output/{squad-slug}/{content-key}/`
+- prefer:
+  - `content.json`
+  - `index.html`
+
+Use this especially when the squad produces multiple sibling outputs in one package.
+
+## Output strategy
+
+If the domain suggests recurring data pipelines, webhooks, or storage-backed delivery:
+
+- load `.aioson/tasks/squad-output-config.md`
+- configure output explicitly
+
+For file-first squads such as reports, landing pages, or one-off artifacts:
+
+- default to `mode: "files"`
+
+## Installed skill reuse
+
+Before inventing output structures, inspect installed squad skills under:
+
+- `.aioson/squads/{squad-slug}/skills/`
+
+Reuse those skills if they already imply known output patterns or blueprints.
+
+## Session HTML deliverable
+
+After every productive response round, write:
+
+- `output/{squad-slug}/{session-id}.html`
+- update `output/{squad-slug}/latest.html`
+
+The HTML should capture the actual session work:
+
+- sober technical hero
+- one section per round
+- one rich block per specialist
+- one synthesis block per round
+- copy button per block
+- copy-all button in the header
+
+Stack:
+
+- Tailwind CSS CDN
+- Alpine.js CDN
+- no build step
+- no Google Fonts
+- no external images
+
+## Design direction for session HTML
+
+- dark, technical, premium
+- not neon dashboard
+- restrained accents
+- comfortable reading width
+- preserve rich content instead of flattening it into summaries
+
+## Output integrity
+
+Never:
+
+- overwrite another squad's output
+- write HTML under `.aioson/`
+- skip `latest.html`
+- reduce structured content to a single blob if the domain naturally wants sections

package/template/.aioson/docs/squad/creation-flow.md

@@ -0,0 +1,135 @@
+---
+description: "Squad creation flow — entry message, project artifact detection, intake questions, autonomy, discovery mini-package, and executor classification."
+---
+
+# Squad Creation Flow
+
+Use this module for new squad creation, blueprint derivation, and major extension work.
+
+## Entry message
+
+Do not begin with a Lite/Genome menu.
+Start direct squad creation with:
+
+> "I will assemble your specialized squad.
+>
+> Reply in a single block if you want:
+> 1. domain or theme
+> 2. main goal
+> 3. expected output type
+> 4. important constraints
+> 5. roles you want in the squad, or I can choose"
+
+If the user later wants genomes, route to `@genome`.
+
+## Project artifact detection
+
+Before asking follow-up questions, scan `.aioson/context/` for reusable upstream artifacts:
+
+- `implementation-plan-*.md`
+- `requirements-*.md`
+- `architecture.md`
+- `prd.md` or `prd-*.md`
+
+If one or more files are clearly relevant to the squad request:
+
+1. Read the implementation plan first when present.
+2. Extract domain, goal, expected outputs, constraints, expected behaviors, and done signals.
+3. Record the consumed file paths in blueprint `sourceDocs`.
+4. Do not ask again for information that is already explicit in those artifacts.
+
+If multiple artifacts exist but relevance is ambiguous, ask one short disambiguation question instead of ignoring them.
+
+## Intake
+
+Ask only for what is still missing after reading the project artifacts. Typical fields are:
+
+1. domain or theme
+2. main goal
+3. output type
+4. important constraints
+5. optional role hints
+
+The user may respond with text, large pasted context, images, or attachments.
+If attachments exist, use them before defining executors.
+
+## Autonomy rule
+
+- default to high autonomy
+- infer reasonable defaults before asking follow-up questions
+- ask additional questions only when the answer would materially change the squad
+- if the user says "keep going" or "just do it", reduce questions further and make assumptions explicit
+
+## Parallel squad rule
+
+- if the user asks for a new squad, create a new squad
+- do not silently reuse or merge an existing squad just because the domain looks similar
+- maintenance or refactor of an existing squad only happens when the user says so explicitly
+
+If the slug collides and the user clearly wants a new squad:
+
+- do not silently reuse the old one
+- propose a derived slug or ask which slug they prefer
+
+## Discovery mini-package
+
+Before generating files, establish:
+
+- current problem
+- practical goal
+- squad MVP boundary
+- out of scope
+- which docs and skills really need to be loaded now
+- which risks or ambiguities could still change the squad composition
+
+If readiness is low:
+
+- ask 1 to 3 short questions, or
+- proceed with explicit assumptions when the user requested autonomy
+
+## Executor classification
+
+Classify every executor with this tree:
+
+```text
+TASK / ROLE
+  ├── Deterministic? → worker
+  ├── Critical human judgment? → human-gate
+  ├── Replicates a real person's methodology? → clone
+  ├── Deep domain expertise? → assistant
+  └── Otherwise → agent
+```
+
+Show the classification review to the user before the warm-up round.
+
+## Assistant behavioral profiles
+
+When a role becomes `type: assistant`, assign one of:
+
+- `dominant-driver`
+- `influential-expressive`
+- `steady-amiable`
+- `compliant-analytical`
+- `dominant-influential`
+- `influential-steady`
+- `steady-compliant`
+- `compliant-dominant`
+
+The chosen profile must shape communication style and decision-making.
+
+## Executor count
+
+Prefer 3 to 5 specialized roles.
+Do not create extra executors just to look comprehensive.
+
+## Creation outcome
+
+By the end of creation, you should know:
+
+- the squad slug
+- the source artifacts that informed the design
+- the executor roster
+- which roles are workers vs agents vs assistants vs clones vs human gates
+- whether the squad is content-first, software-first, or mixed
+- whether workflows, review loops, and content blueprints are needed
+- whether the squad is universal or locale-specific

package/template/.aioson/docs/squad/domain-classification.md

@@ -0,0 +1,117 @@
+---
+description: "Squad domain classification — regulated vs specialized vs common domains, mandatory investigation policy, locale_scope decision, and persistence rules."
+---
+
+# Squad Domain Classification
+
+Use this module before approving a new squad blueprint or materially expanding an existing squad's domain.
+
+## Classification gate
+
+After the basic context is known, classify the domain before generating files or freezing the executor roster.
+
+### Tier 1 — Regulated domains
+
+Typical examples:
+
+- health and pharmacy
+- legal and compliance-heavy advisory
+- finance, investments, and insurance
+- food and nutrition with labeling or safety obligations
+- regulated education
+- cybersecurity with formal compliance scope
+- veterinary, agribusiness, engineering, construction, accounting, and tax
+
+Action:
+
+- investigation via `@orache` is mandatory
+- do not finalize the blueprint, workflow, or executor roster without the report
+- if the user refuses the investigation, explain that the squad cannot be safely generated yet and stop
+
+### Tier 2 — Specialized domains
+
+Typical examples:
+
+- niche gastronomy
+- specialized marketing
+- sports-specific training
+- music production and music theory
+- architecture and interior design
+- non-clinical psychology or coaching
+- specialized recruiting
+
+Action:
+
+- strongly recommend investigation
+- if the user declines, continue only after recording the limitation in `assumptions` and `risks`
+
+### Tier 3 — Common domains
+
+Typical examples:
+
+- general software delivery
+- general marketing
+- generic content creation
+- productivity and project management
+- broad business operations
+
+Action:
+
+- proceed directly
+- do not create unnecessary friction by forcing investigation
+
+## Ephemeral exception
+
+Ephemeral squads default to Tier 3 operationally and may skip blocking investigation unless the user explicitly asks for regulated-domain rigor.
+
+## Mandatory locale decision
+
+After tier classification, decide whether the squad is universal or locale-specific.
+
+If `.aioson/rules/agent-language-policy.md` is present, follow it as the source of truth.
+
+Ask:
+
+> "Should this squad be universal or locale-specific?
+>
+> 1. Universal — reusable across projects, agent files in English
+> 2. Locale-specific — optimized for one country/language, agent files follow that locale"
+
+Rules:
+
+- default to `universal` when no strong local constraint exists
+- if the domain is regulated in one country, suggest the locale that matches that jurisdiction
+- if the user chooses locale-specific, capture both `locale_scope` and `locale_rationale`
+
+## Integration with investigation
+
+When investigation exists, do not leave it as a detached report. Apply it:
+
+- domain vocabulary → executor mission, focus, and skill selection
+- regulations and obligations → hard constraints, human gates, and review criteria
+- anti-patterns → checklist items and `vetoConditions`
+- benchmarks → quality checklist and warm-up expectations
+- structural patterns → workflow phases and content blueprints
+
+## Persistence
+
+Write the following into the blueprint:
+
+```json
+{
+  "domainClassification": {
+    "tier": "tier-1-regulated",
+    "rationale": "Why this classification applies",
+    "regulations": ["ANVISA", "LGPD"],
+    "investigationPolicy": "required"
+  },
+  "locale_scope": "pt-BR",
+  "locale_rationale": "Brazil-only regulation and end users",
+  "investigation": {
+    "slug": "farmacia-regulada",
+    "path": "squad-searches/farmacia-regulada/investigation-20260414.md"
+  }
+}
+```
+
+Copy `domainClassification`, `locale_scope`, `locale_rationale`, `investigation`, and `sourceDocs` into the final manifest when they exist.

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,234 @@
+---
+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
+
+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,56 @@
+---
+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 |
+
+## 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
+- 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?