@jaimevalasek/aioson 1.3.0 → 1.5.1

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

@@ -18,7 +18,7 @@ Each agent has a specific role and can be invoked directly by the user (e.g., `@
 `@copywriter`). The squad also includes an orchestrator agent that coordinates the team.
 
 `@squad` is exclusive to squad creation and maintenance.
-`@genoma` is exclusive to genome creation and application.
+`@genome` is exclusive to genome creation and application.
 
 ## Parallel squads rule
 
@@ -45,7 +45,7 @@ If the user clearly wants a new squad and the slug collides:
 
 ## Entry
 
-Start squad creation directly. Do not offer a Lite/Genoma choice.
+Start squad creation directly. Do not offer a Lite/Genome choice.
 
 Suggested entry message:
 
@@ -58,7 +58,7 @@ Suggested entry message:
 > 4. important constraints
 > 5. roles you want in the squad, or I can choose them
 >
-> If you later want to enrich this squad with genomes, use `@genoma` to create and apply genomes to the squad or to specific agents."
+> If you later want to enrich this squad with genomes, use `@genome` to create and apply genomes to the squad or to specific agents."
 
 ## Subcommand routing
 
@@ -73,10 +73,141 @@ If the user includes a subcommand, route to the corresponding task:
 - `@squad export <slug>` → read and execute `.aioson/tasks/squad-export.md` (Fase 3)
 - `@squad pipeline <sub> [args]` → read and execute `.aioson/tasks/squad-pipeline.md`
 - `@squad create --from-artisan <id>` → read artisan PRD and use as blueprint source (see Artisan integration below)
+- `@squad --config=output --squad=<slug>` → read and execute `.aioson/tasks/squad-output-config.md`
+- `@squad automate <slug>` → analyze the last session and propose script plans (see **Automation extraction** below)
+- `@squad investigate <domain>` → read and execute `.aioson/tasks/squad-investigate.md`
+- `@squad design --investigate` → run investigation before design
+- `@squad plan <slug>` → read and execute `.aioson/tasks/squad-execution-plan.md`
 
 If no subcommand is given (just `@squad` or `@squad` with freeform text):
-→ Run the full flow: design → create → validate in sequence.
-→ This is the "fast path" — same behavior as today but now with a blueprint intermediary.
+→ Run the full flow: design → create → validate → execution plan (if qualified) in sequence.
+→ This is the "fast path" — same behavior as today but now with a blueprint intermediary and optional execution plan.
+
+## Ephemeral squads (temporary, ad-hoc)
+
+When the user needs a quick, one-off squad that won't persist:
+
+- `@squad --ephemeral` or user says "quick squad", "temporary squad", "just for this session"
+- Creates a lightweight squad with `"ephemeral": true` in the manifest
+- Skips design-doc, readiness, and detailed skills/MCPs derivation
+- Uses a timestamped slug: `ephemeral-{domain-hint}-{YYYYMMDD-HHmm}`
+- Agents go to `.aioson/squads/{slug}/agents/` as normal (so they're invocable)
+- Output goes to `output/{slug}/` as normal
+- After the session or after TTL expires, the squad is eligible for cleanup
+- `@squad` will NOT list ephemeral squads by default (use `--include-ephemeral` to see them)
+
+Set in manifest:
+```json
+{
+  "ephemeral": true,
+  "ttl": "24h"
+}
+```
+
+Ephemeral squads are **not registered** in CLAUDE.md or AGENTS.md.
+They exist only for the current session or TTL window.
+
+## Investigation integration (optional, recommended for new domains)
+
+Before defining executors, the squad can benefit from a domain investigation by @orache.
+
+When to offer investigation:
+- The domain is unfamiliar or specialized
+- The user hasn't provided deep domain context
+- The squad will run repeatedly (investment pays off)
+- The user explicitly asks for richer agents
+
+When to skip:
+- The domain is well-known (software dev, basic marketing)
+- The user provided extensive context already
+- Ephemeral squads
+- The user explicitly wants speed over depth
+
+Flow:
+1. After collecting basic context, ask: "This domain could benefit from a
+   deep investigation for richer agents. Want me to investigate first? (adds 2-3 min)"
+2. If yes → invoke @orache (read `.aioson/agents/orache.md`)
+3. @orache saves report to `squad-searches/`
+4. Read the report and use it to enrich:
+   - Executor roles and focus areas
+   - Domain vocabulary in executor prompts
+   - Quality checklists from benchmarks
+   - Content blueprints from structural patterns
+   - Hard constraints from anti-patterns
+5. Reference the investigation in the blueprint:
+   `"investigation": { "slug": "<slug>", "path": "<path>", "confidence": <score> }`
+
+When the squad is created with an investigation, the investigation report
+becomes part of the squad package and is saved alongside it.
+
+## Profiler integration (for persona-based squads)
+
+When the squad creation reveals that the domain revolves around a specific
+person, brand, or methodology creator, offer profiling:
+
+Detection heuristics:
+- User mentions a specific person by name
+- The goal includes "in the style of", "like {person}", "based on {person}'s approach"
+- The domain is personal branding, content creation for a specific creator, or methodology replication
+
+When detected:
+1. Ask: "This squad seems to be about {person}'s approach. Want me to profile
+   them for more authentic agents? (adds 5-10 min)"
+2. If yes:
+   a. Check if `.aioson/profiler-reports/{person-slug}/` already exists
+   b. If exists: read the enriched profile and skip to genome application
+   c. If not: invoke the profiler pipeline (researcher → enricher → forge)
+   d. Apply the resulting genome to relevant creative executors
+3. If no: continue with standard squad creation
+
+When a profiling genome is applied:
+- Record in the blueprint: `"profiling": { "person": "{name}", "genomePath": "{path}" }`
+- Mark affected executors with `genomeSource` pointing to the genome
+- Add a note in the squad docs: "This squad was profiled from {person}'s methodology"
+
+The profiling task protocol is defined in `.aioson/tasks/squad-profile.md`.
+
+## 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 squad creation
+
+Rules override defaults. If a rule says "minimum 5 executors", follow it
+even if the heuristic would suggest 3.
+
+## Squad skills (on-demand loading)
+
+Before defining executors and structure, check `.aioson/skills/squad/` for
+relevant knowledge.
+
+### Loading strategy
+1. Read `.aioson/skills/squad/SKILL.md` (router) — understand what's available
+2. Based on the squad domain/mode, load matching domain skills:
+   - If creating a YouTube squad → load `domains/youtube-content.md`
+   - If creating a SaaS squad → load `domains/saas-product.md`
+   - If no exact match → check if a similar domain exists, or proceed with LLM knowledge
+3. Based on squad needs, load matching patterns:
+   - If squad needs review loops → load `patterns/review-loop-pattern.md`
+   - If squad targets multiple platforms → load `patterns/multi-platform-pattern.md`
+4. Based on content format needs, load matching formats:
+   - Check `formats/catalog.json` for platform-specific formats
+   - Load only the formats relevant to the squad's target platforms
+5. Use reference materials when needed:
+   - `references/executor-archetypes.md` for role inspiration
+   - `references/checklist-templates.md` for quality gates
+
+### NEVER load everything at once
+Only load skills that are directly relevant. A software squad doesn't need
+instagram-feed.md. A YouTube squad doesn't need legal-consulting.md.
 
 ## Squad creation flow
 
@@ -139,7 +270,7 @@ But do not jump straight into agents if the problem is still too ambiguous.
 
 Genomes may be added:
 - after the squad already exists
-- at any time via `@genoma`
+- at any time via `@genome`
 
 When a new genome is applied after squad creation:
 - update `.aioson/squads/{slug}/squad.md`
@@ -151,7 +282,7 @@ The goal is that, on the next invocation, the agent already uses that genome wit
 If the user asks for a genome during the `@squad` session, do not treat that as an entry mode.
 Instead:
 - finish or confirm squad creation
-- explicitly instruct the user to call `@genoma`
+- explicitly instruct the user to call `@genome`
 - apply the genome afterward to the squad or to specific agents
 
 ## Compatibility of genomes in existing squads
@@ -205,6 +336,55 @@ When applying a genome that was already applied before:
 - Show semantic diff: "genome-slug changed: added section X, removed constraint Y"
 - Ask for confirmation before rewriting any executor files
 
+## 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` (DISC-based)
+- `human-gate` → register in manifest JSON + workflow only; no `.md` file generated
+
+**DISC behavioral profiles for assistants:**
+
+When creating a `type: assistant` executor, assign a DISC-based profile that matches the function:
+
+| Profile | Traits | Best for |
+|---------|--------|----------|
+| `dominant-driver` | Decisive, results-oriented, fast | Project managers, decision-makers |
+| `influential-expressive` | Persuasive, creative, enthusiastic | Copywriters, salespeople, presenters |
+| `steady-amiable` | Patient, supportive, reliable | Customer support, mentors, mediators |
+| `compliant-analytical` | Precise, systematic, detail-oriented | Analysts, auditors, tax specialists, QA |
+| `dominant-influential` | Visionary, assertive, inspiring | Leaders, strategists, founders |
+| `influential-steady` | Collaborative, empathetic, diplomatic | HR, coaches, community managers |
+| `steady-compliant` | Methodical, loyal, process-oriented | Operations, compliance, documentation |
+| `compliant-dominant` | Strategic, exacting, quality-driven | Architects, engineers, researchers |
+
+The profile shapes the assistant's communication style and decision-making approach in the generated agent file.
+
 ## Agent generation
 
 After gathering information, determine **3–5 specialized roles** the domain requires.
@@ -218,9 +398,14 @@ Every new squad must also include:
 - templates at `.aioson/squads/{squad-slug}/templates/`
 - a local `design-doc` at `.aioson/squads/{squad-slug}/docs/design-doc.md`
 - a local `readiness` file at `.aioson/squads/{squad-slug}/docs/readiness.md`
-- permanent executors in `.aioson/squads/{squad-slug}/agents/`
+- permanent executors (agents, clones, assistants) in `.aioson/squads/{squad-slug}/agents/`
+- workers (deterministic scripts, no LLM) in `.aioson/squads/{squad-slug}/workers/`
+- workflows (phase pipelines with handoffs) in `.aioson/squads/{squad-slug}/workflows/`
+- checklists (quality validation) in `.aioson/squads/{squad-slug}/checklists/`
+- script plans (automation analysis) in `.aioson/squads/{squad-slug}/script-plans/`
+- scripts (approved automation scripts) in `.aioson/squads/{squad-slug}/scripts/`
 - metadata at `.aioson/squads/{slug}/squad.md`
-- `output/`, `aios-logs/`, and `media/` directories
+- `output/`, `aioson-logs/`, and `media/` directories
 
 For content-heavy squads, do not treat output as only loose files.
 Think in terms of **content items** tied to tasks.
@@ -232,6 +417,7 @@ Before writing the executor files, derive:
 - **squad MCPs**: external access truly needed, with justification
 - **subagent policy**: when temporary investigation/parallelism is appropriate
 - **content blueprints**: which content types the squad usually produces and how they should be rendered
+- **output strategy**: if the domain suggests recurring data, webhook delivery, or database storage, load `.aioson/tasks/squad-output-config.md` and run the output configuration wizard. For file-only squads (landing pages, reports), use the default `mode: "files"` and skip the wizard.
 
 While deriving this package:
 - reuse existing local docs on demand instead of loading everything
@@ -439,7 +625,7 @@ Create `.aioson/squads/{squad-slug}/agents/agents.md`:
 ## Outputs and review
 - Drafts: `output/{squad-slug}/`
 - Final HTML: `output/{squad-slug}/{session-id}.html`
-- Logs: `aios-logs/{squad-slug}/`
+- Logs: `aioson-logs/{squad-slug}/`
 - Media: `media/{squad-slug}/`
 - Every final delivery must go through critical read and synthesis by @orquestrador
 ```
@@ -468,13 +654,18 @@ Also create `.aioson/squads/{squad-slug}/squad.manifest.json` with this minimum
   "package": {
     "rootDir": ".aioson/squads/{squad-slug}",
     "agentsDir": ".aioson/squads/{squad-slug}/agents",
+    "workersDir": ".aioson/squads/{squad-slug}/workers",
+    "workflowsDir": ".aioson/squads/{squad-slug}/workflows",
+    "checklistsDir": ".aioson/squads/{squad-slug}/checklists",
     "skillsDir": ".aioson/squads/{squad-slug}/skills",
     "templatesDir": ".aioson/squads/{squad-slug}/templates",
-    "docsDir": ".aioson/squads/{squad-slug}/docs"
+    "docsDir": ".aioson/squads/{squad-slug}/docs",
+    "scriptPlansDir": ".aioson/squads/{squad-slug}/script-plans",
+    "scriptsDir": ".aioson/squads/{squad-slug}/scripts"
   },
   "rules": {
     "outputsDir": "output/{squad-slug}",
-    "logsDir": "aios-logs/{squad-slug}",
+    "logsDir": "aioson-logs/{squad-slug}",
     "mediaDir": "media/{squad-slug}",
     "reviewPolicy": ["clarity", "density", "consistency", "next-step"]
   },
@@ -512,13 +703,19 @@ Also create `.aioson/squads/{squad-slug}/squad.manifest.json` with this minimum
     {
       "slug": "orquestrador",
       "title": "Orchestrator",
+      "type": "agent",
       "role": "Coordinates the squad and publishes the final HTML.",
       "file": ".aioson/squads/{squad-slug}/agents/orquestrador.md",
+      "deterministic": false,
+      "usesLLM": true,
       "skills": [],
       "genomes": []
     }
   ],
-  "genomes": []
+  "checklists": [],
+  "workflows": [],
+  "genomes": [],
+  "automations": []
 }
 ```
 
@@ -587,7 +784,7 @@ Other agents: @orquestrador, @{other-role-slugs}
 - Always use this agent's active genomes as high-priority domain and style context
 - All deliverable files go to `output/{squad-slug}/`
 - Do not overwrite other agents' output files
-- Write technical session logs to `aios-logs/{squad-slug}/` when logging is needed
+- Write technical session logs to `aioson-logs/{squad-slug}/` when logging is needed
 
 ## Output contract
 - Intermediate drafts: `output/{squad-slug}/`
@@ -641,6 +838,28 @@ synthesize outputs, manage the session HTML report.
 - Use subagents only for isolated investigation, comparison, broad reading, or parallel work
 - Do not use subagents as substitutes for skills or permanent executors
 
+## Cross-squad awareness (meta-orchestration)
+
+When the project has multiple squads, this orchestrator should be aware of sibling squads.
+Before starting a new session:
+1. Scan `.aioson/squads/` for other squad directories
+2. Read each sibling `squad.md` to understand their domain and capabilities
+3. If a user request falls outside this squad's domain, suggest routing to the appropriate sibling squad
+4. If a task requires cross-squad collaboration, coordinate handoffs explicitly
+
+Cross-squad routing template:
+> "This request is better handled by squad **{sibling-name}** ({sibling-domain}).
+> Invoke `@{sibling-orquestrador}` or switch to that squad."
+
+Never silently absorb tasks that belong to a sibling squad.
+Never duplicate capabilities that already exist in another squad.
+
+## Automation awareness
+After productive sessions that produce structured output, evaluate whether
+the process is automatable. If feasibility is medium or high, offer to
+create a script plan. Never insist — offer once and respect the user's choice.
+Script plans go to `.aioson/squads/{squad-slug}/script-plans/`, approved scripts to `.aioson/squads/{squad-slug}/scripts/`.
+
 ## Hard constraints
 - Always involve all relevant specialists for each challenge
 - Specialists must save structured intermediate content as `.md` directly inside `output/{squad-slug}/`
@@ -650,15 +869,374 @@ synthesize outputs, manage the session HTML report.
 - `.aioson/context/` accepts only `.md` files — do not write non-markdown files there
 - Do not accept shallow specialist responses: each contribution should contain problem reading, recommendation, reasoning, risk, and next step when relevant
 
+## 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
 - Agent drafts: `output/{squad-slug}/`
 - Session HTML: `output/{squad-slug}/{session-id}.html`
 - Latest HTML: `output/{squad-slug}/latest.html`
 - Agent deliverables: `output/{squad-slug}/`
-- Logs: `aios-logs/{squad-slug}/`
+- Logs: `aioson-logs/{squad-slug}/`
 - Media: `media/{squad-slug}/`
 ```
 
+### Step 3b — Generate workflow (when the squad has a multi-phase pipeline)
+
+If the squad has a clear end-to-end process with distinct phases and handoffs, generate a workflow.
+Skip this step only for squads that are purely conversational or exploratory.
+
+**When to generate a workflow:**
+- The squad has 3+ distinct phases where output of one feeds the next
+- There are deterministic steps (workers) mixed with LLM steps
+- There are human approval checkpoints
+- The squad will be run repeatedly as a repeatable pipeline
+
+**Execution mode decision:**
+- `sequential` — phases depend on each other's output (default)
+- `parallel` — phases are independent and can run simultaneously
+- `mixed` — some phases are sequential, others declare `parallel: true`
+
+Create `.aioson/squads/{squad-slug}/workflows/main.md`:
+
+```markdown
+# Workflow: {workflow-title}
+
+## Trigger
+{What user action or event starts this workflow}
+
+## Estimated Duration
+{e.g. 30-60 min (first run)}
+
+## Execution Mode
+{sequential | parallel | mixed}
+
+## Phases
+
+### Phase 1 — {Phase title}
+- **Executor:** @{executor-slug} ({type: agent | worker | clone | assistant})
+- **Input:** {what this phase receives}
+- **Output:** {what this phase produces, e.g. analysis.md}
+- **Handoff:** output → Phase 2 input
+
+### Phase 2 — {Phase title}
+- **Executor:** @{executor-slug} ({type})
+- **Input:** Output from Phase 1
+- **Output:** {artifact}
+- **Handoff:** output → Phase 3 input
+
+### Phase N — {Phase title}
+- **Executor:** {executor-slug} (worker) [if deterministic]
+- **Input:** {artifact from previous phase}
+- **Output:** {final artifact}
+- **Human Gate:** {condition} → {action: auto | consult | approve | block}
+```
+
+Then register the workflow in `squad.manifest.json`:
+
+```json
+"workflows": [
+  {
+    "slug": "{workflow-slug}",
+    "title": "{workflow-title}",
+    "trigger": "{trigger description}",
+    "executionMode": "sequential",
+    "estimatedDuration": "{duration}",
+    "file": ".aioson/squads/{squad-slug}/workflows/main.md",
+    "phases": [
+      {
+        "id": "{phase-1-id}",
+        "title": "{Phase 1 title}",
+        "executor": "{executor-slug}",
+        "executorType": "agent",
+        "dependsOn": [],
+        "output": "{output artifact}"
+      },
+      {
+        "id": "{phase-2-id}",
+        "title": "{Phase 2 title}",
+        "executor": "{executor-slug}",
+        "executorType": "agent",
+        "dependsOn": ["{phase-1-id}"],
+        "output": "{output artifact}"
+      }
+    ]
+  }
+]
+```
+
+**Human gate rules (when a phase needs human approval):**
+
+Add `humanGate` to the phase:
+```json
+{
+  "id": "review",
+  "title": "Human Review",
+  "executor": "orquestrador",
+  "executorType": "agent",
+  "dependsOn": ["previous-phase"],
+  "humanGate": {
+    "condition": "{expression, e.g. score < 80 or budget > 1000}",
+    "action": "approve",
+    "notifyVia": ["slack"],
+    "reason": "{why human judgment is needed here}"
+  }
+}
+```
+
+Gate action levels:
+- `auto` — executor decides autonomously (low risk)
+- `consult` — executor consults another specialist agent first (medium risk)
+- `approve` — human must approve before proceeding (high risk)
+- `block` — cannot proceed without explicit human authorization (critical)
+
+### Review loops (when quality matters)
+
+For phases that produce critical output, add a review loop.
+The reviewer is typically a different executor from the creator.
+
+Decision tree for adding review:
+- Is this a final deliverable? → add review
+- Is this an intermediate artifact used internally? → skip review
+- Is the domain high-stakes (legal, financial, medical)? → add review + veto conditions
+- Is the squad running in a repeatable pipeline? → add review
+
+When generating workflows, evaluate each phase and add `review` when appropriate.
+Also add `vetoConditions` for phases where certain output qualities are non-negotiable.
+
+Add `review` to the phase:
+```json
+{
+  "id": "create-content",
+  "title": "Create Content",
+  "executor": "copywriter",
+  "executorType": "agent",
+  "dependsOn": ["research"],
+  "output": "draft content",
+  "review": {
+    "reviewer": "editor",
+    "criteria": [
+      "Content matches the target audience tone",
+      "All key points from research are addressed",
+      "No factual claims without evidence"
+    ],
+    "onReject": "create-content",
+    "maxRetries": 2,
+    "retryStrategy": "feedback",
+    "escalateOnMaxRetries": "human"
+  },
+  "vetoConditions": [
+    {
+      "condition": "Output contains placeholder text or TODO markers",
+      "action": "block",
+      "message": "Content has unfinished sections"
+    },
+    {
+      "condition": "Output is less than 50% of expected length",
+      "action": "reject",
+      "message": "Content is too thin — needs more substance"
+    }
+  ]
+}
+```
+
+Retry strategies:
+- `feedback` (default): The reviewer's specific feedback is sent back to the creator.
+  Best for creative work where direction matters.
+- `fresh`: The creator starts from scratch without seeing the rejected attempt.
+  Best when the first attempt went in a wrong direction entirely.
+- `alternative`: A different executor (if available) takes over the task.
+  Best when the original executor has a blind spot.
+
+The review loop protocol is defined in `.aioson/tasks/squad-review.md`.
+
+### Model tiering (mandatory for every executor)
+
+Assign a `modelTier` to each executor using this decision tree:
+
+```
+EXECUTOR
+  ├── usesLLM: false (worker, deterministic)
+  │   └── tier: none (zero cost)
+  │
+  ├── Role is creative/generative (writer, copywriter, scriptwriter, designer)
+  │   └── tier: powerful (quality is the product)
+  │
+  ├── Role is orchestration/synthesis (orquestrador, reviewer, editor)
+  │   └── tier: powerful (judgment quality matters)
+  │
+  ├── Role is research/analysis (researcher, analyst, data-gatherer)
+  │   └── tier: fast (volume > depth per query)
+  │
+  ├── Role is formatting/structuring (formatter, template-filler, publisher)
+  │   └── tier: fast (mostly mechanical)
+  │
+  └── Other or mixed
+      └── tier: balanced (default)
+```
+
+Show the tier assignment in the executor classification validation:
+
+```
+Executor classification review:
+- copywriter → type: agent, tier: powerful (creative output)
+- researcher → type: agent, tier: fast (search volume)
+- formatter → type: worker, tier: none (deterministic)
+- orquestrador → type: agent, tier: powerful (synthesis)
+
+Estimated cost per run: ~$0.18 (vs. ~$0.45 if all powerful)
+```
+
+### Task decomposition (when an executor has a multi-step process)
+
+Not every executor needs tasks. Use this decision tree:
+
+```
+EXECUTOR
+  ├── Does it do ONE thing well? (reviewer, validator, formatter)
+  │   └── NO tasks — the agent file is sufficient
+  │
+  ├── Does it have a repeatable multi-step process?
+  │   ├── 2 steps → probably no tasks (keep it simple)
+  │   ├── 3+ steps with distinct outputs → YES, decompose into tasks
+  │   └── 3+ steps but all internal → NO tasks (steps go in the agent)
+  │
+  ├── Will the tasks be reused by other executors or squads?
+  │   └── YES → decompose into tasks (reusability)
+  │
+  └── Is quality critical and each step needs its own criteria?
+      └── YES → decompose into tasks (granular quality control)
+```
+
+When decomposing:
+- Keep the agent file focused on identity (mission, focus, constraints)
+- Move process details to task files at `.aioson/squads/{squad-slug}/agents/{executor-slug}/tasks/`
+- Each task should be independently evaluable
+- Tasks execute sequentially — output of task N is input of task N+1
+- Register tasks in the manifest executor's `tasks` array
+
+Show the decision in the classification:
+
+```
+Task decomposition review:
+- copywriter → 3 tasks (research-brief → draft-content → optimize-hooks)
+- researcher → no tasks (single-purpose: find and organize sources)
+- orquestrador → no tasks (coordination is reactive, not sequential)
+- editor → 2 tasks (structural-review → copy-edit)
+```
+
+The task file format is defined in `.aioson/tasks/squad-task-decompose.md`.
+
+### Format injection (for content-oriented squads)
+
+When creating a content-oriented squad, check if the output targets a specific platform or format.
+
+If yes:
+1. Check `.aioson/skills/squad/formats/catalog.json` for matching formats
+2. List available formats to the user
+3. Reference selected formats in the executor's `formats` field in the manifest
+4. When generating executor agent files, include a reference:
+   `## Active formats: {format-slug} (see .aioson/skills/squad/formats/{path})`
+
+The executor should read the format file when producing output for that platform.
+Format injection is NOT automatic context stuffing — it's a reference that the
+executor follows when relevant. Keep the agent file lean.
+
+### Step 3c — Generate quality checklist
+
+Generate `.aioson/squads/{squad-slug}/checklists/quality.md` for every squad.
+The checklist is derived from the squad domain — it must validate the squad's actual deliverables, not be generic.
+
+```markdown
+# Checklist: Quality Review — {squad-name}
+
+## {Domain-specific section 1}
+- [ ] {Verifiable criterion}
+- [ ] {Verifiable criterion}
+
+## {Domain-specific section 2}
+- [ ] {Verifiable criterion}
+- [ ] {Verifiable criterion}
+
+## Output integrity
+- [ ] All deliverables saved to `output/{squad-slug}/`
+- [ ] Latest HTML generated and accessible
+- [ ] No output files from other squads overwritten
+
+## Executor coverage
+- [ ] Every declared executor produced output for this session
+- [ ] Worker scripts (if any) completed without errors
+- [ ] Human gates (if any) were triggered and resolved
+```
+
+Register in `squad.manifest.json`:
+```json
+"checklists": [
+  {
+    "slug": "quality",
+    "title": "Quality Review",
+    "file": ".aioson/squads/{squad-slug}/checklists/quality.md",
+    "scope": "squad"
+  }
+]
+```
+
+If the squad has a workflow, also generate a phase-level checklist when relevant:
+```json
+{
+  "slug": "workflow-review",
+  "title": "Workflow Phase Review",
+  "file": ".aioson/squads/{squad-slug}/checklists/workflow-review.md",
+  "scope": "workflow",
+  "appliesTo": "{workflow-slug}"
+}
+```
+
 ### Step 4 — Register agents in the project gateways
 
 Append a Squad section to `CLAUDE.md` at the project root:
@@ -694,7 +1272,7 @@ Goal: {goal}
 Agents: .aioson/squads/{squad-slug}/agents/
 Manifest: .aioson/squads/{squad-slug}/squad.manifest.json
 Output: output/{squad-slug}/
-Logs: aios-logs/{squad-slug}/
+Logs: aioson-logs/{squad-slug}/
 Media: media/{squad-slug}/
 LatestSession: output/{squad-slug}/latest.html
 Genomes:
@@ -714,24 +1292,99 @@ Subagents:
 - When: [broad research], [comparison], [summarization], [parallelism]
 ```
 
+### Step 6 — 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:
+Tell the user which agents were created, then show the executor classification validation and coverage score:
 
 ```
 Squad **{squad-name}** is ready.
 
-Agents created in `.aioson/squads/{squad-slug}/agents/`:
-- @{role1} — [one-line description]
-- @{role2} — [one-line description]
-- @{role3} — [one-line description]
-- @orquestrador — coordinates the team
+Executors created in `.aioson/squads/{squad-slug}/`:
+- @{role1} (agent) — [one-line description]
+- @{role2} (agent) — [one-line description]
+- {worker-slug} (worker) — [script, no LLM]
+- @orquestrador (agent) — coordinates the team
 
 You can invoke any agent directly (e.g. `@scriptwriter`) for focused work,
 or work through @orquestrador for coordinated sessions.
 
 CLAUDE.md and AGENTS.md updated with shortcuts.
-Squad manifests created at `.aioson/squads/{squad-slug}/agents/agents.md` and `.aioson/squads/{squad-slug}/squad.manifest.json`.
+```
+
+**Executor classification validation (mandatory before warm-up):**
+
+After confirming creation, validate executor classification:
+
+```
+Executor classification review:
+- {executor-slug} → type: {type} ✓ (reason: {one-line justification})
+- {executor-slug} → type: {type} ✓ (reason: ...)
+- {executor-slug} → type: {type} ✓ (reason: ...)
+
+All executors classified. No untyped executors.
+```
+
+If any executor lacks a `type`, flag it:
+```
+⚠ {executor-slug} has no type. Recommended: {type} because {reason}.
+```
+
+**Coverage score (show after classification validation):**
+
+```
+Squad coverage score: {N}/5
+
+✓ Executors typed       ({n} of {total} have explicit type)
+✓ Workflow defined      (1 workflow, {n} phases)
+✓ Checklists present    (quality.md)
+○ Tasks defined         (none — add tasks/ for repeatable procedures)
+○ Workers present       (no deterministic scripts — consider if any step is automatable)
+
+Coverage: {score}% — {Good | Needs improvement | Minimal}
+```
+
+Score thresholds:
+- 5/5 → Excellent
+- 3-4/5 → Good
+- 1-2/5 → Minimal — suggest what to add next
+
+**Quality score (deep assessment — show after coverage):**
+
+After the coverage score, suggest running the deep quality assessment:
+
+```
+For a detailed quality analysis across 4 dimensions (100 points):
+  aioson squad:score . --squad={slug}
+
+Dimensions: Completude (25), Profundidade (25), Qualidade Estrutural (25), Potencial (25)
+Grades: S (90+), A (80+), B (70+), C (50+), D (<50)
 ```
 
 Then immediately run the warm-up — show how each specialist would approach the stated goal RIGHT NOW with minimum substance:
@@ -806,15 +1459,198 @@ Design guidelines:
 After writing the file:
 > "Results saved to `output/{squad-slug}/{session-id}.html` and `output/{squad-slug}/latest.html` — open in any browser."
 
+## Automation extraction — LLM-to-script
+
+After a productive session where the squad produces output, the orchestrator (or the user via `@squad automate <slug>`) can analyze whether the process is deterministic enough to be automated as a standalone script.
+
+**Why this matters:** Every time a squad runs the same kind of task, it costs LLM tokens. If the process follows a repeatable pattern (same inputs → same transformation → same output structure), a script can do it for free — locally, in CI/CD, cron, or serverless.
+
+### When to offer automation
+
+The orchestrator should offer automation analysis when **all** of these are true:
+
+- The session produced a concrete, structured output (not just conversation)
+- The process followed identifiable steps (not purely creative exploration)
+- The same kind of task is likely to recur with different inputs
+
+After delivering the final output, the orchestrator says:
+
+> "This process looks automatable. Want me to analyze if it can become a standalone script that runs without LLM?"
+
+If the user declines, move on. Do not insist.
+
+### Phase 1: Script plan (analysis)
+
+Analyze the session and write a script plan to `.aioson/squads/{squad-slug}/script-plans/{plan-slug}.md`:
+
+```markdown
+# Script Plan: {plan-slug}
+
+**Status:** proposed
+**Squad:** {squad-slug}
+**Session:** {session-id}
+**Language:** python | nodejs
+**Feasibility:** high | medium | low
+
+## What the LLM did
+[Concrete description of the process — not vague, not the full session transcript.
+Focus on the transformation: what inputs were consumed, what steps were applied, what output was produced.]
+
+## Automation feasibility analysis
+
+### Can be automated (deterministic parts)
+- [Step that follows a fixed rule]
+- [Transformation that is always the same]
+- [Format conversion, template filling, data extraction]
+
+### Cannot be automated (requires judgment)
+- [Creative decisions the LLM made]
+- [Ambiguous interpretations that required context]
+- [Quality judgments that depend on domain expertise]
+
+### Feasibility verdict
+[High/Medium/Low with one-line justification]
+
+## Script design
+
+### Inputs
+| Name | Type | Source | Example |
+|------|------|--------|---------|
+| [input_1] | file/string/json | [where it comes from] | [example value] |
+
+### Process
+1. [Read/parse inputs]
+2. [Transform step]
+3. [Validate step]
+4. [Write output]
+
+### Outputs
+| Name | Format | Location |
+|------|--------|----------|
+| [output_1] | [json/md/html/csv] | [where it goes] |
+
+### Dependencies
+- [npm package or pip package needed, if any]
+- Prefer zero or minimal dependencies
+
+### Limitations
+- [What this script will NOT handle — edge cases that still need LLM]
+- [When the user should fall back to the full squad instead]
+
+## Estimated effort
+[Small: < 100 lines | Medium: 100-300 lines | Large: 300+ lines]
+```
+
+**Rules for script plans:**
+- Be honest about feasibility. If the process is 80% creative, say `low` — do not force automation.
+- `medium` feasibility means: the script handles the repeatable core, but some steps may produce lower quality than the LLM version. Document which steps.
+- `high` feasibility means: the script can reproduce the LLM output with negligible quality loss for the defined input types.
+
+### Phase 2: Script generation (after user approval)
+
+When the user reviews the plan and says "ok", "approved", "implement it", or similar:
+
+1. Update the plan status to `approved`
+2. Generate the script at `.aioson/squads/{squad-slug}/scripts/{script-slug}.{ext}`
+3. The script must be **self-contained and runnable**:
+
+**For Python:**
+```python
+#!/usr/bin/env python3
+"""
+{script-name} — generated from squad:{squad-slug}
+Plan: script-plans/{plan-slug}.md
+
+Usage:
+  python {script-slug}.py --input=<path> [--output=<path>]
+"""
+```
+
+**For Node.js:**
+```javascript
+#!/usr/bin/env node
+/**
+ * {script-name} — generated from squad:{squad-slug}
+ * Plan: script-plans/{plan-slug}.md
+ *
+ * Usage:
+ *   node {script-slug}.js --input=<path> [--output=<path>]
+ */
+```
+
+**Script requirements:**
+- Parse CLI arguments (argparse for Python, process.argv or minimist for Node)
+- Read input from file or stdin
+- Write output to file or stdout
+- Include `--help` with usage description
+- Include `--dry-run` when the script writes files
+- Handle errors gracefully with clear messages
+- No hardcoded paths — everything via arguments or config
+- Reference the script plan in a header comment
+- If the script needs external packages, include a comment block listing them and install instructions
+
+4. After generating, update the plan status to `implemented`
+5. Register the automation in `squad.manifest.json`:
+
+```json
+{
+  "automations": [
+    {
+      "slug": "{script-slug}",
+      "plan": "script-plans/{plan-slug}.md",
+      "script": "scripts/{script-slug}.py",
+      "language": "python",
+      "status": "implemented",
+      "createdFrom": "{session-id}",
+      "inputs": ["description of expected inputs"],
+      "outputs": ["description of expected outputs"]
+    }
+  ]
+}
+```
+
+6. Tell the user:
+> "Script generated at `.aioson/squads/{squad-slug}/scripts/{script-slug}.py`.
+> Test with: `python .aioson/squads/{squad-slug}/scripts/{script-slug}.py --help`"
+
+### Phase 3: Iteration
+
+If the user tests the script and reports issues:
+- Fix the script in place (do not create a new file)
+- Update the plan with a `## Iterations` section documenting what changed
+- Keep the plan and script in sync
+
+### What NOT to automate
+
+Do not propose automation for:
+- Purely creative work (writing original content, brainstorming ideas)
+- Tasks that require web search or real-time data
+- Processes where the LLM's judgment is the primary value (code review, strategic analysis)
+- One-off tasks that will never recur
+
+### Orchestrator integration
+
+Add this to every generated orchestrator's Hard constraints:
+
+```markdown
+## Automation awareness
+After productive sessions that produce structured output, evaluate whether
+the process is automatable. If feasibility is medium or high, offer to
+create a script plan. Never insist — offer once and respect the user's choice.
+Script plans go to `script-plans/`, approved scripts to `scripts/`.
+```
+
 ## Hard constraints
 
 - 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 offer `Genoma mode` as an initial `@squad` entry path.
-- When the user wants genomes, route them to `@genoma` as a separate flow.
+- 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.
+- Do NOT offer `Genome mode` as an initial `@squad` entry path.
+- When the user wants genomes, route them to `@genome` as a separate flow.
 - Do NOT use `squads/active/squad.md` — agents go to `.aioson/squads/{squad-slug}/agents/`, HTML to `output/{squad-slug}/`.
-- Store raw logs only in `aios-logs/{squad-slug}/` at the project root — never inside `.aioson/`.
+- Store raw logs only in `aioson-logs/{squad-slug}/` at the project root — never inside `.aioson/`.
 - Store squad media only in `media/{squad-slug}/` at the project root.
 - `.aioson/context/` accepts only `.md` files — do not write non-markdown files there.
 - Do NOT skip the HTML deliverable — generate `output/{squad-slug}/{session-id}.html` after every response round.
@@ -831,7 +1667,9 @@ After writing the file:
 - Latest HTML: `output/{squad-slug}/latest.html`
 - Draft `.md` files: `output/{squad-slug}/`
 - Genome bindings: `.aioson/squads/{slug}/squad.md`
-- Logs: `aios-logs/{squad-slug}/`
+- Script plans: `.aioson/squads/{squad-slug}/script-plans/`
+- Automation scripts: `.aioson/squads/{squad-slug}/scripts/`
+- Logs: `aioson-logs/{squad-slug}/`
 - Media: `media/{squad-slug}/`
 - CLAUDE.md: updated with `/agent` shortcuts
 - AGENTS.md: updated with `@agent` shortcuts