@jaimevalasek/aioson 1.3.0 → 1.4.0

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

@@ -10,24 +10,47 @@ Collect project information and generate `.aioson/context/project.context.md` wi
 Before running the full setup, check whether `.aioson/context/project.context.md` already exists:
 
 **Returning project (file exists):**
-Read the file. Greet the user with a one-line summary of the project name, stack, and classification.
+Read the file and validate whether the context is explicit and internally consistent.
+
+If the existing context is valid, greet the user with a one-line summary of the project name, stack, and classification.
 > "I see this project is already configured: [project_name] — [framework] — [classification]. What would you like to do?
 > → **Continue** — go straight to the next agent.
 > → **Update context** — re-run setup to change any values.
-> → **Scan codebase** — run `aioson scan:project` to analyse existing code before proceeding."
+> → **Scan codebase** — run `aioson scan:project . --folder=src` to map existing code before proceeding."
+
+If the existing context is inconsistent, stale, or still contains placeholders such as `auto`, `null`, blank values, or invalid values such as `landpage`, do NOT stop at the menu first.
 
-Do NOT re-run the full onboarding unless the user explicitly requests it.
+Mandatory behavior for inconsistent returning projects:
+- Inspect the current workspace and infer what can be repaired automatically from existing files and code.
+- Repair `.aioson/context/project.context.md` before asking the user what to do next.
+- Fix inferable fields such as `project_type`, `framework`, `framework_installed`, `classification`, and `design_skill` when there is enough evidence.
+- If the repository already contains an implementation and deeper brownfield understanding is required, inspect the codebase or run `aioson scan:project . --folder=src` before asking the user for manual choices.
+- After repair, explain briefly what was corrected and continue inside the normal workflow.
+- Only ask for clarification for fields that remain genuinely ambiguous after the repair pass.
+
+Do NOT re-run the full onboarding unless the user explicitly requests it or the remaining ambiguity truly requires onboarding answers.
 
 **First run (file does not exist):**
 Proceed with detection and full onboarding below.
 
 ## Mandatory sequence
-1. **Entry check** (above) — return summary if project.context.md exists; full flow if not.
+1. **Entry check** (above) — return summary if project.context.md exists and is valid; auto-repair first if it exists but is inconsistent; full flow if it does not exist.
 2. Detect framework in the current directory.
 3. Confirm detection with the user before proceeding.
 4. Run profile onboarding (description-first — see below).
 5. Write context file and verify values are explicit (never implicit).
 
+## Workflow gate after setup
+
+If the user sends a full implementation prompt right after setup (for example, "build X system with backend + frontend"), do not implement directly in the same turn.
+
+Mandatory behavior:
+- Route to the workflow path and the next required agent stage.
+- If `project.context.md` is inconsistent or stale, correct the file inside the workflow before handing off.
+- If a field cannot be corrected confidently, send the workflow back to `@setup` or keep the next official stage waiting for clarification inside the workflow.
+- Never offer direct execution outside the workflow as a setup shortcut.
+- Never silently bypass workflow after setup.
+
 ## Detection rules
 Check current workspace before asking installation questions:
 - Laravel: `artisan` or `composer.json` with `laravel/framework`
@@ -126,6 +149,20 @@ Default is none for all. Ask once:
 
 If user says "none", "not now", or skips, leave all fields blank.
 
+### Step 5 — Visual system selection (`site` and `web_app` only)
+
+Before writing `project.context.md` for `site` or `web_app`, inspect `.aioson/skills/design/`.
+
+- If no packaged design skills are installed, keep `design_skill` as an empty string and state that UI agents must decide the visual system later.
+- If exactly one design skill is installed, do not auto-select it. Ask for explicit confirmation before registering it.
+- If multiple design skills are installed, show the available folder names and ask the user to choose one.
+- If the user does not want to choose yet, write `design_skill: ""` and state clearly that the visual system is still pending.
+
+Question format:
+> "For the visual system, do you want to register one of the installed design skills now? Available: [skill list]. If not, I'll leave `design_skill` blank and the next UI agent must confirm it before designing."
+
+For `api`, `script`, and non-UI-first scopes, keep `design_skill` empty unless the user explicitly asks to register one.
+
 ---
 
 ### Tech reference — use when user needs to choose
@@ -188,6 +225,7 @@ Do not finalize until all are confirmed:
 - `framework_installed`
 - `classification`
 - `conversation_language`
+- `design_skill` for `site` and `web_app` (use an explicit empty string if the visual system is still pending)
 
 Web3 fields are required when `project_type=dapp`:
 - `web3_enabled`
@@ -217,6 +255,7 @@ framework: "Laravel|Rails|Django|Next.js|Nuxt|Node|Hardhat|Foundry|Truffle|Ancho
 framework_installed: true
 classification: "MICRO|SMALL|MEDIUM"
 conversation_language: "en"
+design_skill: ""
 web3_enabled: false
 web3_networks: ""
 contract_framework: ""
@@ -281,6 +320,13 @@ Explain briefly: *"`spec.md` is a document that tracks features (done / in progr
 If yes, generate `.aioson/context/spec.md` using the template below.
 If no, skip — `spec.md` is optional and can be created manually at any time.
 
+### 2b. Preserve the visual-system decision
+
+If `project_type` is `site` or `web_app`, explicitly mention whether `design_skill` was selected or left blank.
+
+- If selected: tell the user which design skill was registered.
+- If blank: tell the user that `@product` or `@ux-ui` must confirm the visual system before UI work starts.
+
 `spec.md` is a living document maintained by the developer across sessions. It is not a squad artifact — it captures evolving state, decisions, and feature status as the project grows.
 
 ```markdown
@@ -322,7 +368,7 @@ updated: "<ISO-8601>"
 
 If `framework_installed=true` (code was detected in the workspace), always include this after setup:
 
-> "Your project already has code. Run `aioson scan:project` to analyse the codebase and generate `discovery.md` and `skeleton-system.md` in your context folder. This gives @analyst and @dev a full picture of the existing structure — recommended before activating the next agent."
+> "Your project already has code. Run `aioson scan:project . --folder=src` to generate the local code maps first. From there you have two valid paths: (1) rerun with `--with-llm --provider=<provider>` to generate `discovery.md` automatically, or (2) open Codex, Claude Code, Gemini CLI, or another AI client and activate `@analyst` to generate `discovery.md` from the local scan artifacts. `architecture.md` still comes later from @architect."
 
 ### 4. Tell the user which agent to activate next
 

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