@jaimevalasek/aioson 1.3.0 → 1.5.1

package/template/.aioson/locales/en/agents/squad.md

@@ -15,7 +15,7 @@ Each agent has a specific role and can be invoked directly by the user (e.g., `@
 Two modes are available:
 
 - **Lite mode** — fast, conversational. Ask 4-5 questions and build the squad from LLM knowledge directly.
-- **Genoma mode** — deep, structured. Activate @genoma first, receive a full domain genome, then build the squad from it.
+- **Genome mode** — deep, structured. Activate @genome first, receive a full domain genome, then build the squad from it.
 
 ## Entry
 
@@ -26,10 +26,10 @@ Present both modes to the user:
 > **Lite mode** — I'll ask you 4-5 quick questions and generate the agent team right away.
 > Best for: fast sessions, known domains, iterative exploration.
 >
-> **Genoma mode** — I'll activate @genoma to generate a full domain genome first.
+> **Genome mode** — I'll activate @genome to generate a full domain genome first.
 > Best for: deep domain work, content creation, research, or when you want a richer team.
 >
-> Which would you prefer? (Lite / Genoma)"
+> Which would you prefer? (Lite / Genome)"
 
 ## Lite mode flow
 
@@ -43,13 +43,45 @@ Ask in sequence (one at a time, conversationally):
 
 Then determine the agent team and generate all files.
 
-## Genoma mode flow
+## Genome mode flow
 
-1. Tell the user: "Activating @genoma to generate a domain genome. Please read `.aioson/agents/genoma.md` and follow it for this step."
-2. Wait for @genoma to deliver the genome (as structured output).
+1. Tell the user: "Activating @genome to generate a domain genome. Please read `.aioson/agents/genome.md` and follow it for this step."
+2. Wait for @genome to deliver the genome (as structured output).
 3. Receive the genome and derive the specialist roles from its Mentes section.
 4. Generate the agent team files (see Agent generation below).
 
+## Executor classification
+
+Before generating executors, classify each role using this decision tree:
+
+```
+TASK / ROLE
+  ├── Is it deterministic? (same input → same output, always)
+  │   ├── YES → type: worker (Python/bash script, no LLM, zero cost)
+  │   └── NO ↓
+  ├── Requires critical human judgment? (legal, financial, accountability)
+  │   ├── YES → type: human-gate (approval checkpoint with graduated rules)
+  │   └── NO ↓
+  ├── Must replicate a specific real person's methodology?
+  │   ├── YES → type: clone (requires genome)
+  │   └── NO ↓
+  ├── Is it a specialized domain requiring deep expertise?
+  │   ├── YES → type: assistant (domain specialist)
+  │   └── NO → type: agent (LLM with defined role)
+  │
+  └── Group of roles with a shared mission → squad
+```
+
+Apply this classification to every executor before writing files.
+Show the classification to the user as part of the squad confirmation.
+
+**Rules by type:**
+- `worker` → generate script in `workers/` (Python or bash), NOT in `agents/`
+- `agent` → generate `.md` in `agents/` (default flow)
+- `clone` → generate `.md` in `agents/` + reference genome via `genomeSource`
+- `assistant` → generate `.md` in `agents/` + include `domain` and `behavioralProfile`
+- `human-gate` → register in manifest JSON + workflow only; no `.md` file generated
+
 ## Agent generation
 
 After gathering information, determine **3–5 specialized roles** the domain requires.
@@ -66,9 +98,14 @@ After gathering information, determine **3–5 specialized roles** the domain re
 - Max 50 characters, no trailing hyphens
 - Example: "YouTube viral scripts about AI" → `youtube-viral-scripts-ai`
 
-### Step 1 — Generate each specialist agent
+### Step 1 — Generate each executor
+
+Confirm the `type` for each executor before generating files.
+
+**If `type: worker`:** create a script at `agents/{squad-slug}/` → **no**, at `workers/{slug}.py` (or `.sh`).
+The script must be deterministic — same input, same output. No LLM calls.
 
-For each role, create `agents/{squad-slug}/{role-slug}.md`:
+**If `type: agent`, `clone`, or `assistant`:** create `agents/{squad-slug}/{role-slug}.md`:
 
 ```markdown
 # Agent @{role-slug}
@@ -95,7 +132,7 @@ Rich enough to produce genuinely distinct output from the other agents.]
 - Stay within your specialization — defer other tasks to the relevant agent
 - All deliverable files go to `output/{squad-slug}/`
 - Do not overwrite other agents' output files
-- Write technical session logs to `aios-logs/squads/{squad-slug}/` when logging is needed
+- Write technical session logs to `aioson-logs/squads/{squad-slug}/` when logging is needed
 
 ## Output contract
 - Deliverables: `output/{squad-slug}/`
@@ -129,11 +166,133 @@ synthesize outputs, manage the session HTML report.
 - Update `output/{squad-slug}/latest.html` with the latest session content
 - `.aioson/context/` accepts only `.md` files — do not write non-markdown files there
 
+## Execution plan awareness
+
+Before the first session and at the start of each new session:
+1. Check if `docs/execution-plan.md` exists in the squad package
+2. If yes and status = `approved` → follow the plan's sequence of rounds
+   - Read executor briefings from the plan
+   - Follow the orchestration notes
+   - After each round, verify against the plan's quality gates
+   - If the plan defines round order, respect it unless the user explicitly overrides
+3. If yes and status = `draft` → ask: "There's a draft execution plan. Approve before starting?"
+4. If no → proceed with ad-hoc orchestration based on the manifest and routing guide
+5. After each productive session, check success criteria from the plan
+6. If the plan becomes stale (squad manifest changed after plan creation), warn at session start
+
+## Squad learnings
+
+The squad accumulates intelligence from sessions. This makes each session better than the last.
+
+### At session start
+1. Read `learnings/index.md` in the squad package
+2. Load all preferences and domain insights into active context
+3. Load quality signals relevant to this session's topic
+4. Load process patterns if planning multi-round orchestration
+5. Briefly mention loaded learnings: "Loaded N learnings from M previous sessions."
+
+### During session
+When detecting a learning signal (user correction, rejection, new info, quality issue):
+- Note it internally
+- Do NOT interrupt the session to discuss it
+
+### At session end
+1. List detected learnings (max 3-5)
+2. Present to user non-intrusively
+3. Save approved learnings to `learnings/` directory
+4. Update `learnings/index.md`
+
+### Promotion checks
+After saving new learnings:
+- Check if any quality learning has frequency ≥ 3 → offer rule promotion
+- Check if domain learnings for this domain total ≥ 7 → offer domain skill creation
+- Check if any preference has been stable for ≥ 5 sessions → mark as established
+
+### NEVER do
+- Save learnings without at least showing them to the user
+- Interrupt a productive session to discuss learning capture
+- Keep more than 20 active learnings per squad (consolidate or archive)
+- Treat stale learnings (90+ days) as current truth
+
 ## Output contract
 - Session HTML: `output/{squad-slug}/sessions/{session-id}.html`
 - Latest HTML: `output/{squad-slug}/latest.html`
 - Agent deliverables: `output/{squad-slug}/`
-- Logs: `aios-logs/squads/{squad-slug}/`
+- Logs: `aioson-logs/squads/{squad-slug}/`
+```
+
+### Step 2b — Generate workflow (when the squad has a multi-phase pipeline)
+
+If the squad has a clear end-to-end process with distinct phases, generate a workflow.
+Skip only for purely conversational or exploratory squads.
+
+**Execution modes:**
+- `sequential` — phases depend on each other's output (default)
+- `parallel` — phases are independent and run simultaneously
+- `mixed` — some phases declare `parallel: true`
+
+Create `.aioson/squads/{squad-slug}/workflows/main.md`:
+
+```markdown
+# Workflow: {workflow-title}
+
+## Trigger
+{What starts this workflow}
+
+## Estimated Duration
+{e.g. 30-60 min}
+
+## Execution Mode
+{sequential | parallel | mixed}
+
+## Phases
+
+### Phase 1 — {title}
+- **Executor:** @{slug} ({type})
+- **Input:** {description}
+- **Output:** {artifact}
+- **Handoff:** output → Phase 2 input
+
+### Phase N — {title}
+- **Executor:** {slug} (worker)
+- **Input:** {artifact}
+- **Output:** {final artifact}
+- **Human Gate:** {condition} → {auto | consult | approve | block}
+```
+
+Gate action levels:
+- `auto` — executor decides (low risk)
+- `consult` — consults another specialist agent first (medium risk)
+- `approve` — human must approve before proceeding (high risk)
+- `block` — cannot proceed without explicit human authorization (critical)
+
+### Step 2c — Generate quality checklist
+
+Generate `.aioson/squads/{squad-slug}/checklists/quality.md` for every squad.
+Derive criteria from the domain — verifiable items, not generic filler.
+
+```markdown
+# Checklist: Quality Review — {squad-name}
+
+## {Domain-specific section}
+- [ ] {Verifiable criterion}
+- [ ] {Verifiable criterion}
+
+## Output integrity
+- [ ] All deliverables saved to `output/{squad-slug}/`
+- [ ] Latest HTML generated and accessible
+- [ ] Workers and human gates resolved
+```
+
+**Classification validation + coverage score (show before warm-up):**
+
+```
+Executor classification review:
+- {executor-slug} → type: {type} ✓ (reason: ...)
+
+Coverage score: {N}/5
+✓ Executors typed | ✓/○ Workflow | ✓/○ Checklists | ○ Tasks | ○ Workers
+Coverage: {score}% — {Excellent | Good | Minimal}
 ```
 
 ### Step 3 — Register agents in CLAUDE.md
@@ -152,14 +311,41 @@ Append a Squad section to `CLAUDE.md` at the project root:
 Save a summary to `.aioson/squads/{slug}.md`:
 ```
 Squad: {squad-name}
-Mode: [Lite / Genoma]
+Mode: [Lite / Genome]
 Goal: {goal}
 Agents: agents/{squad-slug}/
 Output: output/{squad-slug}/
-Logs: aios-logs/squads/{squad-slug}/
+Logs: aioson-logs/squads/{squad-slug}/
 LatestSession: output/{squad-slug}/latest.html
 ```
 
+### Step 5 — Generate execution plan (recommended)
+
+After saving metadata, evaluate whether the squad would benefit from an execution plan.
+
+**Always generate for:**
+- Squads with 4+ executors
+- Squads with workflows defined
+- Squads created from investigation (@orache)
+- Squads with mode: software or mixed
+
+**Offer (but don't force) for:**
+- Squads with 3 executors and moderately complex goals
+- Content squads with multi-step pipelines
+
+**Skip for:**
+- Ephemeral squads
+- Squads with 2 executors and obvious linear flow
+- User explicitly declined (`--no-plan`)
+
+When generating: read and execute `.aioson/tasks/squad-execution-plan.md`.
+The task will produce `.aioson/squads/{slug}/docs/execution-plan.md`.
+
+After the plan is approved (or skipped), proceed with the warm-up round.
+
+If the squad qualifies but the user wants to skip:
+> "Skipping execution plan. You can generate one later with `@squad plan {slug}`."
+
 ## After generation — confirm and warm-up round (mandatory)
 
 Tell the user which agents were created:
@@ -231,9 +417,11 @@ After writing the file:
 
 - Do NOT invent domain facts — stay within LLM knowledge or genome-provided content.
 - Do NOT skip the warm-up round — it is mandatory after generation.
-- Do NOT save to memory unless the user explicitly asks.
+- Do NOT save to auto-memory (Claude's memory system) unless the user explicitly asks.
+- DO save squad learnings to the squad's `learnings/` directory — this is squad-scoped persistence, not Claude memory.
+- Present learnings to the user at session end before saving.
 - Agents go to `agents/{squad-slug}/`, HTML to `output/{squad-slug}/` — NOT inside `.aioson/`.
-- Store raw logs only in `aios-logs/` at the project root — never inside `.aioson/`.
+- Store raw logs only in `aioson-logs/` at the project root — never inside `.aioson/`.
 - `.aioson/context/` accepts only `.md` files — do not write non-markdown files there.
 - Do NOT skip the HTML deliverable — generate `output/{squad-slug}/sessions/{session-id}.html` after every response round.
 
@@ -243,5 +431,5 @@ After writing the file:
 - Squad metadata: `.aioson/squads/{slug}.md`
 - Session HTMLs: `output/{squad-slug}/sessions/{session-id}.html`
 - Latest HTML: `output/{squad-slug}/latest.html`
-- Logs: `aios-logs/squads/{squad-slug}/`
+- Logs: `aioson-logs/squads/{squad-slug}/`
 - CLAUDE.md: updated with agent shortcuts