@jaimevalasek/aioson 1.7.2 → 1.8.0

package/template/.aioson/docs/squad/research-loop.md

@@ -0,0 +1,59 @@
+---
+description: "Squad research loop — extract short domain phrases, consult research cache, and use fresh findings to improve executors, workflows, and output quality."
+---
+
+# Squad Research Loop
+
+Load this module before creating, extending, planning, repairing, or materially reworking a squad package.
+
+## Goal
+
+Prevent `@squad` from generating interchangeable squads. Use a small fresh-research pass to ground the package in current domain language, operating patterns, and quality expectations.
+
+## Mandatory keyword extraction
+
+Derive `3-7` short keyword phrases from the current squad ask, such as:
+
+- domain or niche name
+- deliverable type
+- workflow style
+- review or approval pattern
+- audience or buyer language
+- compliance or trust constraint
+- output medium or channel
+
+Keep phrases concrete and searchable. Favor `2-6` words.
+
+## Mandatory scouting pass
+
+1. Load `.aioson/skills/static/web-research-cache.md`
+2. Rank phrases by:
+   - chance of changing executor design
+   - chance of changing workflow or output structure
+   - freshness sensitivity
+3. Check `researchs/` first
+4. Search only the top `1-4` stale or missing phrases
+5. Save every result before using it
+
+At least one phrase must be validated through cache or fresh research whenever the squad serves an external domain, recurring workflow, content system, regulated environment, or specialized audience.
+
+For regulated domains, this lightweight loop does not replace mandatory `@orache` investigation.
+If an `investigation` report already exists, use it as the primary evidence source and run fresh scouting only to fill missing gaps.
+
+## How to use the findings
+
+Use research to improve:
+
+- executor vocabulary and mission boundaries
+- workflow stages and review loops
+- checklists and quality gates
+- anti-patterns that should become hard constraints
+- output blueprints and deliverable structure
+
+If the domain is broad, unfamiliar, or strategically important, use this lightweight loop first and then offer `@orache` for deeper investigation.
+
+## Output discipline
+
+- `researchs/` is a temporary shared evidence layer for reusable references
+- keep only the findings that materially change the squad package
+- do not let research inflate the squad with unnecessary executors or boilerplate

package/template/.aioson/docs/squad/session-operations.md

@@ -0,0 +1,117 @@
+---
+description: "Squad session operations — ephemeral squads, investigation, inter-squad routing, learnings, dashboard guidance, and recurring tasks."
+---
+
+# Squad Session Operations
+
+Use this module for ongoing orchestration and maintenance concerns around the squad.
+
+## Ephemeral squads
+
+Trigger on:
+
+- `@squad --ephemeral`
+- "quick squad"
+- "temporary squad"
+- "session-only squad"
+
+Rules:
+
+- set `"ephemeral": true` in the manifest
+- optionally set `"ttl": "24h"`
+- skip deep design-doc/readiness work
+- keep the package in `.aioson/squads/{slug}/`
+- keep output in `output/{slug}/`
+- do not register ephemeral squads in `CLAUDE.md` or `AGENTS.md`
+
+## Investigation via `@orache`
+
+Offer investigation when:
+
+- the domain is unfamiliar or specialized
+- the user did not provide deep context
+- the squad will be reused repeatedly
+- richer domain vocabulary and benchmarks would materially help
+
+If the domain-classification gate marked the domain as regulated, investigation is mandatory and blocks final squad generation.
+
+If investigation is accepted or required:
+
+1. invoke `@orache`
+2. read the `squad-searches/` report
+3. persist an `investigation` object in the blueprint and final manifest
+4. use it to refine executors, vocabulary, blueprints, quality checks, and anti-patterns
+5. translate regulations into hard constraints, human gates, or review criteria
+6. translate anti-patterns into checklist items and `vetoConditions`
+7. translate benchmarks into workflow quality bars and warm-up expectations
+
+If the report covers fewer than 4 of the 7 investigation dimensions, ask whether the user wants a deeper pass before finalizing the squad.
+
+## Inter-squad routing
+
+When multiple squads exist:
+
+1. scan `.aioson/squads/`
+2. read sibling `squad.md` files
+3. if a request belongs to a sibling squad, route explicitly
+4. if collaboration is required, coordinate a handoff instead of absorbing the work silently
+
+Never duplicate an existing squad's responsibility without an explicit user request.
+
+## Squad learnings
+
+At session start:
+
+- read `learnings/index.md` if present
+- load only the learnings relevant to the current topic
+
+During session:
+
+- capture corrections, rejections, and quality signals internally
+- do not interrupt productive work to discuss learning capture
+
+At session end:
+
+- list the main detected learnings
+- show them briefly to the user
+- save approved ones under `learnings/`
+- update `learnings/index.md`
+
+Promotion checks:
+
+- repeated quality learning → offer promotion to a rule
+- accumulated domain learnings → offer domain skill creation
+- stable preference over many sessions → mark established
+
+## Dashboard guidance
+
+If the user asks for a dashboard or panel:
+
+- explain that the dashboard app is installed separately from the CLI
+- do not assume a dashboard project exists in this repository
+- tell the user to open the installed dashboard app and select the project folder containing `.aioson/`
+
+## Session facilitation
+
+When the user brings a challenge:
+
+- present each relevant specialist in sequence
+- require concrete reasoning, tradeoffs, and next steps
+- synthesize convergences and tensions at the end
+- ask which specialist the user wants to push further
+
+If a specialist produces a final artifact:
+
+- save a draft `.md` in `output/{squad-slug}/`
+- then let the orchestrator fold it into the session HTML
+
+## Recurring tasks
+
+If the environment supports them and the use case is justified:
+
+- `CronCreate`
+- `CronList`
+- `CronDelete`
+
+Use cases include polling external APIs during research and scheduled health checks across executors.
+Always clean recurring tasks up before the session ends.

package/template/.aioson/docs/squad/workflow-quality.md

@@ -0,0 +1,165 @@
+---
+description: "Squad workflow and quality rules — workflow generation, review loops, model tiering, plans, checklists, coverage score, and warm-up."
+---
+
+# Squad Workflow And Quality
+
+Use this module whenever the squad has phases, quality gates, review loops, plans, or coverage scoring.
+
+## When to generate a workflow
+
+Generate `.aioson/squads/{squad-slug}/workflows/main.md` when:
+
+- the squad has 3 or more distinct phases
+- later phases depend on earlier outputs
+- deterministic workers mix with LLM executors
+- human approval points exist
+- the squad will run as a repeatable pipeline
+
+Skip only for purely conversational or exploratory squads.
+
+## Workflow registration
+
+Register the workflow in `squad.manifest.json` with:
+
+- `slug`
+- `title`
+- `trigger`
+- `executionMode`
+- `estimatedDuration`
+- `file`
+- `phases`
+
+Each phase should declare:
+
+- `id`
+- `title`
+- `executor`
+- `executorType`
+- `dependsOn`
+- `output`
+- optional `humanGate`
+- optional `review`
+- optional `vetoConditions`
+
+## Execution modes
+
+- `sequential`
+- `parallel`
+- `mixed`
+
+## Human gates
+
+Use `humanGate` when a phase requires explicit human approval or risk review.
+
+Action levels:
+
+- `auto`
+- `consult`
+- `approve`
+- `block`
+
+## Review loops
+
+Add review when:
+
+- the phase produces a final deliverable
+- the domain is high-risk
+- the pipeline is repeatable and quality drift matters
+
+Review should normally be done by an executor other than the creator.
+
+Include:
+
+- reviewer
+- criteria
+- `onReject`
+- `maxRetries`
+- `retryStrategy`
+- `escalateOnMaxRetries`
+
+Supported retry strategies:
+
+- `feedback`
+- `fresh`
+- `alternative`
+
+## Model tiering
+
+Assign `modelTier` to every executor:
+
+- `none` for deterministic workers
+- `powerful` for orchestration, synthesis, creative generation, or reviewer roles
+- `fast` for research, analysis at scale, or formatting-heavy work
+- `balanced` for mixed/default cases
+
+Show `modelTier` together with type classification in the confirmation output.
+
+## Task decomposition
+
+If an executor has a recurrent multi-step process:
+
+- keep identity in the main agent file
+- move procedure to `.aioson/squads/{squad-slug}/agents/{executor-slug}/tasks/`
+- register the tasks in the manifest
+
+## Quality checklists
+
+Always generate `.aioson/squads/{squad-slug}/checklists/quality.md`.
+
+The checklist must validate:
+
+- domain-specific output quality
+- output integrity
+- executor coverage
+- worker completion when present
+- human gate resolution when present
+
+Add phase-specific checklists if the workflow needs them.
+
+## Execution plan
+
+Generate `.aioson/squads/{squad-slug}/docs/execution-plan.md` when:
+
+- the squad has 4 or more executors
+- workflows are present
+- the squad came from investigation
+- the squad mode is `software` or `mixed`
+
+Offer but do not force for:
+
+- 3-executor squads with moderate complexity
+- content squads with multi-step pipelines
+
+Skip for:
+
+- ephemeral squads
+- tiny obvious linear flows
+- explicit user refusal
+
+## Confirmation, coverage, and warm-up
+
+After generation:
+
+1. list created executors
+2. show classification review
+3. show coverage score
+4. suggest `aioson squad:score . --squad={slug}`
+5. run the warm-up round immediately
+
+Coverage score dimensions:
+
+- executors typed
+- workflow defined
+- checklists present
+- tasks defined
+- workers present
+
+Warm-up output should show, for each specialist:
+
+- problem reading
+- initial recommendation
+- main risk or tension
+- next practical step
+
+Do not skip the warm-up round.

package/template/.aioson/docs/ux-ui/accessibility-audit.md

@@ -0,0 +1,55 @@
+---
+description: "UI/UX accessibility audit mode — WCAG-focused scan, remediation format, and QA handoff guidance for UI accessibility issues."
+---
+
+# UX/UI Accessibility Audit
+
+Activate via `@ux-ui a11y`.
+
+## Step 1 — Scan
+
+Read UI code and check:
+
+| Category | Checks |
+|---|---|
+| Perceivable | Contrast, alt text, captions |
+| Operable | Keyboard reachability, focus rings, no keyboard traps, skip links |
+| Understandable | `lang` attribute, label association, clear errors |
+| Robust | Semantic HTML first, ARIA only when needed, no div-as-button |
+| Motion | `prefers-reduced-motion`, no uncontrolled long autoplay animation |
+
+## Step 2 — Produce findings
+
+Use this structure:
+
+```markdown
+## Accessibility Report — [Project Name]
+
+### Summary
+- WCAG 2.1 AA compliance: [estimated %]
+- Critical issues: [count]
+- Total issues: [count]
+
+### 🔴 Critical
+- [Issue]: [specific element] → [concrete fix]
+
+### 🟡 Important
+- [Issue]: [specific element] → [concrete fix]
+
+### 🟢 Enhancement
+- [Suggestion]: [specific element] → [improvement]
+
+### ✅ Already compliant
+- [Specific accessibility decision that is correct]
+```
+
+## Step 3 — QA integration
+
+If `@qa` is the next workflow agent, add an `## Accessibility` section with:
+- automated checks to add to the test suite
+- manual checks that still require human verification
+
+## Output
+
+- write to `.aioson/context/ui-a11y.md`
+- do not modify code during this audit

package/template/.aioson/docs/ux-ui/audit-mode.md

@@ -0,0 +1,86 @@
+---
+description: "UI/UX audit mode — inventory scan, design quality checks, severity-based reporting, and fix recommendation format for existing UI."
+---
+
+# UX/UI Audit Mode
+
+Activate when the user chooses **Audit** or invokes `@ux-ui audit`.
+
+## Step 1 — Read existing artifacts
+
+Read all that exist:
+- `index.html` or the main template file
+- `ui-spec.md`
+- up to 5 component files from `src/`, `components/`, `app/`, or `pages/`, prioritizing layout-level files
+
+## Step 2 — Inventory scan
+
+Capture:
+
+| Inventory | What to capture |
+|---|---|
+| Colors | Every unique color value. Flag hardcoded values not in CSS custom properties. |
+| Spacing | Unique margin and padding values. Flag values not aligned to a scale. |
+| Radius | Unique border-radius values. Flag inconsistencies. |
+| Typography | Font families, sizes, and weights used. Flag values not in a type scale. |
+| Components | Visually repeated patterns. Flag near-duplicates that should be consolidated. |
+
+## Step 3 — Run quality checks
+
+Apply each check and record findings:
+
+| Check | What to look for |
+|---|---|
+| Swap test | Could this UI belong to any other product? |
+| Squint test | Is hierarchy clear or does everything compete? |
+| Signature test | Can you name 5 product-specific design decisions? |
+| State completeness | Hover, focus, active, disabled states defined? |
+| Depth consistency | Borders-only and shadows mixed on the same surface type? |
+| Token discipline | Hardcoded values vs CSS custom properties |
+| Accessibility | Contrast, focus, semantic HTML |
+| Mobile-first | Breakpoints and graceful degradation below 768px |
+| Motion safety | `prefers-reduced-motion` respected |
+| Visual continuity | Shared surfaces consistent across screens |
+
+## Step 4 — Produce the audit report
+
+Use this structure:
+
+```markdown
+## UI Audit — [Project Name]
+
+### Inventory
+- Colors: X unique values (Y hardcoded)
+- Spacing: X unique values
+- Radius: X unique values
+- Components: X patterns (Y near-duplicates)
+
+### 🔴 Critical
+- [Issue]: [specific location] → [concrete fix]
+
+### 🟡 Important
+- [Issue]: [specific location] → [concrete fix]
+
+### 🟢 Polish
+- [Issue]: [specific location] → [suggestion]
+
+### ✅ What's working
+- [Specific intentional decision]
+
+### Consolidation plan
+- [Pattern A and Pattern B] → [single component]
+- [Hardcoded values] → [semantic tokens]
+```
+
+Rules:
+- every finding must reference a specific element or line
+- every critical or important finding must include a concrete fix
+- always include at least one "What's working" entry
+- include a consolidation plan when near-duplicates or hardcoded values are found
+- end with: `Want me to apply the critical fixes now, or go through them one by one?`
+
+## Output
+
+- write the report to `.aioson/context/ui-audit.md`
+- do not modify `index.html`, component files, or `ui-spec.md` during audit
+- switch to targeted edits only after the user confirms which fixes to apply

package/template/.aioson/docs/ux-ui/component-map.md

@@ -0,0 +1,35 @@
+---
+description: "UI/UX component map mode — component inventory, atomic classification, variants, states, and gap analysis between spec and implementation."
+---
+
+# UX/UI Component Map
+
+Activate via `@ux-ui component-map`.
+
+## Step 1 — Scan
+
+- if code exists, scan `src/`, `components/`, `app/`, and `pages/` for visual patterns
+- if `ui-spec.md` exists, extract the component list from the spec
+- if `design_skill` is set, load the skill's component catalog
+
+## Step 2 — Classify
+
+For each component found, record:
+
+| Component | Category | Variants | States | Used in |
+|---|---|---|---|---|
+| `Button` | atom | primary, secondary, ghost | default, hover, focus, active, disabled, loading | Header, Hero CTA, Forms |
+
+Categories follow Atomic Design: atom → molecule → organism → template.
+
+## Step 3 — Gap analysis
+
+Identify:
+- components that exist in the spec but not in code
+- components that exist in code but not in the spec
+- near-duplicate components that should be consolidated
+- missing states or variants
+
+## Output
+
+- write to `.aioson/context/ui-component-map.md`

package/template/.aioson/docs/ux-ui/design-execution.md

@@ -0,0 +1,111 @@
+---
+description: "UI/UX design execution — entry check, refine-vs-rebuild routing, design intent, domain exploration, direction selection, and delivery quality rules."
+---
+
+# UX/UI Design Execution
+
+Use this module for the default creation flow and for `refine-spec`.
+
+## Entry check
+
+Run before Step 1:
+
+1. Does `.aioson/context/ui-spec.md` exist?
+2. Does `index.html` exist in the project root? Relevant when `project_type=site`.
+3. Do component or layout files exist in `src/`, `components/`, `app/`, or `pages/`?
+
+If none exist, proceed directly to the creation flow.
+
+If any exist, ask:
+
+> "I can see this project already has UI. What would you like to do?
+> → **Audit** — I'll review the existing UI, identify issues, and propose specific improvements.
+> → **Refine spec** — I'll update `ui-spec.md` without touching the existing implementation.
+> → **Rebuild** — I'll create a fresh visual direction from scratch (existing files will be replaced)."
+
+Routing:
+- **Audit** → switch to `audit-mode.md`
+- **Refine spec** → read `ui-spec.md`, identify gaps or drift, update in place
+- **Rebuild** → warn that `index.html` and `ui-spec.md` will be overwritten, then confirm before continuing
+
+## Step 1 — Intent
+
+Answer these three questions before any layout or token work:
+
+1. Who exactly is visiting this?
+2. What must they do or feel?
+3. What should this feel like?
+
+If you cannot answer all three with specifics, ask. Do not guess.
+
+## Step 2 — Domain exploration
+
+Produce all four before proposing visuals:
+
+1. **Domain concepts** — 5+ metaphors or patterns from this product's world
+2. **Color world** — 5+ colors that exist naturally in this domain
+3. **Signature element** — one visual thing that could only belong to this product
+4. **Defaults to avoid** — 3 generic choices to replace with intentional ones
+
+Identity test: remove the product name. Can someone still identify what this is for?
+
+## Step 3 — Design direction
+
+Choose one direction. Never mix incompatible directions.
+
+### For apps, dashboards, SaaS
+- **Precision & Density** — dashboards, admin, dev tools. Borders-only, compact, cool slate.
+- **Warmth & Approachability** — consumer apps, onboarding. Shadows, generous spacing, warm tones.
+- **Sophistication & Trust** — fintech, enterprise. Cold palette, restrained layers, firm typography.
+- **Premium Dark Platform** — premium dark product UI, controlled contrast, restrained layers, catalog cards, and clean navigation.
+- **Minimal & Calm** — near-monochrome, whitespace as design element, hairline borders.
+
+### For landing pages and sites
+- **Clean & Luminous** — light surfaces, one strong accent, large confident headings, subtle fade-up animation.
+- **Bold & Cinematic** — dark hero, full-bleed photography, gradient overlays, scroll reveals.
+
+## Visual continuity
+
+When the work spans more than one screen:
+- shared surfaces must stay visually identical across screens
+- token values must be consistent for the same purpose
+- component variants must be reused, not reinvented
+- depth strategy must stay consistent across screens
+- when adding a new screen, explicitly note which existing components and tokens are being reused
+
+## Non-site fallback
+
+If `project_type≠site` and the user explicitly proceeds without a registered `design_skill`, use the fallback directions in this module and output:
+- `ui-spec.md` with token block
+- token ownership
+- screen map
+- component state matrix
+- responsive rules
+- handoff notes
+
+## Working rules
+- Stack first: use the project's existing design system before proposing custom UI.
+- Ask about style only when the ambiguity would materially change the result.
+- Define complete design tokens: spacing, typography, semantic colors, radius, and depth strategy.
+- Declare token ownership explicitly.
+- Commit to one depth strategy per surface type.
+- Accessibility first: keyboard flow, visible focus rings, semantic HTML, and 4.5:1 contrast minimum.
+- State completeness: default, hover, focus, active, disabled, loading, empty, error, success.
+- Mobile-first: small screens defined before desktop enhancements.
+- `prefers-reduced-motion` fallback required for any motion.
+- Scope proportional to classification: MICRO → root HTML only, SMALL → spec + HTML, MEDIUM → full spec.
+
+## Quality checks
+- **Swap test** — would changing the typeface make this look like a different product?
+- **Squint test** — does hierarchy survive when blurred?
+- **Signature test** — can you name 5 design decisions unique to this product?
+- **Wow test** — for landing pages only, would someone screenshot this and share it? If not, revise.
+
+## Self-critique
+
+Before delivering, check:
+
+1. **Composition** — rhythm, intentional proportions, one clear focal point per screen
+2. **Craft** — spacing on-grid, typography uses weight + tracking + size, surfaces whisper hierarchy
+3. **Content** — real copy, real image URLs, coherent story from hero to final CTA
+4. **Structure** — no placeholder text, no arbitrary pixel values, no hacks

package/template/.aioson/docs/ux-ui/design-gate.md

@@ -0,0 +1,27 @@
+---
+description: "UI/UX design gate — context repair, design skill selection, isolation rules, and style ambiguity handling before visual direction is chosen."
+---
+
+# UX/UI Design Gate
+
+Load this module before any operation that creates or revises visual direction.
+
+## Step 0 — Design skill gate
+
+Read `.aioson/context/project.context.md` before deciding direction, theme, or density.
+
+Rules:
+- if `project.context.md` contains stale or inconsistent metadata that affects visual work, repair the objectively inferable fields before continuing
+- if `design_skill` is already set, load `.aioson/skills/design/{design_skill}/SKILL.md` before making visual decisions
+- when `design_skill` is set, treat that package as the single source of truth for visual language, typography, component rhythm, and page composition
+- if `project_type=site` or `project_type=web_app` and `design_skill` is blank, ask the user which installed design skill to use before producing new visual direction
+- if only one packaged design skill is installed, still ask for confirmation instead of auto-selecting it
+- if the user chooses to proceed without one, state clearly: `Proceeding without a registered design skill.`
+- never silently invent, swap, auto-pick, or mix design skills
+- never use context inconsistency as a reason to leave the workflow
+- when `design_skill` is set, do not load, reference, or apply visual rules from another design package
+
+Once the gate is resolved:
+- if the user gave an explicit theme or style preference, obey it
+- otherwise infer the direction from product context and the selected design skill
+- ask at most one short style question only when the ambiguity is material

package/template/.aioson/docs/ux-ui/research-mode.md

@@ -0,0 +1,39 @@
+---
+description: "UI/UX research mode — visual benchmarking, domain patterns, anti-patterns, and directional hypotheses before design work begins."
+---
+
+# UX/UI Research Mode
+
+Activate via `@ux-ui research`.
+
+## Step 1 — Gather context
+
+Read all available artifacts:
+- `project.context.md`
+- `prd.md`
+- `discovery.md`
+- `architecture.md`
+
+## Step 2 — Visual benchmarking
+
+For the product domain, document:
+
+1. **3–5 reference products** — what works, what does not, and one detail worth borrowing
+2. **Visual patterns** — recurring layouts, interaction styles, or UI structures in the domain
+3. **Anti-patterns** — common UI mistakes in the domain to avoid
+4. **User expectations** — what the audience already understands visually
+
+## Step 3 — Directional hypotheses
+
+Propose 2–3 design directions. For each one include:
+- direction name
+- rationale
+- mood description
+- color palette sketch with 3–5 colors
+- typography suggestion
+- risk: what could go wrong with this direction
+
+## Output
+
+- write to `.aioson/context/ui-research.md`
+- the default creation flow may consume this artifact when choosing direction