claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-frontend/roles/analyst/role.md

@@ -0,0 +1,92 @@
+---
+role: analyst
+prefix: ANALYZE
+inner_loop: false
+message_types:
+  success: analyze_ready
+  error: error
+---
+
+# Requirements Analyst
+
+Analyze frontend requirements and retrieve industry design intelligence via ui-ux-pro-max skill. Produce design-intelligence.json and requirements.md for downstream consumption by architect and developer roles.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Industry context | Extracted from task description | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+
+1. Extract session path, industry type, and tech stack from task description
+2. Detect existing design system:
+
+| Signal | Detection Method |
+|--------|-----------------|
+| Token files | Glob `**/*token*.*` |
+| CSS files | Glob `**/*.css` |
+| Package.json | Read for framework dependencies |
+
+3. Detect tech stack from package.json:
+
+| Dependency | Stack |
+|------------|-------|
+| `next` | nextjs |
+| `react` | react |
+| `vue` | vue |
+| `svelte` | svelte |
+| `@shadcn/ui` | shadcn |
+| (none) | html-tailwind |
+
+4. Load .msg/meta.json for shared state
+
+## Phase 3: Design Intelligence Retrieval
+
+Retrieve design intelligence via ui-ux-pro-max skill integration.
+
+**Step 1: Invoke ui-ux-pro-max** (primary path):
+
+| Action | Invocation |
+|--------|------------|
+| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
+| UX guidelines | `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` |
+| Tech stack guide | `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` |
+
+**Step 2: Fallback** (if skill unavailable):
+- Generate design recommendations from LLM general knowledge
+- Log warning: `ui-ux-pro-max not installed. Install via: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
+
+**Step 3: Analyze existing codebase** (if token/CSS files found):
+- Explore existing design patterns (color palette, typography scale, spacing, component patterns)
+
+**Step 4: Competitive reference** (optional, if industry is not "Other"):
+- `WebSearch({ query: "<industry> web design trends best practices" })`
+
+**Step 5: Compile design-intelligence.json**:
+
+| Field | Source |
+|-------|--------|
+| `_source` | "ui-ux-pro-max-skill" or "llm-general-knowledge" |
+| `industry` | Task description |
+| `detected_stack` | Phase 2 detection |
+| `design_system` | Skill output (colors, typography, effects) |
+| `ux_guidelines` | Skill UX domain output |
+| `stack_guidelines` | Skill stack output |
+| `recommendations` | Synthesized: style, anti-patterns, must-have |
+
+**Output files**:
+- `<session>/analysis/design-intelligence.json`
+- `<session>/analysis/requirements.md`
+
+## Phase 4: Self-Review
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| JSON validity | Parse design-intelligence.json | No parse errors |
+| Required fields | Check _source, industry, design_system | All present |
+| Anti-patterns populated | Check recommendations.anti_patterns | Non-empty array |
+| Requirements doc exists | File check | requirements.md written |
+
+Update .msg/meta.json: merge `design_intelligence` and `industry_context` keys.

package/.codex/skills/team-frontend/roles/architect/role.md

@@ -0,0 +1,86 @@
+---
+role: architect
+prefix: ARCH
+inner_loop: false
+message_types:
+  success: arch_ready
+  error: error
+---
+
+# Frontend Architect
+
+Consume design-intelligence.json to define design token system, component architecture, and project structure. Token values prioritize ui-ux-pro-max recommendations. Produce architecture artifacts for developer consumption.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
+| Design intelligence | <session>/analysis/design-intelligence.json | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+
+1. Extract session path and scope from task description
+2. Load design intelligence from analyst output
+3. Load .msg/meta.json for shared state (industry_context, design_intelligence)
+4. Detect existing project structure via Glob `src/**/*`
+
+**Fail-safe**: If design-intelligence.json not found, use default token values and log warning.
+
+## Phase 3: Architecture Design
+
+**Scope selection**:
+
+| Scope | Output |
+|-------|--------|
+| `tokens` | Design token system only |
+| `components` | Component specs only |
+| `full` | Both tokens and components + project structure |
+
+**Step 1: Design Token System** (scope: tokens or full):
+
+Generate `<session>/architecture/design-tokens.json` with categories:
+
+| Category | Content | Source |
+|----------|---------|--------|
+| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max |
+| `typography` | Font families, font sizes (scale) | ui-ux-pro-max |
+| `spacing` | xs through 2xl | Standard scale |
+| `border-radius` | sm, md, lg, full | Standard scale |
+| `shadow` | sm, md, lg | Standard elevation |
+| `transition` | fast, normal, slow | Standard durations |
+
+Use `$type` + `$value` format (Design Tokens Community Group). Support light/dark mode via nested values.
+
+**Step 2: Component Architecture** (scope: components or full):
+
+Generate component specs in `<session>/architecture/component-specs/`:
+- Design reference (style, stack)
+- Props table (name, type, default, description)
+- Variants table
+- Accessibility requirements (role, keyboard, ARIA, contrast)
+- Anti-patterns to avoid (from design intelligence)
+
+**Step 3: Project Structure** (scope: full):
+
+Generate `<session>/architecture/project-structure.md` with stack-specific layout:
+
+| Stack | Key Directories |
+|-------|----------------|
+| react | src/components/, src/pages/, src/hooks/, src/styles/ |
+| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/ |
+| vue | src/components/, src/views/, src/composables/, src/styles/ |
+| html-tailwind | src/components/, src/pages/, src/styles/ |
+
+## Phase 4: Self-Review
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| JSON validity | Parse design-tokens.json | No errors |
+| Required categories | Check color, typography, spacing | All present |
+| Anti-pattern compliance | Token values vs anti-patterns | No violations |
+| Component specs complete | Each has props + accessibility | All complete |
+| File existence | Verify all planned files | All present |
+
+Update .msg/meta.json: merge `design_token_registry` and `component_inventory` keys.

package/.codex/skills/team-frontend/roles/coordinator/commands/analyze.md

@@ -0,0 +1,52 @@
+# Analyze Task
+
+Parse frontend task -> detect capabilities -> assess pipeline complexity -> design roles.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Role |
+|----------|------------|------|
+| analyze, requirements, design intelligence | analyst | analyst |
+| design tokens, component architecture, design system | architect | architect |
+| implement, build, code, develop, page, component | developer | developer |
+| review, audit, quality, test, accessibility | qa | qa |
+
+## Pipeline Selection
+
+| Scope Signal | Pipeline |
+|--------------|----------|
+| single page, landing, simple | page (4-beat) |
+| feature, multi-component, complex | feature (5-beat with arch review gate) |
+| full system, design system, multiple pages | system (7-beat dual-track) |
+
+Default to `feature` if ambiguous.
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| ui-ux-pro-max integration needed | +1 |
+| Existing design system detected | +1 |
+| Accessibility strict mode (healthcare/finance) | +2 |
+| Multiple tech stacks | +2 |
+| Dark mode required | +1 |
+
+Results: 1-2 page, 3-4 feature, 5+ system
+
+## Output
+
+Write <session>/task-analysis.json:
+```json
+{
+  "task_description": "<original>",
+  "pipeline_type": "<page|feature|system>",
+  "capabilities": [{ "name": "<cap>", "role": "<role>", "keywords": ["..."] }],
+  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
+  "complexity": { "score": 0, "level": "Low|Medium|High" },
+  "industry": "<industry>",
+  "constraints": [],
+  "needs_ui_ux_pro_max": true
+}
+```

package/.codex/skills/team-frontend/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,151 @@
+# Command: Dispatch
+
+Create the frontend development task chain with correct dependencies and structured task descriptions. Supports page, feature, and system pipeline modes.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| User requirement | From coordinator Phase 1 | Yes |
+| Session folder | From coordinator Phase 2 | Yes |
+| Pipeline mode | From session.json `pipeline_mode` | Yes |
+| Industry | From session.json `industry` | Yes |
+| Constraints | From session.json `constraints` | No |
+
+1. Load user requirement and scope from session.json
+2. Load pipeline mode (page / feature / system) from session.json
+3. Load industry and constraints for task descriptions
+
+## Phase 3: Task Chain Creation
+
+### Task Description Template
+
+Every task is a JSON entry in the tasks array, written to `<session>/tasks.json`:
+
+```json
+{
+  "id": "<TASK-ID>",
+  "subject": "<TASK-ID>",
+  "description": "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>\nTASK:\n  - <step 1: specific action>\n  - <step 2: specific action>\n  - <step 3: specific action>\nCONTEXT:\n  - Session: <session-folder>\n  - Industry: <industry>\n  - Scope: <scope>\n  - Upstream artifacts: <artifact-1>, <artifact-2>\n  - Shared memory: <session>/.msg/meta.json\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits, focus areas>",
+  "status": "pending",
+  "owner": "<role>",
+  "blockedBy": ["<dependency-list>"]
+}
+```
+
+After building all entries, write the full array to `<session>/tasks.json`.
+
+### Mode Router
+
+| Mode | Task Chain |
+|------|------------|
+| `page` | ANALYZE-001 -> ARCH-001 -> DEV-001 -> QA-001 |
+| `feature` | ANALYZE-001 -> ARCH-001 -> QA-001 -> DEV-001 -> QA-002 |
+| `system` | ANALYZE-001 -> ARCH-001 -> QA-001 -> [ARCH-002 &#124;&#124; DEV-001] -> QA-002 -> DEV-002 -> QA-003 |
+
+---
+
+### Page Mode Task Chain (4 tasks)
+
+**ANALYZE-001** (analyst):
+```json
+{
+  "id": "ANALYZE-001",
+  "subject": "ANALYZE-001",
+  "description": "PURPOSE: Analyze frontend requirements and retrieve design intelligence | Success: design-intelligence.json produced with industry-specific recommendations\nTASK:\n  - Detect tech stack and existing design system\n  - Retrieve design intelligence via ui-ux-pro-max (or LLM fallback)\n  - Analyze existing codebase patterns\n  - Compile design-intelligence.json and requirements.md\nCONTEXT:\n  - Session: <session-folder>\n  - Industry: <industry>\n  - Scope: <scope>\n  - Shared memory: <session>/.msg/meta.json\nEXPECTED: <session>/analysis/design-intelligence.json + requirements.md | Structured design data\nCONSTRAINTS: Read-only analysis | No code modifications",
+  "status": "pending",
+  "owner": "analyst",
+  "blockedBy": []
+}
+```
+
+**ARCH-001** (architect):
+```json
+{
+  "id": "ARCH-001",
+  "subject": "ARCH-001",
+  "description": "PURPOSE: Define design token system and component architecture | Success: design-tokens.json + component specs produced\nTASK:\n  - Load design intelligence from analyst output\n  - Generate design token system (colors, typography, spacing, shadows)\n  - Define component architecture and specs\n  - Generate project structure\nCONTEXT:\n  - Session: <session-folder>\n  - Industry: <industry>\n  - Scope: full\n  - Upstream artifacts: design-intelligence.json, requirements.md\n  - Shared memory: <session>/.msg/meta.json\nEXPECTED: <session>/architecture/design-tokens.json + component-specs/ + project-structure.md\nCONSTRAINTS: Use ui-ux-pro-max recommendations for token values | Support light/dark mode",
+  "status": "pending",
+  "owner": "architect",
+  "blockedBy": ["ANALYZE-001"]
+}
+```
+
+**DEV-001** (developer):
+```json
+{
+  "id": "DEV-001",
+  "subject": "DEV-001",
+  "description": "PURPOSE: Implement frontend page/components from architecture artifacts | Success: All planned files implemented with design token usage\nTASK:\n  - Load design tokens, component specs, project structure\n  - Generate CSS custom properties from design tokens\n  - Implement components following specs and coding standards\n  - Self-validate: no hardcoded colors, cursor-pointer, focus styles, responsive\nCONTEXT:\n  - Session: <session-folder>\n  - Industry: <industry>\n  - Scope: full\n  - Upstream artifacts: design-tokens.json, component-specs/, project-structure.md\n  - Shared memory: <session>/.msg/meta.json\nEXPECTED: src/styles/tokens.css + component files | Design-token compliant code\nCONSTRAINTS: Use CSS variables from tokens | Mobile-first responsive | WCAG AA",
+  "status": "pending",
+  "owner": "developer",
+  "blockedBy": ["ARCH-001"]
+}
+```
+
+**QA-001** (qa):
+```json
+{
+  "id": "QA-001",
+  "subject": "QA-001",
+  "description": "PURPOSE: Execute 5-dimension quality audit on implementation | Success: Score >= 8 with 0 critical issues\nTASK:\n  - Load design intelligence and tokens for compliance checks\n  - Execute 5-dimension audit (code quality, accessibility, design compliance, UX, pre-delivery)\n  - Calculate weighted score and determine verdict\n  - Write audit report\nCONTEXT:\n  - Session: <session-folder>\n  - Industry: <industry>\n  - Review type: code-review\n  - Upstream artifacts: design-intelligence.json, design-tokens.json, src/**\n  - Shared memory: <session>/.msg/meta.json\nEXPECTED: <session>/qa/audit-001.md | Weighted score + verdict + categorized issues\nCONSTRAINTS: Read-only review | No code modifications",
+  "status": "pending",
+  "owner": "qa",
+  "blockedBy": ["DEV-001"]
+}
+```
+
+---
+
+### Feature Mode Task Chain (5 tasks)
+
+Create ANALYZE-001 and ARCH-001 as page mode above, then:
+
+**QA-001** (qa, architecture review):
+- blockedBy: ["ARCH-001"]
+- Review type: architecture-review
+- Reviews architecture artifacts before developer starts
+
+**DEV-001** (developer):
+- blockedBy: ["QA-001"] (waits for arch review to pass)
+
+**QA-002** (qa, code review):
+- blockedBy: ["DEV-001"]
+- Review type: code-review
+
+---
+
+### System Mode Task Chain (7 tasks)
+
+Create ANALYZE-001, ARCH-001, QA-001 as feature mode above, then:
+
+**ARCH-002** (architect, parallel with DEV-001):
+- blockedBy: ["QA-001"]
+- Scope: components (refined specs after QA feedback)
+
+**DEV-001** (developer, parallel with ARCH-002):
+- blockedBy: ["QA-001"]
+- Scope: tokens (CSS generation)
+
+**QA-002** (qa):
+- blockedBy: ["ARCH-002"]
+- Review type: component-review
+
+**DEV-002** (developer):
+- blockedBy: ["QA-002"]
+- Scope: components
+
+**QA-003** (qa, final review):
+- blockedBy: ["DEV-002"]
+- Review type: final
+
+## Phase 4: Validation
+
+| Check | Method | Expected |
+|-------|--------|----------|
+| Task count correct | Read tasks.json, count entries | page: 4, feature: 5, system: 7 |
+| Dependencies correct | Trace dependency graph | Acyclic, correct blockedBy |
+| Structured descriptions | Each has PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | All present |
+| Owner assignments correct | Role matches task prefix | ANALYZE->analyst, ARCH->architect, DEV->developer, QA->qa |
+
+If validation fails, fix the specific task entry in tasks.json and re-validate.

package/.codex/skills/team-frontend/roles/coordinator/commands/monitor.md

@@ -0,0 +1,188 @@
+# Command: Monitor
+
+Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
+
+## Constants
+
+- SPAWN_MODE: background
+- ONE_STEP_PER_INVOCATION: true
+- FAST_ADVANCE_AWARE: true
+- WORKER_AGENT: team-worker
+- MAX_GC_ROUNDS: 2
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| Message contains [analyst], [architect], [developer], [qa] | handleCallback |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session state | <session>/session.json | Yes |
+| Task list | Read `<session>/tasks.json` | Yes |
+| Trigger event | From Entry Router detection | Yes |
+| Pipeline definition | From SKILL.md | Yes |
+
+1. Load session.json for current state, `pipeline_mode`, `gc_rounds`
+2. Read `<session>/tasks.json` to get current task statuses
+3. Identify trigger event type from Entry Router
+
+## Phase 3: Event Handlers
+
+### handleCallback
+
+Triggered when a worker sends completion message.
+
+1. Parse message to identify role and task ID:
+
+| Message Pattern | Role Detection |
+|----------------|---------------|
+| `[analyst]` or task ID `ANALYZE-*` | analyst |
+| `[architect]` or task ID `ARCH-*` | architect |
+| `[developer]` or task ID `DEV-*` | developer |
+| `[qa]` or task ID `QA-*` | qa |
+
+2. Mark task as completed:
+
+Read `<session>/tasks.json`, find entry by id `<task-id>`, set `"status": "completed"`, write back.
+
+3. Record completion in session state
+
+4. Check if checkpoint applies:
+
+| Completed Task | Pipeline Mode | Checkpoint Action |
+|---------------|---------------|-------------------|
+| ANALYZE-001 | all | Log: analysis ready |
+| ARCH-001 | feature/system | Log: architecture ready for review |
+| QA-001 (arch review) | feature/system | Gate: pause if critical issues, wait for architect revision |
+| QA-* (code review) | all | Check verdict for GC loop (see below) |
+
+5. **GC Loop Check** (when QA completes with fix_required):
+
+| Condition | Action |
+|-----------|--------|
+| QA verdict = PASSED or PASSED_WITH_WARNINGS | Proceed to handleSpawnNext |
+| QA verdict = FIX_REQUIRED AND gc_round < 2 | Create DEV-fix + QA-recheck tasks, increment gc_round |
+| QA verdict = FIX_REQUIRED AND gc_round >= 2 | Escalate to user: accept current state or manual intervention |
+
+**GC Fix Task Creation** -- add new entries to `<session>/tasks.json`:
+```json
+{
+  "id": "DEV-fix-<round>",
+  "subject": "DEV-fix-<round>",
+  "description": "PURPOSE: Fix issues identified in QA audit | Success: All critical/high issues resolved\nTASK:\n  - Load QA audit report with findings\n  - Address critical and high severity issues\n  - Re-validate fixes against coding standards\nCONTEXT:\n  - Session: <session-folder>\n  - Upstream artifacts: <session>/qa/audit-<NNN>.md\n  - Shared memory: <session>/.msg/meta.json\nEXPECTED: Fixed source files | QA issues resolved\nCONSTRAINTS: Targeted fixes only | Do not introduce regressions",
+  "status": "pending",
+  "owner": "developer",
+  "blockedBy": []
+}
+```
+
+```json
+{
+  "id": "QA-recheck-<round>",
+  "subject": "QA-recheck-<round>",
+  "description": "PURPOSE: Re-audit after developer fixes | Success: Score >= 8, critical == 0\nTASK:\n  - Execute 5-dimension audit on fixed code\n  - Focus on previously flagged issues\n  - Calculate new score\nCONTEXT:\n  - Session: <session-folder>\n  - Review type: code-review\n  - Shared memory: <session>/.msg/meta.json\nEXPECTED: <session>/qa/audit-<NNN>.md | Improved score\nCONSTRAINTS: Read-only review",
+  "status": "pending",
+  "owner": "qa",
+  "blockedBy": ["DEV-fix-<round>"]
+}
+```
+
+6. Proceed to handleSpawnNext
+
+### handleSpawnNext
+
+Find and spawn the next ready tasks.
+
+1. Scan tasks.json for tasks where:
+   - Status is "pending"
+   - All blockedBy tasks have status "completed"
+
+2. For each ready task, spawn team-worker:
+
+```
+spawn_agent({
+  agent_type: "team_worker",
+  items: [{
+    description: "Spawn <role> worker for <task-id>",
+    team_name: "frontend",
+    name: "<role>",
+    prompt: `## Role Assignment
+role: <role>
+role_spec: ~  or <project>/.codex/skills/team-frontend/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: frontend
+requirement: <task-description>
+inner_loop: <true|false>
+
+Read role_spec file to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
+  }]
+})
+```
+
+3. **Parallel spawn rules**:
+
+| Mode | Scenario | Spawn Behavior |
+|------|----------|---------------|
+| page | Each stage sequential | One worker at a time |
+| feature | After QA-001 arch review | Spawn DEV-001 |
+| system | After QA-001 arch review | Spawn ARCH-002 + DEV-001 in parallel |
+
+4. STOP after spawning -- use `wait_agent({ ids: [<spawned-agent-ids>] })` to wait for next callback
+
+### handleCheck
+
+Output current pipeline status.
+
+```
+Pipeline Status (<mode> mode):
+  [DONE]  ANALYZE-001  (analyst)    -> design-intelligence.json
+  [DONE]  ARCH-001     (architect)  -> design-tokens.json
+  [RUN]   DEV-001      (developer)  -> implementing...
+  [WAIT]  QA-001       (qa)         -> blocked by DEV-001
+
+GC Rounds: 0/2
+Session: <session-id>
+```
+
+Output status -- do NOT advance pipeline.
+
+### handleResume
+
+Resume pipeline after user pause or interruption.
+
+1. Audit tasks.json for inconsistencies:
+   - Tasks stuck in "in_progress" -> reset to "pending"
+   - Tasks with completed blockers but still "pending" -> include in spawn list
+2. Proceed to handleSpawnNext
+
+### handleComplete
+
+Triggered when all pipeline tasks are completed.
+
+**Completion check**:
+
+| Mode | Completion Condition |
+|------|---------------------|
+| page | All 4 tasks (+ any GC fix/recheck tasks) completed |
+| feature | All 5 tasks (+ any GC fix/recheck tasks) completed |
+| system | All 7 tasks (+ any GC fix/recheck tasks) completed |
+
+1. If any tasks not completed, return to handleSpawnNext
+2. If all completed, transition to coordinator Phase 5
+
+## Phase 4: State Persistence
+
+After every handler execution:
+
+1. Update session.json with current state (active tasks, gc_rounds, last event)
+2. Verify tasks.json consistency
+3. STOP and wait for next event