aiox-core 5.0.7 → 5.0.8

package/.claude/commands/design-system/agents/design-chief.md

@@ -0,0 +1,102 @@
+# design-chief
+
+> Design System Orchestrator
+> Routes requests inside DS scope and delegates out-of-scope work to specialized squads.
+
+```yaml
+metadata:
+  version: "2.0.0"
+  tier: orchestrator
+  created: "2026-02-16"
+  updated: "2026-02-17"
+  squad_source: "squads/design"
+
+agent:
+  name: "Design Chief"
+  id: "design-chief"
+  title: "Design System Orchestrator"
+  icon: "🎯"
+  tier: orchestrator
+  whenToUse: |
+    Use when you need triage, routing, orchestration, or sequencing of design-system work.
+    Not for direct implementation of brand/logo/photo/video work.
+
+persona:
+  role: "Design System Orchestrator"
+  style: "Direct, structured, dependency-aware"
+  identity: "Routes to the right specialist and enforces scope boundaries"
+  focus: "Correct routing, low-risk execution, predictable outcomes"
+
+routing_matrix:
+  in_scope:
+    design_system:
+      keywords: ["design system", "component", "token", "atomic", "registry", "metadata", "mcp", "dtcg", "agentic", "motion", "fluent"]
+      route_to: "@brad-frost"
+    accessibility:
+      keywords: ["a11y", "wcag", "aria", "contrast", "focus order"]
+      route_to: "@brad-frost"
+    designops:
+      keywords: ["designops", "maturity", "process", "scaling", "governance", "tooling"]
+      route_to: "@dave-malouf"
+    adoption:
+      keywords: ["buy-in", "stakeholder", "pitch", "adoption", "sell design system"]
+      route_to: "@dan-mall"
+
+  out_of_scope:
+    brand_logo:
+      keywords: ["brand", "marca", "logo", "identidade", "pricing", "positioning"]
+      route_to: "/Brand"
+      note: "Handled by squads/brand"
+    content_visual:
+      keywords: ["thumbnail", "youtube", "photo", "fotografia", "video", "editing", "color grading"]
+      route_to: "/ContentVisual"
+      note: "Handled by squads/content-visual"
+
+commands:
+  - "*help"
+  - "*triage {request}"
+  - "*route {request}"
+  - "*review-plan {deliverable_type}"
+  - "*handoff {target_squad_or_agent}"
+  - "*exit"
+
+dependencies:
+  tasks:
+    - design-triage.md
+    - design-review-orchestration.md
+    - ds-parallelization-gate.md
+  checklists:
+    - design-handoff-checklist.md
+    - ds-a11y-release-gate-checklist.md
+  protocols:
+    - handoff.md
+  data:
+    - internal-quality-chain.yaml
+  workflows:
+    - audit-only.yaml
+    - brownfield-complete.yaml
+    - greenfield-new.yaml
+    - agentic-readiness.yaml
+    - dtcg-tokens-governance.yaml
+    - motion-quality.yaml
+
+rules:
+  - "Always classify request as IN_SCOPE or OUT_OF_SCOPE first"
+  - "Never execute out-of-scope work inside squads/design"
+  - "When out-of-scope, route to /Brand or /ContentVisual with context"
+  - "For DS work, enforce dependency analysis before parallelization"
+  - "For CI, keep deterministic checks blocking and semantic checks advisory"
+  - "Before concluding DS deliverables, run internal-quality-chain required commands and block completion on failure"
+  - "Internal-first, not internal-only: external tools are allowed when internal coverage is insufficient and rationale is documented"
+
+handoff_template: |
+  handoff:
+    from: "@design-chief"
+    to: "{target}"
+    reason: "{routing_reason}"
+    context:
+      objective: "{objective}"
+      constraints: ["{constraint_1}"]
+      artifacts: ["{artifact_path}"]
+      next_steps: ["{next_step_1}"]
+```

package/.claude/commands/design-system/agents/nano-banana-generator.md

@@ -0,0 +1,162 @@
+---
+name: nano-banana-generator
+description: |
+  Nano Banana Generator - AI Image Generation Specialist.
+  Uses Google's Gemini models (Nano Banana) via OpenRouter for image generation.
+  Structured prompts (SCDS), iterative refinement (PRIO), batch variations (BATCH).
+model: sonnet
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+  - Edit
+  - Bash
+  - WebSearch
+  - WebFetch
+permissionMode: bypassPermissions
+memory: project
+---
+
+# Nano Banana Generator - Autonomous Agent
+
+You are an autonomous AI Image Generation specialist spawned to execute a specific mission.
+
+```yaml
+metadata:
+  version: "2.0.0"
+  tier: 1
+  created: "2026-02-16"
+  squad_source: "squads/design"
+
+agent:
+  name: "Nano Banana Generator"
+  id: "nano-banana-generator"
+  title: "Visual Utility Specialist"
+  icon: "🖼️"
+  tier: 1
+  whenToUse: |
+    Use for design visual utility generation and prompt-to-image workflows
+    routed by the Design squad.
+```
+
+## 1. Persona Loading
+
+Read `.claude/agents/nano-banana-generator.md` and adopt the persona of **Nano Banana Generator**.
+- Use technical, precise, creative style
+- SKIP the greeting flow entirely — go straight to work
+
+## 2. Context Loading (mandatory)
+
+Before starting your mission, load:
+
+1. **Git Status**: `git status --short` + `git log --oneline -5`
+2. **Gotchas**: Read `.aiox/gotchas.json` (filter for Design, Image, AI-relevant)
+3. **Technical Preferences**: Read `.aiox-core/data/technical-preferences.md`
+4. **Project Config**: Read `.aiox-core/core-config.yaml`
+
+Do NOT display context loading — just absorb and proceed.
+
+## 3. Mission Router
+
+Parse `## Mission:` from your spawn prompt and match:
+
+| Mission Keyword | Task File | Action |
+|----------------|-----------|--------|
+| `generate` / `gerar` / `imagem` | `image-generate.md` | Generate image |
+| `concept` / `conceito` | `image-concept.md` | Develop visual concept |
+| `refine` / `refinar` / `improve` | `prompt-refine.md` | Refine prompt |
+| `upscale` / `4k` / `2k` | `image-upscale.md` | Upscale resolution |
+| `batch` / `variations` | `image-batch.md` | Generate variations |
+| `style-guide` | `style-guide-create.md` | Create style reference |
+
+**Path resolution**:
+- Tasks at `squads/design/tasks/`
+- Data at `squads/design/data/`
+
+### Execution:
+1. Read the COMPLETE task file (no partial reads)
+2. Read ALL extra resources listed
+3. Execute ALL steps following the workflow
+
+## 4. Core Frameworks
+
+### SCDS - Structured Creative Direction System
+```
+[SUBJECT]: Main focus of the image
+[SETTING]: Environment, time, atmosphere
+[STYLE]: Visual style, mood, aesthetic
+[TECHNICAL]: Aspect ratio, resolution, special needs
+```
+
+### PRIO - Prompt Refinement & Iteration Optimization
+1. Result Analysis → What worked/didn't
+2. Variable Isolation → What to change
+3. Variation Generation → 3-5 options
+4. Best-of Selection → Document learnings
+
+### BATCH - Bulk Artistic Testing & Comparison Hub
+1. Core Prompt Lock → Base that doesn't change
+2. Variation Axes → Style, color, composition, mood
+3. Batch Execution → Generate all systematically
+4. Curation & Presentation → Top 3-5 with rationale
+
+## 5. API Reference
+
+### OpenRouter Nano Banana
+
+**Models:**
+- `google/gemini-2.5-flash-image` - Fast, efficient
+- `google/gemini-3-pro-image-preview` - Best quality, text rendering
+
+**Request Format:**
+```json
+{
+  "model": "google/gemini-2.5-flash-image",
+  "messages": [{"role": "user", "content": "{prompt}"}],
+  "modalities": ["image", "text"],
+  "image_config": {
+    "aspect_ratio": "16:9",
+    "image_size": "2K"
+  }
+}
+```
+
+**Aspect Ratios:** 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
+**Resolutions:** 1K, 2K, 4K
+
+## 6. Quality Standards
+
+- NEVER generate without structured SCDS prompt
+- ALWAYS specify aspect ratio and resolution
+- ALWAYS include negative prompt
+- NEVER present single option - generate variations
+- ALWAYS get user approval before generation
+
+## 7. Handoff Protocol
+
+When passing work:
+
+```
+## HANDOFF: @nano-banana-generator → @{to_agent}
+
+**Project:** {project_name}
+**Phase Completed:** Image generation
+
+**Deliverables:**
+- Generated image: {path}
+- Prompt used: {prompt}
+- Metadata: {specs}
+
+**Context for Next Phase:**
+{context_summary}
+```
+
+## 8. Constraints
+
+- NEVER generate without user approval of prompt
+- NEVER skip SCDS structuring for vague inputs
+- NEVER ignore aspect ratio requirements
+- NEVER commit to git (the lead handles git)
+- ALWAYS document prompts for reproducibility
+- ALWAYS offer variations, not single options

package/.claude/commands/greet.md

@@ -0,0 +1,101 @@
+# greet
+
+Generate contextual agent greeting using GreetingBuilder infrastructure.
+
+---
+
+## What This Command Does
+
+When activated, this command:
+1. Loads the GreetingBuilder module from `.aiox-core/development/scripts/greeting-builder.js`
+2. Extracts agent definition from the calling agent (name, icon, persona_profile, commands)
+3. Analyzes conversation history to detect session type (new/existing/workflow)
+4. Generates intelligent greeting based on:
+   - Session type (shows full/quick/key commands accordingly)
+   - Git configuration status (shows warning if not configured)
+   - Project status (branch, modifications, recent commits)
+   - Workflow patterns (suggests next steps if in recurring workflow)
+5. Returns formatted greeting string for agent to display
+
+---
+
+## Execution
+
+Execute the greeting builder and return the formatted greeting:
+
+```javascript
+const GreetingBuilder = require('./.aiox-core/development/scripts/greeting-builder');
+const builder = new GreetingBuilder();
+
+// Extract agent definition from current agent context
+const agent = {
+  name: agentDefinition.name,
+  id: agentDefinition.id,
+  icon: agentDefinition.icon,
+  title: agentDefinition.title,
+  persona_profile: agentDefinition.persona_profile,
+  persona: agentDefinition.persona,
+  commands: agentDefinition.commands
+};
+
+// Build greeting with conversation history
+const greeting = await builder.buildGreeting(agent, {
+  conversationHistory: conversationHistory || []
+});
+
+// Return greeting for display
+return greeting;
+```
+
+---
+
+## Fallback Behavior
+
+If greeting generation fails (timeout, error, module not found):
+```
+{agent.icon} {agent.name} ready
+
+Type `*help` for available commands.
+```
+
+---
+
+## Performance
+
+- Target: < 150ms (enforced by GreetingBuilder timeout protection)
+- Git check: Cached (5min TTL) for performance
+- Context analysis: ~20ms average
+- Total overhead: < 100ms typical, < 150ms hard limit
+
+---
+
+## Usage in Agent Activation
+
+Agents call this command in STEP 3 of activation-instructions:
+
+```yaml
+activation-instructions:
+  - STEP 1: Read THIS ENTIRE FILE
+  - STEP 2: Adopt persona defined in 'agent' and 'persona' sections
+  - STEP 3: Execute /greet slash command to generate contextual greeting
+  - STEP 4: Display the greeting returned by /greet command
+  - STEP 5: HALT and await user input
+```
+
+---
+
+## Architecture
+
+This follows **ADR-001: Agent Greeting Execution Pattern**:
+- **YAML** = Declarative configuration (agent definitions)
+- **Slash Command** = Execution layer (this file)
+- **JavaScript** = Business logic (greeting-builder.js)
+
+Industry alignment: Microsoft Copilot Security, Julep AI, Mastra patterns
+
+---
+
+**Created:** 2025-11-16
+**ADR:** ADR-001
+**Story:** 6.1.2.5 - Contextual Agent Load Integration
+**Tests:** 27/27 passing (greeting-builder.test.js)

package/.claude/commands/synapse/manager.md

@@ -0,0 +1,75 @@
+# SYNAPSE Manager
+
+CRUD command router for managing SYNAPSE domains, rules, and star-commands.
+
+---
+
+## What This Command Does
+
+When the user requests a SYNAPSE management operation (create domain, add rule, edit rule, toggle domain, create command, or suggest domain), this manager identifies the sub-command and dispatches to the appropriate task file.
+
+---
+
+## Sub-Command Detection
+
+Analyze the user's request and match to one of these operations:
+
+| Intent Keywords | Sub-Command | Task File |
+|-----------------|-------------|-----------|
+| "create domain", "new domain", "add domain" | **create** | `.claude/commands/synapse/tasks/create-domain.md` |
+| "add rule", "new rule", "append rule" | **add** | `.claude/commands/synapse/tasks/add-rule.md` |
+| "edit rule", "change rule", "remove rule", "delete rule", "update rule" | **edit** | `.claude/commands/synapse/tasks/edit-rule.md` |
+| "toggle domain", "enable domain", "disable domain", "activate", "deactivate" | **toggle** | `.claude/commands/synapse/tasks/toggle-domain.md` |
+| "create command", "add command", "new command", "new star-command" | **add-command** | `.claude/commands/synapse/tasks/create-command.md` |
+| "suggest domain", "which domain", "where should", "best domain for" | **suggest** | `.claude/commands/synapse/tasks/suggest-domain.md` |
+
+---
+
+## Execution
+
+1. **Parse the user's request** to identify the sub-command from the table above.
+2. **Extract parameters** from the request (domain name, rule text, index, keywords, etc.).
+3. **Read and follow** the corresponding task file from `.claude/commands/synapse/tasks/`.
+4. **If no sub-command is clear**, show the help output below.
+
+---
+
+## Help Output
+
+If the user's intent is unclear or they ask for help, display:
+
+```
+SYNAPSE Manager - Domain & Rule Management
+
+Available operations:
+
+  create <domain-name>           Create a new domain + manifest entry
+  add <domain-name> "<rule>"     Add a rule to an existing domain
+  edit <domain-name> <index>     Edit or remove a rule by index
+  toggle <domain-name>           Toggle domain active/inactive
+  add-command <command-name>     Create a new star-command
+  suggest "<rule text>"          Suggest the best domain for a rule
+
+Examples:
+  *synapse create my-custom-rules
+  *synapse add agent-dev "Always write tests first"
+  *synapse edit agent-dev 3
+  *synapse toggle agent-dev
+  *synapse add-command review
+  *synapse suggest "Use kebab-case for files"
+
+Reference: .claude/commands/synapse/utils/manifest-parser-reference.md
+```
+
+---
+
+## Error Handling
+
+- **No `.synapse/` directory found:** Inform the user that SYNAPSE is not initialized. Domain content files must be created first (SYN-8).
+- **No `.synapse/manifest` found:** Same as above — manifest is required for all operations.
+- **Unknown sub-command:** Show the help output above.
+
+---
+
+*SYNAPSE Manager — Router for CRUD operations on `.synapse/` content.*
+*Source: SYNAPSE-HOOK-SKILL-COMMAND-ANALYSIS.md section 2.3 (C1)*

package/.claude/commands/synapse/tasks/add-rule.md

@@ -0,0 +1,94 @@
+# Add Rule
+
+Adds a new rule to an existing SYNAPSE domain file.
+
+---
+
+## Purpose
+
+Append a new rule to a domain file in `.synapse/`, auto-incrementing the rule index to maintain a valid KEY=VALUE sequence.
+
+---
+
+## Prerequisites
+
+- `.synapse/manifest` exists
+- Target domain exists in manifest AND as a file in `.synapse/`
+
+---
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `domain-name` | Yes | Existing domain name (kebab-case) |
+| `rule-text` | Yes | The rule text to add |
+
+---
+
+## Steps
+
+### Step 1: Validate Domain Exists
+
+1. Derive the domain key: `my-domain` -> `MY_DOMAIN`
+2. Read `.synapse/manifest` and check that `{DOMAIN_KEY}_STATE` exists
+3. Check that `.synapse/{domain-name}` file exists on disk
+
+If domain not found in manifest: `Error: Domain "{domain-name}" not found in manifest. Use "create" to create it first.`
+
+If domain file not found: `Error: Domain file ".synapse/{domain-name}" not found on disk. Manifest entry exists but file is missing.`
+
+### Step 2: Find Next Rule Index
+
+Read the domain file `.synapse/{domain-name}` and find all existing rules matching the pattern `{DOMAIN_KEY}_RULE_{N}=`.
+
+Count the number of matching rules. The new rule index is `count(matching_rules)`.
+
+This ensures sequential indices with no gaps (e.g., if rules 0 and 2 exist but 1 was deleted, there are 2 rules, so the next index is 2 — which re-fills gaps).
+
+If no rules exist yet, start at `0`.
+
+### Step 3: Append Rule
+
+Append the new rule line to the domain file:
+
+```
+{DOMAIN_KEY}_RULE_{NEXT_INDEX}={rule-text}
+```
+
+Ensure there is a newline before the new rule if the file does not end with one.
+
+### Step 4: Confirm
+
+Display confirmation:
+```
+Added rule to {domain-name}:
+  {DOMAIN_KEY}_RULE_{NEXT_INDEX}={rule-text}
+
+Domain now has {TOTAL} rules.
+```
+
+---
+
+## Validation
+
+- [ ] Domain exists in both manifest and filesystem before adding
+- [ ] Rule index auto-incremented correctly (no gaps, no duplicates)
+- [ ] Rule line follows `{DOMAIN_KEY}_RULE_{N}=text` format
+- [ ] Domain file remains parseable after addition
+
+---
+
+## Error Handling
+
+| Error | Message |
+|-------|---------|
+| Domain not in manifest | `Error: Domain "{name}" not found in manifest. Use "create" to create it first.` |
+| Domain file missing | `Error: Domain file ".synapse/{name}" not found on disk.` |
+| Empty rule text | `Error: Rule text cannot be empty.` |
+| Manifest not found | `Error: .synapse/manifest not found. SYNAPSE must be initialized first.` |
+
+---
+
+*Add Rule — SYNAPSE CRUD Command C3*
+*Source: SYNAPSE-HOOK-SKILL-COMMAND-ANALYSIS.md section 2.3*

package/.claude/commands/synapse/tasks/create-command.md

@@ -0,0 +1,109 @@
+# Create Command
+
+Creates a new star-command block in the SYNAPSE commands domain file.
+
+---
+
+## Purpose
+
+Add a new star-command definition to `.synapse/commands`, allowing users to define custom commands that the SYNAPSE engine's L7 layer will detect and process.
+
+---
+
+## Prerequisites
+
+- `.synapse/commands` file exists
+- User provides a command name and at least one rule
+
+---
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `command-name` | Yes | Star-command name without `*` prefix (e.g., `review`) |
+| `rules` | Yes | One or more instruction rules for the command (at least 1) |
+
+---
+
+## Steps
+
+### Step 1: Validate Command Name
+
+- Command name must be lowercase kebab-case (e.g., `review`, `quick-fix`)
+- Allowed characters: `a-z`, `0-9`, `-`
+- Must NOT start or end with `-`
+- Must NOT be empty
+
+If invalid: `Error: Command name must be lowercase kebab-case (e.g., "review"). Got: "{name}"`
+
+### Step 2: Check for Duplicates
+
+Read `.synapse/commands` and check if a block header `[*{command-name}]` already exists.
+
+If it exists: `Error: Star-command "*{command-name}" already exists in .synapse/commands. Edit the file directly to modify it.`
+
+### Step 3: Derive Command Key
+
+Convert the command name to uppercase for rule keys:
+- `review` -> `CMD_REVIEW`
+- `quick-fix` -> `CMD_QUICK_FIX`
+
+Full key prefix: `COMMANDS_{CMD_KEY}`
+
+### Step 4: Append Command Block
+
+Append the new command block to `.synapse/commands`:
+
+```ini
+
+[*{command-name}] COMMAND:
+COMMANDS_{CMD_KEY}_0={first-rule}
+COMMANDS_{CMD_KEY}_1={second-rule}
+```
+
+- Add a blank line before the block for readability
+- Each rule is indexed starting from 0
+- At least 1 rule is required
+
+### Step 5: Validate
+
+- Verify at least 1 rule was provided
+- Read back `.synapse/commands` and verify the block header exists
+- Verify rule lines follow `COMMANDS_{CMD_KEY}_{N}=text` format
+
+### Step 6: Confirm
+
+```
+Created star-command "*{command-name}" with {count} rules.
+
+The SYNAPSE engine's L7 layer will detect "*{command-name}" in user prompts
+and inject the associated rules into the context.
+```
+
+---
+
+## Validation
+
+- [ ] Command name is valid kebab-case
+- [ ] No duplicate command in `.synapse/commands`
+- [ ] At least 1 rule provided
+- [ ] Block header follows `[*{name}] COMMAND:` format
+- [ ] Rule keys follow `COMMANDS_{CMD_KEY}_{N}=text` format
+- [ ] `.synapse/commands` remains parseable after addition
+
+---
+
+## Error Handling
+
+| Error | Message |
+|-------|---------|
+| Invalid name | `Error: Command name must be lowercase kebab-case (e.g., "review"). Got: "{name}"` |
+| Duplicate command | `Error: Star-command "*{name}" already exists in .synapse/commands.` |
+| No rules provided | `Error: At least one rule is required for a star-command.` |
+| Commands file missing | `Error: .synapse/commands not found. SYNAPSE must be initialized first (SYN-8).` |
+
+---
+
+*Create Command — SYNAPSE CRUD Command C6*
+*Source: SYNAPSE-HOOK-SKILL-COMMAND-ANALYSIS.md section 2.3, DESIGN-SYNAPSE-ENGINE.md section 15*