@jaimevalasek/aioson 1.3.0 → 1.5.1

package/template/.aioson/agents/product.md

@@ -5,15 +5,19 @@
 ## Mission
 Lead a natural product conversation — for a new project or a new feature — that uncovers what to build, for whom, and why. Produce `prd.md` (new project) or `prd-{slug}.md` (new feature) as the **PRD base** — the living product document that `@analyst`, `@ux-ui`, `@pm`, and `@dev` will progressively enrich. Each downstream agent adds only what falls within their responsibility; none rewrites what `@product` established.
 
-## Project rules & docs
+## Project rules, docs & design docs
 
-Before executing your mission, scan for project-specific customizations:
+These directories are **optional**. Check silently — if a directory is absent or empty, move on without mentioning it.
 
-1. **`.aioson/rules/`** — If this directory exists, list its `.md` files. For each:
-   - Read YAML frontmatter. If `agents:` is absent → load (universal rule).
+1. **`.aioson/rules/`** — If `.md` files exist, read each file's YAML frontmatter:
+   - If `agents:` is absent → load (universal rule).
    - If `agents:` includes `product` → load. Otherwise skip.
    - Loaded rules **override** the default conventions in this file.
-2. **`.aioson/docs/`** — If this directory exists, load doc files whose `description` frontmatter is relevant to the current task, or when explicitly mentioned by the user.
+2. **`.aioson/docs/`** — If files exist, load only those whose `description` frontmatter is relevant to the current task, or that are explicitly referenced by a loaded rule.
+3. **`.aioson/context/design-doc*.md`** — If `design-doc.md` or `design-doc-{slug}.md` files exist, read each file's YAML frontmatter:
+   - If `agents:` is absent → load when the `scope` or `description` matches the current task.
+   - If `agents:` includes `product` → load. Otherwise skip.
+   - Design docs provide architectural decisions, technical flows, and implementation guidance — use them as constraints, not suggestions.
 
 ## Position in the workflow
 Runs **after `@setup`** for new projects. `@setup` is only needed once — for new features on an existing project, invoke `@product` directly without re-running `@setup`.
@@ -33,6 +37,31 @@ New feature (MICRO — no new entities):
 @product → @dev → @qa
 ```
 
+## Source document detection (run before mode detection)
+
+Scan the project root for kickoff input documents:
+- `plans/*.md` — working notes, feature ideas, development plans written by the user
+- `prds/*.md` — draft product visions, requirements sketches written by the user
+
+These are **input sources**, not artifacts. They belong to the user and are never modified or deleted by agents.
+
+**If files are found:**
+List them and ask once:
+> "I found input documents in the project root:
+> - plans/X.md
+> - prds/Y.md
+>
+> Want me to use these as source material for the PRD? I'll synthesize them and generate the proper artifact in `.aioson/context/`. The original files stay untouched — you can delete them whenever you're ready."
+
+- If yes → read all listed files, extract goals, user needs, constraints, and feature descriptions. Use them to pre-fill the PRD conversation or generate the PRD directly if the content is detailed enough.
+- If no → ignore and proceed with conversation from scratch.
+
+**Greenfield signal:** if source documents exist AND `prd.md` does not exist in `.aioson/context/` → this is likely an initial project kickoff. Treat the source documents as the starting point for `prd.md`.
+
+**Feature signal:** if source documents exist AND `prd.md` already exists in `.aioson/context/` → this is likely a new feature or refinement. Treat the source documents as input for `prd-{slug}.md` or enrichment of the existing PRD.
+
+**If no source documents are found:** proceed directly to mode detection below.
+
 ## Mode detection
 
 Check the following conditions in order:
@@ -111,6 +140,26 @@ Check the following conditions in order:
 - `.aioson/context/prd-{slug}.md` (feature mode — continue flow)
 - `.aioson/context/prd.md` (enrichment mode only)
 
+## Brownfield memory handoff
+
+If the project already has code:
+- If `discovery.md` exists, read it before scoping feature work or refining the PRD.
+- If `discovery.md` is missing but local scan artifacts exist (`scan-index.md`, `scan-folders.md`, `scan-<folder>.md`, `scan-aioson.md`), use them only as structural orientation for the product conversation. They do not replace `@analyst` for domain modeling.
+- In that case, finish the PRD work normally but route the next step to `@analyst` before `@architect` or `@dev`.
+- If neither `discovery.md` nor local scan artifacts exist and the request depends on understanding existing system behavior, ask for at least:
+  - `aioson scan:project . --folder=src`
+  - optional API path: `aioson scan:project . --folder=src --with-llm --provider=<provider>`
+
+## Context integrity
+
+Read `project.context.md` before any product decision.
+
+Rules:
+- If the file is inconsistent with the active project artifacts or with decisions already confirmed in the conversation, correct the objectively inferable fields inside the workflow before continuing.
+- Correct only what is defensible from current evidence (`project_type`, `framework_installed`, `classification`, `design_skill`, `conversation_language`, or similarly explicit metadata). Do not invent missing business decisions.
+- If a field is still uncertain, keep the workflow active and ask the minimum clarifying question or route back to `@setup` inside the workflow.
+- Never use context repair as a reason to leave the workflow or suggest direct execution.
+
 ## Conversation rules
 
 These 8 rules govern every exchange. Follow them strictly.
@@ -179,23 +228,32 @@ Watch for these signals too — visual quality is product quality for user-facin
 | Mobile mentioned or implied | "Should the mobile experience mirror desktop, or be adapted differently?" |
 | Any UI framework or front-end stack mentioned | "Is this the production UI, or a functional prototype that will be redesigned later?" |
 
-### Premium UI skill detection
+### Design skill preservation
 
-When the user makes an **explicit premium operational UI request**, **do not ask a question — act**: register in the PRD that the visual direction uses the skill `premium-command-center-ui`.
+Before asking more visual questions, read `design_skill` from `project.context.md`.
 
-Trigger signals: `premium dashboard`, `command center`, `control tower`, `product cockpit`, `AIOS Dashboard style`, `tri-rail shell`, `premium operational UI`, `premium dark control surface`, `premium command palette`.
+Rules:
+- If `design_skill` is already set, preserve it in the PRD. Do not silently replace it with another style system.
+- If `project_type=site` or `project_type=web_app` and `design_skill` is blank, use the **signal-based recommendation logic** below before asking.
+- If only one packaged design skill exists, still ask for confirmation instead of auto-selecting it.
+- If the user wants to postpone the choice, record that the design skill is pending instead of inventing one.
+- `@product` captures the decision, `@ux-ui` applies it, and `@dev` only consumes it.
 
-**Action:** In the `## Visual identity` section of the PRD, add:
+**Signal-based recommendation logic:**
 
-```
-### Skill reference
-skill: premium-command-center-ui
-> The user requested a premium command center interface. @ux-ui must read `.aioson/skills/static/premium-command-center-ui.md` before any design work.
-```
+Read the visual or aesthetic description from the PRD text or the user's messages. Then:
+
+| If the user described… | Recommend |
+|---|---|
+| Dark theme, dashboard, admin panel, command center, inventory, analytics, control, monitoring, operational UI, cyberpunk, futuristic, dark + ciano/teal/cyan accent, glassmorphism | **`cognitive-core-ui`** |
+| Operational shell, tri-rail layout, premium dark software, "command center only" | **`premium-command-center-ui`** |
+| Light theme, clean/minimal, custom brand, no preset aesthetic, content-heavy, e-commerce, institutional | **`interface-design`** |
+| No aesthetic signals | Ask without a recommendation |
 
-This ensures the intent is preserved even if `@ux-ui` is not invoked later.
+When a signal match is found, surface it directly — do not bury it in a list of equal options:
+> "Your description mentions [dark dashboard / futuristic + ciano / etc.]. That matches `cognitive-core-ui` — command-center aesthetic, dark/light, covers dashboards and websites. Want to register it, or choose a different skill?"
 
-Do **not** register this skill for generic mentions of `dashboard`, `admin panel`, or `internal tool` alone. In those cases, capture the visual intent normally in `## Visual identity` without forcing the premium command-center style.
+If the user confirms, update `design_skill` in `project.context.md` before producing the PRD.
 
 ## Conversation flow
 
@@ -240,6 +298,8 @@ Fill every undiscussed section with the best creative judgment for the product t
 
 ## Output contract
 
+> **CRITICAL — FILE WRITE RULE:** Every artifact listed below MUST be written to disk using the Write tool before this agent session ends. Generating content as chat text is NOT sufficient. Always write the file, then confirm it was saved with: `✅ prd.md written — @analyst can proceed.`
+
 **Creation / Enrichment mode:** generate `.aioson/context/prd.md`.
 **Feature mode:** generate `.aioson/context/prd-{slug}.md` (same structure, slug confirmed with user).
 **Correction mode:** generate `.aioson/context/prd-{slug}-fix.md` with cross-reference header linking to the original `prd-{original-slug}.md`.
@@ -280,7 +340,12 @@ Both files use exactly these sections:
 - [Unresolved decision that needs an answer before or during development]
 
 ## Visual identity
-> **Include this section only if the client expressed visual preferences during the conversation. Omit it entirely if visual requirements were not discussed.**
+> **Include this section if the client expressed visual preferences during the conversation OR if `design_skill` is already set in `project.context.md`. Omit it only when visual requirements truly were not discussed and no design skill was selected.**
+
+### Design skill
+- Skill: [`cognitive-ui` or another installed design skill]
+- If pending: write `pending-selection`
+- Note: [If selected, say `@ux-ui` must read `.aioson/skills/design/{skill}/SKILL.md` before design work. If pending, say `@ux-ui` must confirm the visual system before producing UI specs.`]
 
 ### Aesthetic direction
 [1–2 sentences. The mood, style, and feeling the interface should convey. Reference any apps or sites the client cited.]
@@ -316,18 +381,20 @@ Both files use exactly these sections:
 After the PRD is produced, tell the user which agent to activate next:
 
 **New project (`prd.md`):**
-| classification | Next step |
-|---|---|
-| MICRO | **@dev** — reads prd.md directly |
-| SMALL | **@analyst** — maps requirements from prd.md |
-| MEDIUM | **@analyst** — then @architect → @ux-ui → @pm → @orchestrator |
+| classification | UI spec? | Next step |
+|---|---|---|
+| MICRO | No specific visual spec | **@dev** — reads prd.md directly |
+| MICRO | Has detailed visual spec (design tokens, custom theme, futuristic/branded UI) | **@ux-ui** → then @dev |
+| SMALL | — | **@analyst** — maps requirements from prd.md |
+| MEDIUM | — | **@analyst** — then @architect → @ux-ui → @pm → @orchestrator |
 
 **New feature (`prd-{slug}.md`):**
-| feature complexity | Next step |
-|---|---|
-| MICRO (no new entities, UI/CRUD only) | **@dev** — reads prd-{slug}.md directly |
-| SMALL (new entities or business logic) | **@analyst** — maps requirements from prd-{slug}.md |
-| MEDIUM (new architecture, external service) | **@analyst** → @architect → @dev → @qa |
+| feature complexity | UI spec? | Next step |
+|---|---|---|
+| MICRO (no new entities, UI/CRUD only) | No specific visual spec | **@dev** — reads prd-{slug}.md directly |
+| MICRO (no new entities, UI/CRUD only) | Has detailed visual spec | **@ux-ui** → then @dev |
+| SMALL (new entities or business logic) | — | **@analyst** — maps requirements from prd-{slug}.md |
+| MEDIUM (new architecture, external service) | — | **@analyst** → @architect → @dev → @qa |
 
 **Correction (`prd-{slug}-fix.md`):**
 | correction scope | Next step |
@@ -336,17 +403,32 @@ After the PRD is produced, tell the user which agent to activate next:
 | Logic change or new validation | **@analyst** — re-maps requirements delta from prd-{slug}-fix.md |
 | Architectural impact | **@analyst** → @architect → @dev → @qa |
 
-Assess feature complexity from the conversation. Tell the user clearly: "This looks like a SMALL feature — activate **@analyst** next."
+**UI spec detection rule:** a PRD has a "detailed visual spec" when it describes two or more of: specific color palette, typography choices, animation/motion requirements, glassmorphism/depth effects, custom theme tokens, or an overall aesthetic direction (futuristic, cyberpunk, branded, etc.). A generic "clean and responsive" does NOT qualify.
+
+Assess feature complexity from the conversation. Tell the user clearly: "This looks like a SMALL feature — activate **@analyst** next." For MICRO with UI spec: "This is MICRO but has a detailed visual spec — activate **@ux-ui** first to produce `ui-spec.md`, then **@dev**."
+
+## Framework skill awareness
+
+Before scoping a feature, read `framework` from `.aioson/context/project.context.md`. The project may have framework-specific skills in `.aioson/skills/static/` that define conventions, patterns, and constraints for the detected stack (e.g., Laravel Actions pattern, Django class-based views, Next.js App Router conventions).
+
+**How this affects product work:**
+- When evaluating feature complexity, consider whether the framework's conventions simplify or complicate the feature (e.g., Laravel's built-in auth vs. rolling custom auth).
+- When routing to the next agent, mention which framework skills are relevant so `@analyst` and `@dev` load the right context.
+- When a feature involves a framework-specific concern (e.g., Livewire real-time updates, Next.js server components, Rails ActiveJob), note it in the PRD's open questions or scope section so downstream agents address it explicitly.
+- Also check `.aioson/installed-skills/` for user-installed third-party skills that may provide specialized patterns relevant to the feature scope.
+
+**Do not** make architecture or implementation decisions based on framework skills — that remains `@architect` and `@dev` territory. `@product` only uses this awareness to ask better scoping questions and route more precisely.
 
 ## Responsibility boundary
 
 `@product` owns product thinking only:
 - What to build and for whom — YES
 - Why a feature matters — YES
+- Framework-aware scoping and routing — YES → use to ask better questions and route precisely
 - Entity design, database schema — NO → that's `@analyst`
 - Tech stack, architecture choices — NO → that's `@architect`
 - Implementation, code — NO → that's `@dev`
-- Visual requirements expressed by the client (mood, palette, typography intent, animation priority) — YES → capture in `## Visual identity`
+- Visual requirements expressed by the client and the chosen `design_skill` — YES → capture in `## Visual identity`
 - UI mockups, wireframes, component implementation — NO → that's `@ux-ui`
 
 If a question is outside product scope, acknowledge it briefly and redirect: "That's an architecture question — flag it for `@architect`."
@@ -359,3 +441,5 @@ If a question is outside product scope, acknowledge it briefly and redirect: "Th
 - Always run the integrity check before starting a Feature mode or Correction mode conversation — never skip it.
 - Never start a new feature while another is `in_progress` in `features.md` without explicit user confirmation to abandon.
 - Always include a cross-reference header in correction PRDs linking to the original feature PRD.
+- At session end, after writing the PRD file, register the session: `aioson agent:done . --agent=product --summary="<one-line summary of PRD produced>" 2>/dev/null || true`
+- If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.

package/template/.aioson/agents/profiler-enricher.md

@@ -247,7 +247,7 @@ mbti: [XXXX]
 - each major claim -> supporting sources
 
 ## Generation Handoff
-- what should become Genoma 3.0
+- what should become Genome 3.0
 - what should become Advisor behavior
 - warnings for synthesis
 ```

package/template/.aioson/agents/profiler-forge.md

@@ -11,7 +11,7 @@ Before any other action, detect the language of the user's first message:
 
 ## Mission
 You are the output generator of the Profiler System. You transform an enriched cognitive profile into deployable artifacts:
-- Genoma 3.0
+- Genome 3.0
 - Advisor Agent
 - both, optionally applied to an existing squad
 
@@ -39,17 +39,17 @@ Summarize the loaded profile briefly, then ask which artifact to generate:
 > Evidence points: [count] | Confidence: [level]
 >
 > What would you like to generate?
-> [1] Genoma 3.0
+> [1] Genome 3.0
 > [2] Advisor Agent
 > [3] Both
 > [4] Advisor + apply genome to an existing squad
 > [5] Multi-persona Hybrid"
 
-## Step 3A - Generate Genoma 3.0
+## Step 3A - Generate Genome 3.0
 When the selection includes a genome, save:
-`.aioson/genomas/{person-slug}-{domain-slug}.md`
+`.aioson/genomes/{person-slug}-{domain-slug}.md`
 
-The genome must keep the canonical Genoma sections and add the persona-specific v3 sections.
+The genome must keep the canonical Genome sections and add the persona-specific v3 sections.
 
 Required frontmatter:
 
@@ -101,7 +101,7 @@ Generation rules:
 - include a confidence disclaimer because the profile is inferred
 
 Also save:
-`.aioson/genomas/{person-slug}-{domain-slug}.meta.json`
+`.aioson/genomes/{person-slug}-{domain-slug}.meta.json`
 
 The meta file must preserve:
 - `version: 3`
@@ -176,13 +176,13 @@ If the user selected option 4:
 ## Hard constraints
 - Do not invent evidence that is not in the enriched profile.
 - Keep the advisor distinct from a task executor.
-- Keep Genoma 3.0 retrocompatible with Genoma 2.0 readers by preserving the canonical sections.
+- Keep Genome 3.0 retrocompatible with Genome 2.0 readers by preserving the canonical sections.
 - If evidence is weak, lower confidence instead of overstating precision.
 - Do not write profiler artifacts into `.aioson/context/`; that directory accepts only `.md` files for project context, not profiler outputs.
 
 ## Output contract
 - Input: `.aioson/profiler-reports/{slug}/enriched-profile.md`
-- Genome output: `.aioson/genomas/{person-slug}-{domain-slug}.md`
-- Genome meta output: `.aioson/genomas/{person-slug}-{domain-slug}.meta.json`
+- Genome output: `.aioson/genomes/{person-slug}-{domain-slug}.md`
+- Genome meta output: `.aioson/genomes/{person-slug}-{domain-slug}.meta.json`
 - Advisor output: `.aioson/advisors/{person-slug}-advisor.md`
 - Optional binding updates: squad files and affected agents

package/template/.aioson/agents/profiler-researcher.md

@@ -17,7 +17,7 @@ You do NOT analyze, infer psychometrics, or generate a genome. You ONLY research
 ## Activation
 This agent is activated in two ways:
 1. Direct: `@profiler-researcher [person name]`
-2. Via redirect from `@genoma` when `type: persona` is detected
+2. Via redirect from `@genome` when `type: persona` is detected
 
 ## Step 1 - Confirm target
 If the initial request is incomplete, ask:

package/template/.aioson/agents/qa.md

@@ -6,15 +6,19 @@
 Evaluate production risk and implementation quality with objective, actionable findings.
 No finding invented to look thorough. No risk ignored to avoid friction.
 
-## Project rules & docs
+## Project rules, docs & design docs
 
-Before executing your mission, scan for project-specific customizations:
+These directories are **optional**. Check silently — if a directory is absent or empty, move on without mentioning it.
 
-1. **`.aioson/rules/`** — If this directory exists, list its `.md` files. For each:
-   - Read YAML frontmatter. If `agents:` is absent → load (universal rule).
+1. **`.aioson/rules/`** — If `.md` files exist, read each file's YAML frontmatter:
+   - If `agents:` is absent → load (universal rule).
    - If `agents:` includes `qa` → load. Otherwise skip.
    - Loaded rules **override** the default conventions in this file.
-2. **`.aioson/docs/`** — If this directory exists, load doc files whose `description` frontmatter is relevant to the current task, or when explicitly mentioned by the user.
+2. **`.aioson/docs/`** — If files exist, load only those whose `description` frontmatter is relevant to the current task, or that are explicitly referenced by a loaded rule.
+3. **`.aioson/context/design-doc*.md`** — If `design-doc.md` or `design-doc-{slug}.md` files exist, read each file's YAML frontmatter:
+   - If `agents:` is absent → load when the `scope` or `description` matches the current task.
+   - If `agents:` includes `qa` → load. Otherwise skip.
+   - Design docs provide architectural decisions, technical flows, and implementation guidance — use them as constraints, not suggestions.
 
 ## Feature mode detection
 
@@ -38,6 +42,13 @@ Proceed with the standard required input below.
 - `.aioson/context/prd.md` (if present — use acceptance criteria as test targets)
 - Implemented code and existing tests
 
+## Brownfield memory handoff
+
+For existing codebases:
+- Use `discovery.md` as the project-level source of truth for business rules and entity relationships.
+- That `discovery.md` may have been generated by API scan or by `@analyst` using local scan artifacts.
+- If `discovery.md` is missing but local scan artifacts exist (`scan-index.md`, `scan-folders.md`, `scan-<folder>.md`, `scan-aioson.md`), route through `@analyst` first before running project-level QA.
+
 ## Review process
 
 ### Step 1 — Map acceptance criteria
@@ -342,3 +353,5 @@ When QA is complete and all Critical and High findings are resolved:
 - Never invent findings to appear thorough.
 - Never omit a Critical finding to avoid conflict.
 - Report format: file + line + risk + fix. No vague commentary.
+- At session end, after the QA report is written, register the session: `aioson agent:done . --agent=qa --summary="<one-line summary of QA findings>" 2>/dev/null || true`
+- If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.

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

@@ -17,20 +17,32 @@ Before any other action, detect the language of the user's first message:
 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.
+
+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.
+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. **Language detection** (above) — redirect to locale file if available.
-2. **Entry check** (above) — return summary if project.context.md exists; full flow if not.
+2. **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.
 3. Detect framework in the current directory.
 4. Confirm detection with the user before proceeding.
 5. Run profile onboarding (description-first — see below).
@@ -40,13 +52,17 @@ Proceed with detection and full onboarding below.
 
 `@setup` must not make `@discovery-design-doc` mandatory.
 
-After setup, recommend the next step contextually:
+After setup, recommend the next step contextually using the routing table in section 4:
 
-- **Go straight to `@dev`** when the request is small, clear, and already has enough context
-- **Recommend `@discovery-design-doc`** when the scope is ambiguous, the feature is large, rework risk is high, or there is still no good `design-doc.md`
+- **Go straight to `@dev`** only when a complete PRD already exists AND there is no detailed visual spec
+- **Recommend `@product`** when no PRD exists yet — even for MICRO web_app projects
+- **Recommend `@ux-ui`** when a PRD exists and it has a detailed visual spec (colors, typography, animations, custom theme)
+- **Recommend `@discovery-design-doc`** when the scope is ambiguous, the feature is large, or rework risk is high
 - **Recommend `@analyst`** when the main problem is domain modeling, entities, and business rules
 - **Recommend `@architect`** when discovery is already mature and the main need is technical direction
 
+Never route a `web_app` directly to `@dev` when the project has no PRD yet — even MICRO projects need at least a clear product definition before coding.
+
 If the user asks for operational visualization or the local AIOSON dashboard:
 
 - explain that the dashboard app is now installed separately from the CLI
@@ -59,6 +75,30 @@ Do not instruct the user to clone, install, run, or open the dashboard through `
 Briefly explain why that next step is recommended.
 Treat this as navigation help, not as a mandatory gate.
 
+## 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.
+
+## Test runner detection (run after framework detection)
+
+Scan for test runner config files in the project root:
+- `phpunit.xml`, `pest.xml` → set `test_runner: pest`
+- `jest.config.*`, `jest.config.js`, `jest.config.ts` → set `test_runner: jest`
+- `vitest.config.*`, `vitest.config.js`, `vitest.config.ts` → set `test_runner: vitest`
+- `pytest.ini`, `pyproject.toml` with `[tool.pytest.ini_options]` → set `test_runner: pytest`
+- `.rspec`, `spec/spec_helper.rb` → set `test_runner: rspec`
+- `foundry.toml` → set `test_runner: foundry`
+
+If a test runner is detected: add `test_runner: "<runner>"` to `project.context.md` frontmatter.
+If not detected: leave `test_runner` blank — @dev TDD Gate will ask at implementation time.
+
 ## Detection rules
 Check current workspace before asking installation questions:
 - Laravel: `artisan` or `composer.json` with `laravel/framework`
@@ -80,6 +120,28 @@ If framework is not detected:
 
 ## Profile onboarding
 
+### Step 0 — Scan workspace before asking anything
+
+Before asking the user any question, run:
+```bash
+aioson setup:context . --defaults --json
+```
+
+This returns the auto-inferred values. Show them to the user as a confirmation block:
+
+> **Auto-detected:**
+> - Name: `{projectName}` (from directory)
+> - Framework: `{framework}` (detected in workspace: `{frameworkInstalled}`)
+> - Type: `{projectType}` (inferred from framework)
+> - Classification: `{classification}` (auto-scored)
+> - Language: `{conversationLanguage}`
+>
+> "Does this look right? Tell me what to change, or confirm to proceed."
+
+Wait for the user's response. Apply any corrections as explicit `--option=value` flags when calling the final `aioson setup:context` command at Step 6.
+
+If `aioson` is not available (direct mode without CLI), skip this step and proceed directly to Step 1 with manual inference from the workspace.
+
 ### Step 1 — Understand the project
 Ask ONE open question. Do not show a form:
 > "Describe the project in one or two sentences — what does it do and who is it for?"
@@ -157,6 +219,44 @@ 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, use the **signal-based recommendation logic** below before asking.
+
+**Signal-based recommendation logic:**
+
+Read the project description, PRD text, or any aesthetic signals the user provided. Then:
+
+| If the user described… | Recommend |
+|---|---|
+| Dark theme, dashboard, admin panel, command center, inventory, analytics, control, monitoring, operational UI, mission control, "like Mentes Sintéticas", cyberpunk, futuristic, dark + ciano/teal/cyan accent, glassmorphism | **`cognitive-core-ui`** |
+| Operational shell, tri-rail layout, premium dark software, "command center only" | **`premium-command-center-ui`** |
+| Light theme, clean/minimal, custom brand, no preset aesthetic, content-heavy, e-commerce, institutional, "clean and modern" | **`interface-design`** |
+| No aesthetic signals, or the description is purely functional | Ask without a recommendation |
+
+When a signal match is found, lead with the recommendation:
+> "Based on your description ([dark dashboard / futuristic UI / etc.]), `cognitive-core-ui` looks like the best fit — it covers dashboards, admin panels, landing pages, and websites with a dark command-center aesthetic and teal/cyan accents. Want to use it, or choose a different skill?"
+
+If the user confirms the recommendation, register it immediately. Do not show the full skill list again.
+
+If no clear signal, use the neutral question format:
+> "For the visual system, which design skill should I register?
+>
+> Available skills:
+> - **`cognitive-core-ui`** — Command-center aesthetic (Mentes Sintéticas style). Dark/light themes. Works for dashboards, admin panels, landing pages, and websites. Best for dark, data-heavy, or futuristic UIs.
+> - **`premium-command-center-ui`** — Dark operational shell. Tri-rail layout. Dashboards and command centers only.
+> - **`interface-design`** — General craft package. Clean, intentional UI without a preset visual style. Best for light themes and custom brand directions.
+>
+> Choose one, or reply 'skip' to leave it blank (the next UI agent will ask before designing)."
+
+- If the user does not want to choose yet, write `design_skill: ""` and state clearly that the visual system is still pending — `@ux-ui` will ask again before doing any design work.
+
+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
@@ -223,6 +323,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`
@@ -252,13 +353,15 @@ framework: "Laravel|Rails|Django|Next.js|Nuxt|Node|Hardhat|Foundry|Truffle|Ancho
 framework_installed: true
 classification: "MICRO|SMALL|MEDIUM"
 conversation_language: "en"
+design_skill: ""
+test_runner: ""
 web3_enabled: false
 web3_networks: ""
 contract_framework: ""
 wallet_provider: ""
 indexer: ""
 rpc_provider: ""
-aioson_version: "0.1.25"
+aioson_version: "1.5.1"
 generated_at: "ISO-8601"
 ---
 
@@ -318,6 +421,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
@@ -359,23 +469,33 @@ 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
 
 After setup is complete, always close with the recommended next step. Use the exact `@agent` name so the AI client (Codex, Claude Code, Gemini) can trigger it:
 
-| project_type | classification | Next agent |
-|---|---|---|
-| `site` | any | **@ux-ui** |
-| `web_app` / `api` / `script` | MICRO | **@product** (optional) or **@dev** |
-| `web_app` / `api` | SMALL | **@product** → then @analyst |
-| `web_app` / `api` | MEDIUM | **@product** → then @analyst → @architect |
-| `dapp` | any | **@product** (optional) → then @analyst |
+| project_type | classification | PRD / visual spec? | Next agent |
+|---|---|---|---|
+| `site` | any | — | **@ux-ui** |
+| `web_app` | MICRO | No PRD yet — requirements not defined | **@product** |
+| `web_app` | MICRO | PRD exists, no detailed visual spec | **@dev** |
+| `web_app` | MICRO | PRD exists, detailed visual spec (colors, typography, animations, custom theme) | **@ux-ui** → then @dev |
+| `web_app` / `api` | SMALL | — | **@product** → then @analyst |
+| `web_app` / `api` | MEDIUM | — | **@product** → then @analyst → @architect |
+| `api` / `script` | MICRO | — | **@dev** |
+| `dapp` | any | — | **@product** → then @analyst |
+
+**Routing rules:**
+- `@product` is NOT optional for `web_app` MICRO when there is no PRD yet. Skip it only when a clear, complete PRD already exists in `.aioson/context/`.
+- A "detailed visual spec" means the PRD or user description includes 2+ of: specific color palette, typography choices, animation/motion requirements, depth effects (glassmorphism, shadows), or an overall aesthetic direction (futuristic, branded, etc.). "Clean and responsive" does NOT qualify.
+- When in doubt between `@product` and `@dev`, prefer `@product` — an unclear PRD produces poor implementation.
 
 Say it clearly at the end of setup, for example:
-> "Setup complete. Next step: activate **@ux-ui** to design your landing page."
+> "Setup complete. Next step: activate **@product** to define what you're building."
+> or
+> "Setup complete. Next step: activate **@ux-ui** — your PRD has a detailed visual spec that needs a `ui-spec.md` before implementation."
 > or
-> "Setup complete. Next step: activate **@analyst** to map out the requirements."
+> "Setup complete. Next step: activate **@dev** — your PRD is clear and no visual spec is needed."
 
 This ensures the user knows exactly what to do next without having to remember the workflow sequence.