fix: merge PR #139 partial — hook path fixes, TaskDrawer multi-source files, lite-tasks URL params

Cherry-pick valid changes from PR #139 (fix/webuibugs-20260314).
CodexLens build tools check dropped — target files deleted in 398601f8.

Changes included:
- Fix hook query key (rulesList → hooksList) and projectPath in cache ops
- Pass projectPath to hook template install API calls
- TaskDrawer: get files from nt.files, flowControl.target_files, or sourceRaw.file
- LiteTasksPage: support URL params (:subType/:id) to auto-open task drawer
- Add lite-tasks/:subType/:id route

Closes #139

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.ccw/personal/coding-style.md

@@ -0,0 +1,27 @@
+---
+title: "Personal Coding Style"
+dimension: personal
+category: general
+keywords:
+  - style
+  - preference
+readMode: optional
+priority: medium
+---
+
+# Personal Coding Style
+
+## Preferences
+
+- Describe your preferred coding style here
+- Example: verbose variable names vs terse, functional vs imperative
+
+## Patterns I Prefer
+
+- List patterns you reach for most often
+- Example: builder pattern, factory functions, tagged unions
+
+## Things I Avoid
+
+- List anti-patterns or approaches you dislike
+- Example: deep inheritance hierarchies, magic strings

.ccw/personal/tool-preferences.md

@@ -0,0 +1,25 @@
+---
+title: "Tool Preferences"
+dimension: personal
+category: general
+keywords:
+  - tool
+  - cli
+  - editor
+readMode: optional
+priority: low
+---
+
+# Tool Preferences
+
+## Editor
+
+- Preferred editor and key extensions/plugins
+
+## CLI Tools
+
+- Preferred shell, package manager, build tools
+
+## Debugging
+
+- Preferred debugging approach and tools

.ccw/specs/architecture-constraints.md

@@ -1,3 +1,13 @@
+---
+title: Architecture Constraints
+readMode: optional
+priority: medium
+category: general
+scope: project
+dimension: specs
+keywords: [architecture, constraint, schema, compatibility, portability, design, arch]
+---
+
 # Architecture Constraints
 
 ## Schema Evolution

.ccw/specs/coding-conventions.md

@@ -1,3 +1,13 @@
+---
+title: Coding Conventions
+readMode: optional
+priority: medium
+category: general
+scope: project
+dimension: specs
+keywords: [coding, convention, style, naming, pattern, navigation, schema, error-handling, implementation, validation, clarity, doc]
+---
+
 # Coding Conventions
 
 ## Navigation & Path Handling
@@ -9,6 +19,7 @@
 ## Document Generation
 
 - [architecture] For document generation systems, adopt Layer 3→2→1 pattern (components → features → indexes) for efficient incremental updates. (learned: 2026-03-07)
+- [tools] When commands need to generate files with deterministic paths and frontmatter, use dedicated ccw tool endpoints (`ccw tool exec`) instead of raw `ccw cli -p` calls. Endpoints control output path, file naming, and structural metadata; CLI tools only generate prose content. (learned: 2026-03-09)
 
 ## Implementation Quality
 

.ccw/workflows/context-tools.md

@@ -1,76 +0,0 @@
-## Context Acquisition (MCP Tools Priority)
-
-**For task context gathering and analysis, ALWAYS prefer MCP tools**:
-
-1. **mcp__ace-tool__search_context** - HIGHEST PRIORITY for code discovery
-   - Semantic search with real-time codebase index
-   - Use for: finding implementations, understanding architecture, locating patterns
-   - Example: `mcp__ace-tool__search_context(project_root_path="/path", query="authentication logic")`
-
-2. **smart_search** - Fallback for structured search
-   - Use `smart_search(query="...")` for keyword/regex search
-   - Use `smart_search(action="find_files", pattern="*.ts")` for file discovery
-   - Supports modes: `auto`, `hybrid`, `exact`, `ripgrep`
-
-3. **read_file** - Batch file reading
-   - Read multiple files in parallel: `read_file(path="file1.ts")`, `read_file(path="file2.ts")`
-   - Supports glob patterns: `read_file(path="src/**/*.config.ts")`
-
-**Priority Order**:
-```
-ACE search_context (semantic) → smart_search (structured) → read_file (batch read) → shell commands (fallback)
-```
-
-**NEVER** use shell commands (`cat`, `find`, `grep`) when MCP tools are available.
-### read_file - Read File Contents
-
-**When**: Read files found by smart_search
-
-**How**:
-```javascript
-read_file(path="/path/to/file.ts")                   // Single file
-read_file(path="/src/**/*.config.ts")                // Pattern matching
-```
-
----
-
-### edit_file - Modify Files
-
-**When**: Built-in Edit tool fails or need advanced features
-
-**How**:
-```javascript
-edit_file(path="/file.ts", old_string="...", new_string="...", mode="update")
-edit_file(path="/file.ts", line=10, content="...", mode="insert_after")
-```
-
-**Modes**: `update` (replace text), `insert_after`, `insert_before`, `delete_line`
-
----
-
-### write_file - Create/Overwrite Files
-
-**When**: Create new files or completely replace content
-
-**How**:
-```javascript
-write_file(path="/new-file.ts", content="...")
-```
-
----
-
-### Exa - External Search
-
-**When**: Find documentation/examples outside codebase
-
-**How**:
-```javascript
-mcp__exa__search(query="React hooks 2025 documentation")
-mcp__exa__search(query="FastAPI auth example", numResults=10)
-mcp__exa__search(query="latest API docs", livecrawl="always")
-```
-
-**Parameters**:
-- `query` (required): Search query string
-- `numResults` (optional): Number of results to return (default: 5)
-- `livecrawl` (optional): `"always"` or `"fallback"` for live crawling

.ccw/workflows/file-modification.md

@@ -1,64 +0,0 @@
-# File Modification
-
-Before modifying files, always:
-- Try built-in Edit tool first
-- Escalate to MCP tools when built-ins fail
-- Use write_file only as last resort
-
-## MCP Tools Usage
-
-### edit_file - Modify Files
-
-**When**: Built-in Edit fails, need dry-run preview, or need line-based operations
-
-**How**:
-```javascript
-edit_file(path="/file.ts", oldText="old", newText="new")              // Replace text
-edit_file(path="/file.ts", oldText="old", newText="new", dryRun=true) // Preview diff
-edit_file(path="/file.ts", oldText="old", newText="new", replaceAll=true) // Replace all
-edit_file(path="/file.ts", mode="line", operation="insert_after", line=10, text="new line")
-edit_file(path="/file.ts", mode="line", operation="delete", line=5, end_line=8)
-```
-
-**Modes**: `update` (replace text, default), `line` (line-based operations)
-
-**Operations** (line mode): `insert_before`, `insert_after`, `replace`, `delete`
-
----
-
-### write_file - Create/Overwrite Files
-
-**When**: Create new files, completely replace content, or edit_file still fails
-
-**How**:
-```javascript
-write_file(path="/new-file.ts", content="file content here")
-write_file(path="/existing.ts", content="...", backup=true)  // Create backup first
-```
-
----
-
-## Priority Logic
-
-> **Note**: Search priority is defined in `context-tools.md` - smart_search has HIGHEST PRIORITY for all discovery tasks.
-
-**Search & Discovery** (defer to context-tools.md):
-1. **smart_search FIRST** for any code/file discovery
-2. Built-in Grep only for single-file exact line search (location already confirmed)
-3. Exa for external/public knowledge
-
-**File Reading**:
-1. Unknown location → **smart_search first**, then Read
-2. Known confirmed file → Built-in Read directly
-3. Pattern matching → smart_search (action="find_files")
-
-**File Editing**:
-1. Always try built-in Edit first
-2. Fails 1+ times → edit_file (MCP)
-3. Still fails → write_file (MCP)
-
-## Decision Triggers
-
-**Search tasks** → Always start with smart_search (per context-tools.md)
-**Known file edits** → Start with built-in Edit, escalate to MCP if fails
-**External knowledge** → Use Exa

.ccw/workflows/review-directory-specification.md

@@ -1,336 +0,0 @@
-# Review Directory Specification
-
-## Overview
-
-Unified directory structure for all review commands (session-based and module-based) within workflow sessions.
-
-## Core Principles
-
-1. **Session-Based**: All reviews run within a workflow session context
-2. **Unified Structure**: Same directory layout for all review types
-3. **Type Differentiation**: Review type indicated by metadata, not directory structure
-4. **Progressive Creation**: Directories created on-demand during review execution
-5. **Archive Support**: Reviews archived with their parent session
-
-## Directory Structure
-
-### Base Location
-```
-.workflow/active/WFS-{session-id}/.review/
-```
-
-### Complete Structure
-```
-.workflow/active/WFS-{session-id}/.review/
-├── review-state.json              # Review orchestrator state machine
-├── review-progress.json           # Real-time progress for dashboard polling
-├── review-metadata.json           # Review configuration and scope
-├── dimensions/                    # Per-dimension analysis results
-│   ├── security.json
-│   ├── architecture.json
-│   ├── quality.json
-│   ├── action-items.json
-│   ├── performance.json
-│   ├── maintainability.json
-│   └── best-practices.json
-├── iterations/                    # Deep-dive iteration results
-│   ├── iteration-1-finding-{uuid}.json
-│   ├── iteration-2-finding-{uuid}.json
-│   └── ...
-├── reports/                       # Human-readable reports
-│   ├── security-analysis.md
-│   ├── security-cli-output.txt
-│   ├── architecture-analysis.md
-│   ├── architecture-cli-output.txt
-│   ├── ...
-│   ├── deep-dive-1-{uuid}.md
-│   └── deep-dive-2-{uuid}.md
-├── REVIEW-SUMMARY.md              # Final consolidated summary
-└── dashboard.html                 # Interactive review dashboard
-```
-
-## Review Metadata Schema
-
-**File**: `review-metadata.json`
-
-```json
-{
-  "review_id": "review-20250125-143022",
-  "review_type": "module|session",
-  "session_id": "WFS-auth-system",
-  "created_at": "2025-01-25T14:30:22Z",
-  "scope": {
-    "type": "module|session",
-    "module_scope": {
-      "target_pattern": "src/auth/**",
-      "resolved_files": [
-        "src/auth/service.ts",
-        "src/auth/validator.ts"
-      ],
-      "file_count": 2
-    },
-    "session_scope": {
-      "commit_range": "abc123..def456",
-      "changed_files": [
-        "src/auth/service.ts",
-        "src/payment/processor.ts"
-      ],
-      "file_count": 2
-    }
-  },
-  "dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
-  "max_iterations": 3,
-  "cli_tools": {
-    "primary": "gemini",
-    "fallback": ["qwen", "codex"]
-  }
-}
-```
-
-## Review State Schema
-
-**File**: `review-state.json`
-
-```json
-{
-  "review_id": "review-20250125-143022",
-  "phase": "init|parallel|aggregate|iterate|complete",
-  "current_iteration": 1,
-  "dimensions_status": {
-    "security": "pending|in_progress|completed|failed",
-    "architecture": "completed",
-    "quality": "in_progress",
-    "action-items": "pending",
-    "performance": "pending",
-    "maintainability": "pending",
-    "best-practices": "pending"
-  },
-  "severity_distribution": {
-    "critical": 2,
-    "high": 5,
-    "medium": 12,
-    "low": 8
-  },
-  "critical_files": [
-    "src/auth/service.ts",
-    "src/payment/processor.ts"
-  ],
-  "iterations": [
-    {
-      "iteration": 1,
-      "findings_selected": ["uuid-1", "uuid-2", "uuid-3"],
-      "completed_at": "2025-01-25T15:30:00Z"
-    }
-  ],
-  "completion_criteria": {
-    "critical_count": 0,
-    "high_count_threshold": 5,
-    "max_iterations": 3
-  },
-  "next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete"
-}
-```
-
-## Session Integration
-
-### Session Discovery
-
-**review-session-cycle** (auto-discover):
-```bash
-# Auto-detect active session
-/workflow:review-session-cycle
-
-# Or specify session explicitly
-/workflow:review-session-cycle WFS-auth-system
-```
-
-**review-module-cycle** (require session):
-```bash
-# Must have active session or specify one
-/workflow:review-module-cycle src/auth/** --session WFS-auth-system
-
-# Or use active session
-/workflow:review-module-cycle src/auth/**
-```
-
-### Session Creation Logic
-
-**For review-module-cycle**:
-
-1. **Check Active Session**: Search `.workflow/active/WFS-*`
-2. **If Found**: Use active session's `.review/` directory
-3. **If Not Found**:
-   - **Option A** (Recommended): Prompt user to create session first
-   - **Option B**: Auto-create review-only session: `WFS-review-{pattern-hash}`
-
-**Recommended Flow**:
-```bash
-# Step 1: Start session
-/workflow:session:start --new "Review auth module"
-# Creates: .workflow/active/WFS-review-auth-module/
-
-# Step 2: Run review
-/workflow:review-module-cycle src/auth/**
-# Creates: .workflow/active/WFS-review-auth-module/.review/
-```
-
-## Command Phase 1 Requirements
-
-### Both Commands Must:
-
-1. **Session Discovery**:
-   ```javascript
-   // Check for active session
-   const sessions = Glob('.workflow/active/WFS-*');
-   if (sessions.length === 0) {
-     // Prompt user to create session first
-     error("No active session found. Please run /workflow:session:start first");
-   }
-   const sessionId = sessions[0].match(/WFS-[^/]+/)[0];
-   ```
-
-2. **Create .review/ Structure**:
-   ```javascript
-   const reviewDir = `.workflow/active/${sessionId}/.review/`;
-
-   // Create directory structure
-   Bash(`mkdir -p ${reviewDir}/dimensions`);
-   Bash(`mkdir -p ${reviewDir}/iterations`);
-   Bash(`mkdir -p ${reviewDir}/reports`);
-   ```
-
-3. **Initialize Metadata**:
-   ```javascript
-   // Write review-metadata.json
-   Write(`${reviewDir}/review-metadata.json`, JSON.stringify({
-     review_id: `review-${timestamp}`,
-     review_type: "module|session",
-     session_id: sessionId,
-     created_at: new Date().toISOString(),
-     scope: {...},
-     dimensions: [...],
-     max_iterations: 3,
-     cli_tools: {...}
-   }));
-
-   // Write review-state.json
-   Write(`${reviewDir}/review-state.json`, JSON.stringify({
-     review_id: `review-${timestamp}`,
-     phase: "init",
-     current_iteration: 0,
-     dimensions_status: {},
-     severity_distribution: {},
-     critical_files: [],
-     iterations: [],
-     completion_criteria: {},
-     next_action: "execute_parallel_reviews"
-   }));
-   ```
-
-4. **Generate Dashboard**:
-   ```javascript
-   const template = Read('~/.claude/templates/review-cycle-dashboard.html');
-   const dashboard = template
-     .replace('{{SESSION_ID}}', sessionId)
-     .replace('{{REVIEW_TYPE}}', reviewType)
-     .replace('{{REVIEW_DIR}}', reviewDir);
-   Write(`${reviewDir}/dashboard.html`, dashboard);
-
-   // Output to user
-   console.log(`📊 Review Dashboard: file://${absolutePath(reviewDir)}/dashboard.html`);
-   console.log(`📂 Review Output: ${reviewDir}`);
-   ```
-
-## Archive Strategy
-
-### On Session Completion
-
-When `/workflow:session:complete` is called:
-
-1. **Preserve Review Directory**:
-   ```javascript
-   // Move entire session including .review/
-   Bash(`mv .workflow/active/${sessionId} .workflow/archives/${sessionId}`);
-   ```
-
-2. **Review Archive Structure**:
-   ```
-   .workflow/archives/WFS-auth-system/
-   ├── workflow-session.json
-   ├── IMPL_PLAN.md
-   ├── TODO_LIST.md
-   ├── .task/
-   ├── .summaries/
-   └── .review/                    # Review results preserved
-       ├── review-metadata.json
-       ├── REVIEW-SUMMARY.md
-       └── dashboard.html
-   ```
-
-3. **Access Archived Reviews**:
-   ```bash
-   # Open archived dashboard
-   start .workflow/archives/WFS-auth-system/.review/dashboard.html
-   ```
-
-## Benefits
-
-### 1. Unified Structure
-- Same directory layout for all review types
-- Consistent file naming and schemas
-- Easier maintenance and tooling
-
-### 2. Session Integration
-- Review history tracked with implementation
-- Easy correlation between code changes and reviews
-- Simplified archiving and retrieval
-
-### 3. Progressive Creation
-- Directories created only when needed
-- No upfront overhead
-- Clean session initialization
-
-### 4. Type Flexibility
-- Module-based and session-based reviews in same structure
-- Type indicated by metadata, not directory layout
-- Easy to add new review types
-
-### 5. Dashboard Consistency
-- Same dashboard template for both types
-- Unified progress tracking
-- Consistent user experience
-
-## Migration Path
-
-### For Existing Commands
-
-**review-session-cycle**:
-1. Change output from `.workflow/.reviews/session-{id}/` to `.workflow/active/{session-id}/.review/`
-2. Update Phase 1 to use session discovery
-3. Add review-metadata.json creation
-
-**review-module-cycle**:
-1. Add session requirement (or auto-create)
-2. Change output from `.workflow/.reviews/module-{hash}/` to `.workflow/active/{session-id}/.review/`
-3. Update Phase 1 to use session discovery
-4. Add review-metadata.json creation
-
-### Backward Compatibility
-
-**For existing standalone reviews** in `.workflow/.reviews/`:
-- Keep for reference
-- Document migration in README
-- Provide migration script if needed
-
-## Implementation Checklist
-
-- [ ] Update workflow-architecture.md with .review/ structure
-- [ ] Update review-session-cycle.md command specification
-- [ ] Update review-module-cycle.md command specification
-- [ ] Update review-cycle-dashboard.html template
-- [ ] Create review-metadata.json schema validation
-- [ ] Update /workflow:session:complete to preserve .review/
-- [ ] Update documentation examples
-- [ ] Test both review types with new structure
-- [ ] Validate dashboard compatibility
-- [ ] Document migration path for existing reviews

.ccw/workflows/task-core.md

@@ -1,214 +0,0 @@
-# Task System Core Reference
-
-## Overview
-Task commands provide single-execution workflow capabilities with full context awareness, hierarchical organization, and agent orchestration.
-
-## Task JSON Schema
-All task files use this simplified 5-field schema:
-
-```json
-{
-  "id": "IMPL-1.2",
-  "title": "Implement JWT authentication",
-  "status": "pending|active|completed|blocked|container",
-
-  "meta": {
-    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
-    "agent": "@code-developer|@action-planning-agent|@test-fix-agent|@universal-executor"
-  },
-
-  "context": {
-    "requirements": ["JWT authentication", "OAuth2 support"],
-    "focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
-    "acceptance": ["JWT validation works", "OAuth flow complete"],
-    "parent": "IMPL-1",
-    "depends_on": ["IMPL-1.1"],
-    "inherited": {
-      "from": "IMPL-1",
-      "context": ["Authentication system design completed"]
-    },
-    "shared_context": {
-      "auth_strategy": "JWT with refresh tokens"
-    }
-  },
-
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "gather_context",
-        "action": "Read dependency summaries",
-        "command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)",
-        "output_to": "auth_design_context",
-        "on_error": "skip_optional"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Implement JWT authentication system",
-        "description": "Implement comprehensive JWT authentication system with token generation, validation, and refresh logic",
-        "modification_points": ["Add JWT token generation", "Implement token validation middleware", "Create refresh token logic"],
-        "logic_flow": ["User login request → validate credentials", "Generate JWT access and refresh tokens", "Store refresh token securely", "Return tokens to client"],
-        "depends_on": [],
-        "output": "jwt_implementation"
-      }
-    ],
-    "target_files": [
-      "src/auth/login.ts:handleLogin:75-120",
-      "src/middleware/auth.ts:validateToken",
-      "src/auth/PasswordReset.ts"
-    ]
-  }
-}
-```
-
-## Field Structure Details
-
-### focus_paths Field (within context)
-**Purpose**: Specifies concrete project paths relevant to task implementation
-
-**Format**:
-- **Array of strings**: `["folder1", "folder2", "specific_file.ts"]`
-- **Concrete paths**: Use actual directory/file names without wildcards
-- **Mixed types**: Can include both directories and specific files
-- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
-
-**Examples**:
-```json
-// Authentication system task
-"focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
-
-// UI component task
-"focus_paths": ["src/components/Button", "src/styles", "tests/components"]
-```
-
-### flow_control Field Structure
-**Purpose**: Universal process manager for task execution
-
-**Components**:
-- **pre_analysis**: Array of sequential process steps
-- **implementation_approach**: Task execution strategy
-- **target_files**: Files to modify/create - existing files in `file:function:lines` format, new files as `file` only
-
-**Step Structure**:
-```json
-{
-  "step": "gather_context",
-  "action": "Human-readable description",
-  "command": "bash(executable command with [variables])",
-  "output_to": "variable_name",
-  "on_error": "skip_optional|fail|retry_once|manual_intervention"
-}
-```
-
-## Hierarchical System
-
-### Task Hierarchy Rules
-- **Format**: IMPL-N (main), IMPL-N.M (subtasks) - uppercase required
-- **Maximum Depth**: 2 levels only
-- **10-Task Limit**: Hard limit enforced across all tasks
-- **Container Tasks**: Parents with subtasks (not executable)
-- **Leaf Tasks**: No subtasks (executable)
-- **File Cohesion**: Related files must stay in same task
-
-### Task Complexity Classifications
-- **Simple**: ≤5 tasks, single-level tasks, direct execution
-- **Medium**: 6-10 tasks, two-level hierarchy, context coordination
-- **Over-scope**: >10 tasks requires project re-scoping into iterations
-
-### Complexity Assessment Rules
-- **Creation**: System evaluates and assigns complexity
-- **10-task limit**: Hard limit enforced - exceeding requires re-scoping
-- **Execution**: Can upgrade (Simple→Medium→Over-scope), triggers re-scoping
-- **Override**: Users can manually specify complexity within 10-task limit
-
-### Status Rules
-- **pending**: Ready for execution
-- **active**: Currently being executed
-- **completed**: Successfully finished
-- **blocked**: Waiting for dependencies
-- **container**: Has subtasks (parent only)
-
-## Session Integration
-
-### Active Session Detection
-```bash
-# Check for active session in sessions directory
-active_session=$(find .workflow/active/ -name 'WFS-*' -type d 2>/dev/null | head -1)
-```
-
-### Workflow Context Inheritance
-Tasks inherit from:
-1. `workflow-session.json` - Session metadata
-2. Parent task context (for subtasks)
-3. `IMPL_PLAN.md` - Planning document
-
-### File Locations
-- **Task JSON**: `.workflow/active/WFS-[topic]/.task/IMPL-*.json` (uppercase required)
-- **Session State**: `.workflow/active/WFS-[topic]/workflow-session.json`
-- **Planning Doc**: `.workflow/active/WFS-[topic]/IMPL_PLAN.md`
-- **Progress**: `.workflow/active/WFS-[topic]/TODO_LIST.md`
-
-## Agent Mapping
-
-### Automatic Agent Selection
-- **@code-developer**: Implementation tasks, coding, test writing
-- **@action-planning-agent**: Design, architecture planning
-- **@test-fix-agent**: Test execution, failure diagnosis, code fixing
-- **@universal-executor**: Optional manual review (only when explicitly requested)
-
-### Agent Context Filtering
-Each agent receives tailored context:
-- **@code-developer**: Complete implementation details, test requirements
-- **@action-planning-agent**: High-level requirements, risks, architecture
-- **@test-fix-agent**: Test execution, failure diagnosis, code fixing
-- **@universal-executor**: Quality standards, security considerations (when requested)
-
-## Deprecated Fields
-
-### Legacy paths Field
-**Deprecated**: The semicolon-separated `paths` field has been replaced by `context.focus_paths` array.
-
-**Old Format** (no longer used):
-```json
-"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts"
-```
-
-**New Format** (use this instead):
-```json
-"context": {
-  "focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
-}
-```
-
-## Validation Rules
-
-### Pre-execution Checks
-1. Task exists and is valid JSON
-2. Task status allows operation
-3. Dependencies are met
-4. Active workflow session exists
-5. All 5 core fields present (id, title, status, meta, context, flow_control)
-6. Total task count ≤ 10 (hard limit)
-7. File cohesion maintained in focus_paths
-
-### Hierarchy Validation
-- Parent-child relationships valid
-- Maximum depth not exceeded
-- Container tasks have subtasks
-- No circular dependencies
-
-## Error Handling Patterns
-
-### Common Errors
-- **Task not found**: Check ID format and session
-- **Invalid status**: Verify task can be operated on
-- **Missing session**: Ensure active workflow exists
-- **Max depth exceeded**: Restructure hierarchy
-- **Missing implementation**: Complete required fields
-
-### Recovery Strategies
-- Session validation with clear guidance
-- Automatic ID correction suggestions
-- Implementation field completion prompts
-- Hierarchy restructuring options

.ccw/workflows/tool-strategy.md

@@ -1,216 +0,0 @@
-# Tool Strategy - When to Use What
-
-> **Focus**: Decision triggers and selection logic, NOT syntax (already registered with Claude)
-
-## Quick Decision Tree
-
-```
-Need context?
-├─ Exa available? → Use Exa (fastest, most comprehensive)
-├─ Large codebase (>500 files)? → codex_lens
-├─ Known files (<5)? → Read tool
-└─ Unknown files? → smart_search → Read tool
-
-Need to modify files?
-├─ Built-in Edit fails? → mcp__ccw-tools__edit_file
-└─ Still fails? → mcp__ccw-tools__write_file
-
-Need to search?
-├─ Semantic/concept search? → smart_search (mode=semantic)
-├─ Exact pattern match? → Grep tool
-└─ Multiple search modes needed? → smart_search (mode=auto)
-```
-
----
-
-## 1. Context Gathering Tools
-
-### Exa (`mcp__exa__get_code_context_exa`)
-
-**Use When**:
-- ✅ Researching external APIs, libraries, frameworks
-- ✅ Need recent documentation (post-cutoff knowledge)
-- ✅ Looking for implementation examples in public repos
-- ✅ Comparing architectural patterns across projects
-
-**Don't Use When**:
-- ❌ Searching internal codebase (use smart_search/codex_lens)
-- ❌ Files already in working directory (use Read)
-
-**Trigger Indicators**:
-- User mentions specific library/framework names
-- Questions about "best practices", "how does X work"
-- Need to verify current API signatures
-
----
-
-### read_file (`mcp__ccw-tools__read_file`)
-
-**Use When**:
-- ✅ Reading multiple related files at once (batch reading)
-- ✅ Need directory traversal with pattern matching
-- ✅ Searching file content with regex (`contentPattern`)
-- ✅ Want to limit depth/file count for large directories
-
-**Don't Use When**:
-- ❌ Single file read → Use built-in Read tool (faster)
-- ❌ Unknown file locations → Use smart_search first
-- ❌ Need semantic search → Use smart_search or codex_lens
-
-**Trigger Indicators**:
-- Need to read "all TypeScript files in src/"
-- Need to find "files containing TODO comments"
-- Want to read "up to 20 config files"
-
-**Advantages over Built-in Read**:
-- Batch operation (multiple files in one call)
-- Pattern-based filtering (glob + content regex)
-- Directory traversal with depth control
-
----
-
-### codex_lens (`mcp__ccw-tools__codex_lens`)
-
-**Use When**:
-- ✅ Large codebase (>500 files) requiring repeated searches
-- ✅ Need semantic understanding of code relationships
-- ✅ Working across multiple sessions (persistent index)
-- ✅ Symbol-level navigation needed
-
-**Don't Use When**:
-- ❌ Small project (<100 files) → Use smart_search (no indexing overhead)
-- ❌ One-time search → Use smart_search or Grep
-- ❌ Files change frequently → Indexing overhead not worth it
-
-**Trigger Indicators**:
-- "Find all implementations of interface X"
-- "What calls this function across the codebase?"
-- Multi-session workflow on same codebase
-
-**Action Selection**:
-- `init`: First time in new codebase
-- `search`: Find code patterns
-- `search_files`: Find files by path/name pattern
-- `symbol`: Get symbols in specific file
-- `status`: Check if index exists/is stale
-- `clean`: Remove stale index
-
----
-
-### smart_search (`mcp__ccw-tools__smart_search`)
-
-**Use When**:
-- ✅ Don't know exact file locations
-- ✅ Need concept/semantic search ("authentication logic")
-- ✅ Medium-sized codebase (100-500 files)
-- ✅ One-time or infrequent searches
-
-**Don't Use When**:
-- ❌ Known exact file path → Use Read directly
-- ❌ Large codebase + repeated searches → Use codex_lens
-- ❌ Exact pattern match → Use Grep (faster)
-
-**Mode Selection**:
-- `auto`: Let tool decide (default, safest)
-- `exact`: Know exact pattern, need fast results
-- `fuzzy`: Typo-tolerant file/symbol names
-- `semantic`: Concept-based ("error handling", "data validation")
-- `graph`: Dependency/relationship analysis
-
-**Trigger Indicators**:
-- "Find files related to user authentication"
-- "Where is the payment processing logic?"
-- "Locate database connection setup"
-
----
-
-## 2. File Modification Tools
-
-### edit_file (`mcp__ccw-tools__edit_file`)
-
-**Use When**:
-- ✅ Built-in Edit tool failed 1+ times
-- ✅ Need dry-run preview before applying
-- ✅ Need line-based operations (insert_after, insert_before)
-- ✅ Need to replace all occurrences
-
-**Don't Use When**:
-- ❌ Built-in Edit hasn't failed yet → Try built-in first
-- ❌ Need to create new file → Use write_file
-
-**Trigger Indicators**:
-- Built-in Edit returns "old_string not found"
-- Built-in Edit fails due to whitespace/formatting
-- Need to verify changes before applying (dryRun=true)
-
-**Mode Selection**:
-- `mode=update`: Replace text (similar to built-in Edit)
-- `mode=line`: Line-based operations (insert_after, insert_before, delete)
-
----
-
-### write_file (`mcp__ccw-tools__write_file`)
-
-**Use When**:
-- ✅ Creating brand new files
-- ✅ MCP edit_file still fails (last resort)
-- ✅ Need to completely replace file content
-- ✅ Need backup before overwriting
-
-**Don't Use When**:
-- ❌ File exists + small change → Use Edit tools
-- ❌ Built-in Edit hasn't been tried → Try built-in Edit first
-
-**Trigger Indicators**:
-- All Edit attempts failed
-- Need to create new file with specific content
-- User explicitly asks to "recreate file"
-
----
-
-## 3. Decision Logic
-
-### File Reading Priority
-
-```
-1. Known single file? → Built-in Read
-2. Multiple files OR pattern matching? → mcp__ccw-tools__read_file
-3. Unknown location? → smart_search, then Read
-4. Large codebase + repeated access? → codex_lens
-```
-
-### File Editing Priority
-
-```
-1. Always try built-in Edit first
-2. Fails 1+ times? → mcp__ccw-tools__edit_file
-3. Still fails? → mcp__ccw-tools__write_file (last resort)
-```
-
-### Search Tool Priority
-
-```
-1. External knowledge? → Exa
-2. Exact pattern in small codebase? → Built-in Grep
-3. Semantic/unknown location? → smart_search
-4. Large codebase + repeated searches? → codex_lens
-```
-
----
-
-## 4. Anti-Patterns
-
-**Don't**:
-- Use codex_lens for one-time searches in small projects
-- Use smart_search when file path is already known
-- Use write_file before trying Edit tools
-- Use Exa for internal codebase searches
-- Use read_file for single file when Read tool works
-
-**Do**:
-- Start with simplest tool (Read, Edit, Grep)
-- Escalate to MCP tools when built-ins fail
-- Use semantic search (smart_search) for exploratory tasks
-- Use indexed search (codex_lens) for large, stable codebases
-- Use Exa for external/public knowledge
-

.ccw/workflows/workflow-architecture.md

@@ -1,942 +0,0 @@
-# Workflow Architecture
-
-## Overview
-
-This document defines the complete workflow system architecture using a **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition.
-
-## Core Architecture
-
-### JSON-Only Data Model
-**JSON files (.task/IMPL-*.json) are the only authoritative source of task state. All markdown documents are read-only generated views.**
-
-- **Task State**: Stored exclusively in JSON files
-- **Documents**: Generated on-demand from JSON data
-- **No Synchronization**: Eliminates bidirectional sync complexity
-- **Performance**: Direct JSON access without parsing overhead
-
-### Key Design Decisions
-- **JSON files are the single source of truth** - All markdown documents are read-only generated views
-- **Marker files for session tracking** - Ultra-simple active session management
-- **Unified file structure definition** - Same structure template for all workflows, created on-demand
-- **Dynamic task decomposition** - Subtasks created as needed during execution
-- **On-demand file creation** - Directories and files created only when required
-- **Agent-agnostic task definitions** - Complete context preserved for autonomous execution
-
-## Session Management
-
-### Directory-Based Session Management
-**Simple Location-Based Tracking**: Sessions in `.workflow/active/` directory
-
-```bash
-.workflow/
-├── active/
-│   ├── WFS-oauth-integration/         # Active session directory
-│   ├── WFS-user-profile/             # Active session directory
-│   └── WFS-bug-fix-123/              # Active session directory
-└── archives/
-    └── WFS-old-feature/              # Archived session (completed)
-```
-
-
-### Session Operations
-
-#### Detect Active Session(s)
-```bash
-active_sessions=$(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
-count=$(echo "$active_sessions" | wc -l)
-
-if [ -z "$active_sessions" ]; then
-  echo "No active session"
-elif [ "$count" -eq 1 ]; then
-  session_name=$(basename "$active_sessions")
-  echo "Active session: $session_name"
-else
-  echo "Multiple sessions found:"
-  echo "$active_sessions" | while read session_dir; do
-    session=$(basename "$session_dir")
-    echo "  - $session"
-  done
-  echo "Please specify which session to work with"
-fi
-```
-
-#### Archive Session
-```bash
-mv .workflow/active/WFS-feature .workflow/archives/WFS-feature
-```
-
-### Session State Tracking
-Each session directory contains `workflow-session.json`:
-
-```json
-{
-  "session_id": "WFS-[topic-slug]",
-  "project": "feature description",
-  "type": "simple|medium|complex",
-  "current_phase": "PLAN|IMPLEMENT|REVIEW",
-  "status": "active|paused|completed",
-  "progress": {
-    "completed_phases": ["PLAN"],
-    "current_tasks": ["IMPL-1", "IMPL-2"]
-  }
-}
-```
-
-## Task System
-
-### Hierarchical Task Structure
-**Maximum Depth**: 2 levels (IMPL-N.M format)
-
-```
-IMPL-1              # Main task
-IMPL-1.1            # Subtask of IMPL-1 (dynamically created)
-IMPL-1.2            # Another subtask of IMPL-1
-IMPL-2              # Another main task
-IMPL-2.1            # Subtask of IMPL-2 (dynamically created)
-```
-
-**Task Status Rules**:
-- **Container tasks**: Parent tasks with subtasks (cannot be directly executed)
-- **Leaf tasks**: Only these can be executed directly
-- **Status inheritance**: Parent status derived from subtask completion
-
-### Enhanced Task JSON Schema
-All task files use this unified 6-field schema with optional artifacts enhancement:
-
-```json
-{
-  "id": "IMPL-1.2",
-  "title": "Implement JWT authentication",
-  "status": "pending|active|completed|blocked|container",
-  "context_package_path": ".workflow/WFS-session/.process/context-package.json",
-
-  "meta": {
-    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
-    "agent": "@code-developer|@action-planning-agent|@test-fix-agent|@universal-executor"
-  },
-
-  "context": {
-    "requirements": ["JWT authentication", "OAuth2 support"],
-    "focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
-    "acceptance": ["JWT validation works", "OAuth flow complete"],
-    "parent": "IMPL-1",
-    "depends_on": ["IMPL-1.1"],
-    "inherited": {
-      "from": "IMPL-1",
-      "context": ["Authentication system design completed"]
-    },
-    "shared_context": {
-      "auth_strategy": "JWT with refresh tokens"
-    },
-    "artifacts": [
-      {
-        "type": "role_analyses",
-        "source": "brainstorm_clarification",
-        "path": ".workflow/WFS-session/.brainstorming/*/analysis*.md",
-        "priority": "highest",
-        "contains": "role_specific_requirements_and_design"
-      }
-    ]
-  },
-
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "check_patterns",
-        "action": "Analyze existing patterns",
-        "command": "bash(rg 'auth' [focus_paths] | head -10)",
-        "output_to": "patterns"
-      },
-      {
-        "step": "analyze_architecture",
-        "action": "Review system architecture",
-        "command": "gemini \"analyze patterns: [patterns]\"",
-        "output_to": "design"
-      },
-      {
-        "step": "check_deps",
-        "action": "Check dependencies",
-        "command": "bash(echo [depends_on] | xargs cat)",
-        "output_to": "context"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Set up authentication infrastructure",
-        "description": "Install JWT library and create auth config following [design] patterns from [parent]",
-        "modification_points": [
-          "Add JWT library dependencies to package.json",
-          "Create auth configuration file using [parent] patterns"
-        ],
-        "logic_flow": [
-          "Install jsonwebtoken library via npm",
-          "Configure JWT secret and expiration from [inherited]",
-          "Export auth config for use by [jwt_generator]"
-        ],
-        "depends_on": [],
-        "output": "auth_config"
-      },
-      {
-        "step": 2,
-        "title": "Implement JWT generation",
-        "description": "Create JWT token generation logic using [auth_config] and [inherited] validation patterns",
-        "modification_points": [
-          "Add JWT generation function in auth service",
-          "Implement token signing with [auth_config]"
-        ],
-        "logic_flow": [
-          "User login → validate credentials with [inherited]",
-          "Generate JWT payload with user data",
-          "Sign JWT using secret from [auth_config]",
-          "Return signed token"
-        ],
-        "depends_on": [1],
-        "output": "jwt_generator"
-      },
-      {
-        "step": 3,
-        "title": "Implement JWT validation middleware",
-        "description": "Create middleware to validate JWT tokens using [auth_config] and [shared] rules",
-        "modification_points": [
-          "Create validation middleware using [jwt_generator]",
-          "Add token verification using [shared] rules",
-          "Implement user attachment to request object"
-        ],
-        "logic_flow": [
-          "Protected route → extract JWT from Authorization header",
-          "Validate token signature using [auth_config]",
-          "Check token expiration and [shared] rules",
-          "Decode payload and attach user to request",
-          "Call next() or return 401 error"
-        ],
-        "command": "bash(npm test -- middleware.test.ts)",
-        "depends_on": [1, 2],
-        "output": "auth_middleware"
-      }
-    ],
-    "target_files": [
-      "src/auth/login.ts:handleLogin:75-120",
-      "src/middleware/auth.ts:validateToken",
-      "src/auth/PasswordReset.ts"
-    ]
-  }
-}
-```
-
-### Focus Paths & Context Management
-
-#### Context Package Path (Top-Level Field)
-The **context_package_path** field provides the location of the smart context package:
-- **Location**: Top-level field (not in `artifacts` array)
-- **Path**: `.workflow/WFS-session/.process/context-package.json`
-- **Purpose**: References the comprehensive context package containing project structure, dependencies, and brainstorming artifacts catalog
-- **Usage**: Loaded in `pre_analysis` steps via `Read({{context_package_path}})`
-
-#### Focus Paths Format
-The **focus_paths** field specifies concrete project paths for task implementation:
-- **Array of strings**: `["folder1", "folder2", "specific_file.ts"]`
-- **Concrete paths**: Use actual directory/file names without wildcards
-- **Mixed types**: Can include both directories and specific files
-- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
-
-#### Artifacts Field ⚠️ NEW FIELD
-Optional field referencing brainstorming outputs for task execution:
-
-```json
-"artifacts": [
-  {
-    "type": "role_analyses|topic_framework|individual_role_analysis",
-    "source": "brainstorm_clarification|brainstorm_framework|brainstorm_roles",
-    "path": ".workflow/WFS-session/.brainstorming/document.md",
-    "priority": "highest|high|medium|low"
-  }
-]
-```
-
-**Types & Priority**: role_analyses (highest) → topic_framework (medium) → individual_role_analysis (low)
-
-#### Flow Control Configuration
-The **flow_control** field manages task execution through structured sequential steps. For complete format specifications and usage guidelines, see [Flow Control Format Guide](#flow-control-format-guide) below.
-
-**Quick Reference**:
-- **pre_analysis**: Context gathering steps (supports multiple command types)
-- **implementation_approach**: Implementation steps array with dependency management
-- **target_files**: Target files for modification (file:function:lines format)
-- **Variable references**: Use `[variable_name]` to reference step outputs
-- **Tool integration**: Supports Gemini, Codex, Bash commands, and MCP tools
-
-## Flow Control Format Guide
-
-The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow control steps for sequential execution. There are **two distinct formats** used in different scenarios:
-
-### Format Comparison Matrix
-
-| Aspect | Inline Format | JSON Format |
-|--------|--------------|-------------|
-| **Used In** | Brainstorm workflows | Implementation tasks |
-| **Agent** | conceptual-planning-agent | code-developer, test-fix-agent, doc-generator |
-| **Location** | Task() prompt (markdown) | .task/IMPL-*.json file |
-| **Persistence** | Temporary (prompt-only) | Persistent (file storage) |
-| **Complexity** | Simple (3-5 steps) | Complex (10+ steps) |
-| **Dependencies** | None | Full `depends_on` support |
-| **Purpose** | Load brainstorming context | Implement task with preparation |
-
-### Inline Format (Brainstorm)
-
-**Marker**: `[FLOW_CONTROL]` written directly in Task() prompt
-
-**Structure**: Markdown list format
-
-**Used By**: Brainstorm commands (`auto-parallel.md`, role commands)
-
-**Agent**: `conceptual-planning-agent`
-
-**Example**:
-```markdown
-[FLOW_CONTROL]
-
-### Flow Control Steps
-**AGENT RESPONSIBILITY**: Execute these pre_analysis steps sequentially with context accumulation:
-
-1. **load_topic_framework**
-   - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
-   - Output: topic_framework
-
-2. **load_role_template**
-   - Action: Load role-specific planning template
-   - Command: bash($(cat "~/.ccw/workflows/cli-templates/planning-roles/{role}.md"))
-   - Output: role_template
-
-3. **load_session_metadata**
-   - Action: Load session metadata and topic description
-   - Command: bash(cat .workflow/WFS-{session}/workflow-session.json 2>/dev/null || echo '{}')
-   - Output: session_metadata
-```
-
-**Characteristics**:
-- 3-5 simple context loading steps
-- Written directly in prompt (not persistent)
-- No dependency management between steps
-- Used for temporary context preparation
-- Variables: `[variable_name]` for output references
-
-### JSON Format (Implementation)
-
-**Marker**: `[FLOW_CONTROL]` used in TodoWrite or documentation to indicate task has flow control
-
-**Structure**: Complete JSON structure in task file
-
-**Used By**: Implementation tasks (IMPL-*.json)
-
-**Agents**: `code-developer`, `test-fix-agent`, `doc-generator`
-
-**Example**:
-```json
-"flow_control": {
-  "pre_analysis": [
-    {
-      "step": "load_role_analyses",
-      "action": "Load role analysis documents from brainstorming",
-      "commands": [
-        "bash(ls .workflow/WFS-{session}/.brainstorming/*/analysis*.md 2>/dev/null || echo 'not found')",
-        "Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md)",
-        "Read(each discovered role analysis file)"
-      ],
-      "output_to": "role_analyses",
-      "on_error": "skip_optional"
-    },
-    {
-      "step": "local_codebase_exploration",
-      "action": "Explore codebase using local search",
-      "commands": [
-        "bash(rg '^(function|class|interface).*auth' --type ts -n --max-count 15)",
-        "bash(find . -name '*auth*' -type f | grep -v node_modules | head -10)"
-      ],
-      "output_to": "codebase_structure"
-    }
-  ],
-  "implementation_approach": [
-    {
-      "step": 1,
-      "title": "Setup infrastructure",
-      "description": "Install JWT library and create config following [role_analyses]",
-      "modification_points": [
-        "Add JWT library dependencies to package.json",
-        "Create auth configuration file"
-      ],
-      "logic_flow": [
-        "Install jsonwebtoken library via npm",
-        "Configure JWT secret from [role_analyses]",
-        "Export auth config for use by [jwt_generator]"
-      ],
-      "depends_on": [],
-      "output": "auth_config"
-    },
-    {
-      "step": 2,
-      "title": "Implement JWT generation",
-      "description": "Create JWT token generation logic using [auth_config]",
-      "modification_points": [
-        "Add JWT generation function in auth service",
-        "Implement token signing with [auth_config]"
-      ],
-      "logic_flow": [
-        "User login → validate credentials",
-        "Generate JWT payload with user data",
-        "Sign JWT using secret from [auth_config]",
-        "Return signed token"
-      ],
-      "depends_on": [1],
-      "output": "jwt_generator"
-    }
-  ],
-  "target_files": [
-    "src/auth/login.ts:handleLogin:75-120",
-    "src/middleware/auth.ts:validateToken"
-  ]
-}
-```
-
-**Characteristics**:
-- Persistent storage in .task/IMPL-*.json files
-- Complete dependency management (`depends_on` arrays)
-- Two-phase structure: `pre_analysis` + `implementation_approach`
-- Error handling strategies (`on_error` field)
-- Target file specifications
-- Variables: `[variable_name]` for cross-step references
-
-### JSON Format Field Specifications
-
-#### pre_analysis Field
-**Purpose**: Context gathering phase before implementation
-
-**Structure**: Array of step objects with sequential execution
-
-**Step Fields**:
-- **step**: Step identifier (string, e.g., "load_role_analyses")
-- **action**: Human-readable description of the step
-- **command** or **commands**: Single command string or array of command strings
-- **output_to**: Variable name for storing step output
-- **on_error**: Error handling strategy (`skip_optional`, `fail`, `retry_once`, `manual_intervention`)
-
-**Command Types Supported**:
-- **Bash commands**: `bash(command)` - Any shell command
-- **Tool calls**: `Read(file)`, `Glob(pattern)`, `Grep(pattern)`
-- **MCP tools**: `mcp__exa__get_code_context_exa()`, `mcp__exa__web_search_exa()`
-- **CLI commands**: `gemini`, `qwen`, `codex --full-auto exec`
-
-**Example**:
-```json
-{
-  "step": "load_context",
-  "action": "Load project context and patterns",
-  "commands": [
-    "bash(ccw tool exec get_modules_by_depth '{}')",
-    "Read(CLAUDE.md)"
-  ],
-  "output_to": "project_structure",
-  "on_error": "skip_optional"
-}
-```
-
-#### implementation_approach Field
-**Purpose**: Define implementation steps with dependency management
-
-**Structure**: Array of step objects (NOT object format)
-
-**Step Fields (All Required)**:
-- **step**: Unique step number (1, 2, 3, ...) - serves as step identifier
-- **title**: Brief step title
-- **description**: Comprehensive implementation description with context variable references
-- **modification_points**: Array of specific code modification targets
-- **logic_flow**: Array describing business logic execution sequence
-- **depends_on**: Array of step numbers this step depends on (e.g., `[1]`, `[1, 2]`) - empty array `[]` for independent steps
-- **output**: Output variable name that can be referenced by subsequent steps via `[output_name]`
-
-**Optional Fields**:
-- **command**: Command for step execution (supports any shell command or CLI tool)
-  - When omitted: Agent interprets modification_points and logic_flow to execute
-  - When specified: Command executes the step directly
-
-**Execution Modes**:
-- **Default (without command)**: Agent executes based on modification_points and logic_flow
-- **With command**: Specified command handles execution
-
-**Command Field Usage**:
-- **Default approach**: Omit command field - let agent execute autonomously
-- **CLI tools (codex/gemini/qwen)**: Add ONLY when user explicitly requests CLI tool usage
-- **Simple commands**: Can include bash commands, test commands, validation scripts
-- **Complex workflows**: Use command for multi-step operations or tool coordination
-
-**Command Format Examples** (only when explicitly needed):
-```json
-// Simple Bash
-"command": "bash(npm install package)"
-"command": "bash(npm test)"
-
-// Validation
-"command": "bash(test -f config.ts && grep -q 'JWT_SECRET' config.ts)"
-
-// Codex (user requested)
-"command": "codex -C path --full-auto exec \"task\" --skip-git-repo-check -s danger-full-access"
-
-// Codex Resume (user requested, maintains context)
-"command": "codex --full-auto exec \"task\" resume --last --skip-git-repo-check -s danger-full-access"
-
-// Gemini (user requested)
-"command": "gemini \"analyze [context]\""
-
-// Qwen (fallback for Gemini)
-"command": "qwen \"analyze [context]\""
-```
-
-**Example Step**:
-```json
-{
-  "step": 2,
-  "title": "Implement JWT generation",
-  "description": "Create JWT token generation logic using [auth_config]",
-  "modification_points": [
-    "Add JWT generation function in auth service",
-    "Implement token signing with [auth_config]"
-  ],
-  "logic_flow": [
-    "User login → validate credentials",
-    "Generate JWT payload with user data",
-    "Sign JWT using secret from [auth_config]",
-    "Return signed token"
-  ],
-  "depends_on": [1],
-  "output": "jwt_generator"
-}
-```
-
-#### target_files Field
-**Purpose**: Specify files to be modified or created
-
-**Format**: Array of strings
-- **Existing files**: `"file:function:lines"` (e.g., `"src/auth/login.ts:handleLogin:75-120"`)
-- **New files**: `"path/to/NewFile.ts"` (file path only)
-
-### Tool Reference
-
-**Available Command Types**:
-
-**Gemini CLI**:
-```bash
-gemini "prompt"
-gemini --approval-mode yolo "prompt"  # For write mode
-```
-
-**Qwen CLI** (Gemini fallback):
-```bash
-qwen "prompt"
-qwen --approval-mode yolo "prompt"  # For write mode
-```
-
-**Codex CLI**:
-```bash
-codex -C directory --full-auto exec "task" --skip-git-repo-check -s danger-full-access
-codex --full-auto exec "task" resume --last --skip-git-repo-check -s danger-full-access
-```
-
-**Built-in Tools**:
-- `Read(file_path)` - Read file contents
-- `Glob(pattern)` - Find files by pattern
-- `Grep(pattern)` - Search content with regex
-- `bash(command)` - Execute bash command
-
-**MCP Tools**:
-- `mcp__exa__get_code_context_exa(query="...")` - Get code context from Exa
-- `mcp__exa__web_search_exa(query="...")` - Web search via Exa
-
-**Bash Commands**:
-```bash
-bash(rg 'pattern' src/)
-bash(find . -name "*.ts")
-bash(npm test)
-bash(git log --oneline | head -5)
-```
-
-### Variable System & Context Flow
-
-**Variable Reference Syntax**:
-Both formats use `[variable_name]` syntax for referencing outputs from previous steps.
-
-**Variable Types**:
-- **Step outputs**: `[step_output_name]` - Reference any pre_analysis step output
-- **Task properties**: `[task_property]` - Reference any task context field
-- **Previous results**: `[analysis_result]` - Reference accumulated context
-- **Implementation outputs**: Reference outputs from previous implementation steps
-
-**Examples**:
-```json
-// Reference pre_analysis output
-"description": "Install JWT library following [role_analyses]"
-
-// Reference previous step output
-"description": "Create middleware using [auth_config] and [jwt_generator]"
-
-// Reference task context
-"command": "bash(cd [focus_paths] && npm test)"
-```
-
-**Context Accumulation Process**:
-1. **Structure Analysis**: `get_modules_by_depth.sh` → project hierarchy
-2. **Pattern Analysis**: Tool-specific commands → existing patterns
-3. **Dependency Mapping**: Previous task summaries → inheritance context
-4. **Task Context Generation**: Combined analysis → task.context fields
-
-**Context Inheritance Rules**:
-- **Parent → Child**: Container tasks pass context via `context.inherited`
-- **Dependency → Dependent**: Previous task summaries via `context.depends_on`
-- **Session → Task**: Global session context included in all tasks
-- **Module → Feature**: Module patterns inform feature implementation
-
-### Agent Processing Rules
-
-**conceptual-planning-agent** (Inline Format):
-- Parses markdown list from prompt
-- Executes 3-5 simple loading steps
-- No dependency resolution needed
-- Accumulates context in variables
-- Used only in brainstorm workflows
-
-**code-developer, test-fix-agent** (JSON Format):
-- Loads complete task JSON from file
-- Executes `pre_analysis` steps sequentially
-- Processes `implementation_approach` with dependency resolution
-- Handles complex variable substitution
-- Updates task status in JSON file
-
-### Usage Guidelines
-
-**Use Inline Format When**:
-- Running brainstorm workflows
-- Need 3-5 simple context loading steps
-- No persistence required
-- No dependencies between steps
-- Temporary context preparation
-
-**Use JSON Format When**:
-- Implementing features or tasks
-- Need 10+ complex execution steps
-- Require dependency management
-- Need persistent task definitions
-- Complex variable flow between steps
-- Error handling strategies needed
-
-### Variable Reference Syntax
-
-Both formats use `[variable_name]` syntax for referencing outputs:
-
-**Inline Format**:
-```markdown
-2. **analyze_context**
-   - Action: Analyze using [topic_framework] and [role_template]
-   - Output: analysis_results
-```
-
-**JSON Format**:
-```json
-{
-  "step": 2,
-  "description": "Implement following [role_analyses] and [codebase_structure]",
-  "depends_on": [1],
-  "output": "implementation"
-}
-```
-
-### Task Validation Rules
-1. **ID Uniqueness**: All task IDs must be unique
-2. **Hierarchical Format**: Must follow IMPL-N[.M] pattern (maximum 2 levels)
-3. **Parent References**: All parent IDs must exist as JSON files
-4. **Status Consistency**: Status values from defined enumeration
-5. **Required Fields**: All 5 core fields must be present (id, title, status, meta, context, flow_control)
-6. **Focus Paths Structure**: context.focus_paths must contain concrete paths (no wildcards)
-7. **Flow Control Format**: pre_analysis must be array with required fields
-8. **Dependency Integrity**: All task-level depends_on references must exist as JSON files
-9. **Artifacts Structure**: context.artifacts (optional) must use valid type, priority, and path format
-10. **Implementation Steps Array**: implementation_approach must be array of step objects
-11. **Step Number Uniqueness**: All step numbers within a task must be unique and sequential (1, 2, 3, ...)
-12. **Step Dependencies**: All step-level depends_on numbers must reference valid steps within same task
-13. **Step Sequence**: Step numbers should match array order (first item step=1, second item step=2, etc.)
-14. **Step Required Fields**: Each step must have step, title, description, modification_points, logic_flow, depends_on, output
-15. **Step Optional Fields**: command field is optional - when omitted, agent executes based on modification_points and logic_flow
-
-## Workflow Structure
-
-### Unified File Structure
-All workflows use the same file structure definition regardless of complexity. **Directories and files are created on-demand as needed**, not all at once during initialization.
-
-#### Complete Structure Reference
-```
-.workflow/
-├── [.scratchpad/]              # Non-session-specific outputs (created when needed)
-│   ├── analyze-*-[timestamp].md        # One-off analysis results
-│   ├── chat-*-[timestamp].md           # Standalone chat sessions
-│   ├── plan-*-[timestamp].md           # Ad-hoc planning notes
-│   ├── bug-index-*-[timestamp].md      # Quick bug analyses
-│   ├── code-analysis-*-[timestamp].md  # Standalone code analysis
-│   ├── execute-*-[timestamp].md        # Ad-hoc implementation logs
-│   └── codex-execute-*-[timestamp].md  # Multi-stage execution logs
-│
-├── [design-run-*/]             # Standalone UI design outputs (created when needed)
-│   └── (timestamped)/          # Timestamped design runs without session
-│       ├── .intermediates/     # Intermediate analysis files
-│       │   ├── style-analysis/ # Style analysis data
-│       │   │   ├── computed-styles.json        # Extracted CSS values
-│       │   │   └── design-space-analysis.json  # Design directions
-│       │   └── layout-analysis/ # Layout analysis data
-│       │       ├── dom-structure-{target}.json # DOM extraction
-│       │       └── inspirations/               # Layout research
-│       │           └── {target}-layout-ideas.txt
-│       ├── style-extraction/   # Final design systems
-│       │   ├── style-1/        # design-tokens.json, style-guide.md
-│       │   └── style-N/
-│       ├── layout-extraction/  # Layout templates
-│       │   └── layout-templates.json
-│       ├── prototypes/         # Generated HTML/CSS prototypes
-│       │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
-│       │   ├── compare.html    # Interactive matrix view
-│       │   └── index.html      # Navigation page
-│       └── .run-metadata.json  # Run configuration
-│
-├── active/                          # Active workflow sessions
-│   └── WFS-[topic-slug]/
-│       ├── workflow-session.json        # Session metadata and state (REQUIRED)
-│       ├── [.brainstorming/]           # Optional brainstorming phase (created when needed)
-│       ├── [.chat/]                    # CLI interaction sessions (created when analysis is run)
-│       │   ├── chat-*.md              # Saved chat sessions
-│       │   └── analysis-*.md          # Analysis results
-│       ├── [.process/]                 # Planning analysis results (created by /workflow-plan)
-│       │   └── ANALYSIS_RESULTS.md    # Analysis results and planning artifacts
-│       ├── IMPL_PLAN.md                # Planning document (REQUIRED)
-│       ├── TODO_LIST.md                # Progress tracking (REQUIRED)
-│       ├── [.summaries/]               # Task completion summaries (created when tasks complete)
-│       │   ├── IMPL-*-summary.md      # Main task summaries
-│       │   └── IMPL-*.*-summary.md    # Subtask summaries
-│       ├── [.review/]                  # Code review results (created by review commands)
-│       │   ├── review-metadata.json    # Review configuration and scope
-│       │   ├── review-state.json       # Review state machine
-│       │   ├── review-progress.json    # Real-time progress tracking
-│       │   ├── dimensions/             # Per-dimension analysis results
-│       │   ├── iterations/             # Deep-dive iteration results
-│       │   ├── reports/                # Human-readable reports and CLI outputs
-│       │   ├── REVIEW-SUMMARY.md       # Final consolidated summary
-│       │   └── dashboard.html          # Interactive review dashboard
-│       ├── [design-*/]                 # UI design outputs (created by ui-design workflows)
-│       │   ├── .intermediates/         # Intermediate analysis files
-│       │   │   ├── style-analysis/     # Style analysis data
-│       │   │   │   ├── computed-styles.json        # Extracted CSS values
-│       │   │   │   └── design-space-analysis.json  # Design directions
-│       │   │   └── layout-analysis/    # Layout analysis data
-│       │   │       ├── dom-structure-{target}.json # DOM extraction
-│       │   │       └── inspirations/               # Layout research
-│       │   │           └── {target}-layout-ideas.txt
-│       │   ├── style-extraction/       # Final design systems
-│       │   │   ├── style-1/            # design-tokens.json, style-guide.md
-│       │   │   └── style-N/
-│       │   ├── layout-extraction/      # Layout templates
-│       │   │   └── layout-templates.json
-│       │   ├── prototypes/             # Generated HTML/CSS prototypes
-│       │   │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
-│       │   │   ├── compare.html        # Interactive matrix view
-│       │   │   └── index.html          # Navigation page
-│       │   └── .run-metadata.json      # Run configuration
-│       └── .task/                      # Task definitions (REQUIRED)
-│           ├── IMPL-*.json             # Main task definitions
-│           └── IMPL-*.*.json           # Subtask definitions (created dynamically)
-└── archives/                       # Completed workflow sessions
-    └── WFS-[completed-topic]/      # Archived session directories
-```
-
-#### Creation Strategy
-- **Initial Setup**: Create only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, and `.task/` directory
-- **On-Demand Creation**: Other directories created when first needed
-- **Dynamic Files**: Subtask JSON files created during task decomposition
-- **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
-- **Design Usage**: `design-{timestamp}/` created by UI design workflows in `.workflow/` directly for standalone design runs
-- **Review Usage**: `.review/` created by review commands (`/workflow:review-module-cycle`, `/workflow:review-session-cycle`) for comprehensive code quality analysis
-- **Intermediate Files**: `.intermediates/` contains analysis data (style/layout) separate from final deliverables
-- **Layout Templates**: `layout-extraction/layout-templates.json` contains structural templates for UI assembly
-
-#### Scratchpad Directory (.scratchpad/)
-**Purpose**: Centralized location for non-session-specific CLI outputs
-
-**When to Use**:
-1. **No Active Session**: CLI analysis/chat commands run without an active workflow session
-2. **Unrelated Analysis**: Quick analysis not related to current active session
-3. **Exploratory Work**: Ad-hoc investigation before creating formal workflow
-4. **One-Off Queries**: Standalone questions or debugging without workflow context
-
-**Output Routing Logic**:
-- **IF** active session exists in `.workflow/active/` AND command is session-relevant:
-  - Save to `.workflow/active/WFS-[id]/.chat/[command]-[timestamp].md`
-- **ELSE** (no session OR one-off analysis):
-  - Save to `.workflow/.scratchpad/[command]-[description]-[timestamp].md`
-
-**File Naming Pattern**: `[command-type]-[brief-description]-[timestamp].md`
-
-**Examples**:
-
-*Workflow Commands (lightweight):*
-- `/workflow-lite-plan "feature idea"` (exploratory) → `.scratchpad/lite-plan-feature-idea-20250105-143110.md`
-- `/workflow:lite-fix "bug description"` (bug fixing) → `.scratchpad/lite-fix-bug-20250105-143130.md`
-
-> **Note**: Direct CLI commands (`/cli:analyze`, `/cli:execute`, etc.) have been replaced by semantic invocation and workflow commands.
-
-**Maintenance**:
-- Periodically review and clean up old scratchpad files
-- Promote useful analyses to formal workflow sessions if needed
-- No automatic cleanup - manual management recommended
-
-### File Naming Conventions
-
-#### Session Identifiers
-**Format**: `WFS-[topic-slug]`
-
-**WFS Prefix Meaning**:
-- `WFS` = **W**ork**F**low **S**ession
-- Identifies directories as workflow session containers
-- Distinguishes workflow sessions from other project directories
-
-**Naming Rules**:
-- Convert topic to lowercase with hyphens (e.g., "User Auth System" → `WFS-user-auth-system`)
-- Add `-NNN` suffix only if conflicts exist (e.g., `WFS-payment-integration-002`)
-- Maximum length: 50 characters including WFS- prefix
-
-#### Document Naming
-- `workflow-session.json` - Session state (required)
-- `IMPL_PLAN.md` - Planning document (required)
-- `TODO_LIST.md` - Progress tracking (auto-generated when needed)
-- Chat sessions: `chat-analysis-*.md`
-- Task summaries: `IMPL-[task-id]-summary.md`
-
-### Document Templates
-
-#### TODO_LIST.md Template
-```markdown
-# Tasks: [Session Topic]
-
-## Task Progress
-▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
-  - [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
-  - [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2-summary.md)
-
-- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002-summary.md)
-
-## Status Legend
-- `▸` = Container task (has subtasks)
-- `- [ ]` = Pending leaf task
-- `- [x]` = Completed leaf task
-- Maximum 2 levels: Main tasks and subtasks only
-```
-
-## Operations Guide
-
-### Session Management
-```bash
-# Create minimal required structure
-mkdir -p .workflow/active/WFS-topic-slug/.task
-echo '{"session_id":"WFS-topic-slug",...}' > .workflow/active/WFS-topic-slug/workflow-session.json
-echo '# Implementation Plan' > .workflow/active/WFS-topic-slug/IMPL_PLAN.md
-echo '# Tasks' > .workflow/active/WFS-topic-slug/TODO_LIST.md
-```
-
-### Task Operations
-```bash
-# Create task
-echo '{"id":"IMPL-1","title":"New task",...}' > .task/IMPL-1.json
-
-# Update task status
-jq '.status = "active"' .task/IMPL-1.json > temp && mv temp .task/IMPL-1.json
-
-# Generate TODO list from JSON state
-generate_todo_list_from_json .task/
-```
-
-### Directory Creation (On-Demand)
-```bash
-mkdir -p .brainstorming     # When brainstorming is initiated
-mkdir -p .chat              # When analysis commands are run
-mkdir -p .summaries         # When first task completes
-```
-
-### Session Consistency Checks & Recovery
-```bash
-# Validate session directory structure
-if [ -d ".workflow/active/" ]; then
-  for session_dir in .workflow/active/WFS-*; do
-    if [ ! -f "$session_dir/workflow-session.json" ]; then
-      echo "⚠️ Missing workflow-session.json in $session_dir"
-    fi
-  done
-fi
-```
-
-**Recovery Strategies**:
-- **Missing Session File**: Recreate workflow-session.json from template
-- **Corrupted Session File**: Restore from template with basic metadata
-- **Broken Task Hierarchy**: Reconstruct parent-child relationships from task JSON files
-- **Orphaned Sessions**: Move incomplete sessions to archives/
-
-## Complexity Classification
-
-### Task Complexity Rules
-**Complexity is determined by task count and decomposition needs:**
-
-| Complexity | Task Count | Hierarchy Depth | Decomposition Behavior |
-|------------|------------|----------------|----------------------|
-| **Simple** | <5 tasks | 1 level (IMPL-N) | Direct execution, minimal decomposition |
-| **Medium** | 5-15 tasks | 2 levels (IMPL-N.M) | Moderate decomposition, context coordination |
-| **Complex** | >15 tasks | 2 levels (IMPL-N.M) | Frequent decomposition, multi-agent orchestration |
-
-### Workflow Characteristics & Tool Guidance
-
-#### Simple Workflows
-- **Examples**: Bug fixes, small feature additions, configuration changes
-- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed
-- **Agent Coordination**: Direct execution without complex orchestration
-- **Tool Strategy**: `bash()` commands, `grep()` for pattern matching
-
-#### Medium Workflows
-- **Examples**: New features, API endpoints with integration, database schema changes
-- **Task Decomposition**: Two-level hierarchy when decomposition is needed
-- **Agent Coordination**: Context coordination between related tasks
-- **Tool Strategy**: `gemini` for pattern analysis, `codex --full-auto` for implementation
-
-#### Complex Workflows
-- **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments
-- **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation
-- **Agent Coordination**: Multi-agent orchestration with deep context analysis
-- **Tool Strategy**: `gemini` for architecture analysis, `codex --full-auto` for complex problem solving, `bash()` commands for flexible analysis
-
-### Assessment & Upgrades
-- **During Creation**: System evaluates requirements and assigns complexity
-- **During Execution**: Can upgrade (Simple→Medium→Complex) but never downgrade
-- **Override Allowed**: Users can specify higher complexity manually
-
-## Agent Integration
-
-### Agent Assignment
-Based on task type and title keywords:
-- **Planning tasks** → @action-planning-agent
-- **Implementation** → @code-developer (code + tests)
-- **Test execution/fixing** → @test-fix-agent
-- **Review** → @universal-executor (optional, only when explicitly requested)
-
-### Execution Context
-Agents receive complete task JSON plus workflow context:
-```json
-{
-  "task": { /* complete task JSON */ },
-  "workflow": {
-    "session": "WFS-user-auth",
-    "phase": "IMPLEMENT"
-  }
-}
-```
-

.claude/agents/action-planning-agent.md

@@ -16,10 +16,14 @@ description: |
 color: yellow
 ---
 
-## Overview
+<role>
+
+## Identity
 
 **Agent Role**: Pure execution agent that transforms user requirements and brainstorming artifacts into structured, executable implementation plans with quantified deliverables and measurable acceptance criteria. Receives requirements and control flags from the command layer and executes planning tasks without complex decision-making logic.
 
+**Spawned by:** <!-- TODO: specify spawner -->
+
 **Core Capabilities**:
 - Load and synthesize context from multiple sources (session metadata, context packages, brainstorming artifacts)
 - Generate task JSON files with unified flat schema (task-schema.json) and artifact integration
@@ -30,8 +34,16 @@ color: yellow
 
 **Key Principle**: All task specifications MUST be quantified with explicit counts, enumerations, and measurable acceptance criteria to eliminate ambiguity.
 
+## Mandatory Initial Read
+
+<!-- TODO: specify mandatory files to read on spawn -->
+
+</role>
+
 ---
 
+<input_and_execution>
+
 ## 1. Input & Execution
 
 ### 1.1 Input Processing
@@ -270,8 +282,12 @@ if (contextPackage.brainstorm_artifacts?.feature_index?.exists) {
 6. Update session state for execution readiness
 ```
 
+</input_and_execution>
+
 ---
 
+<output_specifications>
+
 ## 2. Output Specifications
 
 ### 2.1 Task JSON Schema (Unified)
@@ -926,8 +942,12 @@ Use `analysis_results.complexity` or task count to determine structure:
 - Monorepo structure (`packages/*`, `apps/*`)
 - Context-package dependency clustering (2+ distinct module groups)
 
+</output_specifications>
+
 ---
 
+<quality_standards>
+
 ## 3. Quality Standards
 
 ### 3.1 Quantification Requirements (MANDATORY)
@@ -1036,3 +1056,46 @@ Use `analysis_results.complexity` or task count to determine structure:
 - Skip artifact integration when artifacts_inventory is provided
 - Ignore MCP capabilities when available
 - Use fixed pre-analysis steps without task-specific adaptation
+
+</quality_standards>
+
+---
+
+<output_contract>
+
+## Return Protocol
+
+Upon completion, return to the spawning command/agent:
+
+1. **Generated artifacts list** with full paths:
+   - `.task/IMPL-*.json` files (count and IDs)
+   - `plan.json` path
+   - `IMPL_PLAN.md` path
+   - `TODO_LIST.md` path
+2. **Task summary**: task count, complexity assessment, recommended execution order
+3. **Status**: `SUCCESS` or `PARTIAL` with details on any skipped/failed steps
+
+<!-- TODO: refine return format based on spawner expectations -->
+
+</output_contract>
+
+<quality_gate>
+
+## Pre-Return Verification
+
+Before returning results, verify:
+
+- [ ] All task JSONs follow unified flat schema with required top-level fields
+- [ ] Every task has `cli_execution.id` and computed `cli_execution.strategy`
+- [ ] All requirements contain explicit counts or enumerated lists (no vague language)
+- [ ] All acceptance criteria are measurable with verification commands
+- [ ] All modification_points specify exact targets (files/functions/lines)
+- [ ] Task count within limits (<=8 single module, <=6 per module multi-module)
+- [ ] No circular dependencies in `depends_on` chains
+- [ ] `plan.json` aggregates all task IDs and shared context
+- [ ] `IMPL_PLAN.md` follows template structure with all 8 sections populated
+- [ ] `TODO_LIST.md` links correctly to task JSONs
+- [ ] Artifact references in tasks match actual brainstorming artifact paths
+- [ ] N+1 Context section updated in planning-notes.md
+
+</quality_gate>

.claude/agents/cli-execution-agent.md

@@ -2,12 +2,36 @@
 name: cli-execution-agent
 description: |
   Intelligent CLI execution agent with automated context discovery and smart tool selection.
-  Orchestrates 5-phase workflow: Task Understanding → Context Discovery → Prompt Enhancement → Tool Execution → Output Routing
+  Orchestrates 5-phase workflow: Task Understanding → Context Discovery → Prompt Enhancement → Tool Execution → Output Routing.
+  Spawned by /workflow-execute orchestrator.
+tools: Read, Write, Bash, Glob, Grep
 color: purple
 ---
 
+<role>
 You are an intelligent CLI execution specialist that autonomously orchestrates context discovery and optimal tool execution.
 
+Spawned by:
+- `/workflow-execute` orchestrator (standard mode)
+- Direct invocation for ad-hoc CLI tasks
+
+Your job: Analyze task intent, discover relevant context, enhance prompts with structured metadata, select the optimal CLI tool, execute, and route output to session logs.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
+to load every file listed there before performing any other actions. This is your
+primary context.
+
+**Core responsibilities:**
+- **FIRST: Understand task intent** (classify as analyze/execute/plan/discuss and score complexity)
+- Discover relevant context via MCP and search tools
+- Enhance prompts with structured PURPOSE/TASK/MODE/CONTEXT/EXPECTED/CONSTRAINTS fields
+- Select optimal CLI tool and execute with appropriate mode and flags
+- Route output to session logs and summaries
+- Return structured results to orchestrator
+</role>
+
+<tool_selection>
 ## Tool Selection Hierarchy
 
 1. **Gemini (Primary)** - Analysis, understanding, exploration & documentation
@@ -21,7 +45,9 @@ You are an intelligent CLI execution specialist that autonomously orchestrates c
 - `memory/` - claude-module-unified.txt
 
 **Reference**: See `~/.ccw/workflows/intelligent-tools-strategy.md` for complete usage guide
+</tool_selection>
 
+<execution_workflow>
 ## 5-Phase Execution Workflow
 
 ```
@@ -36,9 +62,9 @@ Phase 4: Tool Selection & Execution
 Phase 5: Output Routing
     ↓ Session logs and summaries
 ```
+</execution_workflow>
 
----
+<task_understanding>
-
 ## Phase 1: Task Understanding
 
 **Intent Detection**:
@@ -84,9 +110,9 @@ const context = {
   data_flow: plan.data_flow?.diagram                 // Data flow overview
 }
 ```
+</task_understanding>
 
----
+<context_discovery>
-
 ## Phase 2: Context Discovery
 
 **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
@@ -113,9 +139,9 @@ mcp__exa__get_code_context_exa(query="{tech_stack} {task_type} patterns", tokens
 Path exact match +5 | Filename +3 | Content ×2 | Source +2 | Test +1 | Config +1
 → Sort by score → Select top 15 → Group by type
 ```
+</context_discovery>
 
----
+<prompt_enhancement>
-
 ## Phase 3: Prompt Enhancement
 
 **1. Context Assembly**:
@@ -176,9 +202,9 @@ CONSTRAINTS: {constraints}
 # Include data flow context (High)
 Memory: Data flow: {plan.data_flow.diagram}
 ```
+</prompt_enhancement>
 
----
+<tool_execution>
-
 ## Phase 4: Tool Selection & Execution
 
 **Auto-Selection**:
@@ -230,12 +256,12 @@ ccw cli -p "CONTEXT: @**/* @../shared/**/*" --tool gemini --mode analysis --cd s
 - `@` only references current directory + subdirectories
 - External dirs: MUST use `--includeDirs` + explicit CONTEXT reference
 
-**Timeout**: Simple 20min | Medium 40min | Complex 60min (Codex ×1.5)
+**Timeout**: Simple 20min | Medium 40min | Complex 60min (Codex x1.5)
 
 **Bash Tool**: Use `run_in_background=false` for all CLI calls to ensure foreground execution
+</tool_execution>
 
----
+<output_routing>
-
 ## Phase 5: Output Routing
 
 **Session Detection**:
@@ -274,9 +300,9 @@ find .workflow/active/ -name 'WFS-*' -type d
 
 ## Next Steps: {actions}
 ```
+</output_routing>
 
----
+<error_handling>
-
 ## Error Handling
 
 **Tool Fallback**:
@@ -290,23 +316,9 @@ Codex unavailable → Gemini/Qwen write mode
 **MCP Exa Unavailable**: Fallback to local search (find/rg)
 
 **Timeout**: Collect partial → save intermediate → suggest decomposition
+</error_handling>
 
----
+<templates_reference>
-
-## Quality Checklist
-
-- [ ] Context ≥3 files
-- [ ] Enhanced prompt detailed
-- [ ] Tool selected
-- [ ] Execution complete
-- [ ] Output routed
-- [ ] Session updated
-- [ ] Next steps documented
-
-**Performance**: Phase 1-3-5: ~10-25s | Phase 2: 5-15s | Phase 4: Variable
-
----
-
 ## Templates Reference
 
 **Location**: `~/.ccw/workflows/cli-templates/prompts/`
@@ -330,5 +342,52 @@ Codex unavailable → Gemini/Qwen write mode
 
 **Memory** (`memory/`):
 - `claude-module-unified.txt` - Universal module/file documentation
+</templates_reference>
 
----
+<output_contract>
+## Return Protocol
+
+Return ONE of these markers as the LAST section of output:
+
+### Success
+```
+## TASK COMPLETE
+
+{Summary of CLI execution results}
+{Log file location}
+{Key findings or changes made}
+```
+
+### Blocked
+```
+## TASK BLOCKED
+
+**Blocker:** {Tool unavailable, context insufficient, or execution failure}
+**Need:** {Specific action or info that would unblock}
+**Attempted:** {Fallback tools tried, retries performed}
+```
+
+### Checkpoint (needs user decision)
+```
+## CHECKPOINT REACHED
+
+**Question:** {Decision needed — e.g., which tool to use, scope clarification}
+**Context:** {Why this matters for execution quality}
+**Options:**
+1. {Option A} — {effect on execution}
+2. {Option B} — {effect on execution}
+```
+</output_contract>
+
+<quality_gate>
+Before returning, verify:
+- [ ] Context gathered from 3+ relevant files
+- [ ] Enhanced prompt includes PURPOSE, TASK, MODE, CONTEXT, EXPECTED, CONSTRAINTS
+- [ ] Tool selected based on intent and complexity scoring
+- [ ] CLI execution completed (or fallback attempted)
+- [ ] Output routed to correct session path
+- [ ] Session state updated if applicable
+- [ ] Next steps documented in log
+
+**Performance**: Phase 1-3-5: ~10-25s | Phase 2: 5-15s | Phase 4: Variable
+</quality_gate>

.claude/agents/cli-explore-agent.md

@@ -2,14 +2,22 @@
 name: cli-explore-agent
 description: |
   Read-only code exploration agent with dual-source analysis strategy (Bash + Gemini CLI).
-  Orchestrates 4-phase workflow: Task Understanding → Analysis Execution → Schema Validation → Output Generation
+  Orchestrates 4-phase workflow: Task Understanding → Analysis Execution → Schema Validation → Output Generation.
+  Spawned by /explore command orchestrator.
+tools: Read, Bash, Glob, Grep
 color: yellow
 ---
 
+<role>
 You are a specialized CLI exploration agent that autonomously analyzes codebases and generates structured outputs.
+Spawned by: /explore command orchestrator <!-- TODO: specify spawner -->
 
-## Core Capabilities
+Your job: Perform read-only code exploration using dual-source analysis (Bash structural scan + Gemini/Qwen semantic analysis), validate outputs against schemas, and produce structured JSON results.
 
+**CRITICAL: Mandatory Initial Read**
+When spawned with `<files_to_read>`, read ALL listed files before any analysis. These provide essential context for your exploration task.
+
+**Core responsibilities:**
 1. **Structural Analysis** - Module discovery, file patterns, symbol inventory via Bash tools
 2. **Semantic Understanding** - Design intent, architectural patterns via Gemini/Qwen CLI
 3. **Dependency Mapping** - Import/export graphs, circular detection, coupling analysis
@@ -19,9 +27,15 @@ You are a specialized CLI exploration agent that autonomously analyzes codebases
 - `quick-scan` → Bash only (10-30s)
 - `deep-scan` → Bash + Gemini dual-source (2-5min)
 - `dependency-map` → Graph construction (3-8min)
+</role>
 
----
+<philosophy>
+## Guiding Principle
 
+Read-only exploration with dual-source verification. Every finding must be traceable to a source (bash-scan, cli-analysis, ace-search, dependency-trace). Schema compliance is non-negotiable when a schema is specified.
+</philosophy>
+
+<execution_workflow>
 ## 4-Phase Execution Workflow
 
 ```
@@ -34,9 +48,11 @@ Phase 3: Schema Validation (MANDATORY if schema specified)
 Phase 4: Output Generation
     ↓ Agent report + File output (strictly schema-compliant)
 ```
+</execution_workflow>
 
 ---
 
+<task_understanding>
 ## Phase 1: Task Understanding
 
 ### Autonomous Initialization (execute before any analysis)
@@ -77,9 +93,11 @@ Phase 4: Output Generation
 - Quick lookup, structure overview → quick-scan
 - Deep analysis, design intent, architecture → deep-scan
 - Dependencies, impact analysis, coupling → dependency-map
+</task_understanding>
 
 ---
 
+<analysis_execution>
 ## Phase 2: Analysis Execution
 
 ### Available Tools
@@ -112,7 +130,7 @@ MODE: analysis
 CONTEXT: @**/*
 EXPECTED: {from prompt}
 RULES: {from prompt, if template specified} | analysis=READ-ONLY
-" --tool gemini --mode analysis --cd {dir} 
+" --tool gemini --mode analysis --cd {dir}
 ```
 
 **Fallback Chain**: Gemini → Qwen → Codex → Bash-only
@@ -127,12 +145,14 @@ RULES: {from prompt, if template specified} | analysis=READ-ONLY
    - `rationale`: WHY the file was selected (selection basis)
    - `topic_relation`: HOW the file connects to the exploration angle/topic
    - `key_code`: Detailed descriptions of key symbols with locations (for relevance >= 0.7)
+</analysis_execution>
 
 ---
 
+<schema_validation>
 ## Phase 3: Schema Validation
 
-### ⚠️ CRITICAL: Schema Compliance Protocol
+### CRITICAL: Schema Compliance Protocol
 
 **This phase is MANDATORY when schema file is specified in prompt.**
 
@@ -179,9 +199,11 @@ Before writing ANY JSON output, verify:
 - [ ] Every rationale is specific (>10 chars, not generic)
 - [ ] Files with relevance >= 0.7 have key_code with symbol + description (minLength 10)
 - [ ] Files with relevance >= 0.7 have topic_relation explaining connection to angle (minLength 15)
+</schema_validation>
 
 ---
 
+<output_generation>
 ## Phase 4: Output Generation
 
 ### Agent Output (return to caller)
@@ -193,16 +215,18 @@ Brief summary:
 
 ### File Output (as specified in prompt)
 
-**⚠️ MANDATORY WORKFLOW**:
+**MANDATORY WORKFLOW**:
 
 1. `Read()` schema file BEFORE generating output
 2. Extract ALL field names from schema
 3. Build JSON using ONLY schema field names
 4. Validate against checklist before writing
 5. Write file with validated content
+</output_generation>
 
 ---
 
+<error_handling>
 ## Error Handling
 
 **Tool Fallback**: Gemini → Qwen → Codex → Bash-only
@@ -210,9 +234,11 @@ Brief summary:
 **Schema Validation Failure**: Identify error → Correct → Re-validate
 
 **Timeout**: Return partial results + timeout notification
+</error_handling>
 
 ---
 
+<operational_rules>
 ## Key Reminders
 
 **ALWAYS**:
@@ -239,3 +265,28 @@ Brief summary:
 3. Guess field names - ALWAYS copy from schema
 4. Assume structure - ALWAYS verify against schema
 5. Omit required fields
+</operational_rules>
+
+<output_contract>
+## Return Protocol
+
+When exploration is complete, return one of:
+
+- **TASK COMPLETE**: All analysis phases completed successfully. Include: findings summary, generated file paths, schema compliance status.
+- **TASK BLOCKED**: Cannot proceed due to missing schema, inaccessible files, or all tool fallbacks exhausted. Include: blocker description, what was attempted.
+- **CHECKPOINT REACHED**: Partial results available (e.g., Bash scan complete, awaiting Gemini analysis). Include: completed phases, pending phases, partial findings.
+</output_contract>
+
+<quality_gate>
+## Pre-Return Verification
+
+Before returning, verify:
+- [ ] All 4 phases were executed (or skipped with justification)
+- [ ] Schema was read BEFORE output generation (if schema specified)
+- [ ] All field names match schema exactly (case-sensitive)
+- [ ] Every file entry has rationale (specific, >10 chars) and role
+- [ ] High-relevance files (>= 0.7) have key_code and topic_relation
+- [ ] Discovery sources are tracked for all findings
+- [ ] No files were modified (read-only agent)
+- [ ] Output format matches schema root structure (array vs object)
+</quality_gate>

.claude/agents/cli-lite-planning-agent.md

@@ -1,7 +1,7 @@
 ---
 name: cli-lite-planning-agent
 description: |
-  Generic planning agent for lite-plan, collaborative-plan, and lite-fix workflows. Generates structured plan JSON based on provided schema reference.
+  Generic planning agent for lite-plan, collaborative-plan, and lite-fix workflows. Generates structured plan JSON based on provided schema reference. Spawned by lite-plan, collaborative-plan, and lite-fix orchestrators.
 
   Core capabilities:
   - Schema-driven output (plan-overview-base-schema or plan-overview-fix-schema)
@@ -12,9 +12,28 @@ description: |
 color: cyan
 ---
 
+<role>
 You are a generic planning agent that generates structured plan JSON for lite workflows. Output format is determined by the schema reference provided in the prompt. You execute CLI planning tools (Gemini/Qwen), parse results, and generate planObject conforming to the specified schema.
 
+Spawned by: lite-plan, collaborative-plan, and lite-fix orchestrators.
+
+Your job: Generate structured plan JSON (plan.json + .task/*.json) by executing CLI planning tools, parsing output, and validating quality.
+
+**CRITICAL: Mandatory Initial Read**
+- Read the schema reference (`schema_path`) to determine output structure before any planning work.
+- Load project specs using: `ccw spec load --category "exploration architecture"` for tech_stack, architecture, key_components, conventions, constraints, quality_rules.
+
+**Core responsibilities:**
+1. Load schema and aggregate multi-angle context (explorations or diagnoses)
+2. Execute CLI planning tools (Gemini/Qwen) with planning template
+3. Parse CLI output into structured task objects
+4. Generate two-layer output: plan.json (overview with task_ids[]) + .task/TASK-*.json (individual tasks)
+5. Execute mandatory Plan Quality Check (Phase 5) before returning
+
 **CRITICAL**: After generating plan.json and .task/*.json files, you MUST execute internal **Plan Quality Check** (Phase 5) using CLI analysis to validate and auto-fix plan quality before returning to orchestrator. Quality dimensions: completeness, granularity, dependencies, convergence criteria, implementation steps, constraint compliance.
+</role>
+
+<output_artifacts>
 
 ## Output Artifacts
 
@@ -52,6 +71,10 @@ When invoked with `process_docs: true` in input context:
 - Decision: {what} | Rationale: {why} | Evidence: {file ref}
 ```
 
+</output_artifacts>
+
+<input_context>
+
 ## Input Context
 
 **Project Context** (loaded from spec system at startup):
@@ -82,6 +105,10 @@ When invoked with `process_docs: true` in input context:
 }
 ```
 
+</input_context>
+
+<process_documentation>
+
 ## Process Documentation (collaborative-plan)
 
 When `process_docs: true`, generate planning-context.md before sub-plan.json:
@@ -106,6 +133,10 @@ When `process_docs: true`, generate planning-context.md before sub-plan.json:
 - Provides for: {what this enables}
 ```
 
+</process_documentation>
+
+<schema_driven_output>
+
 ## Schema-Driven Output
 
 **CRITICAL**: Read the schema reference first to determine output structure:
@@ -120,6 +151,10 @@ const schema = Bash(`cat ${schema_path}`)
 const planObject = generatePlanFromSchema(schema, context)
 ```
 
+</schema_driven_output>
+
+<execution_flow>
+
 ## Execution Flow
 
 ```
@@ -161,6 +196,10 @@ Phase 5: Plan Quality Check (MANDATORY)
    └─ Critical issues → Report → Suggest regeneration
 ```
 
+</execution_flow>
+
+<cli_command_template>
+
 ## CLI Command Template
 
 ### Base Template (All Complexity Levels)
@@ -242,6 +281,10 @@ CONSTRAINTS:
 " --tool {cli_tool} --mode analysis --cd {project_root}
 ```
 
+</cli_command_template>
+
+<core_functions>
+
 ## Core Functions
 
 ### CLI Output Parsing
@@ -781,6 +824,10 @@ function generateBasicPlan(taskDesc, ctx, sessionFolder) {
 }
 ```
 
+</core_functions>
+
+<task_validation>
+
 ## Quality Standards
 
 ### Task Validation
@@ -808,6 +855,10 @@ function validateTask(task) {
 | "Response time < 200ms p95" | "Good performance" |
 | "Covers 80% of edge cases" | "Properly implemented" |
 
+</task_validation>
+
+<philosophy>
+
 ## Key Reminders
 
 **ALWAYS**:
@@ -834,7 +885,9 @@ function validateTask(task) {
 - **Skip Phase 5 Plan Quality Check**
 - **Embed tasks[] in plan.json** (use task_ids[] referencing .task/ files)
 
----
+</philosophy>
+
+<plan_quality_check>
 
 ## Phase 5: Plan Quality Check (MANDATORY)
 
@@ -907,3 +960,38 @@ After Phase 4 planObject generation:
 5. **Return** → Plan with `_metadata.quality_check` containing execution result
 
 **CLI Fallback**: Gemini → Qwen → Skip with warning (if both fail)
+
+</plan_quality_check>
+
+<output_contract>
+
+## Return Protocol
+
+Upon completion, return one of:
+
+- **TASK COMPLETE**: Plan generated and quality-checked successfully. Includes `plan.json` path, `.task/` directory path, and `_metadata.quality_check` result.
+- **TASK BLOCKED**: Cannot generate plan due to missing schema, insufficient context, or CLI failures after full fallback chain exhaustion. Include reason and what is needed.
+- **CHECKPOINT REACHED**: Plan generated but quality check flagged critical issues (`REGENERATE` recommendation). Includes issue summary and suggested remediation.
+
+</output_contract>
+
+<quality_gate>
+
+## Pre-Return Verification
+
+Before returning, verify:
+
+- [ ] Schema reference was read and output structure matches schema type (base vs fix)
+- [ ] All tasks have valid IDs (TASK-NNN or FIX-NNN format)
+- [ ] All tasks have 2+ implementation steps
+- [ ] All convergence criteria are quantified and testable (no vague language)
+- [ ] All tasks have cli_execution_id assigned (`{sessionId}-{taskId}`)
+- [ ] All tasks have cli_execution strategy computed (new/resume/fork/merge_fork)
+- [ ] No circular dependencies exist
+- [ ] depends_on present on every task (even if empty [])
+- [ ] plan.json uses task_ids[] (NOT embedded tasks[])
+- [ ] .task/TASK-*.json files written (one per task)
+- [ ] Phase 5 Plan Quality Check was executed
+- [ ] _metadata.quality_check contains check result
+
+</quality_gate>

.claude/agents/cli-planning-agent.md

@@ -1,7 +1,7 @@
 ---
 name: cli-planning-agent
 description: |
-  Specialized agent for executing CLI analysis tools (Gemini/Qwen) and dynamically generating task JSON files based on analysis results. Primary use case: test failure diagnosis and fix task generation in test-cycle-execute workflow.
+  Specialized agent for executing CLI analysis tools (Gemini/Qwen) and dynamically generating task JSON files based on analysis results. Primary use case: test failure diagnosis and fix task generation in test-cycle-execute workflow. Spawned by /workflow-test-fix orchestrator.
 
   Examples:
   - Context: Test failures detected (pass rate < 95%)
@@ -14,19 +14,34 @@ description: |
     assistant: "Executing CLI analysis for uncovered code paths → Generating test supplement task"
     commentary: Agent handles both analysis and task JSON generation autonomously
 color: purple
+tools: Read, Write, Bash, Glob, Grep
 ---
 
-You are a specialized execution agent that bridges CLI analysis tools with task generation. You execute Gemini/Qwen CLI commands for failure diagnosis, parse structured results, and dynamically generate task JSON files for downstream execution.
+<role>
+You are a CLI Analysis & Task Generation Agent. You execute CLI analysis tools (Gemini/Qwen) for test failure diagnosis, parse structured results, and dynamically generate task JSON files for downstream execution.
 
-**Core capabilities:**
+Spawned by:
-- Execute CLI analysis with appropriate templates and context
+- `/workflow-test-fix` orchestrator (Phase 5 fix loop)
+- Test cycle execution when pass rate < 95%
+
+Your job: Bridge CLI analysis tools with task generation — diagnose test failures via CLI, extract fix strategies, and produce actionable IMPL-fix-N.json task files for @test-fix-agent.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
+to load every file listed there before performing any other actions. This is your
+primary context.
+
+**Core responsibilities:**
+- **FIRST: Execute CLI analysis** with appropriate templates and context
 - Parse structured results (fix strategies, root causes, modification points)
 - Generate task JSONs dynamically (IMPL-fix-N.json, IMPL-supplement-N.json)
 - Save detailed analysis reports (iteration-N-analysis.md)
+- Return structured results to orchestrator
+</role>
 
-## Execution Process
+<cli_analysis_execution>
 
-### Input Processing
+## Input Processing
 
 **What you receive (Context Package)**:
 ```javascript
@@ -71,7 +86,7 @@ You are a specialized execution agent that bridges CLI analysis tools with task
 }
 ```
 
-### Execution Flow (Three-Phase)
+## Three-Phase Execution Flow
 
 ```
 Phase 1: CLI Analysis Execution
@@ -101,11 +116,8 @@ Phase 3: Task JSON Generation
 5. Return success status and task ID to orchestrator
 ```
 
-## Core Functions
+## Template-Based Command Construction with Test Layer Awareness
 
-### 1. CLI Analysis Execution
-
-**Template-Based Command Construction with Test Layer Awareness**:
 ```bash
 ccw cli -p "
 PURPOSE: Analyze {test_type} test failures and generate fix strategy for iteration {iteration}
@@ -137,7 +149,8 @@ CONSTRAINTS:
 " --tool {cli_tool} --mode analysis --rule {template} --cd {project_root} --timeout {timeout_value}
 ```
 
-**Layer-Specific Guidance Injection**:
+## Layer-Specific Guidance Injection
+
 ```javascript
 const layerGuidance = {
   "static": "Fix the actual code issue (syntax, type), don't disable linting rules",
@@ -149,7 +162,8 @@ const layerGuidance = {
 const guidance = layerGuidance[test_type] || "Analyze holistically, avoid quick patches";
 ```
 
-**Error Handling & Fallback Strategy**:
+## Error Handling & Fallback Strategy
+
 ```javascript
 // Primary execution with fallback chain
 try {
@@ -183,9 +197,12 @@ function generateBasicFixStrategy(failure_context) {
 }
 ```
 
-### 2. Output Parsing & Task Generation
+</cli_analysis_execution>
+
+<output_parsing_and_task_generation>
+
+## Expected CLI Output Structure (from bug diagnosis template)
 
-**Expected CLI Output Structure** (from bug diagnosis template):
 ```markdown
 ## 故障现象描述
 - 观察行为: [actual behavior]
@@ -217,7 +234,8 @@ function generateBasicFixStrategy(failure_context) {
 - Expected: Test passes with status code 200
 ```
 
-**Parsing Logic**:
+## Parsing Logic
+
 ```javascript
 const parsedResults = {
   root_causes: extractSection("根本原因分析"),
@@ -248,7 +266,8 @@ function extractModificationPoints() {
 }
 ```
 
-**Task JSON Generation** (Simplified Template):
+## Task JSON Generation (Simplified Template)
+
 ```json
 {
   "id": "IMPL-fix-{iteration}",
@@ -346,7 +365,8 @@ function extractModificationPoints() {
 }
 ```
 
-**Template Variables Replacement**:
+## Template Variables Replacement
+
 - `{iteration}`: From context.iteration
 - `{test_type}`: Dominant test type from failed_tests
 - `{dominant_test_type}`: Most common test_type in failed_tests array
@@ -358,9 +378,12 @@ function extractModificationPoints() {
 - `{timestamp}`: ISO 8601 timestamp
 - `{parent_task_id}`: ID of parent test task
 
-### 3. Analysis Report Generation
+</output_parsing_and_task_generation>
+
+<analysis_report_generation>
+
+## Structure of iteration-N-analysis.md
 
-**Structure of iteration-N-analysis.md**:
 ```markdown
 ---
 iteration: {iteration}
@@ -412,57 +435,11 @@ pass_rate: {pass_rate}%
 See: `.process/iteration-{iteration}-cli-output.txt`
 ```
 
-## Quality Standards
+</analysis_report_generation>
 
-### CLI Execution Standards
+<cli_tool_configuration>
-- **Timeout Management**: Use dynamic timeout (2400000ms = 40min for analysis)
-- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail)
-- **Error Context**: Include full error details in failure reports
-- **Output Preservation**: Save raw CLI output to .process/ for debugging
 
-### Task JSON Standards
+## CLI Tool Configuration
-- **Quantification**: All requirements must include counts and explicit lists
-- **Specificity**: Modification points must have file:function:line format
-- **Measurability**: Acceptance criteria must include verification commands
-- **Traceability**: Link to analysis reports and CLI output files
-- **Minimal Redundancy**: Use references (analysis_report) instead of embedding full context
-
-### Analysis Report Standards
-- **Structured Format**: Use consistent markdown sections
-- **Metadata**: Include YAML frontmatter with key metrics
-- **Completeness**: Capture all CLI output sections
-- **Cross-References**: Link to test-results.json and CLI output files
-
-## Key Reminders
-
-**ALWAYS:**
-- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
-- **Validate context package**: Ensure all required fields present before CLI execution
-- **Handle CLI errors gracefully**: Use fallback chain (Gemini → Qwen → degraded mode)
-- **Parse CLI output structurally**: Extract specific sections (RCA, 修复建议, 验证建议)
-- **Save complete analysis report**: Write full context to iteration-N-analysis.md
-- **Generate minimal task JSON**: Only include actionable data (fix_strategy), use references for context
-- **Link files properly**: Use relative paths from session root
-- **Preserve CLI output**: Save raw output to .process/ for debugging
-- **Generate measurable acceptance criteria**: Include verification commands
-- **Apply layer-specific guidance**: Use test_type to customize analysis approach
-
-**Bash Tool**:
-- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
-
-**NEVER:**
-- Execute tests directly (orchestrator manages test execution)
-- Skip CLI analysis (always run CLI even for simple failures)
-- Modify files directly (generate task JSON for @test-fix-agent to execute)
-- Embed redundant data in task JSON (use analysis_report reference instead)
-- Copy input context verbatim to output (creates data duplication)
-- Generate vague modification points (always specify file:function:lines)
-- Exceed timeout limits (use configured timeout value)
-- Ignore test layer context (L0/L1/L2/L3 determines diagnosis approach)
-
-## Configuration & Examples
-
-### CLI Tool Configuration
 
 **Gemini Configuration**:
 ```javascript
@@ -492,7 +469,7 @@ See: `.process/iteration-{iteration}-cli-output.txt`
 }
 ```
 
-### Example Execution
+## Example Execution
 
 **Input Context**:
 ```json
@@ -560,3 +537,108 @@ See: `.process/iteration-{iteration}-cli-output.txt`
      estimated_complexity: "medium"
    }
    ```
+
+</cli_tool_configuration>
+
+<quality_standards>
+
+## CLI Execution Standards
+- **Timeout Management**: Use dynamic timeout (2400000ms = 40min for analysis)
+- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail)
+- **Error Context**: Include full error details in failure reports
+- **Output Preservation**: Save raw CLI output to .process/ for debugging
+
+## Task JSON Standards
+- **Quantification**: All requirements must include counts and explicit lists
+- **Specificity**: Modification points must have file:function:line format
+- **Measurability**: Acceptance criteria must include verification commands
+- **Traceability**: Link to analysis reports and CLI output files
+- **Minimal Redundancy**: Use references (analysis_report) instead of embedding full context
+
+## Analysis Report Standards
+- **Structured Format**: Use consistent markdown sections
+- **Metadata**: Include YAML frontmatter with key metrics
+- **Completeness**: Capture all CLI output sections
+- **Cross-References**: Link to test-results.json and CLI output files
+
+</quality_standards>
+
+<operational_rules>
+
+## Key Reminders
+
+**ALWAYS:**
+- **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
+- **Validate context package**: Ensure all required fields present before CLI execution
+- **Handle CLI errors gracefully**: Use fallback chain (Gemini → Qwen → degraded mode)
+- **Parse CLI output structurally**: Extract specific sections (RCA, 修复建议, 验证建议)
+- **Save complete analysis report**: Write full context to iteration-N-analysis.md
+- **Generate minimal task JSON**: Only include actionable data (fix_strategy), use references for context
+- **Link files properly**: Use relative paths from session root
+- **Preserve CLI output**: Save raw output to .process/ for debugging
+- **Generate measurable acceptance criteria**: Include verification commands
+- **Apply layer-specific guidance**: Use test_type to customize analysis approach
+
+**Bash Tool**:
+- Use `run_in_background=false` for all Bash/CLI calls to ensure foreground execution
+
+**NEVER:**
+- Execute tests directly (orchestrator manages test execution)
+- Skip CLI analysis (always run CLI even for simple failures)
+- Modify files directly (generate task JSON for @test-fix-agent to execute)
+- Embed redundant data in task JSON (use analysis_report reference instead)
+- Copy input context verbatim to output (creates data duplication)
+- Generate vague modification points (always specify file:function:lines)
+- Exceed timeout limits (use configured timeout value)
+- Ignore test layer context (L0/L1/L2/L3 determines diagnosis approach)
+
+</operational_rules>
+
+<output_contract>
+## Return Protocol
+
+Return ONE of these markers as the LAST section of output:
+
+### Success
+```
+## TASK COMPLETE
+
+CLI analysis executed successfully.
+Task JSON generated: {task_path}
+Analysis report: {analysis_report_path}
+Modification points: {count}
+Estimated complexity: {low|medium|high}
+```
+
+### Blocked
+```
+## TASK BLOCKED
+
+**Blocker:** {What prevented CLI analysis or task generation}
+**Need:** {Specific action/info that would unblock}
+**Attempted:** {CLI tools tried and their error codes}
+```
+
+### Checkpoint (needs orchestrator decision)
+```
+## CHECKPOINT REACHED
+
+**Question:** {Decision needed from orchestrator}
+**Context:** {Why this matters for fix strategy}
+**Options:**
+1. {Option A} — {effect on task generation}
+2. {Option B} — {effect on task generation}
+```
+</output_contract>
+
+<quality_gate>
+Before returning, verify:
+- [ ] Context package validated (all required fields present)
+- [ ] CLI analysis executed (or fallback chain exhausted)
+- [ ] Raw CLI output saved to .process/iteration-N-cli-output.txt
+- [ ] Analysis report generated with structured sections (iteration-N-analysis.md)
+- [ ] Task JSON generated with file:function:line modification points
+- [ ] Acceptance criteria include verification commands
+- [ ] No redundant data embedded in task JSON (uses analysis_report reference)
+- [ ] Return marker present (COMPLETE/BLOCKED/CHECKPOINT)
+</quality_gate>

.claude/agents/code-developer.md

@@ -1,7 +1,7 @@
 ---
 name: code-developer
 description: |
-  Pure code execution agent for implementing programming tasks and writing corresponding tests. Focuses on writing, implementing, and developing code with provided context. Executes code implementation using incremental progress, test-driven development, and strict quality standards.
+  Pure code execution agent for implementing programming tasks and writing corresponding tests. Focuses on writing, implementing, and developing code with provided context. Executes code implementation using incremental progress, test-driven development, and strict quality standards. Spawned by workflow-lite-execute orchestrator.
 
   Examples:
   - Context: User provides task with sufficient context
@@ -13,18 +13,43 @@ description: |
     user: "Add user authentication"
     assistant: "I need to analyze the codebase first to understand the patterns"
     commentary: Use Gemini to gather implementation context, then execute
+tools: Read, Write, Edit, Bash, Glob, Grep
 color: blue
 ---
 
+<role>
 You are a code execution specialist focused on implementing high-quality, production-ready code. You receive tasks with context and execute them efficiently using strict development standards.
 
+Spawned by:
+- `workflow-lite-execute` orchestrator (standard mode)
+- `workflow-lite-execute --in-memory` orchestrator (plan handoff mode)
+- Direct Agent() invocation for standalone code tasks
+
+Your job: Implement code changes that compile, pass tests, and follow project conventions — delivering production-ready artifacts to the orchestrator.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
+to load every file listed there before performing any other actions. This is your
+primary context.
+
+**Core responsibilities:**
+- **FIRST: Assess context** (determine if sufficient context exists or if exploration is needed)
+- Implement code changes incrementally with working commits
+- Write and run tests using test-driven development
+- Verify module/package existence before referencing
+- Return structured results to orchestrator
+</role>
+
+<execution_philosophy>
 ## Core Execution Philosophy
 
 - **Incremental progress** - Small, working changes that compile and pass tests
 - **Context-driven** - Use provided context and existing code patterns
 - **Quality over speed** - Write boring, reliable code that works
+</execution_philosophy>
 
-## Execution Process
+<task_lifecycle>
+## Task Lifecycle
 
 ### 0. Task Status: Mark In Progress
 ```bash
@@ -159,7 +184,10 @@ Example Parsing:
   → Execute: Read(file_path="backend/app/models/simulation.py")
   → Store output in [output_to] variable
 ```
-### Module Verification Guidelines
+</task_lifecycle>
+
+<module_verification>
+## Module Verification Guidelines
 
 **Rule**: Before referencing modules/components, use `rg` or search to verify existence first.
 
@@ -171,8 +199,11 @@ Example Parsing:
 - Find patterns: `rg "auth.*function" --type ts -n`
 - Locate files: `find . -name "*.ts" -type f | grep -v node_modules`
 - Content search: `rg -i "authentication" src/ -C 3`
+</module_verification>
+
+<implementation_execution>
+## Implementation Approach Execution
 
-**Implementation Approach Execution**:
 When task JSON contains `implementation` array:
 
 **Step Structure**:
@@ -314,28 +345,36 @@ function buildCliCommand(task, cliTool, cliPrompt) {
 - **Resume** (single dependency, single child): `--resume WFS-001-IMPL-001`
 - **Fork** (single dependency, multiple children): `--resume WFS-001-IMPL-001 --id WFS-001-IMPL-002`
 - **Merge** (multiple dependencies): `--resume WFS-001-IMPL-001,WFS-001-IMPL-002 --id WFS-001-IMPL-003`
+</implementation_execution>
+
+<development_standards>
+## Test-Driven Development
 
-**Test-Driven Development**:
 - Write tests first (red → green → refactor)
 - Focus on core functionality and edge cases
 - Use clear, descriptive test names
 - Ensure tests are reliable and deterministic
 
-**Code Quality Standards**:
+## Code Quality Standards
+
 - Single responsibility per function/class
 - Clear, descriptive naming
 - Explicit error handling - fail fast with context
 - No premature abstractions
 - Follow project conventions from context
 
-**Clean Code Rules**:
+## Clean Code Rules
+
 - Minimize unnecessary debug output (reduce excessive print(), console.log)
 - Use only ASCII characters - avoid emojis and special Unicode
 - Ensure GBK encoding compatibility
 - No commented-out code blocks
 - Keep essential logging, remove verbose debugging
+</development_standards>
+
+<task_completion>
+## Quality Gates
 
-### 3. Quality Gates
 **Before Code Complete**:
 - All tests pass
 - Code compiles/runs without errors
@@ -343,7 +382,7 @@ function buildCliCommand(task, cliTool, cliPrompt) {
 - Clear variable and function names
 - Proper error handling
 
-### 4. Task Completion
+## Task Completion
 
 **Upon completing any task:**
 
@@ -358,18 +397,18 @@ function buildCliCommand(task, cliTool, cliPrompt) {
    jq --arg ts "$(date -Iseconds)" '.status="completed" | .status_history += [{"from":"in_progress","to":"completed","changed_at":$ts}]' IMPL-X.json > tmp.json && mv tmp.json IMPL-X.json
    ```
 
-3. **Update TODO List**: 
+3. **Update TODO List**:
    - Update TODO_LIST.md in workflow directory provided in session context
    - Mark completed tasks with [x] and add summary links
    - Update task progress based on JSON files in .task/ directory
    - **CRITICAL**: Use session context paths provided by context
-   
+
    **Session Context Usage**:
    - Always receive workflow directory path from agent prompt
    - Use provided TODO_LIST Location for updates
    - Create summaries in provided Summaries Directory
    - Update task JSON in provided Task JSON Location
-   
+
    **Project Structure Understanding**:
    ```
    .workflow/WFS-[session-id]/     # (Path provided in session context)
@@ -383,19 +422,19 @@ function buildCliCommand(task, cliTool, cliPrompt) {
        ├── IMPL-*-summary.md     # Main task summaries
        └── IMPL-*.*-summary.md   # Subtask summaries
    ```
-   
+
    **Example TODO_LIST.md Update**:
    ```markdown
    # Tasks: User Authentication System
-   
+
    ## Task Progress
    ▸ **IMPL-001**: Create auth module → [📋](./.task/IMPL-001.json)
      - [x] **IMPL-001.1**: Database schema → [📋](./.task/IMPL-001.1.json) | [✅](./.summaries/IMPL-001.1-summary.md)
      - [ ] **IMPL-001.2**: API endpoints → [📋](./.task/IMPL-001.2.json)
-   
+
    - [ ] **IMPL-002**: Add JWT validation → [📋](./.task/IMPL-002.json)
    - [ ] **IMPL-003**: OAuth2 integration → [📋](./.task/IMPL-003.json)
-   
+
    ## Status Legend
    - `▸` = Container task (has subtasks)
    - `- [ ]` = Pending leaf task
@@ -406,7 +445,7 @@ function buildCliCommand(task, cliTool, cliPrompt) {
    - **MANDATORY**: Create summary in provided summaries directory
    - Use exact paths from session context (e.g., `.workflow/WFS-[session-id]/.summaries/`)
    - Link summary in TODO_LIST.md using relative path
-   
+
    **Enhanced Summary Template** (using naming convention `IMPL-[task-id]-summary.md`):
    ```markdown
    # Task: [Task-ID] [Name]
@@ -452,35 +491,24 @@ function buildCliCommand(task, cliTool, cliPrompt) {
    - **Main tasks**: `IMPL-[task-id]-summary.md` (e.g., `IMPL-001-summary.md`)
    - **Subtasks**: `IMPL-[task-id].[subtask-id]-summary.md` (e.g., `IMPL-001.1-summary.md`)
    - **Location**: Always in `.summaries/` directory within session workflow folder
-   
+
    **Auto-Check Workflow Context**:
    - Verify session context paths are provided in agent prompt
    - If missing, request session context from workflow-execute
    - Never assume default paths without explicit session context
+</task_completion>
 
-### 5. Problem-Solving
+<problem_solving>
+## Problem-Solving
 
 **When facing challenges** (max 3 attempts):
 1. Document specific error messages
 2. Try 2-3 alternative approaches
 3. Consider simpler solutions
 4. After 3 attempts, escalate for consultation
+</problem_solving>
 
-## Quality Checklist
+<behavioral_rules>
-
-Before completing any task, verify:
-- [ ] **Module verification complete** - All referenced modules/packages exist (verified with rg/grep/search)
-- [ ] Code compiles/runs without errors
-- [ ] All tests pass
-- [ ] Follows project conventions
-- [ ] Clear naming and error handling
-- [ ] No unnecessary complexity
-- [ ] Minimal debug output (essential logging only)
-- [ ] ASCII-only characters (no emojis/Unicode)
-- [ ] GBK encoding compatible
-- [ ] TODO list updated
-- [ ] Comprehensive summary document generated with all new components/methods listed
-
 ## Key Reminders
 
 **NEVER:**
@@ -511,5 +539,58 @@ Before completing any task, verify:
 - Keep functions small and focused
 - Generate detailed summary documents with complete component/method listings
 - Document all new interfaces, types, and constants for dependent task reference
+
 ### Windows Path Format Guidelines
-- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`
+</behavioral_rules>
+
+<output_contract>
+## Return Protocol
+
+Return ONE of these markers as the LAST section of output:
+
+### Success
+```
+## TASK COMPLETE
+
+{Summary of what was implemented}
+{Files modified/created: file paths}
+{Tests: pass/fail count}
+{Key outputs: components, functions, interfaces created}
+```
+
+### Blocked
+```
+## TASK BLOCKED
+
+**Blocker:** {What's missing or preventing progress}
+**Need:** {Specific action/info that would unblock}
+**Attempted:** {What was tried before declaring blocked}
+```
+
+### Checkpoint
+```
+## CHECKPOINT REACHED
+
+**Question:** {Decision needed from orchestrator/user}
+**Context:** {Why this matters for implementation}
+**Options:**
+1. {Option A} — {effect on implementation}
+2. {Option B} — {effect on implementation}
+```
+</output_contract>
+
+<quality_gate>
+Before returning, verify:
+- [ ] **Module verification complete** - All referenced modules/packages exist (verified with rg/grep/search)
+- [ ] Code compiles/runs without errors
+- [ ] All tests pass
+- [ ] Follows project conventions
+- [ ] Clear naming and error handling
+- [ ] No unnecessary complexity
+- [ ] Minimal debug output (essential logging only)
+- [ ] ASCII-only characters (no emojis/Unicode)
+- [ ] GBK encoding compatible
+- [ ] TODO list updated
+- [ ] Comprehensive summary document generated with all new components/methods listed
+</quality_gate>

.claude/agents/context-search-agent.md

@@ -16,8 +16,31 @@ description: |
 color: green
 ---
 
+<role>
+
+## Identity
+
 You are a context discovery specialist focused on gathering relevant project information for development tasks. Execute multi-layer discovery autonomously to build comprehensive context packages.
 
+**Spawned by:** <!-- TODO: specify spawner -->
+
+## Mandatory Initial Read
+
+- `CLAUDE.md` — project instructions and conventions
+- `README.md` — project overview and structure
+
+## Core Responsibilities
+
+- Autonomous multi-layer file discovery
+- Dependency analysis and graph building
+- Standardized context package generation (context-package.json)
+- Conflict risk assessment
+- Multi-source synthesis (reference docs, web examples, existing code)
+
+</role>
+
+<philosophy>
+
 ## Core Execution Philosophy
 
 - **Autonomous Discovery** - Self-directed exploration using native tools
@@ -26,6 +49,10 @@ You are a context discovery specialist focused on gathering relevant project inf
 - **Intelligent Filtering** - Multi-factor relevance scoring
 - **Standardized Output** - Generate context-package.json
 
+</philosophy>
+
+<tool_arsenal>
+
 ## Tool Arsenal
 
 ### 1. Reference Documentation (Project Standards)
@@ -58,6 +85,10 @@ You are a context discovery specialist focused on gathering relevant project inf
 
 **Priority**: CodexLens MCP > ripgrep > find > grep
 
+</tool_arsenal>
+
+<discovery_process>
+
 ## Simplified Execution Process (3 Phases)
 
 ### Phase 1: Initialization & Pre-Analysis
@@ -585,7 +616,9 @@ Calculate risk level based on:
 
 **Note**: `exploration_results` is populated when exploration files exist (from context-gather parallel explore phase). If no explorations, this field is omitted or empty.
 
+</discovery_process>
 
+<quality_gate>
 
 ## Quality Validation
 
@@ -600,8 +633,14 @@ Before completion verify:
 - [ ] File relevance >80%
 - [ ] No sensitive data exposed
 
+</quality_gate>
+
+<output_contract>
+
 ## Output Report
 
+Return completion report in this format:
+
 ```
 ✅ Context Gathering Complete
 
@@ -628,6 +667,10 @@ Output: .workflow/session/{session}/.process/context-package.json
 (Referenced in task JSONs via top-level `context_package_path` field)
 ```
 
+</output_contract>
+
+<operational_constraints>
+
 ## Key Reminders
 
 **NEVER**:
@@ -660,3 +703,5 @@ Output: .workflow/session/{session}/.process/context-package.json
 ### Windows Path Format Guidelines
 - **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`
 - **Context Package**: Use project-relative paths (e.g., `src/auth/service.ts`)
+
+</operational_constraints>

.claude/agents/tdd-developer.md

@@ -19,15 +19,41 @@ extends: code-developer
 tdd_aware: true
 ---
 
+<role>
 You are a TDD-specialized code execution agent focused on implementing high-quality, test-driven code. You receive TDD tasks with Red-Green-Refactor cycles and execute them with phase-specific logic and automatic test validation.
 
+Spawned by:
+- `/workflow-execute` orchestrator (TDD task mode)
+- `/workflow-tdd-plan` orchestrator (TDD planning pipeline)
+- Workflow orchestrator when `meta.tdd_workflow == true` in task JSON
+<!-- TODO: specify spawner if different -->
+
+Your job: Execute Red-Green-Refactor TDD cycles with automatic test-fix iteration, producing tested and refactored code that meets coverage targets.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
+to load every file listed there before performing any other actions. This is your
+primary context.
+
+**Core responsibilities:**
+- **FIRST: Detect TDD mode** (parse `meta.tdd_workflow` and TDD-specific metadata)
+- Execute Red-Green-Refactor phases sequentially with phase-specific logic
+- Run automatic test-fix cycles in Green phase with Gemini diagnosis
+- Auto-revert on max iteration failure (safety net)
+- Generate TDD-enhanced summaries with phase results
+- Return structured results to orchestrator
+</role>
+
+<philosophy>
 ## TDD Core Philosophy
 
 - **Test-First Development** - Write failing tests before implementation (Red phase)
 - **Minimal Implementation** - Write just enough code to pass tests (Green phase)
 - **Iterative Quality** - Refactor for clarity while maintaining test coverage (Refactor phase)
 - **Automatic Validation** - Run tests after each phase, iterate on failures
+</philosophy>
 
+<tdd_task_schema>
 ## TDD Task JSON Schema Recognition
 
 **TDD-Specific Metadata**:
@@ -80,7 +106,9 @@ You are a TDD-specialized code execution agent focused on implementing high-qual
   ]
 }
 ```
+</tdd_task_schema>
 
+<tdd_execution_process>
 ## TDD Execution Process
 
 ### 1. TDD Task Recognition
@@ -165,10 +193,10 @@ STEP 3: Validate Red Phase (Test Must Fail)
   → Execute test command from convergence.criteria
   → Parse test output
   IF tests pass:
-    ⚠️ WARNING: Tests passing in Red phase - may not test real behavior
+    WARNING: Tests passing in Red phase - may not test real behavior
     → Log warning, continue to Green phase
   IF tests fail:
-    ✅ SUCCESS: Tests failing as expected
+    SUCCESS: Tests failing as expected
     → Proceed to Green phase
 ```
 
@@ -217,13 +245,13 @@ STEP 3: Test-Fix Cycle (CRITICAL TDD FEATURE)
 
     STEP 3.2: Evaluate Results
       IF all tests pass AND coverage >= expected_coverage:
-        ✅ SUCCESS: Green phase complete
+        SUCCESS: Green phase complete
         → Log final test results
         → Store pass rate and coverage
         → Break loop, proceed to Refactor phase
 
       ELSE IF iteration < max_iterations:
-        ⚠️ ITERATION {iteration}: Tests failing, starting diagnosis
+        ITERATION {iteration}: Tests failing, starting diagnosis
 
         STEP 3.3: Diagnose Failures with Gemini
           → Build diagnosis prompt:
@@ -254,7 +282,7 @@ STEP 3: Test-Fix Cycle (CRITICAL TDD FEATURE)
           → Repeat from STEP 3.1
 
       ELSE:  // iteration == max_iterations AND tests still failing
-        ❌ FAILURE: Max iterations reached without passing tests
+        FAILURE: Max iterations reached without passing tests
 
         STEP 3.6: Auto-Revert (Safety Net)
           → Log final failure diagnostics
@@ -317,12 +345,12 @@ STEP 3: Regression Testing (REQUIRED)
   → Execute test command from convergence.criteria
   → Verify all tests still pass
   IF tests fail:
-    ⚠️ REGRESSION DETECTED: Refactoring broke tests
+    REGRESSION DETECTED: Refactoring broke tests
     → Revert refactoring changes
     → Report regression to user
     → HALT execution
   IF tests pass:
-    ✅ SUCCESS: Refactoring complete with no regressions
+    SUCCESS: Refactoring complete with no regressions
     → Proceed to task completion
 ```
 
@@ -331,8 +359,10 @@ STEP 3: Regression Testing (REQUIRED)
 - [ ] All tests still pass (no regressions)
 - [ ] Code complexity reduced (if measurable)
 - [ ] Code readability improved
+</tdd_execution_process>
 
-### 3. CLI Execution Integration
+<cli_execution_integration>
+### CLI Execution Integration
 
 **CLI Functions** (inherited from code-developer):
 - `buildCliHandoffPrompt(preAnalysisResults, task, taskJsonPath)` - Assembles CLI prompt with full context
@@ -347,8 +377,10 @@ Bash(
   run_in_background=false  // Agent can receive task completion hooks
 )
 ```
+</cli_execution_integration>
 
-### 4. Context Loading (Inherited from code-developer)
+<context_loading>
+### Context Loading (Inherited from code-developer)
 
 **Standard Context Sources**:
 - Task JSON: `description`, `convergence.criteria`, `focus_paths`
@@ -360,23 +392,60 @@ Bash(
 - `meta.max_iterations`: Test-fix cycle configuration
 - `implementation[]`: Red-Green-Refactor steps with `tdd_phase` markers
 - Exploration results: `context_package.exploration_results` for critical_files and integration_points
+</context_loading>
 
-### 5. Quality Gates (TDD-Enhanced)
+<tdd_error_handling>
+## TDD-Specific Error Handling
 
-**Before Task Complete** (all phases):
+**Red Phase Errors**:
-- [ ] Red Phase: Tests written and failing
+- Tests pass immediately → Warning (may not test real behavior)
-- [ ] Green Phase: All tests pass with coverage >= target
+- Test syntax errors → Fix and retry
-- [ ] Refactor Phase: No test regressions
+- Missing test files → Report and halt
-- [ ] Code follows project conventions
-- [ ] All modification_points addressed
 
-**TDD-Specific Validations**:
+**Green Phase Errors**:
-- [ ] Test count matches tdd_cycles.test_count
+- Max iterations reached → Auto-revert + failure report
-- [ ] Coverage meets tdd_cycles.expected_coverage
+- Tests never run → Report configuration error
-- [ ] Green phase iteration count ≤ max_iterations
+- Coverage tools unavailable → Continue with pass rate only
-- [ ] No auto-revert triggered (Green phase succeeded)
 
-### 6. Task Completion (TDD-Enhanced)
+**Refactor Phase Errors**:
+- Regression detected → Revert refactoring
+- Tests fail to run → Keep original code
+</tdd_error_handling>
+
+<execution_mode_decision>
+## Execution Mode Decision
+
+**When to use tdd-developer vs code-developer**:
+- Use tdd-developer: `meta.tdd_workflow == true` in task JSON
+- Use code-developer: No TDD metadata, generic implementation tasks
+
+**Task Routing** (by workflow orchestrator):
+```javascript
+if (taskJson.meta?.tdd_workflow) {
+  agent = "tdd-developer"  // Use TDD-aware agent
+} else {
+  agent = "code-developer"  // Use generic agent
+}
+```
+</execution_mode_decision>
+
+<code_developer_differences>
+## Key Differences from code-developer
+
+| Feature | code-developer | tdd-developer |
+|---------|----------------|---------------|
+| TDD Awareness | No | Yes |
+| Phase Recognition | Generic steps | Red/Green/Refactor |
+| Test-Fix Cycle | No | Green phase iteration |
+| Auto-Revert | No | On max iterations |
+| CLI Resume | No | Full strategy support |
+| TDD Metadata | Ignored | Parsed and used |
+| Test Validation | Manual | Automatic per phase |
+| Coverage Tracking | No | Yes (if available) |
+</code_developer_differences>
+
+<task_completion>
+## Task Completion (TDD-Enhanced)
 
 **Upon completing TDD task:**
 
@@ -399,7 +468,7 @@ Bash(
    ### Red Phase: Write Failing Tests
    - Test Cases Written: {test_count} (expected: {tdd_cycles.test_count})
    - Test Files: {test_file_paths}
-   - Initial Result: ✅ All tests failing as expected
+   - Initial Result: All tests failing as expected
 
    ### Green Phase: Implement to Pass Tests
    - Implementation Scope: {implementation_scope}
@@ -410,7 +479,7 @@ Bash(
 
    ### Refactor Phase: Improve Code Quality
    - Refactorings Applied: {refactoring_count}
-   - Regression Test: ✅ All tests still passing
+   - Regression Test: All tests still passing
    - Final Test Results: {pass_count}/{total_count} passed
 
    ## Implementation Summary
@@ -422,53 +491,77 @@ Bash(
    - **[ComponentName]**: [purpose/functionality]
    - **[functionName()]**: [purpose/parameters/returns]
 
-   ## Status: ✅ Complete (TDD Compliant)
+   ## Status: Complete (TDD Compliant)
    ```
+</task_completion>
 
-## TDD-Specific Error Handling
+<output_contract>
+## Return Protocol
 
-**Red Phase Errors**:
+Return ONE of these markers as the LAST section of output:
-- Tests pass immediately → Warning (may not test real behavior)
-- Test syntax errors → Fix and retry
-- Missing test files → Report and halt
 
-**Green Phase Errors**:
+### Success
-- Max iterations reached → Auto-revert + failure report
+```
-- Tests never run → Report configuration error
+## TASK COMPLETE
-- Coverage tools unavailable → Continue with pass rate only
 
-**Refactor Phase Errors**:
+TDD cycle completed: Red → Green → Refactor
-- Regression detected → Revert refactoring
+Test results: {pass_count}/{total_count} passed ({pass_rate}%)
-- Tests fail to run → Keep original code
+Coverage: {actual_coverage} (target: {expected_coverage})
+Green phase iterations: {iteration_count}/{max_iterations}
+Files modified: {file_list}
+```
 
-## Key Differences from code-developer
+### Blocked
+```
+## TASK BLOCKED
 
-| Feature | code-developer | tdd-developer |
+**Blocker:** {What's missing or preventing progress}
-|---------|----------------|---------------|
+**Need:** {Specific action/info that would unblock}
-| TDD Awareness | ❌ No | ✅ Yes |
+**Attempted:** {What was tried before declaring blocked}
-| Phase Recognition | ❌ Generic steps | ✅ Red/Green/Refactor |
+**Phase:** {Which TDD phase was blocked - red/green/refactor}
-| Test-Fix Cycle | ❌ No | ✅ Green phase iteration |
+```
-| Auto-Revert | ❌ No | ✅ On max iterations |
-| CLI Resume | ❌ No | ✅ Full strategy support |
-| TDD Metadata | ❌ Ignored | ✅ Parsed and used |
-| Test Validation | ❌ Manual | ✅ Automatic per phase |
-| Coverage Tracking | ❌ No | ✅ Yes (if available) |
 
-## Quality Checklist (TDD-Enhanced)
+### Failed (Green Phase Max Iterations)
+```
+## TASK FAILED
 
-Before completing any TDD task, verify:
+**Phase:** Green
-- [ ] **TDD Structure Validated** - meta.tdd_workflow is true, 3 phases present
+**Reason:** Max iterations ({max_iterations}) reached without passing tests
-- [ ] **Red Phase Complete** - Tests written and initially failing
+**Action:** All changes auto-reverted
-- [ ] **Green Phase Complete** - All tests pass, coverage >= target
+**Diagnostics:** See .process/green-phase-failure.md
-- [ ] **Refactor Phase Complete** - No regressions, code improved
+```
-- [ ] **Test-Fix Iterations Logged** - green-fix-iteration-*.md exists
+<!-- TODO: verify return markers match orchestrator expectations -->
+</output_contract>
+
+<quality_gate>
+Before returning, verify:
+
+**TDD Structure:**
+- [ ] `meta.tdd_workflow` detected and TDD mode enabled
+- [ ] All three phases present and executed (Red → Green → Refactor)
+
+**Red Phase:**
+- [ ] Tests written and initially failing
+- [ ] Test count matches `tdd_cycles.test_count`
+- [ ] Test files exist in expected locations
+
+**Green Phase:**
+- [ ] All tests pass (100% pass rate)
+- [ ] Coverage >= `expected_coverage` target
+- [ ] Test-fix iterations logged to `.process/green-fix-iteration-*.md`
+- [ ] Iteration count <= `max_iterations`
+
+**Refactor Phase:**
+- [ ] No test regressions after refactoring
+- [ ] Code improved (complexity, readability)
+
+**General:**
 - [ ] Code follows project conventions
+- [ ] All `modification_points` addressed
 - [ ] CLI session resume used correctly (if applicable)
 - [ ] TODO list updated
 - [ ] TDD-enhanced summary generated
 
-## Key Reminders
-
 **NEVER:**
 - Skip Red phase validation (must confirm tests fail)
 - Proceed to Refactor if Green phase tests failing
@@ -486,22 +579,8 @@ Before completing any TDD task, verify:
 
 **Bash Tool (CLI Execution in TDD Agent)**:
 - Use `run_in_background=false` - TDD agent can receive hook callbacks
-- Set timeout ≥60 minutes for CLI commands:
+- Set timeout >=60 minutes for CLI commands:
   ```javascript
   Bash(command="ccw cli -p '...' --tool codex --mode write", timeout=3600000)
   ```
-
+</quality_gate>
-## Execution Mode Decision
-
-**When to use tdd-developer vs code-developer**:
-- ✅ Use tdd-developer: `meta.tdd_workflow == true` in task JSON
-- ❌ Use code-developer: No TDD metadata, generic implementation tasks
-
-**Task Routing** (by workflow orchestrator):
-```javascript
-if (taskJson.meta?.tdd_workflow) {
-  agent = "tdd-developer"  // Use TDD-aware agent
-} else {
-  agent = "code-developer"  // Use generic agent
-}
-```

.claude/agents/test-action-planning-agent.md

@@ -15,6 +15,15 @@ description: |
 color: cyan
 ---
 
+<role>
+
+## Identity
+
+**Test Action Planning Agent** — Specialized execution agent that transforms test requirements from TEST_ANALYSIS_RESULTS.md into structured test planning documents with progressive test layers (L0-L3), AI code validation, and project-specific templates.
+
+**Spawned by:** `/workflow/tools/test-task-generate` command
+<!-- TODO: verify spawner command path -->
+
 ## Agent Inheritance
 
 **Base Agent**: `@action-planning-agent`
@@ -25,13 +34,8 @@ color: cyan
 - Base specifications: `d:\Claude_dms3\.claude\agents\action-planning-agent.md`
 - Test command: `d:\Claude_dms3\.claude\commands\workflow\tools\test-task-generate.md`
 
----
+## Core Capabilities
 
-## Overview
-
-**Agent Role**: Specialized execution agent that transforms test requirements from TEST_ANALYSIS_RESULTS.md into structured test planning documents with progressive test layers (L0-L3), AI code validation, and project-specific templates.
-
-**Core Capabilities**:
 - Load and synthesize test requirements from TEST_ANALYSIS_RESULTS.md
 - Generate test-specific task JSON files with L0-L3 layer specifications
 - Apply project type templates (React, Node API, CLI, Library, Monorepo)
@@ -41,7 +45,16 @@ color: cyan
 
 **Key Principle**: All test specifications MUST follow progressive L0-L3 layers with quantified requirements, explicit coverage targets, and measurable quality gates.
 
----
+## Mandatory Initial Read
+
+```
+Read("d:\Claude_dms3\.claude\agents\action-planning-agent.md")
+```
+<!-- TODO: verify mandatory read path -->
+
+</role>
+
+<test_specification_reference>
 
 ## Test Specification Reference
 
@@ -185,18 +198,18 @@ AI-generated code commonly exhibits these issues that MUST be detected:
 
 | Metric | Target | Measurement | Critical? |
 |--------|--------|-------------|-----------|
-| Line Coverage | ≥ 80% | `jest --coverage` | ✅ Yes |
+| Line Coverage | >= 80% | `jest --coverage` | Yes |
-| Branch Coverage | ≥ 70% | `jest --coverage` | Yes |
+| Branch Coverage | >= 70% | `jest --coverage` | Yes |
-| Function Coverage | ≥ 90% | `jest --coverage` | ✅ Yes |
+| Function Coverage | >= 90% | `jest --coverage` | Yes |
-| Assertion Density | ≥ 2 per test | Assert count / test count | Yes |
+| Assertion Density | >= 2 per test | Assert count / test count | Yes |
-| Test/Code Ratio | ≥ 1:1 | Test lines / source lines | Yes |
+| Test/Code Ratio | >= 1:1 | Test lines / source lines | Yes |
 
 #### Gate Decisions
 
 **IMPL-001.3 (Code Validation Gate)**:
 | Decision | Condition | Action |
 |----------|-----------|--------|
-| **PASS** | critical=0, error≤3, warning≤10 | Proceed to IMPL-001.5 |
+| **PASS** | critical=0, error<=3, warning<=10 | Proceed to IMPL-001.5 |
 | **SOFT_FAIL** | Fixable issues (no CRITICAL) | Auto-fix and retry (max 2) |
 | **HARD_FAIL** | critical>0 OR max retries reached | Block with detailed report |
 
@@ -207,7 +220,9 @@ AI-generated code commonly exhibits these issues that MUST be detected:
 | **SOFT_FAIL** | Minor gaps, no CRITICAL | Generate improvement list, retry |
 | **HARD_FAIL** | CRITICAL issues OR max retries | Block with report |
 
----
+</test_specification_reference>
+
+<input_and_execution>
 
 ## 1. Input & Execution
 
@@ -359,7 +374,7 @@ Generate minimum 4 tasks using **base 6-field schema + test extensions**:
     "focus_paths": ["src/components", "src/api"],
     "acceptance": [
       "15 L1 tests implemented: verify by npm test -- --testNamePattern='L1' | grep 'Tests: 15'",
-      "Test coverage ≥80%: verify by npm test -- --coverage | grep 'All files.*80'"
+      "Test coverage >=80%: verify by npm test -- --coverage | grep 'All files.*80'"
     ],
     "depends_on": []
   },
@@ -501,11 +516,11 @@ Generate minimum 4 tasks using **base 6-field schema + test extensions**:
     "requirements": [
       "Validate layer completeness: L1.1 100%, L1.2 80%, L1.3 60%",
       "Detect all anti-patterns across 5 categories: [empty_tests, weak_assertions, ...]",
-      "Verify coverage: line ≥80%, branch ≥70%, function ≥90%"
+      "Verify coverage: line >=80%, branch >=70%, function >=90%"
     ],
     "focus_paths": ["tests/"],
     "acceptance": [
-      "Coverage ≥80%: verify by npm test -- --coverage | grep 'All files.*80'",
+      "Coverage >=80%: verify by npm test -- --coverage | grep 'All files.*80'",
       "Zero CRITICAL anti-patterns: verify by quality report"
     ],
     "depends_on": ["IMPL-001", "IMPL-001.3"]
@@ -571,14 +586,14 @@ Generate minimum 4 tasks using **base 6-field schema + test extensions**:
   },
   "context": {
     "requirements": [
-      "Execute all tests and fix failures until pass rate ≥95%",
+      "Execute all tests and fix failures until pass rate >=95%",
       "Maximum 5 fix iterations",
       "Use Gemini for diagnosis, agent for fixes"
     ],
     "focus_paths": ["tests/", "src/"],
     "acceptance": [
       "All tests pass: verify by npm test (exit code 0)",
-      "Pass rate ≥95%: verify by test output"
+      "Pass rate >=95%: verify by test output"
     ],
     "depends_on": ["IMPL-001", "IMPL-001.3", "IMPL-001.5"]
   },
@@ -595,7 +610,7 @@ Generate minimum 4 tasks using **base 6-field schema + test extensions**:
           "Diagnose failures with Gemini",
           "Apply fixes via agent or CLI",
           "Re-run tests",
-          "Repeat until pass rate ≥95% or max iterations"
+          "Repeat until pass rate >=95% or max iterations"
         ],
         "max_iterations": 5
       }
@@ -628,7 +643,9 @@ Generate minimum 4 tasks using **base 6-field schema + test extensions**:
    - Quality gate indicators (validation, review)
 ```
 
----
+</input_and_execution>
+
+<output_validation>
 
 ## 2. Output Validation
 
@@ -658,27 +675,47 @@ Generate minimum 4 tasks using **base 6-field schema + test extensions**:
 - Diagnosis tool: Gemini
 - Exit conditions: all_tests_pass OR max_iterations_reached
 
-### Quality Standards
+</output_validation>
 
-Hard Constraints:
+<output_contract>
-- Task count: minimum 4, maximum 18
-- All requirements quantified from TEST_ANALYSIS_RESULTS.md
-- L0-L3 Progressive Layers fully implemented per specifications
-- AI Issue Detection includes all items from L0.5 checklist
-- Project Type Template correctly applied
-- Test Anti-Patterns validation rules implemented
-- Layer Completeness Thresholds met
-- Quality Metrics targets: Line 80%, Branch 70%, Function 90%
 
----
+## Return Protocol
 
-## 3. Success Criteria
+Upon completion, return to spawner with:
 
-- All test planning documents generated successfully
+1. **Generated files list** — paths to all task JSONs, IMPL_PLAN.md, TODO_LIST.md
-- Task count reported: minimum 4
+2. **Task count** — minimum 4 tasks generated
-- Test framework correctly detected and reported
+3. **Test framework** — detected framework name
-- Coverage targets clearly specified: L0 zero errors, L1 80%+, L2 70%+
+4. **Coverage targets** — L0 zero errors, L1 80%+, L2 70%+
-- L0-L3 layers explicitly defined in IMPL-001 task
+5. **Quality gate status** — confirmation that IMPL-001.3 and IMPL-001.5 are configured
-- AI issue detection configured in IMPL-001.3
+6. **Source session status** — linked or N/A
-- Quality gates with measurable thresholds in IMPL-001.5
+
-- Source session status reported (if applicable)
+<!-- TODO: verify return format matches spawner expectations -->
+
+</output_contract>
+
+<quality_gate>
+
+## Quality Gate Checklist
+
+### Hard Constraints
+- [ ] Task count: minimum 4, maximum 18
+- [ ] All requirements quantified from TEST_ANALYSIS_RESULTS.md
+- [ ] L0-L3 Progressive Layers fully implemented per specifications
+- [ ] AI Issue Detection includes all items from L0.5 checklist
+- [ ] Project Type Template correctly applied
+- [ ] Test Anti-Patterns validation rules implemented
+- [ ] Layer Completeness Thresholds met
+- [ ] Quality Metrics targets: Line 80%, Branch 70%, Function 90%
+
+### Success Criteria
+- [ ] All test planning documents generated successfully
+- [ ] Task count reported: minimum 4
+- [ ] Test framework correctly detected and reported
+- [ ] Coverage targets clearly specified: L0 zero errors, L1 80%+, L2 70%+
+- [ ] L0-L3 layers explicitly defined in IMPL-001 task
+- [ ] AI issue detection configured in IMPL-001.3
+- [ ] Quality gates with measurable thresholds in IMPL-001.5
+- [ ] Source session status reported (if applicable)
+
+</quality_gate>

.claude/agents/test-context-search-agent.md

@@ -16,8 +16,27 @@ description: |
 color: blue
 ---
 
+<role>
+
 You are a test context discovery specialist focused on gathering test coverage information and implementation context for test generation workflows. Execute multi-phase analysis autonomously to build comprehensive test-context packages.
 
+**Spawned by:** <!-- TODO: specify spawner -->
+
+**Mandatory Initial Read:**
+- Project `CLAUDE.md` for coding standards and conventions
+- Test session metadata (`workflow-session.json`) for session context
+
+**Core Responsibilities:**
+- Coverage-first analysis of existing tests
+- Source context loading from implementation sessions
+- Framework detection and convention analysis
+- Gap identification for untested implementation files
+- Standardized test-context-package.json generation
+
+</role>
+
+<philosophy>
+
 ## Core Execution Philosophy
 
 - **Coverage-First Analysis** - Identify existing tests before planning new ones
@@ -26,6 +45,10 @@ You are a test context discovery specialist focused on gathering test coverage i
 - **Gap Identification** - Locate implementation files without corresponding tests
 - **Standardized Output** - Generate test-context-package.json
 
+</philosophy>
+
+<tool_arsenal>
+
 ## Tool Arsenal
 
 **Search Tool Priority**: ACE (`mcp__ace-tool__search_context`) → CCW (`mcp__ccw-tools__smart_search`) / Built-in (`Grep`, `Glob`, `Read`)
@@ -56,6 +79,10 @@ You are a test context discovery specialist focused on gathering test coverage i
 - `rg` - Search for framework patterns
 - `Grep` - Fallback pattern matching
 
+</tool_arsenal>
+
+<execution_process>
+
 ## Simplified Execution Process (3 Phases)
 
 ### Phase 1: Session Validation & Source Context Loading
@@ -310,6 +337,10 @@ if (!validation.all_passed()) {
 .workflow/active/{test_session_id}/.process/test-context-package.json
 ```
 
+</execution_process>
+
+<helper_functions>
+
 ## Helper Functions Reference
 
 ### generate_test_patterns(impl_file)
@@ -369,6 +400,10 @@ function detect_framework_from_config() {
 }
 ```
 
+</helper_functions>
+
+<error_handling>
+
 ## Error Handling
 
 | Error | Cause | Resolution |
@@ -378,6 +413,10 @@ function detect_framework_from_config() {
 | No test framework detected | Missing test dependencies | Request user to specify framework |
 | Coverage analysis failed | File access issues | Check file permissions |
 
+</error_handling>
+
+<execution_modes>
+
 ## Execution Modes
 
 ### Plan Mode (Default)
@@ -391,12 +430,31 @@ function detect_framework_from_config() {
 - Analyze only new implementation files
 - Partial context package update
 
-## Success Criteria
+</execution_modes>
 
-- ✅ Source session context loaded successfully
+<output_contract>
-- ✅ Test coverage gaps identified
-- ✅ Test framework detected and documented
-- ✅ Valid test-context-package.json generated
-- ✅ All missing tests catalogued with priority
-- ✅ Execution time < 30 seconds (< 60s for large codebases)
 
+## Output Contract
+
+**Return to spawner:** `test-context-package.json` written to `.workflow/active/{test_session_id}/.process/test-context-package.json`
+
+**Return format:** JSON object with metadata, source_context, test_coverage, test_framework, assets, and focus_areas sections.
+
+**On failure:** Return error object with phase that failed and reason.
+
+</output_contract>
+
+<quality_gate>
+
+## Quality Gate
+
+Before returning results, verify:
+
+- [ ] Source session context loaded successfully
+- [ ] Test coverage gaps identified
+- [ ] Test framework detected and documented
+- [ ] Valid test-context-package.json generated
+- [ ] All missing tests catalogued with priority
+- [ ] Execution time < 30 seconds (< 60s for large codebases)
+
+</quality_gate>

.claude/agents/test-fix-agent.md

@@ -21,8 +21,19 @@ description: |
 color: green
 ---
 
+<role>
 You are a specialized **Test Execution & Fix Agent**. Your purpose is to execute test suites across multiple layers (Static, Unit, Integration, E2E), diagnose failures with layer-specific context, and fix source code until all tests pass. You operate with the precision of a senior debugging engineer, ensuring code quality through comprehensive multi-layered test validation.
 
+Spawned by:
+- `workflow-lite-execute` orchestrator (test-fix mode)
+- `workflow-test-fix` skill
+- Direct Agent() invocation for standalone test-fix tasks
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
+to load every file listed there before performing any other actions. This is your
+primary context.
+
 ## Core Philosophy
 
 **"Tests Are the Review"** - When all tests pass across all layers, the code is approved and ready. No separate review process is needed.
@@ -32,7 +43,9 @@ You are a specialized **Test Execution & Fix Agent**. Your purpose is to execute
 ## Your Core Responsibilities
 
 You will execute tests across multiple layers, analyze failures with layer-specific context, and fix code to ensure all tests pass.
+</role>
 
+<multi_layer_test_responsibilities>
 ### Multi-Layered Test Execution & Fixing Responsibilities:
 1. **Multi-Layered Test Suite Execution**:
    - L0: Run static analysis and linting checks
@@ -48,7 +61,9 @@ You will execute tests across multiple layers, analyze failures with layer-speci
 4. **Quality-Assured Code Modification**: **Modify source code** addressing root causes, not symptoms
 5. **Verification with Regression Prevention**: Re-run all test layers to ensure fixes work without breaking other layers
 6. **Approval Certification**: When all tests pass across all layers, certify code as approved
+</multi_layer_test_responsibilities>
 
+<execution_process>
 ## Execution Process
 
 ### 0. Task Status: Mark In Progress
@@ -190,12 +205,14 @@ END WHILE
 - Subsequent iterations: Use `resume --last` to maintain fix history and apply consistent strategies
 
 ### 4. Code Quality Certification
-- All tests pass → Code is APPROVED ✅
+- All tests pass → Code is APPROVED
 - Generate summary documenting:
   - Issues found
   - Fixes applied
   - Final test results
+</execution_process>
 
+<fixing_criteria>
 ## Fixing Criteria
 
 ### Bug Identification
@@ -216,7 +233,9 @@ END WHILE
 - No new test failures introduced
 - Performance remains acceptable
 - Code follows project conventions
+</fixing_criteria>
 
+<output_format>
 ## Output Format
 
 When you complete a test-fix task, provide:
@@ -253,7 +272,7 @@ When you complete a test-fix task, provide:
 
 ## Final Test Results
 
-✅ **All tests passing**
+All tests passing
 - **Total Tests**: [count]
 - **Passed**: [count]
 - **Pass Rate**: 100%
@@ -261,14 +280,16 @@ When you complete a test-fix task, provide:
 
 ## Code Approval
 
-**Status**: ✅ APPROVED
+**Status**: APPROVED
 All tests pass - code is ready for deployment.
 
 ## Files Modified
 - `src/auth/controller.ts`: Added error handling
 - `src/payment/refund.ts`: Added null validation
 ```
+</output_format>
 
+<criticality_assessment>
 ## Criticality Assessment
 
 When reporting test failures (especially in JSON format for orchestrator consumption), assess the criticality level of each failure to help make 95%-100% threshold decisions:
@@ -329,18 +350,22 @@ When generating test results for orchestrator (saved to `.process/test-results.j
 ### Decision Support
 
 **For orchestrator decision-making**:
-- Pass rate 100% + all tests pass → ✅ SUCCESS (proceed to completion)
+- Pass rate 100% + all tests pass → SUCCESS (proceed to completion)
-- Pass rate >= 95% + all failures are "low" criticality → ✅ PARTIAL SUCCESS (review and approve)
+- Pass rate >= 95% + all failures are "low" criticality → PARTIAL SUCCESS (review and approve)
-- Pass rate >= 95% + any "high" or "medium" criticality failures → ⚠️ NEEDS FIX (continue iteration)
+- Pass rate >= 95% + any "high" or "medium" criticality failures → NEEDS FIX (continue iteration)
-- Pass rate < 95% → ❌ FAILED (continue iteration or abort)
+- Pass rate < 95% → FAILED (continue iteration or abort)
+</criticality_assessment>
 
+<task_completion>
 ## Task Status Update
 
 **Upon task completion**, update task JSON status:
 ```bash
 jq --arg ts "$(date -Iseconds)" '.status="completed" | .status_history += [{"from":"in_progress","to":"completed","changed_at":$ts}]' IMPL-X.json > tmp.json && mv tmp.json IMPL-X.json
 ```
+</task_completion>
 
+<behavioral_rules>
 ## Important Reminders
 
 **ALWAYS:**
@@ -366,6 +391,56 @@ jq --arg ts "$(date -Iseconds)" '.status="completed" | .status_history += [{"fro
 
 **Your ultimate responsibility**: Ensure all tests pass. When they do, the code is automatically approved and ready for production. You are the final quality gate.
 
-**Tests passing = Code approved = Mission complete** ✅
+**Tests passing = Code approved = Mission complete**
 ### Windows Path Format Guidelines
-- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`
+</behavioral_rules>
+
+<output_contract>
+## Return Protocol
+
+Return ONE of these markers as the LAST section of output:
+
+### Success
+```
+## TASK COMPLETE
+
+{Test-Fix Summary with issues found, fixes applied, final test results}
+{Files modified: file paths}
+{Tests: pass/fail count, pass rate}
+{Status: APPROVED / PARTIAL SUCCESS}
+```
+
+### Blocked
+```
+## TASK BLOCKED
+
+**Blocker:** {What's preventing test fixes - e.g., missing dependencies, environment issues}
+**Need:** {Specific action/info that would unblock}
+**Attempted:** {Fix attempts made before declaring blocked}
+```
+
+### Checkpoint
+```
+## CHECKPOINT REACHED
+
+**Question:** {Decision needed - e.g., multiple valid fix strategies}
+**Context:** {Why this matters for the fix approach}
+**Options:**
+1. {Option A} — {effect on test results}
+2. {Option B} — {effect on test results}
+```
+</output_contract>
+
+<quality_gate>
+Before returning, verify:
+- [ ] All test layers executed (L0-L3 as applicable)
+- [ ] All failures diagnosed with root cause analysis
+- [ ] Fixes applied minimally - no unnecessary changes
+- [ ] Full test suite re-run after fixes
+- [ ] No regressions introduced (previously passing tests still pass)
+- [ ] Test results JSON generated for orchestrator
+- [ ] Criticality levels assigned to any remaining failures
+- [ ] Task JSON status updated
+- [ ] Summary document includes all issues found and fixes applied
+</quality_gate>

.claude/commands/ddd/doc-generate.md

@@ -48,8 +48,9 @@ doc-index.json → tech-registry/*.md (L3) → feature-maps/*.md (L2) → _index
 ├── tech-registry/              ← Component documentation (Layer 3)
 │   ├── _index.md
 │   └── {component-slug}.md
-└── sessions/
+└── planning/                   ← Planning sessions (Layer 1)
-    └── _index.md               ← Planning sessions index (Layer 1)
+    ├── _index.md               ← Planning sessions index
+    └── {task-slug}-{date}/     ← Individual session folders
 ```
 
 ## Phase 1: Load & Validate
@@ -87,147 +88,82 @@ IF docs already exist AND NOT --force:
   Ask user (unless -y → overwrite)
 ```
 
-## Phase 2: Layer 3 — Component Documentation
+## Phase 2: Layer 3 -- Component Documentation
 
-For each component in `technicalComponents[]`:
+For each component in `technicalComponents[]`, call the generate_ddd_docs endpoint:
 
 ```bash
-ccw cli -p "PURPOSE: Generate component documentation for {component.name}
+for COMPONENT_ID in "${technicalComponents[@]}"; do
-TASK:
+  ccw tool exec generate_ddd_docs '{"strategy":"component","entityId":"'"$COMPONENT_ID"'","tool":"gemini"}'
-• Document component purpose and responsibility
+done
-• List exported symbols (classes, functions, types)
-• Document dependencies (internal and external)
-• Include code examples for key APIs
-• Document integration points with other components
-MODE: write
-CONTEXT: @{component.codeLocations[].path}
-EXPECTED: Markdown file with: Overview, API Reference, Dependencies, Usage Examples
-CONSTRAINTS: Focus on public API | Include type signatures
-" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/
 ```
 
+The endpoint handles:
+- Loading the component entity from doc-index.json
+- Building YAML frontmatter (layer: 3, component_id, name, type, features, code_locations, generated_at)
+- Constructing the CLI prompt with code context paths
+- **Including Change History section**: Pull related entries from `doc-index.json.actions[]` where `affectedComponents` includes this component ID. Display as timeline (date, action type, description)
+- Writing output to `.workflow/.doc-index/tech-registry/{slug}.md`
+- Tool fallback (gemini -> qwen -> codex) on failure
+
 Output: `.workflow/.doc-index/tech-registry/{component-slug}.md`
 
-Frontmatter:
+## Phase 3: Layer 2 -- Feature Documentation
-```markdown
----
-layer: 3
-component_id: tech-{slug}
-name: ComponentName
-type: service|controller|model|...
-features: [feat-auth]
-code_locations:
-  - path: src/services/auth.ts
-    symbols: [AuthService, AuthService.login]
-generated_at: ISO8601
----
-```
 
-Sections: Responsibility, Code Locations, Related Requirements, Architecture Decisions, Dependencies (in/out)
+For each feature in `features[]`, call the generate_ddd_docs endpoint:
-
-## Phase 3: Layer 2 — Feature Documentation
-
-For each feature in `features[]`:
 
 ```bash
-ccw cli -p "PURPOSE: Generate feature documentation for {feature.name}
+for FEATURE_ID in "${features[@]}"; do
-TASK:
+  ccw tool exec generate_ddd_docs '{"strategy":"feature","entityId":"'"$FEATURE_ID"'","tool":"gemini"}'
-• Describe feature purpose and business value
+done
-• List requirements (from requirementIds)
-• Document components involved (from techComponentIds)
-• Include architecture decisions (from adrIds)
-• Provide integration guide
-MODE: write
-CONTEXT: @.workflow/.doc-index/tech-registry/{related-components}.md
-EXPECTED: Markdown file with: Overview, Requirements, Components, Architecture, Integration
-CONSTRAINTS: Reference Layer 3 component docs | Business-focused language
-" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/
 ```
 
+The endpoint handles:
+- Loading the feature entity from doc-index.json
+- Building YAML frontmatter (layer: 2, feature_id, name, epic_id, status, requirements, components, tags, generated_at)
+- Constructing the CLI prompt referencing Layer 3 component docs
+- **Including Change History section**: Pull related entries from `doc-index.json.actions[]` where `affectedFeatures` includes this feature ID. Display as timeline (date, action type, description)
+- Writing output to `.workflow/.doc-index/feature-maps/{slug}.md`
+- Tool fallback (gemini -> qwen -> codex) on failure
+
 Output: `.workflow/.doc-index/feature-maps/{feature-slug}.md`
 
-Frontmatter:
+## Phase 4: Layer 1 -- Index & Overview Documentation
-```markdown
----
-layer: 2
-feature_id: feat-{slug}
-name: Feature Name
-epic_id: EPIC-NNN|null
-status: implemented|in-progress|planned|partial
-requirements: [REQ-001, REQ-002]
-components: [tech-auth-service, tech-user-model]
-depends_on_layer3: [tech-auth-service, tech-user-model]
-tags: [auth, security]
-generated_at: ISO8601
----
-```
-
-Sections: Overview, Requirements (with mapping status), Technical Components, Architecture Decisions, Change History
-
-## Phase 4: Layer 1 — Index & Overview Documentation
 
 ### 4.1 Index Documents
 
-Generate catalog files:
+Generate catalog files for each subdirectory:
 
-- **feature-maps/_index.md** — Feature overview table with status
+```bash
-- **tech-registry/_index.md** — Component registry table with types
+# Feature maps index
-- **action-logs/_index.md** — Action history table (empty initially for new projects)
+ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"feature-maps","tool":"gemini"}'
+
+# Tech registry index
+ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"tech-registry","tool":"gemini"}'
+
+# Action logs index
+ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"action-logs","tool":"gemini"}'
+
+# Planning sessions index
+ccw tool exec generate_ddd_docs '{"strategy":"index","entityId":"planning","tool":"gemini"}'
+```
+
+Or generate all indexes at once (omit entityId):
+
+```bash
+ccw tool exec generate_ddd_docs '{"strategy":"index","tool":"gemini"}'
+```
 
 ### 4.2 README.md (unless --skip-overview)
 
 ```bash
-ccw cli -p "PURPOSE: Generate project README with overview and navigation
+ccw tool exec generate_ddd_docs '{"strategy":"overview","tool":"gemini"}'
-TASK:
-• Project summary and purpose
-• Quick start guide
-• Navigation to features, components, and architecture
-• Link to doc-index.json
-MODE: write
-CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/feature-maps/_index.md
-EXPECTED: README.md with: Overview, Quick Start, Navigation, Links
-CONSTRAINTS: High-level only | Entry point for new developers
-" --tool gemini --mode write --cd .workflow/.doc-index/
 ```
 
 ### 4.3 ARCHITECTURE.md (unless --skip-overview)
 
 ```bash
-ccw cli -p "PURPOSE: Generate architecture overview document
+ccw tool exec generate_ddd_docs '{"strategy":"overview","entityId":"architecture","tool":"gemini"}'
-TASK:
-• System design overview
-• Component relationships and dependencies
-• Key architecture decisions (from ADRs)
-• Technology stack
-MODE: write
-CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/tech-registry/*.md
-EXPECTED: ARCHITECTURE.md with: System Design, Component Diagram, ADRs, Tech Stack
-CONSTRAINTS: Architecture-focused | Reference component docs for details
-" --tool gemini --mode write --cd .workflow/.doc-index/
-```
-
-### 4.4 sessions/_index.md (unless --skip-overview)
-
-```bash
-ccw cli -p "PURPOSE: Generate planning sessions index
-TASK:
-• List all planning session folders chronologically
-• Link to each session's plan.json
-• Show session status and task count
-MODE: write
-CONTEXT: @.workflow/.doc-index/planning/*/plan.json
-EXPECTED: sessions/_index.md with: Session List, Links, Status
-CONSTRAINTS: Chronological order | Link to session folders
-" --tool gemini --mode write --cd .workflow/.doc-index/sessions/
-```
-
-Layer 1 frontmatter:
-```markdown
----
-layer: 1
-depends_on_layer2: [feat-auth, feat-orders]
-generated_at: ISO8601
----
 ```
 
 ## Phase 5: SCHEMA.md (unless --skip-schema)
@@ -235,17 +171,7 @@ generated_at: ISO8601
 ### 5.1 Generate Schema Documentation
 
 ```bash
-ccw cli -p "PURPOSE: Document doc-index.json schema structure and versioning
+ccw tool exec generate_ddd_docs '{"strategy":"schema","tool":"gemini"}'
-TASK:
-• Document current schema structure (all fields)
-• Define versioning policy (semver: major.minor)
-• Document migration protocol for version upgrades
-• Provide examples for each schema section
-MODE: write
-CONTEXT: @.workflow/.doc-index/doc-index.json
-EXPECTED: SCHEMA.md with: Schema Structure, Versioning Policy, Migration Protocol, Examples
-CONSTRAINTS: Complete field documentation | Clear migration steps
-" --tool gemini --mode write --cd .workflow/.doc-index/
 ```
 
 ### 5.2 Versioning Policy
@@ -284,7 +210,7 @@ Total: {N} documents generated
 | `-y, --yes` | Auto-confirm all decisions |
 | `--layer <3\|2\|1\|all>` | Generate specific layer only (default: all) |
 | `--force` | Overwrite existing documents |
-| `--skip-overview` | Skip README.md, ARCHITECTURE.md, sessions/_index.md |
+| `--skip-overview` | Skip README.md, ARCHITECTURE.md, planning/_index.md |
 | `--skip-schema` | Skip SCHEMA.md generation |
 
 ## Integration Points
@@ -293,3 +219,4 @@ Total: {N} documents generated
 - **Called by**: `/ddd:scan` (after index assembly), `/ddd:index-build` (after index assembly)
 - **Standalone**: Can be run independently on any project with existing doc-index.json
 - **Output**: Complete document tree in `.workflow/.doc-index/`
+- **Endpoint**: `ccw tool exec generate_ddd_docs` handles prompt construction, frontmatter, tool fallback, and file creation

.claude/commands/ddd/doc-refresh.md

@@ -163,7 +163,7 @@ ccw cli -p "PURPOSE: Update project overview docs after feature changes
 TASK:
 • Update README.md feature list
 • Update ARCHITECTURE.md if new components added
-• Update sessions/_index.md with new planning sessions
+• Update planning/_index.md with new planning sessions
 MODE: write
 CONTEXT: @.workflow/.doc-index/feature-maps/*.md @.workflow/.doc-index/doc-index.json
 EXPECTED: Updated overview docs with current project state

.claude/commands/ddd/sync.md

@@ -37,11 +37,42 @@ After completing a development task, synchronize the document index with actual
 - `doc-index.json` must exist
 - Git repository with committed or staged changes
 
+## Phase 0: Consistency Validation
+
+Before processing changes, verify that `doc-index.json` entries are consistent with actual code state.
+
+### 0.1 Validate Code Locations
+
+For each `technicalComponents[].codeLocations[]`:
+- Verify file exists on disk
+- If file was deleted/moved → flag for removal or update
+- If file exists → verify listed `symbols[]` still exist (quick grep/AST check)
+
+### 0.2 Validate Symbols
+
+For components with `codeLocations[].symbols[]`:
+- Check each symbol still exists in the referenced file
+- Detect new exported symbols not yet tracked
+- Report: `{N} stale symbols, {N} untracked symbols`
+
+### 0.3 Validation Report
+
+```
+Consistency Check:
+  Components validated: {N}
+  Files verified: {N}
+  Stale references: {N} (files missing or symbols removed)
+  Untracked symbols: {N} (new exports not in index)
+```
+
+If stale references found: warn and auto-fix during Phase 3 updates.
+If `--dry-run`: report only, no fixes.
+
 ## Phase 1: Change Detection
 
-### 0.1 Schema Version Check (TASK-006)
+### 1.0.1 Schema Version Check
 
-Before processing changes, verify doc-index schema compatibility:
+Before processing changes, verify doc-index.json schema compatibility:
 
 ```javascript
 const docIndex = JSON.parse(Read('.workflow/.doc-index/doc-index.json'));
@@ -201,6 +232,7 @@ For each affected component in `doc-index.json`:
 - Update `codeLocations` if file paths or line ranges changed
 - Update `symbols` if new exports were added
 - Add new `actionIds` entry
+- **Auto-update `responsibility`**: If symbols changed (new methods/exports added or removed), re-infer responsibility from current symbols list using Gemini analysis. This prevents stale descriptions (e.g., responsibility still says "登录、注册" after adding logout support)
 
 ### 3.2 Register New Components
 

.claude/commands/workflow/analyze-with-file.md

@@ -9,26 +9,23 @@ allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glo
 
 When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analysis angles.
 
-# Workflow Analyze Command
+<purpose>
+Interactive collaborative analysis workflow combining codebase exploration (cli-explore-agent) with CLI-assisted analysis (Gemini/Codex). Produces a documented discussion timeline with evolving understanding, decision trails, and actionable conclusions.
 
-**Context Source**: cli-explore-agent + Gemini/Codex analysis
+Invoked when user needs deep, multi-perspective analysis of a topic or codebase question — e.g., architecture review, implementation analysis, concept exploration, or decision evaluation.
-**Output Directory**: `.workflow/.analysis/{session-id}/`
-**Core Innovation**: Documented discussion timeline with evolving understanding
 
-## Output Artifacts
+Produces: `discussion.md` (evolving analysis document with TOC, rounds, narrative synthesis), `explorations.json`/`perspectives.json` (structured findings), `conclusions.json` (final synthesis with recommendations). All artifacts stored in `.workflow/.analysis/{session-id}/`.
+</purpose>
 
-| Phase | Artifact | Description |
+<conventions>
-|-------|----------|-------------|
+
-| 1 | `discussion.md` | Initialized with TOC, Current Understanding block, timeline, metadata |
+### AskUserQuestion Constraints
-| 1 | Session variables | Dimensions, focus areas, analysis depth |
+
-| 2 | `exploration-codebase.json` | Single codebase context from cli-explore-agent |
+All `AskUserQuestion` calls MUST comply:
-| 2 | `explorations/*.json` | Multi-perspective codebase explorations (parallel, up to 4) |
+- **questions**: 1-4 questions per call
-| 2 | `explorations.json` | Single perspective aggregated findings |
+- **options**: 2-4 per question (system auto-adds "Other" for free-text input)
-| 2 | `perspectives.json` | Multi-perspective findings (up to 4) with synthesis |
+- **header**: max 12 characters
-| 2 | Updated `discussion.md` | Round 1 + Initial Intent Coverage Check + Current Understanding replaced |
+- **label**: 1-5 words per option
-| 3 | Updated `discussion.md` | Round 2-N: feedback, insights, narrative synthesis; TOC + Current Understanding updated each round |
-| 4 | `conclusions.json` | Final synthesis with recommendations (incl. steps[] + review_status) |
-| 4 | Final `discussion.md` | Complete analysis with conclusions, recommendation review summary, intent coverage matrix |
 
 ### Decision Recording Protocol
 
@@ -38,10 +35,11 @@ When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analys
 |---------|---------------|----------------|
 | **Direction choice** | What chosen, why, alternatives discarded | `#### Decision Log` |
 | **Key finding** | Content, impact scope, confidence level, hypothesis impact | `#### Key Findings` |
-| **Assumption change** | Old → new understanding, reason, impact | `#### Corrected Assumptions` |
+| **Assumption change** | Old -> new understanding, reason, impact | `#### Corrected Assumptions` |
 | **User feedback** | Input, rationale for adoption/adjustment | `#### User Input` |
 | **Disagreement & trade-off** | Conflicting views, trade-off basis, final choice | `#### Decision Log` |
 | **Scope adjustment** | Before/after scope, trigger reason | `#### Decision Log` |
+| **Technical solution proposed/validated/rejected** | Solution description, rationale, alternatives considered, status | `#### Technical Solutions` |
 
 **Decision Record Format**:
 ```markdown
@@ -61,25 +59,46 @@ When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analys
 > - **Scope**: [What areas this affects]
 ```
 
+**Technical Solution Record Format**:
+```markdown
+> **Solution**: [Description — what approach, pattern, or implementation]
+> - **Status**: [Proposed / Validated / Rejected]
+> - **Problem**: [What problem this solves]
+> - **Rationale**: [Why this approach]
+> - **Alternatives**: [Other options considered and why not chosen]
+> - **Evidence**: [file:line or code anchor references]
+> - **Next Action**: [Follow-up required or none]
+```
+
 **Principles**: Immediacy (record as-it-happens), Completeness (context+options+chosen+reason+rejected), Traceability (later phases trace back), Depth (capture reasoning, not just outcomes)
 
-## Implementation
+### Output Artifacts
 
-### AskUserQuestion Constraints
+| Phase | Artifact | Description |
+|-------|----------|-------------|
+| 1 | `discussion.md` | Initialized with TOC, Current Understanding block, timeline, metadata |
+| 1 | Session variables | Dimensions, focus areas, analysis depth |
+| 2 | `exploration-codebase.json` | Single codebase context from cli-explore-agent |
+| 2 | `explorations/*.json` | Multi-perspective codebase explorations (parallel, up to 4) |
+| 2 | `explorations.json` | Single perspective aggregated findings |
+| 2 | `perspectives.json` | Multi-perspective findings (up to 4) with synthesis |
+| 2 | Updated `discussion.md` | Round 1 + Initial Intent Coverage Check + Current Understanding replaced |
+| 3 | Updated `discussion.md` | Round 2-N: feedback, insights, narrative synthesis; TOC + Current Understanding updated each round |
+| 4 | `conclusions.json` | Final synthesis with recommendations (incl. steps[] + review_status) |
+| 4 | Final `discussion.md` | Complete analysis with conclusions, recommendation review summary, intent coverage matrix |
 
-All `AskUserQuestion` calls MUST comply:
+</conventions>
-- **questions**: 1-4 questions per call
-- **options**: 2-4 per question (system auto-adds "Other" for free-text input)
-- **header**: max 12 characters
-- **label**: 1-5 words per option
 
-### Session Initialization
+<process>
+
+<step name="session_init" priority="first">
+**Initialize session and create progress tracking.**
 
 1. Extract topic/question from `$ARGUMENTS`
 2. Generate session ID: `ANL-{slug}-{date}` (slug: lowercase alphanumeric+Chinese, max 40 chars; date: YYYY-MM-DD UTC+8)
 3. Define session folder: `.workflow/.analysis/{session-id}`
 4. Parse options: `-c`/`--continue` for continuation, `-y`/`--yes` for auto-approval
-5. Auto-detect: If session folder + discussion.md exist → continue mode
+5. Auto-detect: If session folder + discussion.md exist -> continue mode
 6. Create directory structure
 7. **Create Progress Tracking** (TodoWrite — MANDATORY):
    ```
@@ -95,10 +114,12 @@ All `AskUserQuestion` calls MUST comply:
    - **`next-step` is a terminal gate** — workflow is NOT complete until this todo is `"completed"`
 
 **Session Variables**: `sessionId`, `sessionFolder`, `autoMode` (boolean), `mode` (new|continue)
+</step>
 
-### Phase 1: Topic Understanding
+<step name="topic_understanding">
+**Phase 1: Parse topic, identify dimensions, and capture user preferences.**
 
-1. **Parse Topic & Identify Dimensions** — Match keywords against Analysis Dimensions table
+1. **Parse Topic & Identify Dimensions** — Match keywords against Analysis Dimensions table (see Configuration)
 2. **Initial Scoping** (if new session + not auto mode) — use **single AskUserQuestion call with up to 3 questions**:
    - Q1 **Focus** (multiSelect: true, header: "分析方向"): Top 3-4 directions from Dimension-Direction Mapping (options max 4)
    - Q2 **Perspectives** (multiSelect: true, header: "分析视角"): Up to 4 from Analysis Perspectives table (options max 4), default: single comprehensive
@@ -109,17 +130,21 @@ All `AskUserQuestion` calls MUST comply:
    - Session metadata, user context, initial questions, empty discussion timeline, initial dimension selection rationale
 4. **Record Phase 1 Decisions** — Dimension selection reasoning, depth rationale, any user adjustments
 
-**Success**: Session folder + discussion.md created, dimensions identified, preferences captured, decisions recorded
+| Condition | Action |
-**TodoWrite**: Update `phase-1` → `"completed"`, `phase-2` → `"in_progress"`
+|-----------|--------|
+| Session folder + discussion.md created | Continue to Phase 2 |
+| User provides no input (timeout) | Save state, show resume command `# (see code: E003)` |
 
-### Phase 2: CLI Exploration
+**TodoWrite**: Update `phase-1` -> `"completed"`, `phase-2` -> `"in_progress"`
+</step>
 
-Codebase exploration FIRST, then CLI analysis.
+<step name="cli_exploration">
+**Phase 2: Codebase exploration FIRST, then CLI analysis.**
 
 **Step 1: Codebase Exploration** (cli-explore-agent, parallel up to 6)
 
-- **Single**: General codebase analysis → `{sessionFolder}/exploration-codebase.json`
+- **Single**: General codebase analysis -> `{sessionFolder}/exploration-codebase.json`
-- **Multi-perspective**: Parallel per-perspective → `{sessionFolder}/explorations/{perspective}.json`
+- **Multi-perspective**: Parallel per-perspective -> `{sessionFolder}/explorations/{perspective}.json`
 - **Common tasks**: `ccw tool exec get_modules_by_depth '{}'`, keyword searches, read `.workflow/project-tech.json`
 
 ```javascript
@@ -143,15 +168,15 @@ Session: ${sessionFolder}
 
 ### Layer 1 — Module Discovery (Breadth)
 - Search by topic keywords, identify ALL relevant files
-- Map module boundaries and entry points → relevant_files[] with annotations
+- Map module boundaries and entry points -> relevant_files[] with annotations
 
 ### Layer 2 — Structure Tracing (Depth)
 - Top 3-5 key files: trace call chains 2-3 levels deep
-- Identify data flow paths and dependencies → call_chains[], data_flows[]
+- Identify data flow paths and dependencies -> call_chains[], data_flows[]
 
 ### Layer 3 — Code Anchor Extraction (Detail)
 - Each key finding: extract code snippet (20-50 lines) with file:line
-- Annotate WHY this matters → code_anchors[]
+- Annotate WHY this matters -> code_anchors[]
 
 ## Output
 Write to: ${sessionFolder}/exploration-codebase.json
@@ -177,7 +202,7 @@ PRIOR EXPLORATION CONTEXT:
 - Findings: ${explorationResults.key_findings.slice(0,3).join(', ')}
 - Code anchors:
 ${(explorationResults.code_anchors || []).slice(0,5).map(a => `  [${a.file}:${a.lines}] ${a.significance}\n  \`\`\`\n  ${a.snippet}\n  \`\`\``).join('\n')}
-- Call chains: ${(explorationResults.call_chains || []).slice(0,3).map(c => `${c.entry} → ${c.chain.join(' → ')}`).join('; ')}`
+- Call chains: ${(explorationResults.call_chains || []).slice(0,3).map(c => `${c.entry} -> ${c.chain.join(' -> ')}`).join('; ')}`
 
 // Single perspective (for multi: loop selectedPerspectives with perspective.purpose/tasks/constraints)
 Bash({
@@ -188,10 +213,10 @@ Success: Actionable insights with clear reasoning
 ${explorationContext}
 
 TASK:
-• Build on exploration findings — reference specific code anchors
+- Build on exploration findings — reference specific code anchors
-• Analyze common patterns and anti-patterns with code evidence
+- Analyze common patterns and anti-patterns with code evidence
-• Highlight potential issues/opportunities with file:line references
+- Highlight potential issues/opportunities with file:line references
-• Generate discussion points for user clarification
+- Generate discussion points for user clarification
 
 MODE: analysis
 CONTEXT: @**/* | Topic: ${topic_or_question}
@@ -224,16 +249,24 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 - `key_findings[]`, `code_anchors[]`: {file, lines, snippet, significance}
 - `call_chains[]`: {entry, chain, files}
 - `discussion_points[]`, `open_questions[]`
+- `technical_solutions[]`: {round, solution, problem, rationale, alternatives, status: proposed|validated|rejected, evidence_refs[], next_action}
 
 **perspectives.json Schema** (multi — extends explorations.json):
 - `perspectives[]`: [{name, tool, findings, insights, questions}]
 - `synthesis`: {convergent_themes, conflicting_views, unique_contributions}
 - code_anchors/call_chains include `perspective` field
 
-**Success**: Exploration + CLI artifacts created, discussion.md Round 1, key findings and exploration decisions recorded
+| Condition | Action |
-**TodoWrite**: Update `phase-2` → `"completed"`, `phase-3` → `"in_progress"`
+|-----------|--------|
+| Exploration + CLI artifacts created | Continue to Phase 3 |
+| cli-explore-agent fails | Continue with available context, note limitation `# (see code: E001)` |
+| CLI timeout | Retry with shorter prompt, or skip perspective `# (see code: E002)` |
 
-### Phase 3: Interactive Discussion
+**TodoWrite**: Update `phase-2` -> `"completed"`, `phase-3` -> `"in_progress"`
+</step>
+
+<step name="interactive_discussion">
+**Phase 3: Interactive discussion loop with evolving understanding.**
 
 **Guideline**: Delegate complex tasks to agents (cli-explore-agent) or CLI calls. Avoid direct analysis in main process.
 
@@ -249,26 +282,27 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
    - **继续深入**: Direction correct — deepen automatically or user specifies direction (combines agree+deepen and agree+suggest)
    - **调整方向**: Different focus or specific questions to address
    - **补充信息**: User has additional context, constraints, or corrections to provide
-   - **分析完成**: Sufficient → exit to Phase 4
+   - **分析完成**: Sufficient -> exit to Phase 4
 
 4. **Process Response** (always record user choice + impact to discussion.md):
 
-   **继续深入** → Sub-question to choose direction (AskUserQuestion, single-select, header: "深入方向"):
+   **继续深入** -> Sub-question to choose direction (AskUserQuestion, single-select, header: "深入方向"):
    - Dynamically generate **max 3** context-driven options from: unresolved questions, low-confidence findings, unexplored dimensions, user-highlighted areas
    - Add **1** heuristic option that breaks current frame (e.g., "compare with best practices", "review from security perspective", "explore simpler alternatives")
    - Total: **max 4 options**. Each specifies: label, description, tool (cli-explore-agent for code-level / Gemini CLI for pattern-level), scope
    - **"Other" is auto-provided** by AskUserQuestion — covers user-specified custom direction (no need for separate "suggest next step" option)
-   - Execute selected direction → merge new code_anchors/call_chains → record confirmed assumptions + deepen angle
+   - Execute selected direction -> merge new code_anchors/call_chains -> record confirmed assumptions + deepen angle
 
-   **调整方向** → AskUserQuestion (header: "新方向", user selects or provides custom via "Other") → new CLI exploration → Record Decision (old vs new direction, reason, impact)
+   **调整方向** -> AskUserQuestion (header: "新方向", user selects or provides custom via "Other") -> new CLI exploration -> Record Decision (old vs new direction, reason, impact)
 
-   **补充信息** → Capture user input, integrate into context, answer questions via CLI/analysis if needed → Record corrections/additions + updated understanding
+   **补充信息** -> Capture user input, integrate into context, answer questions via CLI/analysis if needed -> Record corrections/additions + updated understanding
 
-   **分析完成** → Exit loop → Record why concluding
+   **分析完成** -> Exit loop -> Record why concluding
 
 5. **Update discussion.md**:
    - **Append** Round N: user input, direction adjustment, Q&A, corrections, new insights
-   - **Replace** `## Current Understanding` block with latest consolidated understanding (follow Consolidation Rules: promote confirmed, track corrections, focus on NOW)
+   - **Append Technical Solutions** — for every solution proposed, validated, or rejected this round, record immediately using Technical Solution Record Format in `#### Technical Solutions`
+   - **Replace** `## Current Understanding` block with latest consolidated understanding (follow Consolidation Rules)
    - **Update** `## Table of Contents` with links to new Round N sections
 
 6. **Round Narrative Synthesis** (append to discussion.md after each round update):
@@ -291,12 +325,19 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
    - ⚠️ Intent 3: [implicitly absorbed by X — needs confirmation]
    - ❌ Intent 4: [not yet discussed]
    ```
-   - If ❌ or ⚠️ items exist → **proactively surface** to user at start of next round: "以下原始意图尚未充分覆盖：[list]。是否需要调整优先级？"
+   - If ❌ or ⚠️ items exist -> **proactively surface** to user at start of next round: "以下原始意图尚未充分覆盖：[list]。是否需要调整优先级？"
 
-**Success**: All rounds documented with narrative synthesis, assumptions corrected, all decisions recorded with rejection reasoning, direction changes with before/after
+| Condition | Action |
-**TodoWrite**: Update `phase-3` → `"completed"`, `phase-4` → `"in_progress"`
+|-----------|--------|
+| User selects "分析完成" | Exit loop, proceed to Phase 4 |
+| Max rounds (5) reached | Force synthesis, offer continuation `# (see code: E004)` |
+| User timeout | Save state, show resume command `# (see code: E003)` |
 
-### Phase 4: Synthesis & Conclusion
+**TodoWrite**: Update `phase-3` -> `"completed"`, `phase-4` -> `"in_progress"`
+</step>
+
+<step name="synthesis_conclusion">
+**Phase 4: Synthesize findings, verify intent coverage, and determine next steps.**
 
 1. **Intent Coverage Verification** (MANDATORY before synthesis):
    - Check each original intent: ✅ Addressed / 🔀 Transformed / ⚠️ Absorbed / ❌ Missed
@@ -305,7 +346,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
    | # | Original Intent | Status | Where Addressed | Notes |
    |---|----------------|--------|-----------------|-------|
    | 1 | [intent] | ✅ Addressed | Round N, Conclusion #M | |
-   | 2 | [intent] | 🔀 Transformed | Round N → M | Original: X → Final: Y |
+   | 2 | [intent] | 🔀 Transformed | Round N -> M | Original: X -> Final: Y |
    | 3 | [intent] | ❌ Missed | — | Reason |
    ```
    - **Gate**: ❌ Missed items must be either (a) addressed in additional round or (b) confirmed deferred by user
@@ -314,7 +355,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 2. **Consolidate Insights**:
    - Compile Decision Trail from all phases
    - Key conclusions with evidence + confidence (high/medium/low)
-   - Recommendations with rationale + priority (high/medium/low)
+   - Recommendations with rationale + priority (high/medium/low) — **merge validated `technical_solutions[]` from explorations.json as high-priority recommendations**
    - Open questions, follow-up suggestions
    - Decision summary linking conclusions back to decisions
    - Write to conclusions.json
@@ -332,27 +373,28 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 
 5. **Interactive Recommendation Review** (skip in auto mode):
 
-   Walk through each recommendation one-by-one for user confirmation:
+   Present all recommendations, then batch-confirm via **single AskUserQuestion call** (up to 4 questions):
 
    ```
-   For each recommendation (ordered by priority high→medium→low):
+   1. Display all recommendations with numbering (action, rationale, priority, steps[])
-     1. Present: action, rationale, priority, steps[] (numbered sub-steps)
+   2. Single AskUserQuestion call — one question per recommendation (max 4, ordered by priority high->medium->low):
-     2. AskUserQuestion (single-select, header: "建议#N"):
+      Each question (single-select, header: "建议#N"):
-        - **确认** (label: "确认", desc: "Accept as-is") → review_status = "accepted"
+        - **确认** (label: "确认", desc: "Accept as-is") -> review_status = "accepted"
-        - **修改** (label: "修改", desc: "Adjust scope/steps") → record modification → review_status = "modified"
+        - **修改** (label: "修改", desc: "Adjust scope/steps") -> review_status = "modified"
-        - **删除** (label: "删除", desc: "Not needed") → record reason → review_status = "rejected"
+        - **删除** (label: "删除", desc: "Not needed") -> review_status = "rejected"
-        - **跳过审议** (label: "跳过审议", desc: "Accept all remaining") → break loop
+   3. If >4 recommendations: batch in groups of 4 with additional AskUserQuestion calls
-     3. Record review decision to discussion.md Decision Log
+   4. For "修改" selections: follow up to capture modification details
-     4. Update conclusions.json recommendation.review_status
+   5. Record all review decisions to discussion.md Decision Log
+   6. Update conclusions.json recommendation.review_status for each
    ```
 
-   **After review loop**: Display summary of reviewed recommendations:
+   **After review**: Display summary of reviewed recommendations:
    - Accepted: N items | Modified: N items | Rejected: N items
    - Only accepted/modified recommendations proceed to next step
 
 6. **MANDATORY GATE: Next Step Selection** — workflow MUST NOT end without executing this step.
 
-   **TodoWrite**: Update `phase-4` → `"completed"`, `next-step` → `"in_progress"`
+   **TodoWrite**: Update `phase-4` -> `"completed"`, `next-step` -> `"in_progress"`
 
    > **CRITICAL**: This AskUserQuestion is a **terminal gate**. The workflow is INCOMPLETE if this question is not asked. After displaying conclusions (step 4) and recommendation review (step 5), you MUST immediately proceed here.
 
@@ -363,7 +405,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 
    **Handle user selection**:
 
-   **"执行任务"** → MUST invoke Skill tool (do NOT just display a summary and stop):
+   **"执行任务"** -> MUST invoke Skill tool (do NOT just display a summary and stop):
    1. Build `taskDescription` from high/medium priority recommendations (fallback: summary)
    2. Assemble context: `## Prior Analysis ({sessionId})` + summary + key files (up to 8) + key findings (up to 5) from exploration-codebase.json
    3. **Invoke Skill tool immediately**:
@@ -373,15 +415,15 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
       If Skill invocation is omitted, the workflow is BROKEN.
    4. After Skill invocation, analyze-with-file is complete — do not output any additional content
 
-   **"产出Issue"** → Convert recommendations to issues:
+   **"产出Issue"** -> Convert recommendations to issues:
    1. For each recommendation in conclusions.recommendations (priority high/medium):
       - Build issue JSON: `{title, context: rec.action + rec.rationale, priority: rec.priority == 'high' ? 2 : 3, source: 'discovery', labels: dimensions}`
       - Create via pipe: `echo '<issue-json>' | ccw issue create`
    2. Display created issue IDs with next step hint: `/issue:plan <id>`
 
-   **"完成"** → No further action needed.
+   **"完成"** -> No further action needed.
 
-   **TodoWrite**: Update `next-step` → `"completed"` after user selection is handled
+   **TodoWrite**: Update `next-step` -> `"completed"` after user selection is handled
 
 **conclusions.json Schema**:
 - `session_id`, `topic`, `completed`, `total_rounds`, `summary`
@@ -392,10 +434,43 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')}
 - `decision_trail[]`: {round, decision, context, options_considered, chosen, rejected_reasons, reason, impact}
 - `narrative_trail[]`: {round, starting_point, key_progress, hypothesis_impact, updated_understanding, remaining_questions}
 - `intent_coverage[]`: {intent, status, where_addressed, notes}
+</step>
 
-**Success**: conclusions.json created, discussion.md finalized, Intent Coverage Matrix verified, complete decision trail documented, `next-step` gate completed
+</process>
 
-## Configuration
+<error_codes>
+
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | cli-explore-agent fails — continue with available context, note limitation | cli_exploration |
+| E002 | error | CLI timeout — retry with shorter prompt, or skip perspective | cli_exploration |
+| E003 | error | User timeout — save state, show resume command | topic_understanding, interactive_discussion |
+| E004 | warning | Max discussion rounds (5) reached — force synthesis, offer continuation | interactive_discussion |
+| E005 | error | No relevant findings from exploration — broaden search, ask user for clarification | cli_exploration |
+| E006 | warning | Session folder conflict — append timestamp suffix | session_init |
+| E007 | error | Gemini unavailable — fallback to Codex or manual analysis | cli_exploration |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Session folder created with valid session ID
+- [ ] Progress tracking (TodoWrite) initialized with all 5 items
+- [ ] Dimensions identified and user preferences captured (Phase 1)
+- [ ] discussion.md initialized with TOC, Current Understanding, metadata
+- [ ] Codebase exploration completed with code_anchors and call_chains (Phase 2)
+- [ ] CLI analysis executed and findings aggregated
+- [ ] Initial Intent Coverage Check appended to discussion.md
+- [ ] Interactive discussion rounds documented with narrative synthesis (Phase 3)
+- [ ] Intent Drift Check performed each round >= 2
+- [ ] All decisions recorded per Decision Recording Protocol
+- [ ] Intent Coverage Matrix verified in Phase 4
+- [ ] conclusions.json created with key_conclusions, recommendations, decision_trail
+- [ ] discussion.md finalized with conclusions, Decision Trail, session statistics
+- [ ] Recommendation review completed (non-auto mode)
+- [ ] Next Step terminal gate executed — `next-step` todo is `"completed"`
+</success_criteria>
+
+<configuration>
 
 ### Analysis Perspectives
 
@@ -439,22 +514,12 @@ Present 2-3 top directions per dimension, allow multi-select + custom.
 | Rule | Description |
 |------|-------------|
 | Promote confirmed insights | Move validated findings to "What We Established" |
-| Track corrections | Keep important wrong→right transformations |
+| Track corrections | Keep important wrong->right transformations |
 | Focus on current state | What do we know NOW |
 | Avoid timeline repetition | Don't copy discussion details |
 | Preserve key learnings | Keep insights valuable for future reference |
 
-## Error Handling
+</configuration>
-
-| Error | Resolution |
-|-------|------------|
-| cli-explore-agent fails | Continue with available context, note limitation |
-| CLI timeout | Retry with shorter prompt, or skip perspective |
-| User timeout | Save state, show resume command |
-| Max rounds reached | Force synthesis, offer continuation |
-| No relevant findings | Broaden search, ask user for clarification |
-| Session folder conflict | Append timestamp suffix |
-| Gemini unavailable | Fallback to Codex or manual analysis |
 
 > **Lite-plan handoff**: Phase 4「执行任务」assembles analysis context as inline `## Prior Analysis` block, allowing lite-plan to skip redundant exploration.
 

.claude/commands/workflow/session/sync.md

@@ -65,11 +65,14 @@ Analyze context and produce two update payloads. Use LLM reasoning (current agen
 ```javascript
 // ── Guidelines extraction ──
 // Scan git diff + session for:
-//   - New patterns adopted → convention
+//   - Debugging experiences → bug
-//   - Restrictions discovered → constraint
+//   - Reusable code patterns → pattern
-//   - Surprises / gotchas → learning
+//   - Architecture/design decisions → decision
+//   - Conventions, constraints, insights → rule
 //
-// Output: array of { type, category, text }
+// Output: array of { type, tag, text }
+//   type: 'bug' | 'pattern' | 'decision' | 'rule'
+//   tag: domain tag (api, routing, schema, security, etc.)
 // RULE: Only extract genuinely reusable insights. Skip trivial/obvious items.
 // RULE: Deduplicate against existing guidelines before adding.
 
@@ -118,7 +121,7 @@ console.log(`
 ── Sync Preview ──
 
 Guidelines (${guidelineUpdates.length} items):
-${guidelineUpdates.map(g => `  [${g.type}/${g.category}] ${g.text}`).join('\n') || '  (none)'}
+${guidelineUpdates.map(g => `  [${g.type}:${g.tag}] ${g.text}`).join('\n') || '  (none)'}
 
 Tech [${detectCategory(summary)}]:
   ${techEntry.title}
@@ -137,26 +140,102 @@ if (!autoYes) {
 ## Step 4: Write
 
 ```javascript
-// ── Update specs/*.md ──
+const matter = require('gray-matter')  // YAML frontmatter parser
-// Uses .ccw/specs/ directory (same as frontend/backend spec-index-builder)
+
-if (guidelineUpdates.length > 0) {
+// ── Frontmatter check & repair helper ──
-  // Map guideline types to spec files
+// Ensures target spec file has valid YAML frontmatter with keywords
-  const specFileMap = {
+// Uses gray-matter for robust parsing (handles malformed frontmatter, missing fields)
-    convention: '.ccw/specs/coding-conventions.md',
+function ensureFrontmatter(filePath, tag, type) {
-    constraint: '.ccw/specs/architecture-constraints.md',
+  const titleMap = {
-    learning: '.ccw/specs/coding-conventions.md' // learnings appended to conventions
+    'coding-conventions': 'Coding Conventions',
+    'architecture-constraints': 'Architecture Constraints',
+    'learnings': 'Learnings',
+    'quality-rules': 'Quality Rules'
+  }
+  const basename = filePath.split('/').pop().replace('.md', '')
+  const title = titleMap[basename] || basename
+  const defaultFm = {
+    title,
+    readMode: 'optional',
+    priority: 'medium',
+    scope: 'project',
+    dimension: 'specs',
+    keywords: [tag, type]
   }
 
+  if (!file_exists(filePath)) {
+    // Case A: Create new file with frontmatter
+    Write(filePath, matter.stringify(`\n# ${title}\n\n`, defaultFm))
+    return
+  }
+
+  const raw = Read(filePath)
+  let parsed
+  try {
+    parsed = matter(raw)
+  } catch {
+    parsed = { data: {}, content: raw }
+  }
+
+  const hasFrontmatter = raw.trimStart().startsWith('---')
+
+  if (!hasFrontmatter) {
+    // Case B: File exists but no frontmatter → prepend
+    Write(filePath, matter.stringify(raw, defaultFm))
+    return
+  }
+
+  // Case C: Frontmatter exists → ensure keywords include current tag
+  const existingKeywords = parsed.data.keywords || []
+  const newKeywords = [...new Set([...existingKeywords, tag, type])]
+
+  if (newKeywords.length !== existingKeywords.length) {
+    parsed.data.keywords = newKeywords
+    Write(filePath, matter.stringify(parsed.content, parsed.data))
+  }
+}
+
+// ── Update specs/*.md ──
+// Uses .ccw/specs/ directory - unified [type:tag] entry format
+if (guidelineUpdates.length > 0) {
+  // Map knowledge types to spec files
+  const specFileMap = {
+    bug: '.ccw/specs/learnings.md',
+    pattern: '.ccw/specs/coding-conventions.md',
+    decision: '.ccw/specs/architecture-constraints.md',
+    rule: null // determined by content below
+  }
+
+  const date = new Date().toISOString().split('T')[0]
+  const needsDate = { bug: true, pattern: true, decision: true, rule: false }
+
   for (const g of guidelineUpdates) {
-    const targetFile = specFileMap[g.type]
+    // For rule type, route by content and tag
+    let targetFile = specFileMap[g.type]
+    if (!targetFile) {
+      const isQuality = /\b(test|coverage|lint|eslint|质量|测试覆盖|pre-commit|tsc|type.check)\b/i.test(g.text)
+        || ['testing', 'quality', 'lint'].includes(g.tag)
+      const isConstraint = /\b(禁止|no|never|must not|forbidden|不得|不允许)\b/i.test(g.text)
+      if (isQuality) {
+        targetFile = '.ccw/specs/quality-rules.md'
+      } else if (isConstraint) {
+        targetFile = '.ccw/specs/architecture-constraints.md'
+      } else {
+        targetFile = '.ccw/specs/coding-conventions.md'
+      }
+    }
+
+    // Ensure frontmatter exists and keywords are up-to-date
+    ensureFrontmatter(targetFile, g.tag, g.type)
+
     const existing = Read(targetFile)
-    const ruleText = g.type === 'learning'
+    const entryLine = needsDate[g.type]
-      ? `- [${g.category}] ${g.text} (learned: ${new Date().toISOString().split('T')[0]})`
+      ? `- [${g.type}:${g.tag}] ${g.text} (${date})`
-      : `- [${g.category}] ${g.text}`
+      : `- [${g.type}:${g.tag}] ${g.text}`
 
     // Deduplicate: skip if text already in file
     if (!existing.includes(g.text)) {
-      const newContent = existing.trimEnd() + '\n' + ruleText + '\n'
+      const newContent = existing.trimEnd() + '\n' + entryLine + '\n'
       Write(targetFile, newContent)
     }
   }
@@ -198,4 +277,5 @@ Write(techPath, JSON.stringify(tech, null, 2))
 ## Related Commands
 
 - `/workflow:spec:setup` - Initialize project with specs scaffold
-- `/workflow:spec:add` - Interactive wizard to create individual specs with scope selection
+- `/workflow:spec:add` - Add knowledge entries (bug/pattern/decision/rule) with unified [type:tag] format
+- `/workflow:spec:load` - Interactive spec loader with keyword/type/tag filtering

.claude/commands/workflow/spec/load.md

@@ -0,0 +1,392 @@
+---
+name: load
+description: Interactive spec loader - ask what user needs, then load relevant specs by keyword routing
+argument-hint: "[--all] [--type <bug|pattern|decision|rule>] [--tag <tag>] [\"keyword query\"]"
+examples:
+  - /workflow:spec:load
+  - /workflow:spec:load "api routing"
+  - /workflow:spec:load --type bug
+  - /workflow:spec:load --all
+  - /workflow:spec:load --tag security
+---
+
+# Spec Load Command (/workflow:spec:load)
+
+## Overview
+
+Interactive entry point for loading and browsing project specs. Asks the user what they need, then routes to the appropriate spec content based on keywords, type filters, or tag filters.
+
+**Design**: Menu-driven → keyword match → load & display. No file modifications.
+
+**Note**: This command may be called by other workflow commands. Upon completion, return immediately to continue the calling workflow.
+
+## Usage
+```bash
+/workflow:spec:load                    # Interactive menu
+/workflow:spec:load "api routing"      # Direct keyword search
+/workflow:spec:load --type bug         # Filter by knowledge type
+/workflow:spec:load --tag security     # Filter by domain tag
+/workflow:spec:load --all              # Load all specs
+```
+
+## Execution Process
+
+```
+Input Parsing:
+   ├─ Parse --all flag → loadAll = true | false
+   ├─ Parse --type (bug|pattern|decision|rule)
+   ├─ Parse --tag (domain tag)
+   └─ Parse keyword query (positional text)
+
+Decision:
+   ├─ --all → Load all specs (Path C)
+   ├─ --type or --tag or keyword → Direct filter (Path B)
+   └─ No args → Interactive menu (Path A)
+
+Path A: Interactive Menu
+   ├─ Step A1: Ask user intent
+   ├─ Step A2: Route to action
+   └─ Step A3: Display results
+
+Path B: Direct Filter
+   ├─ Step B1: Build filter from args
+   ├─ Step B2: Search specs
+   └─ Step B3: Display results
+
+Path C: Load All
+   └─ Display all spec contents
+
+Output:
+   └─ Formatted spec entries matching user query
+```
+
+## Implementation
+
+### Step 1: Parse Input
+
+```javascript
+const args = $ARGUMENTS
+const argsLower = args.toLowerCase()
+
+const loadAll = argsLower.includes('--all')
+const hasType = argsLower.includes('--type')
+const hasTag = argsLower.includes('--tag')
+
+let type = hasType ? args.match(/--type\s+(\w+)/i)?.[1]?.toLowerCase() : null
+let tag = hasTag ? args.match(/--tag\s+([\w-]+)/i)?.[1]?.toLowerCase() : null
+
+// Extract keyword query (everything that's not a flag)
+let keyword = args
+  .replace(/--type\s+\w+/gi, '')
+  .replace(/--tag\s+[\w-]+/gi, '')
+  .replace(/--all/gi, '')
+  .replace(/^["']|["']$/g, '')
+  .trim()
+
+// Validate type
+if (type && !['bug', 'pattern', 'decision', 'rule'].includes(type)) {
+  console.log("Invalid type. Use 'bug', 'pattern', 'decision', or 'rule'.")
+  return
+}
+```
+
+### Step 2: Determine Mode
+
+```javascript
+const useInteractive = !loadAll && !hasType && !hasTag && !keyword
+```
+
+### Path A: Interactive Menu
+
+```javascript
+if (useInteractive) {
+  const answer = AskUserQuestion({
+    questions: [{
+      question: "What specs would you like to load?",
+      header: "Action",
+      multiSelect: false,
+      options: [
+        {
+          label: "Browse all specs",
+          description: "Load and display all project spec entries"
+        },
+        {
+          label: "Search by keyword",
+          description: "Find specs matching a keyword (e.g., api, security, routing)"
+        },
+        {
+          label: "View bug experiences",
+          description: "Load all [bug:*] debugging experience entries"
+        },
+        {
+          label: "View code patterns",
+          description: "Load all [pattern:*] reusable code pattern entries"
+        }
+      ]
+    }]
+  })
+
+  const choice = answer.answers["Action"]
+
+  if (choice === "Browse all specs") {
+    loadAll = true
+  } else if (choice === "View bug experiences") {
+    type = "bug"
+  } else if (choice === "View code patterns") {
+    type = "pattern"
+  } else if (choice === "Search by keyword") {
+    // Ask for keyword
+    const kwAnswer = AskUserQuestion({
+      questions: [{
+        question: "Enter keyword(s) to search for:",
+        header: "Keyword",
+        multiSelect: false,
+        options: [
+          { label: "api", description: "API endpoints, HTTP, REST, routing" },
+          { label: "security", description: "Authentication, authorization, input validation" },
+          { label: "arch", description: "Architecture, design patterns, module structure" },
+          { label: "perf", description: "Performance, caching, optimization" }
+        ]
+      }]
+    })
+    keyword = kwAnswer.answers["Keyword"].toLowerCase()
+  } else {
+    // "Other" — user typed custom input, use as keyword
+    keyword = choice.toLowerCase()
+  }
+}
+```
+
+### Step 3: Load Spec Files
+
+```javascript
+// Discover all spec files
+const specFiles = [
+  '.ccw/specs/coding-conventions.md',
+  '.ccw/specs/architecture-constraints.md',
+  '.ccw/specs/learnings.md',
+  '.ccw/specs/quality-rules.md'
+]
+
+// Also check personal specs
+const personalFiles = [
+  '~/.ccw/personal/conventions.md',
+  '~/.ccw/personal/constraints.md',
+  '~/.ccw/personal/learnings.md',
+  '.ccw/personal/conventions.md',
+  '.ccw/personal/constraints.md',
+  '.ccw/personal/learnings.md'
+]
+
+// Read all existing spec files
+const allEntries = []
+
+for (const file of [...specFiles, ...personalFiles]) {
+  if (!file_exists(file)) continue
+  const content = Read(file)
+
+  // Extract entries using unified format regex
+  // Entry line: - [type:tag] summary (date)
+  // Extended:       - key: value
+  const lines = content.split('\n')
+  let currentEntry = null
+
+  for (const line of lines) {
+    const entryMatch = line.match(/^- \[(\w+):([\w-]+)\] (.*?)(?:\s+\((\d{4}-\d{2}-\d{2})\))?$/)
+    if (entryMatch) {
+      if (currentEntry) allEntries.push(currentEntry)
+      currentEntry = {
+        type: entryMatch[1],
+        tag: entryMatch[2],
+        summary: entryMatch[3],
+        date: entryMatch[4] || null,
+        extended: {},
+        source: file,
+        raw: line
+      }
+    } else if (currentEntry && /^\s{4}- ([\w-]+):\s?(.*)/.test(line)) {
+      const fieldMatch = line.match(/^\s{4}- ([\w-]+):\s?(.*)/)
+      currentEntry.extended[fieldMatch[1]] = fieldMatch[2]
+    } else if (currentEntry && !/^\s{4}/.test(line) && line.trim() !== '') {
+      // Non-indented non-empty line = end of current entry
+      allEntries.push(currentEntry)
+      currentEntry = null
+    }
+
+    // Also handle legacy format: - [tag] text (learned: date)
+    const legacyMatch = line.match(/^- \[([\w-]+)\] (.+?)(?:\s+\(learned: (\d{4}-\d{2}-\d{2})\))?$/)
+    if (!entryMatch && legacyMatch) {
+      if (currentEntry) allEntries.push(currentEntry)
+      currentEntry = {
+        type: 'rule',
+        tag: legacyMatch[1],
+        summary: legacyMatch[2],
+        date: legacyMatch[3] || null,
+        extended: {},
+        source: file,
+        raw: line,
+        legacy: true
+      }
+    }
+  }
+  if (currentEntry) allEntries.push(currentEntry)
+}
+```
+
+### Step 4: Filter Entries
+
+```javascript
+let filtered = allEntries
+
+// Filter by type
+if (type) {
+  filtered = filtered.filter(e => e.type === type)
+}
+
+// Filter by tag
+if (tag) {
+  filtered = filtered.filter(e => e.tag === tag)
+}
+
+// Filter by keyword (search in tag, summary, and extended fields)
+if (keyword) {
+  const kw = keyword.toLowerCase()
+  const kwTerms = kw.split(/\s+/)
+
+  filtered = filtered.filter(e => {
+    const searchText = [
+      e.type, e.tag, e.summary,
+      ...Object.values(e.extended)
+    ].join(' ').toLowerCase()
+
+    return kwTerms.every(term => searchText.includes(term))
+  })
+}
+
+// If --all, keep everything (no filter)
+```
+
+### Step 5: Display Results
+
+```javascript
+if (filtered.length === 0) {
+  const filterDesc = []
+  if (type) filterDesc.push(`type=${type}`)
+  if (tag) filterDesc.push(`tag=${tag}`)
+  if (keyword) filterDesc.push(`keyword="${keyword}"`)
+
+  console.log(`
+No specs found matching: ${filterDesc.join(', ') || '(all)'}
+
+Available spec files:
+${specFiles.filter(f => file_exists(f)).map(f => `  - ${f}`).join('\n') || '  (none)'}
+
+Suggestions:
+- Use /workflow:spec:setup to initialize specs
+- Use /workflow:spec:add to add new entries
+- Use /workflow:spec:load --all to see everything
+`)
+  return
+}
+
+// Group by source file
+const grouped = {}
+for (const entry of filtered) {
+  if (!grouped[entry.source]) grouped[entry.source] = []
+  grouped[entry.source].push(entry)
+}
+
+// Display
+console.log(`
+## Specs Loaded (${filtered.length} entries)
+${type ? `Type: ${type}` : ''}${tag ? ` Tag: ${tag}` : ''}${keyword ? ` Keyword: "${keyword}"` : ''}
+`)
+
+for (const [source, entries] of Object.entries(grouped)) {
+  console.log(`### ${source}`)
+  console.log('')
+
+  for (const entry of entries) {
+    // Render entry
+    const datePart = entry.date ? ` (${entry.date})` : ''
+    console.log(`- [${entry.type}:${entry.tag}] ${entry.summary}${datePart}`)
+
+    // Render extended fields
+    for (const [key, value] of Object.entries(entry.extended)) {
+      console.log(`    - ${key}: ${value}`)
+    }
+  }
+  console.log('')
+}
+
+// Summary footer
+const typeCounts = {}
+for (const e of filtered) {
+  typeCounts[e.type] = (typeCounts[e.type] || 0) + 1
+}
+const typeBreakdown = Object.entries(typeCounts)
+  .map(([t, c]) => `${t}: ${c}`)
+  .join(', ')
+
+console.log(`---`)
+console.log(`Total: ${filtered.length} entries (${typeBreakdown})`)
+console.log(`Sources: ${Object.keys(grouped).join(', ')}`)
+```
+
+## Examples
+
+### Interactive Browse
+```bash
+/workflow:spec:load
+# → Menu: "What specs would you like to load?"
+# → User selects "Browse all specs"
+# → Displays all entries grouped by file
+```
+
+### Keyword Search
+```bash
+/workflow:spec:load "api routing"
+# → Filters entries where tag/summary/extended contains "api" AND "routing"
+# → Displays matching entries
+```
+
+### Type Filter
+```bash
+/workflow:spec:load --type bug
+# → Shows all [bug:*] entries from learnings.md
+```
+
+### Tag Filter
+```bash
+/workflow:spec:load --tag security
+# → Shows all [*:security] entries across all spec files
+```
+
+### Combined Filters
+```bash
+/workflow:spec:load --type rule --tag api
+# → Shows all [rule:api] entries
+```
+
+### Load All
+```bash
+/workflow:spec:load --all
+# → Displays every entry from every spec file
+```
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| No spec files found | Suggest `/workflow:spec:setup` to initialize |
+| No matching entries | Show available files and suggest alternatives |
+| Invalid type | Exit with valid type list |
+| Corrupt entry format | Skip unparseable lines, continue loading |
+
+## Related Commands
+
+- `/workflow:spec:setup` - Initialize project with specs scaffold
+- `/workflow:spec:add` - Add knowledge entries (bug/pattern/decision/rule) with unified [type:tag] format
+- `/workflow:session:sync` - Quick-sync session work to specs and project-tech
+- `ccw spec list` - View spec file index
+- `ccw spec load` - CLI-level spec loading (used by hooks)

.claude/commands/workflow/spec/setup.md

@@ -471,70 +471,129 @@ For each category of collected answers, append rules to the corresponding spec M
 - Round 5 (quality): `category: execution` (testing phase)
 
 ```javascript
+const matter = require('gray-matter')  // YAML frontmatter parser
+
+// ── Frontmatter check & repair helper ──
+// Ensures target spec file has valid YAML frontmatter with keywords
+// Uses gray-matter for robust parsing (handles malformed frontmatter, missing fields)
+function ensureSpecFrontmatter(filePath, extraKeywords = []) {
+  const titleMap = {
+    'coding-conventions': 'Coding Conventions',
+    'architecture-constraints': 'Architecture Constraints',
+    'learnings': 'Learnings',
+    'quality-rules': 'Quality Rules'
+  }
+  const basename = filePath.split('/').pop().replace('.md', '')
+  const title = titleMap[basename] || basename
+  const defaultKw = filePath.includes('conventions') ? 'convention'
+    : filePath.includes('constraints') ? 'constraint' : 'quality'
+  const defaultFm = {
+    title,
+    readMode: 'optional',
+    priority: 'medium',
+    category: 'general',
+    scope: 'project',
+    dimension: 'specs',
+    keywords: [...new Set([defaultKw, ...extraKeywords])]
+  }
+
+  if (!file_exists(filePath)) {
+    // Case A: Create new file with frontmatter
+    const specDir = path.dirname(filePath)
+    if (!fs.existsSync(specDir)) {
+      fs.mkdirSync(specDir, { recursive: true })
+    }
+    Write(filePath, matter.stringify(`\n# ${title}\n\n`, defaultFm))
+    return
+  }
+
+  const raw = Read(filePath)
+  let parsed
+  try {
+    parsed = matter(raw)
+  } catch {
+    parsed = { data: {}, content: raw }
+  }
+
+  const hasFrontmatter = raw.trimStart().startsWith('---')
+
+  if (!hasFrontmatter) {
+    // Case B: File exists but no frontmatter → prepend
+    Write(filePath, matter.stringify(raw, defaultFm))
+    return
+  }
+
+  // Case C: Frontmatter exists → ensure keywords include extras
+  const existingKeywords = parsed.data.keywords || []
+  const newKeywords = [...new Set([...existingKeywords, defaultKw, ...extraKeywords])]
+
+  if (newKeywords.length !== existingKeywords.length) {
+    parsed.data.keywords = newKeywords
+    Write(filePath, matter.stringify(parsed.content, parsed.data))
+  }
+}
+
 // Helper: append rules to a spec MD file with category support
 // Uses .ccw/specs/ directory (same as frontend/backend spec-index-builder)
 function appendRulesToSpecFile(filePath, rules, defaultCategory = 'general') {
   if (rules.length === 0) return
 
-  // Ensure .ccw/specs/ directory exists
+  // Extract domain tags from rules for keyword accumulation
-  const specDir = path.dirname(filePath)
+  const ruleTags = rules
-  if (!fs.existsSync(specDir)) {
+    .map(r => r.match(/\[[\w]+:([\w-]+)\]/)?.[1])
-    fs.mkdirSync(specDir, { recursive: true })
+    .filter(Boolean)
-  }
 
-  // Check if file exists
+  // Ensure frontmatter exists and keywords include rule tags
-  if (!file_exists(filePath)) {
+  ensureSpecFrontmatter(filePath, [...new Set(ruleTags)])
-    // Create file with frontmatter including category
-    const frontmatter = `---
-title: ${filePath.includes('conventions') ? 'Coding Conventions' : filePath.includes('constraints') ? 'Architecture Constraints' : 'Quality Rules'}
-readMode: optional
-priority: medium
-category: ${defaultCategory}
-scope: project
-dimension: specs
-keywords: [${defaultCategory}, ${filePath.includes('conventions') ? 'convention' : filePath.includes('constraints') ? 'constraint' : 'quality'}]
----
-
-# ${filePath.includes('conventions') ? 'Coding Conventions' : filePath.includes('constraints') ? 'Architecture Constraints' : 'Quality Rules'}
-
-`
-    Write(filePath, frontmatter)
-  }
 
   const existing = Read(filePath)
-  // Append new rules as markdown list items after existing content
+  // Append new rules as markdown list items - rules are already in [type:tag] format from caller
-  const newContent = existing.trimEnd() + '\n' + rules.map(r => `- ${r}`).join('\n') + '\n'
+  const newContent = existing.trimEnd() + '\n' + rules.map(r => {
+    // If rule already has - prefix or [type:tag] format, use as-is
+    if (/^- /.test(r)) return r
+    if (/^\[[\w]+:[\w-]+\]/.test(r)) return `- ${r}`
+    return `- [rule:${defaultCategory}] ${r}`
+  }).join('\n') + '\n'
   Write(filePath, newContent)
 }
 
-// Write conventions (general category) - use .ccw/specs/ (same as frontend/backend)
+// Helper: infer domain tag from rule content
-appendRulesToSpecFile('.ccw/specs/coding-conventions.md',
+function inferTag(text) {
-  [...newCodingStyle, ...newNamingPatterns, ...newFileStructure, ...newDocumentation],
+  const t = text.toLowerCase()
-  'general')
+  if (/\b(api|http|rest|endpoint|routing)\b/.test(t)) return 'api'
+  if (/\b(security|auth|permission|xss|sql|sanitize)\b/.test(t)) return 'security'
+  if (/\b(database|db|sql|postgres|mysql)\b/.test(t)) return 'db'
+  if (/\b(react|component|hook|jsx|tsx)\b/.test(t)) return 'react'
+  if (/\b(performance|cache|lazy|async|slow)\b/.test(t)) return 'perf'
+  if (/\b(test|coverage|mock|jest|vitest)\b/.test(t)) return 'testing'
+  if (/\b(architecture|layer|module|dependency)\b/.test(t)) return 'arch'
+  if (/\b(naming|camel|pascal|prefix|suffix)\b/.test(t)) return 'naming'
+  if (/\b(file|folder|directory|structure)\b/.test(t)) return 'file'
+  if (/\b(doc|comment|jsdoc|readme)\b/.test(t)) return 'doc'
+  if (/\b(build|webpack|vite|compile)\b/.test(t)) return 'build'
+  if (/\b(deploy|ci|cd|docker)\b/.test(t)) return 'deploy'
+  if (/\b(lint|eslint|prettier|format)\b/.test(t)) return 'lint'
+  if (/\b(type|typescript|strict|any)\b/.test(t)) return 'typing'
+  return 'style' // fallback for coding conventions
+}
 
-// Write constraints (planning category)
+// Write conventions - infer domain tags from content
+appendRulesToSpecFile('.ccw/specs/coding-conventions.md',
+  [...newCodingStyle, ...newNamingPatterns, ...newFileStructure, ...newDocumentation]
+    .map(r => /^\[[\w]+:[\w-]+\]/.test(r) ? r : `[rule:${inferTag(r)}] ${r}`),
+  'style')
+
+// Write constraints - infer domain tags from content
 appendRulesToSpecFile('.ccw/specs/architecture-constraints.md',
-  [...newArchitecture, ...newTechStack, ...newPerformance, ...newSecurity],
+  [...newArchitecture, ...newTechStack, ...newPerformance, ...newSecurity]
-  'planning')
+    .map(r => /^\[[\w]+:[\w-]+\]/.test(r) ? r : `[rule:${inferTag(r)}] ${r}`),
+  'arch')
 
 // Write quality rules (execution category)
 if (newQualityRules.length > 0) {
   const qualityPath = '.ccw/specs/quality-rules.md'
-  if (!file_exists(qualityPath)) {
+  // ensureSpecFrontmatter handles create/repair/keyword-update
-    Write(qualityPath, `---
+  ensureSpecFrontmatter(qualityPath, ['quality', 'testing', 'coverage', 'lint'])
-title: Quality Rules
-readMode: required
-priority: high
-category: execution
-scope: project
-dimension: specs
-keywords: [execution, quality, testing, coverage, lint]
----
-
-# Quality Rules
-
-`)
-  }
   appendRulesToSpecFile(qualityPath,
     newQualityRules.map(q => `${q.rule} (scope: ${q.scope}, enforced by: ${q.enforced_by})`),
     'execution')
@@ -644,7 +703,8 @@ Next steps:
 
 ## Related Commands
 
-- `/workflow:spec:add` - Interactive wizard to create individual specs with scope selection
+- `/workflow:spec:add` - Add knowledge entries (bug/pattern/decision/rule) with unified [type:tag] format
+- `/workflow:spec:load` - Interactive spec loader with keyword/type/tag filtering
 - `/workflow:session:sync` - Quick-sync session work to specs and project-tech
 - `workflow-plan` skill - Start planning with initialized project context
 - `/workflow:status --project` - View project state and guidelines

.claude/skills/ccw-help/command.json

@@ -289,7 +289,7 @@
     },
     {
       "name": "init-guidelines",
-      "command": "/workflow:init-guidelines",
+      "command": "/workflow:spec:setup -guidelines",
       "description": "Interactive wizard to fill specs/*.md based on project analysis",
       "arguments": "[--reset]",
       "category": "workflow",
@@ -300,7 +300,7 @@
     },
     {
       "name": "init-specs",
-      "command": "/workflow:init-specs",
+      "command": "/workflow:spec:setup -specs",
       "description": "Interactive wizard to create individual specs or personal constraints with scope selection",
       "arguments": "[--scope <global|project>] [--dimension <specs|personal>] [--category <general|exploration|planning|execution>]",
       "category": "workflow",
@@ -311,7 +311,7 @@
     },
     {
       "name": "init",
-      "command": "/workflow:init",
+      "command": "/workflow:spec:setup ",
       "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent",
       "arguments": "[--regenerate] [--skip-specs]",
       "category": "workflow",

.claude/skills/ccw-help/index/all-commands.json

@@ -276,7 +276,7 @@
   },
   {
     "name": "init-guidelines",
-    "command": "/workflow:init-guidelines",
+    "command": "/workflow:spec:setup -guidelines",
     "description": "Interactive wizard to fill specs/*.md based on project analysis",
     "arguments": "[--reset]",
     "category": "workflow",
@@ -287,7 +287,7 @@
   },
   {
     "name": "init-specs",
-    "command": "/workflow:init-specs",
+    "command": "/workflow:spec:setup -specs",
     "description": "Interactive wizard to create individual specs or personal constraints with scope selection",
     "arguments": "[--scope <global|project>] [--dimension <specs|personal>] [--category <general|exploration|planning|execution>]",
     "category": "workflow",
@@ -298,7 +298,7 @@
   },
   {
     "name": "init",
-    "command": "/workflow:init",
+    "command": "/workflow:spec:setup ",
     "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent",
     "arguments": "[--regenerate] [--skip-specs]",
     "category": "workflow",

.claude/skills/ccw-help/index/by-category.json

@@ -298,7 +298,7 @@
       },
       {
         "name": "init-guidelines",
-        "command": "/workflow:init-guidelines",
+        "command": "/workflow:spec:setup -guidelines",
         "description": "Interactive wizard to fill specs/*.md based on project analysis",
         "arguments": "[--reset]",
         "category": "workflow",
@@ -309,7 +309,7 @@
       },
       {
         "name": "init-specs",
-        "command": "/workflow:init-specs",
+        "command": "/workflow:spec:setup -specs",
         "description": "Interactive wizard to create individual specs or personal constraints with scope selection",
         "arguments": "[--scope <global|project>] [--dimension <specs|personal>] [--category <general|exploration|planning|execution>]",
         "category": "workflow",
@@ -320,7 +320,7 @@
       },
       {
         "name": "init",
-        "command": "/workflow:init",
+        "command": "/workflow:spec:setup ",
         "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent",
         "arguments": "[--regenerate] [--skip-specs]",
         "category": "workflow",

.claude/skills/ccw-help/index/by-use-case.json

@@ -145,7 +145,7 @@
     },
     {
       "name": "init-guidelines",
-      "command": "/workflow:init-guidelines",
+      "command": "/workflow:spec:setup -guidelines",
       "description": "Interactive wizard to fill specs/*.md based on project analysis",
       "arguments": "[--reset]",
       "category": "workflow",
@@ -156,7 +156,7 @@
     },
     {
       "name": "init-specs",
-      "command": "/workflow:init-specs",
+      "command": "/workflow:spec:setup -specs",
       "description": "Interactive wizard to create individual specs or personal constraints with scope selection",
       "arguments": "[--scope <global|project>] [--dimension <specs|personal>] [--category <general|exploration|planning|execution>]",
       "category": "workflow",
@@ -167,7 +167,7 @@
     },
     {
       "name": "init",
-      "command": "/workflow:init",
+      "command": "/workflow:spec:setup ",
       "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent",
       "arguments": "[--regenerate] [--skip-specs]",
       "category": "workflow",

.claude/skills/command-generator/SKILL.md

@@ -1,190 +0,0 @@
----
-name: command-generator
-description: Command file generator - 5 phase workflow for creating Claude Code command files with YAML frontmatter. Generates .md command files for project or user scope. Triggers on "create command", "new command", "command generator".
-allowed-tools: Read, Write, Edit, Bash, Glob
----
-
-# Command Generator
-
-CLI-based command file generator producing Claude Code command .md files through a structured 5-phase workflow. Supports both project-level (`.claude/commands/`) and user-level (`~/.claude/commands/`) command locations.
-
-## Architecture Overview
-
-```
-+-----------------------------------------------------------+
-|                    Command Generator                        |
-|                                                            |
-|  Input: skillName, description, location, [group], [hint]  |
-|                         |                                  |
-|  +-------------------------------------------------+      |
-|  |  Phase 1-5: Sequential Pipeline                 |      |
-|  |                                                 |      |
-|  |  [P1] --> [P2] --> [P3] --> [P4] --> [P5]      |      |
-|  |  Param   Target   Template  Content   File     |      |
-|  |  Valid   Path     Loading   Format    Gen      |      |
-|  +-------------------------------------------------+      |
-|                         |                                  |
-|  Output: {scope}/.claude/commands/{group}/{name}.md       |
-|                                                            |
-+-----------------------------------------------------------+
-```
-
-## Key Design Principles
-
-1. **Single Responsibility**: Generates one command file per invocation
-2. **Scope Awareness**: Supports project and user-level command locations
-3. **Template-Driven**: Uses consistent template for all generated commands
-4. **Validation First**: Validates all required parameters before file operations
-5. **Non-Destructive**: Warns if command file already exists
-
----
-
-## Execution Flow
-
-```
-Phase 1: Parameter Validation
-   - Ref: phases/01-parameter-validation.md
-   - Validate: skillName (required), description (required), location (required)
-   - Optional: group, argumentHint
-   - Output: validated params object
-
-Phase 2: Target Path Resolution
-   - Ref: phases/02-target-path-resolution.md
-   - Resolve: location -> target commands directory
-   - Support: project (.claude/commands/) vs user (~/.claude/commands/)
-   - Handle: group subdirectory if provided
-   - Output: targetPath string
-
-Phase 3: Template Loading
-   - Ref: phases/03-template-loading.md
-   - Load: templates/command-md.md
-   - Template contains YAML frontmatter with placeholders
-   - Output: templateContent string
-
-Phase 4: Content Formatting
-   - Ref: phases/04-content-formatting.md
-   - Substitute: {{name}}, {{description}}, {{group}}, {{argumentHint}}
-   - Handle: optional fields (group, argumentHint)
-   - Output: formattedContent string
-
-Phase 5: File Generation
-   - Ref: phases/05-file-generation.md
-   - Check: file existence (warn if exists)
-   - Write: formatted content to target path
-   - Output: success confirmation with file path
-```
-
-## Usage Examples
-
-### Basic Command (Project Scope)
-```javascript
-Skill(skill="command-generator", args={
-  skillName: "deploy",
-  description: "Deploy application to production environment",
-  location: "project"
-})
-// Output: .claude/commands/deploy.md
-```
-
-### Grouped Command with Argument Hint
-```javascript
-Skill(skill="command-generator", args={
-  skillName: "create",
-  description: "Create new issue from GitHub URL or text",
-  location: "project",
-  group: "issue",
-  argumentHint: "[-y|--yes] <github-url | text-description> [--priority 1-5]"
-})
-// Output: .claude/commands/issue/create.md
-```
-
-### User-Level Command
-```javascript
-Skill(skill="command-generator", args={
-  skillName: "global-status",
-  description: "Show global Claude Code status",
-  location: "user"
-})
-// Output: ~/.claude/commands/global-status.md
-```
-
----
-
-## Reference Documents by Phase
-
-### Phase 1: Parameter Validation
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/01-parameter-validation.md](phases/01-parameter-validation.md) | Validate required parameters | Phase 1 execution |
-
-### Phase 2: Target Path Resolution
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/02-target-path-resolution.md](phases/02-target-path-resolution.md) | Resolve target directory | Phase 2 execution |
-
-### Phase 3: Template Loading
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/03-template-loading.md](phases/03-template-loading.md) | Load command template | Phase 3 execution |
-| [templates/command-md.md](templates/command-md.md) | Command file template | Template reference |
-
-### Phase 4: Content Formatting
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/04-content-formatting.md](phases/04-content-formatting.md) | Format content with params | Phase 4 execution |
-
-### Phase 5: File Generation
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/05-file-generation.md](phases/05-file-generation.md) | Write final file | Phase 5 execution |
-
-### Design Specifications
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [specs/command-design-spec.md](specs/command-design-spec.md) | Command design guidelines | Understanding best practices |
-
----
-
-## Output Structure
-
-### Generated Command File
-
-```markdown
----
-name: {skillName}
-description: {description}
-{group} {argumentHint}
----
-
-# {skillName} Command
-
-## Overview
-{Auto-generated placeholder for command overview}
-
-## Usage
-{Auto-generated placeholder for usage examples}
-
-## Execution Flow
-{Auto-generated placeholder for execution steps}
-```
-
----
-
-## Error Handling
-
-| Error | Stage | Action |
-|-------|-------|--------|
-| Missing skillName | Phase 1 | Error: "skillName is required" |
-| Missing description | Phase 1 | Error: "description is required" |
-| Missing location | Phase 1 | Error: "location is required (project or user)" |
-| Invalid location | Phase 2 | Error: "location must be 'project' or 'user'" |
-| Template not found | Phase 3 | Error: "Command template not found" |
-| File exists | Phase 5 | Warning: "Command file already exists, will overwrite" |
-| Write failure | Phase 5 | Error: "Failed to write command file" |
-
----
-
-## Related Skills
-
-- **skill-generator**: Create complete skills with phases, templates, and specs
-- **flow-coordinator**: Orchestrate multi-step command workflows

.claude/skills/command-generator/phases/01-parameter-validation.md

@@ -1,174 +0,0 @@
-# Phase 1: Parameter Validation
-
-Validate all required parameters for command generation.
-
-## Objective
-
-Ensure all required parameters are provided before proceeding with command generation:
-- **skillName**: Command identifier (required)
-- **description**: Command description (required)
-- **location**: Target scope - "project" or "user" (required)
-- **group**: Optional grouping subdirectory
-- **argumentHint**: Optional argument hint string
-
-## Input
-
-Parameters received from skill invocation:
-- `skillName`: string (required)
-- `description`: string (required)
-- `location`: "project" | "user" (required)
-- `group`: string (optional)
-- `argumentHint`: string (optional)
-
-## Validation Rules
-
-### Required Parameters
-
-```javascript
-const requiredParams = {
-  skillName: {
-    type: 'string',
-    minLength: 1,
-    pattern: /^[a-z][a-z0-9-]*$/,  // lowercase, alphanumeric, hyphens
-    error: 'skillName must be lowercase alphanumeric with hyphens, starting with a letter'
-  },
-  description: {
-    type: 'string',
-    minLength: 10,
-    error: 'description must be at least 10 characters'
-  },
-  location: {
-    type: 'string',
-    enum: ['project', 'user'],
-    error: 'location must be "project" or "user"'
-  }
-};
-```
-
-### Optional Parameters
-
-```javascript
-const optionalParams = {
-  group: {
-    type: 'string',
-    pattern: /^[a-z][a-z0-9-]*$/,
-    default: null,
-    error: 'group must be lowercase alphanumeric with hyphens'
-  },
-  argumentHint: {
-    type: 'string',
-    default: '',
-    error: 'argumentHint must be a string'
-  }
-};
-```
-
-## Execution Steps
-
-### Step 1: Extract Parameters
-
-```javascript
-// Extract from skill args
-const params = {
-  skillName: args.skillName,
-  description: args.description,
-  location: args.location,
-  group: args.group || null,
-  argumentHint: args.argumentHint || ''
-};
-```
-
-### Step 2: Validate Required Parameters
-
-```javascript
-function validateRequired(params, rules) {
-  const errors = [];
-  
-  for (const [key, rule] of Object.entries(rules)) {
-    const value = params[key];
-    
-    // Check existence
-    if (value === undefined || value === null || value === '') {
-      errors.push(`${key} is required`);
-      continue;
-    }
-    
-    // Check type
-    if (typeof value !== rule.type) {
-      errors.push(`${key} must be a ${rule.type}`);
-      continue;
-    }
-    
-    // Check minLength
-    if (rule.minLength && value.length < rule.minLength) {
-      errors.push(`${key} must be at least ${rule.minLength} characters`);
-    }
-    
-    // Check pattern
-    if (rule.pattern && !rule.pattern.test(value)) {
-      errors.push(rule.error);
-    }
-    
-    // Check enum
-    if (rule.enum && !rule.enum.includes(value)) {
-      errors.push(`${key} must be one of: ${rule.enum.join(', ')}`);
-    }
-  }
-  
-  return errors;
-}
-
-const requiredErrors = validateRequired(params, requiredParams);
-if (requiredErrors.length > 0) {
-  throw new Error(`Validation failed:\n${requiredErrors.join('\n')}`);
-}
-```
-
-### Step 3: Validate Optional Parameters
-
-```javascript
-function validateOptional(params, rules) {
-  const warnings = [];
-  
-  for (const [key, rule] of Object.entries(rules)) {
-    const value = params[key];
-    
-    if (value !== null && value !== undefined && value !== '') {
-      if (rule.pattern && !rule.pattern.test(value)) {
-        warnings.push(`${key}: ${rule.error}`);
-      }
-    }
-  }
-  
-  return warnings;
-}
-
-const optionalWarnings = validateOptional(params, optionalParams);
-// Log warnings but continue
-```
-
-### Step 4: Normalize Parameters
-
-```javascript
-const validatedParams = {
-  skillName: params.skillName.trim().toLowerCase(),
-  description: params.description.trim(),
-  location: params.location.trim().toLowerCase(),
-  group: params.group ? params.group.trim().toLowerCase() : null,
-  argumentHint: params.argumentHint ? params.argumentHint.trim() : ''
-};
-```
-
-## Output
-
-```javascript
-{
-  status: 'validated',
-  params: validatedParams,
-  warnings: optionalWarnings
-}
-```
-
-## Next Phase
-
-Proceed to [Phase 2: Target Path Resolution](02-target-path-resolution.md) with `validatedParams`.

.claude/skills/command-generator/phases/02-target-path-resolution.md

@@ -1,171 +0,0 @@
-# Phase 2: Target Path Resolution
-
-Resolve the target commands directory based on location parameter.
-
-## Objective
-
-Determine the correct target path for the command file based on:
-- **location**: "project" or "user" scope
-- **group**: Optional subdirectory for command organization
-- **skillName**: Command filename (with .md extension)
-
-## Input
-
-From Phase 1 validation:
-```javascript
-{
-  skillName: string,      // e.g., "create"
-  description: string,
-  location: "project" | "user",
-  group: string | null,   // e.g., "issue"
-  argumentHint: string
-}
-```
-
-## Path Resolution Rules
-
-### Location Mapping
-
-```javascript
-const locationMap = {
-  project: '.claude/commands',
-  user: '~/.claude/commands'  // Expands to user home directory
-};
-```
-
-### Path Construction
-
-```javascript
-function resolveTargetPath(params) {
-  const baseDir = locationMap[params.location];
-  
-  if (!baseDir) {
-    throw new Error(`Invalid location: ${params.location}. Must be "project" or "user".`);
-  }
-  
-  // Expand ~ to user home if present
-  const expandedBase = baseDir.startsWith('~') 
-    ? path.join(os.homedir(), baseDir.slice(1))
-    : baseDir;
-  
-  // Build full path
-  let targetPath;
-  if (params.group) {
-    // Grouped command: .claude/commands/{group}/{skillName}.md
-    targetPath = path.join(expandedBase, params.group, `${params.skillName}.md`);
-  } else {
-    // Top-level command: .claude/commands/{skillName}.md
-    targetPath = path.join(expandedBase, `${params.skillName}.md`);
-  }
-  
-  return targetPath;
-}
-```
-
-## Execution Steps
-
-### Step 1: Get Base Directory
-
-```javascript
-const location = validatedParams.location;
-const baseDir = locationMap[location];
-
-if (!baseDir) {
-  throw new Error(`Invalid location: ${location}. Must be "project" or "user".`);
-}
-```
-
-### Step 2: Expand User Path (if applicable)
-
-```javascript
-const os = require('os');
-const path = require('path');
-
-let expandedBase = baseDir;
-if (baseDir.startsWith('~')) {
-  expandedBase = path.join(os.homedir(), baseDir.slice(1));
-}
-```
-
-### Step 3: Construct Full Path
-
-```javascript
-let targetPath;
-let targetDir;
-
-if (validatedParams.group) {
-  // Command with group subdirectory
-  targetDir = path.join(expandedBase, validatedParams.group);
-  targetPath = path.join(targetDir, `${validatedParams.skillName}.md`);
-} else {
-  // Top-level command
-  targetDir = expandedBase;
-  targetPath = path.join(targetDir, `${validatedParams.skillName}.md`);
-}
-```
-
-### Step 4: Ensure Target Directory Exists
-
-```javascript
-// Check and create directory if needed
-Bash(`mkdir -p "${targetDir}"`);
-```
-
-### Step 5: Check File Existence
-
-```javascript
-const fileExists = Bash(`test -f "${targetPath}" && echo "EXISTS" || echo "NOT_FOUND"`);
-
-if (fileExists.includes('EXISTS')) {
-  console.warn(`Warning: Command file already exists at ${targetPath}. Will overwrite.`);
-}
-```
-
-## Output
-
-```javascript
-{
-  status: 'resolved',
-  targetPath: targetPath,     // Full path to command file
-  targetDir: targetDir,       // Directory containing command
-  fileName: `${skillName}.md`,
-  fileExists: fileExists.includes('EXISTS'),
-  params: validatedParams     // Pass through to next phase
-}
-```
-
-## Path Examples
-
-### Project Scope (No Group)
-```
-location: "project"
-skillName: "deploy"
--> .claude/commands/deploy.md
-```
-
-### Project Scope (With Group)
-```
-location: "project"
-skillName: "create"
-group: "issue"
--> .claude/commands/issue/create.md
-```
-
-### User Scope (No Group)
-```
-location: "user"
-skillName: "global-status"
--> ~/.claude/commands/global-status.md
-```
-
-### User Scope (With Group)
-```
-location: "user"
-skillName: "sync"
-group: "session"
--> ~/.claude/commands/session/sync.md
-```
-
-## Next Phase
-
-Proceed to [Phase 3: Template Loading](03-template-loading.md) with `targetPath` and `params`.

.claude/skills/command-generator/phases/03-template-loading.md

@@ -1,123 +0,0 @@
-# Phase 3: Template Loading
-
-Load the command template file for content generation.
-
-## Objective
-
-Load the command template from the skill's templates directory. The template provides:
-- YAML frontmatter structure
-- Placeholder variables for substitution
-- Standard command file sections
-
-## Input
-
-From Phase 2:
-```javascript
-{
-  targetPath: string,
-  targetDir: string,
-  fileName: string,
-  fileExists: boolean,
-  params: {
-    skillName: string,
-    description: string,
-    location: string,
-    group: string | null,
-    argumentHint: string
-  }
-}
-```
-
-## Template Location
-
-```
-.claude/skills/command-generator/templates/command-md.md
-```
-
-## Execution Steps
-
-### Step 1: Locate Template File
-
-```javascript
-// Template is located in the skill's templates directory
-const skillDir = '.claude/skills/command-generator';
-const templatePath = `${skillDir}/templates/command-md.md`;
-```
-
-### Step 2: Read Template Content
-
-```javascript
-const templateContent = Read(templatePath);
-
-if (!templateContent) {
-  throw new Error(`Command template not found at ${templatePath}`);
-}
-```
-
-### Step 3: Validate Template Structure
-
-```javascript
-// Verify template contains expected placeholders
-const requiredPlaceholders = ['{{name}}', '{{description}}'];
-const optionalPlaceholders = ['{{group}}', '{{argumentHint}}'];
-
-for (const placeholder of requiredPlaceholders) {
-  if (!templateContent.includes(placeholder)) {
-    throw new Error(`Template missing required placeholder: ${placeholder}`);
-  }
-}
-```
-
-### Step 4: Store Template for Next Phase
-
-```javascript
-const template = {
-  content: templateContent,
-  requiredPlaceholders: requiredPlaceholders,
-  optionalPlaceholders: optionalPlaceholders
-};
-```
-
-## Template Format Reference
-
-The template should follow this structure:
-
-```markdown
----
-name: {{name}}
-description: {{description}}
-{{#if group}}group: {{group}}{{/if}}
-{{#if argumentHint}}argument-hint: {{argumentHint}}{{/if}}
----
-
-# {{name}} Command
-
-[Template content with placeholders]
-```
-
-## Output
-
-```javascript
-{
-  status: 'loaded',
-  template: {
-    content: templateContent,
-    requiredPlaceholders: requiredPlaceholders,
-    optionalPlaceholders: optionalPlaceholders
-  },
-  targetPath: targetPath,
-  params: params
-}
-```
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| Template file not found | Throw error with path |
-| Missing required placeholder | Throw error with missing placeholder name |
-| Empty template | Throw error |
-
-## Next Phase
-
-Proceed to [Phase 4: Content Formatting](04-content-formatting.md) with `template`, `targetPath`, and `params`.

.claude/skills/command-generator/phases/04-content-formatting.md

@@ -1,184 +0,0 @@
-# Phase 4: Content Formatting
-
-Format template content by substituting placeholders with parameter values.
-
-## Objective
-
-Replace all placeholder variables in the template with validated parameter values:
-- `{{name}}` -> skillName
-- `{{description}}` -> description
-- `{{group}}` -> group (if provided)
-- `{{argumentHint}}` -> argumentHint (if provided)
-
-## Input
-
-From Phase 3:
-```javascript
-{
-  template: {
-    content: string,
-    requiredPlaceholders: string[],
-    optionalPlaceholders: string[]
-  },
-  targetPath: string,
-  params: {
-    skillName: string,
-    description: string,
-    location: string,
-    group: string | null,
-    argumentHint: string
-  }
-}
-```
-
-## Placeholder Mapping
-
-```javascript
-const placeholderMap = {
-  '{{name}}': params.skillName,
-  '{{description}}': params.description,
-  '{{group}}': params.group || '',
-  '{{argumentHint}}': params.argumentHint || ''
-};
-```
-
-## Execution Steps
-
-### Step 1: Initialize Content
-
-```javascript
-let formattedContent = template.content;
-```
-
-### Step 2: Substitute Required Placeholders
-
-```javascript
-// These must always be replaced
-formattedContent = formattedContent.replace(/\{\{name\}\}/g, params.skillName);
-formattedContent = formattedContent.replace(/\{\{description\}\}/g, params.description);
-```
-
-### Step 3: Handle Optional Placeholders
-
-```javascript
-// Group placeholder
-if (params.group) {
-  formattedContent = formattedContent.replace(/\{\{group\}\}/g, params.group);
-} else {
-  // Remove group line if not provided
-  formattedContent = formattedContent.replace(/^group: \{\{group\}\}\n?/gm, '');
-  formattedContent = formattedContent.replace(/\{\{group\}\}/g, '');
-}
-
-// Argument hint placeholder
-if (params.argumentHint) {
-  formattedContent = formattedContent.replace(/\{\{argumentHint\}\}/g, params.argumentHint);
-} else {
-  // Remove argument-hint line if not provided
-  formattedContent = formattedContent.replace(/^argument-hint: \{\{argumentHint\}\}\n?/gm, '');
-  formattedContent = formattedContent.replace(/\{\{argumentHint\}\}/g, '');
-}
-```
-
-### Step 4: Handle Conditional Sections
-
-```javascript
-// Remove empty frontmatter lines (caused by missing optional fields)
-formattedContent = formattedContent.replace(/\n{3,}/g, '\n\n');
-
-// Handle {{#if group}} style conditionals
-if (formattedContent.includes('{{#if')) {
-  // Process group conditional
-  if (params.group) {
-    formattedContent = formattedContent.replace(/\{\{#if group\}\}([\s\S]*?)\{\{\/if\}\}/g, '$1');
-  } else {
-    formattedContent = formattedContent.replace(/\{\{#if group\}\}[\s\S]*?\{\{\/if\}\}/g, '');
-  }
-  
-  // Process argumentHint conditional
-  if (params.argumentHint) {
-    formattedContent = formattedContent.replace(/\{\{#if argumentHint\}\}([\s\S]*?)\{\{\/if\}\}/g, '$1');
-  } else {
-    formattedContent = formattedContent.replace(/\{\{#if argumentHint\}\}[\s\S]*?\{\{\/if\}\}/g, '');
-  }
-}
-```
-
-### Step 5: Validate Final Content
-
-```javascript
-// Ensure no unresolved placeholders remain
-const unresolvedPlaceholders = formattedContent.match(/\{\{[^}]+\}\}/g);
-if (unresolvedPlaceholders) {
-  console.warn(`Warning: Unresolved placeholders found: ${unresolvedPlaceholders.join(', ')}`);
-}
-
-// Ensure frontmatter is valid
-const frontmatterMatch = formattedContent.match(/^---\n([\s\S]*?)\n---/);
-if (!frontmatterMatch) {
-  throw new Error('Generated content has invalid frontmatter structure');
-}
-```
-
-### Step 6: Generate Summary
-
-```javascript
-const summary = {
-  name: params.skillName,
-  description: params.description.substring(0, 50) + (params.description.length > 50 ? '...' : ''),
-  location: params.location,
-  group: params.group,
-  hasArgumentHint: !!params.argumentHint
-};
-```
-
-## Output
-
-```javascript
-{
-  status: 'formatted',
-  content: formattedContent,
-  targetPath: targetPath,
-  summary: summary
-}
-```
-
-## Content Example
-
-### Input Template
-```markdown
----
-name: {{name}}
-description: {{description}}
-{{#if group}}group: {{group}}{{/if}}
-{{#if argumentHint}}argument-hint: {{argumentHint}}{{/if}}
----
-
-# {{name}} Command
-```
-
-### Output (with all fields)
-```markdown
----
-name: create
-description: Create structured issue from GitHub URL or text description
-group: issue
-argument-hint: [-y|--yes] <github-url | text-description> [--priority 1-5]
----
-
-# create Command
-```
-
-### Output (minimal fields)
-```markdown
----
-name: deploy
-description: Deploy application to production environment
----
-
-# deploy Command
-```
-
-## Next Phase
-
-Proceed to [Phase 5: File Generation](05-file-generation.md) with `content` and `targetPath`.

.claude/skills/command-generator/phases/05-file-generation.md

@@ -1,185 +0,0 @@
-# Phase 5: File Generation
-
-Write the formatted content to the target command file.
-
-## Objective
-
-Generate the final command file by:
-1. Checking for existing file (warn if present)
-2. Writing formatted content to target path
-3. Confirming successful generation
-
-## Input
-
-From Phase 4:
-```javascript
-{
-  status: 'formatted',
-  content: string,
-  targetPath: string,
-  summary: {
-    name: string,
-    description: string,
-    location: string,
-    group: string | null,
-    hasArgumentHint: boolean
-  }
-}
-```
-
-## Execution Steps
-
-### Step 1: Pre-Write Check
-
-```javascript
-// Check if file already exists
-const fileExists = Bash(`test -f "${targetPath}" && echo "EXISTS" || echo "NOT_FOUND"`);
-
-if (fileExists.includes('EXISTS')) {
-  console.warn(`
-WARNING: Command file already exists at: ${targetPath}
-The file will be overwritten with new content.
-  `);
-}
-```
-
-### Step 2: Ensure Directory Exists
-
-```javascript
-// Get directory from target path
-const targetDir = path.dirname(targetPath);
-
-// Create directory if it doesn't exist
-Bash(`mkdir -p "${targetDir}"`);
-```
-
-### Step 3: Write File
-
-```javascript
-// Write the formatted content
-Write(targetPath, content);
-```
-
-### Step 4: Verify Write
-
-```javascript
-// Confirm file was created
-const verifyExists = Bash(`test -f "${targetPath}" && echo "SUCCESS" || echo "FAILED"`);
-
-if (!verifyExists.includes('SUCCESS')) {
-  throw new Error(`Failed to create command file at ${targetPath}`);
-}
-
-// Verify content was written
-const writtenContent = Read(targetPath);
-if (!writtenContent || writtenContent.length === 0) {
-  throw new Error(`Command file created but appears to be empty`);
-}
-```
-
-### Step 5: Generate Success Report
-
-```javascript
-const report = {
-  status: 'completed',
-  file: {
-    path: targetPath,
-    name: summary.name,
-    location: summary.location,
-    group: summary.group,
-    size: writtenContent.length,
-    created: new Date().toISOString()
-  },
-  command: {
-    name: summary.name,
-    description: summary.description,
-    hasArgumentHint: summary.hasArgumentHint
-  },
-  nextSteps: [
-    `Edit ${targetPath} to add implementation details`,
-    'Add usage examples and execution flow',
-    'Test the command with Claude Code'
-  ]
-};
-```
-
-## Output
-
-### Success Output
-
-```javascript
-{
-  status: 'completed',
-  file: {
-    path: '.claude/commands/issue/create.md',
-    name: 'create',
-    location: 'project',
-    group: 'issue',
-    size: 1234,
-    created: '2026-02-27T12:00:00.000Z'
-  },
-  command: {
-    name: 'create',
-    description: 'Create structured issue from GitHub URL...',
-    hasArgumentHint: true
-  },
-  nextSteps: [
-    'Edit .claude/commands/issue/create.md to add implementation details',
-    'Add usage examples and execution flow',
-    'Test the command with Claude Code'
-  ]
-}
-```
-
-### Console Output
-
-```
-Command generated successfully!
-
-File: .claude/commands/issue/create.md
-Name: create
-Description: Create structured issue from GitHub URL...
-Location: project
-Group: issue
-
-Next Steps:
-1. Edit .claude/commands/issue/create.md to add implementation details
-2. Add usage examples and execution flow
-3. Test the command with Claude Code
-```
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| Directory creation failed | Throw error with directory path |
-| File write failed | Throw error with target path |
-| Empty file detected | Throw error and attempt cleanup |
-| Permission denied | Throw error with permission hint |
-
-## Cleanup on Failure
-
-```javascript
-// If any step fails, attempt to clean up partial artifacts
-function cleanup(targetPath) {
-  try {
-    Bash(`rm -f "${targetPath}"`);
-  } catch (e) {
-    // Ignore cleanup errors
-  }
-}
-```
-
-## Completion
-
-The command file has been successfully generated. The skill execution is complete.
-
-### Usage Example
-
-```bash
-# Use the generated command
-/issue:create https://github.com/owner/repo/issues/123
-
-# Or with the group prefix
-/issue:create "Login fails with special chars"
-```

.claude/skills/command-generator/specs/command-design-spec.md

@@ -1,160 +0,0 @@
-# Command Design Specification
-
-Guidelines and best practices for designing Claude Code command files.
-
-## Command File Structure
-
-### YAML Frontmatter
-
-Every command file must start with YAML frontmatter containing:
-
-```yaml
----
-name: command-name           # Required: Command identifier (lowercase, hyphens)
-description: Description     # Required: Brief description of command purpose
-argument-hint: "[args]"      # Optional: Argument format hint
-allowed-tools: Tool1, Tool2  # Optional: Restricted tool set
-examples:                    # Optional: Usage examples
-  - /command:example1
-  - /command:example2 --flag
----
-```
-
-### Frontmatter Fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Command identifier, lowercase with hyphens |
-| `description` | Yes | Brief description, appears in command listings |
-| `argument-hint` | No | Usage hint for arguments (shown in help) |
-| `allowed-tools` | No | Restrict available tools for this command |
-| `examples` | No | Array of usage examples |
-
-## Naming Conventions
-
-### Command Names
-
-- Use lowercase letters only
-- Separate words with hyphens (`create-issue`, not `createIssue`)
-- Keep names short but descriptive (2-3 words max)
-- Use verbs for actions (`deploy`, `create`, `analyze`)
-
-### Group Names
-
-- Groups organize related commands
-- Use singular nouns (`issue`, `session`, `workflow`)
-- Common groups: `issue`, `workflow`, `session`, `memory`, `cli`
-
-### Path Examples
-
-```
-.claude/commands/deploy.md           # Top-level command
-.claude/commands/issue/create.md     # Grouped command
-.claude/commands/workflow/init.md    # Grouped command
-```
-
-## Content Sections
-
-### Required Sections
-
-1. **Overview**: Brief description of command purpose
-2. **Usage**: Command syntax and examples
-3. **Execution Flow**: High-level process diagram
-
-### Recommended Sections
-
-4. **Implementation**: Code examples for each phase
-5. **Error Handling**: Error cases and recovery
-6. **Related Commands**: Links to related functionality
-
-## Best Practices
-
-### 1. Clear Purpose
-
-Each command should do one thing well:
-
-```
-Good: /issue:create - Create a new issue
-Bad:  /issue:manage - Create, update, delete issues (too broad)
-```
-
-### 2. Consistent Structure
-
-Follow the same pattern across all commands in a group:
-
-```markdown
-# All issue commands should have:
-- Overview
-- Usage with examples
-- Phase-based implementation
-- Error handling table
-```
-
-### 3. Progressive Detail
-
-Start simple, add detail in phases:
-
-```
-Phase 1: Quick overview
-Phase 2: Implementation details
-Phase 3: Edge cases and errors
-```
-
-### 4. Reusable Patterns
-
-Use consistent patterns for common operations:
-
-```javascript
-// Input parsing pattern
-const args = parseArguments($ARGUMENTS);
-const flags = parseFlags($ARGUMENTS);
-
-// Validation pattern
-if (!args.required) {
-  throw new Error('Required argument missing');
-}
-```
-
-## Scope Guidelines
-
-### Project Commands (`.claude/commands/`)
-
-- Project-specific workflows
-- Team conventions
-- Integration with project tools
-
-### User Commands (`~/.claude/commands/`)
-
-- Personal productivity tools
-- Cross-project utilities
-- Global configuration
-
-## Error Messages
-
-### Good Error Messages
-
-```
-Error: GitHub issue URL required
-Usage: /issue:create <github-url>
-Example: /issue:create https://github.com/owner/repo/issues/123
-```
-
-### Bad Error Messages
-
-```
-Error: Invalid input
-```
-
-## Testing Commands
-
-After creating a command, test:
-
-1. **Basic invocation**: Does it run without arguments?
-2. **Argument parsing**: Does it handle valid arguments?
-3. **Error cases**: Does it show helpful errors for invalid input?
-4. **Help text**: Is the usage clear?
-
-## Related Documentation
-
-- [SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) - Full skill design specification
-- [../skill-generator/SKILL.md](../skill-generator/SKILL.md) - Meta-skill for creating skills

.claude/skills/command-generator/templates/command-md.md

@@ -1,75 +0,0 @@
----
-name: {{name}}
-description: {{description}}
-{{#if argumentHint}}argument-hint: {{argumentHint}}
-{{/if}}---
-
-# {{name}} Command
-
-## Overview
-
-[Describe the command purpose and what it does]
-
-## Usage
-
-```bash
-/{{#if group}}{{group}}:{{/if}}{{name}} [arguments]
-```
-
-**Examples**:
-```bash
-# Example 1: Basic usage
-/{{#if group}}{{group}}:{{/if}}{{name}}
-
-# Example 2: With arguments
-/{{#if group}}{{group}}:{{/if}}{{name}} --option value
-```
-
-## Execution Flow
-
-```
-Phase 1: Input Parsing
-   - Parse arguments and flags
-   - Validate input parameters
-
-Phase 2: Core Processing
-   - Execute main logic
-   - Handle edge cases
-
-Phase 3: Output Generation
-   - Format results
-   - Display to user
-```
-
-## Implementation
-
-### Phase 1: Input Parsing
-
-```javascript
-// Parse command arguments
-const args = parseArguments($ARGUMENTS);
-```
-
-### Phase 2: Core Processing
-
-```javascript
-// TODO: Implement core logic
-```
-
-### Phase 3: Output Generation
-
-```javascript
-// TODO: Format and display output
-```
-
-## Error Handling
-
-| Error | Action |
-|-------|--------|
-| Invalid input | Show usage and error message |
-| Processing failure | Log error and suggest recovery |
-
-## Related Commands
-
-- [Related command 1]
-- [Related command 2]

.claude/skills/delegation-check/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: delegation-check
+description: Check workflow delegation prompts against agent role definitions for content separation violations. Detects conflicts, duplication, boundary leaks, and missing contracts. Triggers on "check delegation", "delegation conflict", "prompt vs role check".
+allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion
+---
+
+<purpose>
+Validate that command delegation prompts (Agent() calls) and agent role definitions respect GSD content separation boundaries. Detects 7 conflict dimensions: role re-definition, domain expertise leaking into prompts, quality gate duplication, output format conflicts, process override, scope authority conflicts, and missing contracts.
+
+Invoked when user requests "check delegation", "delegation conflict", "prompt vs role check", or when reviewing workflow skill quality.
+</purpose>
+
+<required_reading>
+- @.claude/skills/delegation-check/specs/separation-rules.md
+</required_reading>
+
+<process>
+
+## 1. Determine Scan Scope
+
+Parse `$ARGUMENTS` to identify what to check.
+
+| Signal | Scope |
+|--------|-------|
+| File path to command `.md` | Single command + its agents |
+| File path to agent `.md` | Single agent + commands that spawn it |
+| Directory path (e.g., `.claude/skills/team-*/`) | All commands + agents in that skill |
+| "all" or no args | Scan all `.claude/commands/`, `.claude/skills/*/`, `.claude/agents/` |
+
+If ambiguous, ask:
+
+```
+AskUserQuestion(
+  header: "Scan Scope",
+  question: "What should I check for delegation conflicts?",
+  options: [
+    { label: "Specific skill", description: "Check one skill directory" },
+    { label: "Specific command+agent pair", description: "Check one command and its spawned agents" },
+    { label: "Full scan", description: "Scan all commands, skills, and agents" }
+  ]
+)
+```
+
+## 2. Discover Command-Agent Pairs
+
+For each command file in scope:
+
+**2a. Extract Agent() calls from commands:**
+
+```bash
+# Search both Agent() (current) and Task() (legacy GSD) patterns
+grep -n "Agent(\|Task(" "$COMMAND_FILE"
+grep -n "subagent_type" "$COMMAND_FILE"
+```
+
+For each `Agent()` call, extract:
+- `subagent_type` → agent name
+- Full prompt content between the prompt markers (the string passed as `prompt=`)
+- Line range of the delegation prompt
+
+**2b. Locate agent definitions:**
+
+For each `subagent_type` found:
+```bash
+# Check standard locations
+ls .claude/agents/${AGENT_NAME}.md 2>/dev/null
+ls .claude/skills/*/agents/${AGENT_NAME}.md 2>/dev/null
+```
+
+**2c. Build pair map:**
+
+```
+$PAIRS = [
+  {
+    command: { path, agent_calls: [{ line, subagent_type, prompt_content }] },
+    agent: { path, role, sections, quality_gate, output_contract }
+  }
+]
+```
+
+If an agent file cannot be found, record as `MISSING_AGENT` — this is itself a finding.
+
+## 3. Parse Delegation Prompts
+
+For each Agent() call, extract structured blocks from the prompt content:
+
+| Block | What It Contains |
+|-------|-----------------|
+| `<objective>` | What to accomplish |
+| `<files_to_read>` | Input file paths |
+| `<additional_context>` / `<planning_context>` / `<verification_context>` | Runtime parameters |
+| `<output>` / `<expected_output>` | Output format/location expectations |
+| `<quality_gate>` | Per-invocation quality checklist |
+| `<deep_work_rules>` / `<instructions>` | Cross-cutting policy or revision instructions |
+| `<downstream_consumer>` | Who consumes the output |
+| `<success_criteria>` | Success conditions |
+| Free-form text | Unstructured instructions |
+
+Also detect ANTI-PATTERNS in prompt content:
+- Role identity statements ("You are a...", "Your role is...")
+- Domain expertise (decision tables, heuristics, comparison examples)
+- Process definitions (numbered steps, step-by-step instructions beyond scope)
+- Philosophy statements ("always prefer...", "never do...")
+- Anti-pattern lists that belong in agent definition
+
+## 4. Parse Agent Definitions
+
+For each agent file, extract:
+
+| Section | Key Content |
+|---------|------------|
+| `<role>` | Identity, spawner, responsibilities, mandatory read |
+| `<philosophy>` | Guiding principles |
+| `<upstream_input>` | How agent interprets input |
+| `<output_contract>` | Return markers (COMPLETE/BLOCKED/CHECKPOINT) |
+| `<quality_gate>` | Self-check criteria |
+| Domain sections | All `<section_name>` tags with their content |
+| YAML frontmatter | name, description, tools |
+
+## 5. Run Conflict Checks (7 Dimensions)
+
+### Dimension 1: Role Re-definition
+
+**Question:** Does the delegation prompt redefine the agent's identity?
+
+**Check:** Scan prompt content for:
+- "You are a..." / "You are the..." / "Your role is..."
+- "Your job is to..." / "Your responsibility is..."
+- "Core responsibilities:" lists
+- Any content that contradicts agent's `<role>` section
+
+**Allowed:** References to mode ("standard mode", "revision mode") that the agent's `<role>` already lists in "Spawned by:".
+
+**Severity:** `error` if prompt redefines role; `warning` if prompt adds responsibilities not in agent's `<role>`.
+
+### Dimension 2: Domain Expertise Leak
+
+**Question:** Does the delegation prompt embed domain knowledge that belongs in the agent?
+
+**Check:** Scan prompt content for:
+- Decision/routing tables (`| Condition | Action |`)
+- Good-vs-bad comparison examples (`| TOO VAGUE | JUST RIGHT |`)
+- Heuristic rules ("If X then Y", "Always prefer Z")
+- Anti-pattern lists ("DO NOT...", "NEVER...")
+- Detailed process steps beyond task scope
+
+**Exception:** `<deep_work_rules>` is an acceptable cross-cutting policy pattern from GSD — flag as `info` only.
+
+**Severity:** `error` if prompt contains domain tables/examples that duplicate agent content; `warning` if prompt contains heuristics not in agent.
+
+### Dimension 3: Quality Gate Duplication
+
+**Question:** Do the prompt's quality checks overlap or conflict with the agent's own `<quality_gate>`?
+
+**Check:** Compare prompt `<quality_gate>` / `<success_criteria>` items against agent's `<quality_gate>` items:
+- **Duplicate:** Same check appears in both → `warning` (redundant, may diverge)
+- **Conflict:** Contradictory criteria (e.g., prompt says "max 3 tasks", agent says "max 5 tasks") → `error`
+- **Missing:** Prompt expects quality checks agent doesn't have → `info`
+
+**Severity:** `error` for contradictions; `warning` for duplicates; `info` for gaps.
+
+### Dimension 4: Output Format Conflict
+
+**Question:** Does the prompt's expected output format conflict with the agent's `<output_contract>`?
+
+**Check:**
+- Prompt `<expected_output>` markers vs agent's `<output_contract>` return markers
+- Prompt expects specific format agent doesn't define
+- Prompt expects file output but agent's contract only defines markers (or vice versa)
+- Return marker names differ (prompt expects `## DONE`, agent returns `## TASK COMPLETE`)
+
+**Severity:** `error` if return markers conflict; `warning` if format expectations unspecified on either side.
+
+### Dimension 5: Process Override
+
+**Question:** Does the delegation prompt dictate HOW the agent should work?
+
+**Check:** Scan prompt for:
+- Numbered step-by-step instructions ("Step 1:", "First..., Then..., Finally...")
+- Process flow definitions beyond `<objective>` scope
+- Tool usage instructions ("Use grep to...", "Run bash command...")
+- Execution ordering that conflicts with agent's own execution flow
+
+**Allowed:** `<instructions>` block for revision mode (telling agent what changed, not how to work).
+
+**Severity:** `error` if prompt overrides agent's process; `warning` if prompt suggests process hints.
+
+### Dimension 6: Scope Authority Conflict
+
+**Question:** Does the prompt make decisions that belong to the agent's domain?
+
+**Check:**
+- Prompt specifies implementation choices (library selection, architecture patterns) when agent's `<philosophy>` or domain sections own these decisions
+- Prompt overrides agent's discretion areas
+- Prompt locks decisions that agent's `<context_fidelity>` says are "Claude's Discretion"
+
+**Allowed:** Passing through user-locked decisions from CONTEXT.md — this is proper delegation, not authority conflict.
+
+**Severity:** `error` if prompt makes domain decisions agent should own; `info` if prompt passes through user decisions (correct behavior).
+
+### Dimension 7: Missing Contracts
+
+**Question:** Are the delegation handoff points properly defined?
+
+**Check:**
+- Agent has `<output_contract>` with return markers → command handles all markers?
+- Command's return handling covers COMPLETE, BLOCKED, CHECKPOINT
+- Agent lists "Spawned by:" — does command actually spawn it?
+- Agent expects `<files_to_read>` — does prompt provide it?
+- Agent has `<upstream_input>` — does prompt provide matching input structure?
+
+**Severity:** `error` if return marker handling is missing; `warning` if agent expects input the prompt doesn't provide.
+
+## 6. Aggregate and Report
+
+### 6a. Per-pair summary
+
+For each command-agent pair, aggregate findings:
+
+```
+{command_path} → {agent_name}
+  Agent() at line {N}:
+    D1 (Role Re-def):      {PASS|WARN|ERROR} — {detail}
+    D2 (Domain Leak):       {PASS|WARN|ERROR} — {detail}
+    D3 (Quality Gate):      {PASS|WARN|ERROR} — {detail}
+    D4 (Output Format):     {PASS|WARN|ERROR} — {detail}
+    D5 (Process Override):  {PASS|WARN|ERROR} — {detail}
+    D6 (Scope Authority):   {PASS|WARN|ERROR} — {detail}
+    D7 (Missing Contract):  {PASS|WARN|ERROR} — {detail}
+```
+
+### 6b. Overall verdict
+
+| Verdict | Condition |
+|---------|-----------|
+| **CLEAN** | 0 errors, 0-2 warnings |
+| **REVIEW** | 0 errors, 3+ warnings |
+| **CONFLICT** | 1+ errors |
+
+### 6c. Fix recommendations
+
+For each finding, provide:
+- **Location:** file:line
+- **What's wrong:** concrete description
+- **Fix:** move content to correct owner (command or agent)
+- **Example:** before/after snippet if applicable
+
+## 7. Present Results
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DELEGATION-CHECK ► SCAN COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Scope: {description}
+Pairs checked: {N} command-agent pairs
+Findings: {E} errors, {W} warnings, {I} info
+
+Verdict: {CLEAN | REVIEW | CONFLICT}
+
+| Pair | D1 | D2 | D3 | D4 | D5 | D6 | D7 |
+|------|----|----|----|----|----|----|-----|
+| {cmd} → {agent} | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ | ✅ |
+| ... | | | | | | | |
+
+{If CONFLICT: detailed findings with fix recommendations}
+
+───────────────────────────────────────────────────────
+
+## Fix Priority
+
+1. {Highest severity fix}
+2. {Next fix}
+...
+
+───────────────────────────────────────────────────────
+```
+
+</process>
+
+<success_criteria>
+- [ ] Scan scope determined and all files discovered
+- [ ] All Agent() calls extracted from commands with full prompt content
+- [ ] All corresponding agent definitions located and parsed
+- [ ] 7 conflict dimensions checked for each command-agent pair
+- [ ] No false positives on legitimate patterns (mode references, user decision passthrough, `<deep_work_rules>`)
+- [ ] Fix recommendations provided for every error/warning
+- [ ] Summary table with per-pair dimension results displayed
+- [ ] Overall verdict determined (CLEAN/REVIEW/CONFLICT)
+</success_criteria>

.claude/skills/delegation-check/specs/separation-rules.md

@@ -0,0 +1,269 @@
+# GSD Content Separation Rules
+
+Rules for validating the boundary between **command delegation prompts** (Agent() calls) and **agent role definitions** (agent `.md` files). Derived from analysis of GSD's `plan-phase.md`, `execute-phase.md`, `research-phase.md` and their corresponding agents (`gsd-planner`, `gsd-plan-checker`, `gsd-executor`, `gsd-phase-researcher`, `gsd-verifier`).
+
+## Core Principle
+
+**Commands own WHEN and WHERE. Agents own WHO and HOW.**
+
+A delegation prompt tells the agent what to do *this time*. The agent definition tells the agent who it *always* is.
+
+## Ownership Matrix
+
+### Command Delegation Prompt Owns
+
+| Concern | XML Block | Example |
+|---------|-----------|---------|
+| What to accomplish | `<objective>` | "Execute plan 3 of phase 2" |
+| Input file paths | `<files_to_read>` | "- {state_path} (Project State)" |
+| Runtime parameters | `<additional_context>` | "Phase: 5, Mode: revision" |
+| Output location | `<output>` | "Write to: {phase_dir}/RESEARCH.md" |
+| Expected return format | `<expected_output>` | "## VERIFICATION PASSED or ## ISSUES FOUND" |
+| Who consumes output | `<downstream_consumer>` | "Output consumed by /gsd:execute-phase" |
+| Revision context | `<instructions>` | "Make targeted updates to address checker issues" |
+| Cross-cutting policy | `<deep_work_rules>` | Anti-shallow execution rules (applies to all agents) |
+| Per-invocation quality | `<quality_gate>` (in prompt) | Invocation-specific checks (e.g., "every task has `<read_first>`") |
+| Flow control | Revision loops, return routing | "If TASK COMPLETE → step 13. If BLOCKED → offer options" |
+| User interaction | `AskUserQuestion` | "Provide context / Skip / Abort" |
+| Banners | Status display | "━━━ GSD ► PLANNING PHASE {X} ━━━" |
+
+### Agent Role Definition Owns
+
+| Concern | XML Section | Example |
+|---------|-------------|---------|
+| Identity | `<role>` | "You are a GSD planner" |
+| Spawner list | `<role>` → Spawned by | "/gsd:plan-phase orchestrator" |
+| Responsibilities | `<role>` → Core responsibilities | "Decompose phases into parallel-optimized plans" |
+| Mandatory read protocol | `<role>` → Mandatory Initial Read | "MUST use Read tool to load every file in `<files_to_read>`" |
+| Project discovery | `<project_context>` | "Read CLAUDE.md, check .claude/skills/" |
+| Guiding principles | `<philosophy>` | Quality degradation curve by context usage |
+| Input interpretation | `<upstream_input>` | "Decisions → LOCKED, Discretion → freedom" |
+| Decision honoring | `<context_fidelity>` | "Locked decisions are NON-NEGOTIABLE" |
+| Core insight | `<core_principle>` | "Plan completeness ≠ Goal achievement" |
+| Domain expertise | Named domain sections | `<verification_dimensions>`, `<task_breakdown>`, `<dependency_graph>` |
+| Return protocol | `<output_contract>` | TASK COMPLETE / TASK BLOCKED / CHECKPOINT REACHED |
+| Self-check | `<quality_gate>` (in agent) | Permanent checks for every invocation |
+| Anti-patterns | `<anti_patterns>` | "DO NOT check code existence" |
+| Examples | `<examples>` | Scope exceeded analysis example |
+
+## Conflict Patterns
+
+### Pattern 1: Role Re-definition
+
+**Symptom:** Delegation prompt contains identity language.
+
+```
+# BAD — prompt redefines role
+Agent({
+  subagent_type: "gsd-plan-checker",
+  prompt: "You are a code quality expert. Your job is to review plans...
+    <objective>Verify phase 5 plans</objective>"
+})
+
+# GOOD — prompt states objective only
+Agent({
+  subagent_type: "gsd-plan-checker",
+  prompt: "<verification_context>
+    <files_to_read>...</files_to_read>
+  </verification_context>
+  <expected_output>## VERIFICATION PASSED or ## ISSUES FOUND</expected_output>"
+})
+```
+
+**Why it's wrong:** The agent's `<role>` section already defines identity. Re-definition in prompt can contradict, confuse, or override the agent's self-understanding.
+
+**Detection:** Regex for `You are a|Your role is|Your job is to|Your responsibility is|Core responsibilities:` in prompt content.
+
+### Pattern 2: Domain Expertise Leak
+
+**Symptom:** Delegation prompt contains decision tables, heuristics, or examples.
+
+```
+# BAD — prompt embeds domain knowledge
+Agent({
+  subagent_type: "gsd-planner",
+  prompt: "<objective>Create plans for phase 3</objective>
+    Remember: tasks should have 2-3 items max.
+    | TOO VAGUE | JUST RIGHT |
+    | 'Add auth' | 'Add JWT auth with refresh rotation' |"
+})
+
+# GOOD — agent's own <task_breakdown> section owns this knowledge
+Agent({
+  subagent_type: "gsd-planner",
+  prompt: "<planning_context>
+    <files_to_read>...</files_to_read>
+  </planning_context>"
+})
+```
+
+**Why it's wrong:** Domain knowledge in prompts duplicates agent content. When agent evolves, prompt doesn't update — they diverge. Agent's domain sections are the single source of truth.
+
+**Exception — `<deep_work_rules>`:** GSD uses this as a cross-cutting policy block (not domain expertise per se) that applies anti-shallow-execution rules across all agents. This is acceptable because:
+1. It's structural policy, not domain knowledge
+2. It applies uniformly to all planning agents
+3. It supplements (not duplicates) agent's own quality gate
+
+**Detection:**
+- Tables with `|` in prompt content (excluding `<files_to_read>` path tables)
+- "Good:" / "Bad:" / "Example:" comparison pairs
+- "Always..." / "Never..." / "Prefer..." heuristic statements
+- Numbered rules lists (>3 items) that aren't revision instructions
+
+### Pattern 3: Quality Gate Duplication
+
+**Symptom:** Same quality check appears in both prompt and agent definition.
+
+```
+# PROMPT quality_gate
+- [ ] Every task has `<read_first>`
+- [ ] Every task has `<acceptance_criteria>`
+- [ ] Dependencies correctly identified
+
+# AGENT quality_gate
+- [ ] Every task has `<read_first>` with at least the file being modified
+- [ ] Every task has `<acceptance_criteria>` with grep-verifiable conditions
+- [ ] Dependencies correctly identified
+```
+
+**Analysis:**
+- "Dependencies correctly identified" → **duplicate** (exact match)
+- "`<read_first>`" in both → **overlap** (prompt is less specific than agent)
+- "`<acceptance_criteria>`" → **overlap** (same check, different specificity)
+
+**When duplication is OK:** Prompt's `<quality_gate>` adds *invocation-specific* checks not in agent's permanent gate (e.g., "Phase requirement IDs all covered" is specific to this phase, not general).
+
+**Detection:** Fuzzy match quality gate items between prompt and agent (>60% token overlap).
+
+### Pattern 4: Output Format Conflict
+
+**Symptom:** Command expects return markers the agent doesn't define.
+
+```
+# COMMAND handles:
+- "## VERIFICATION PASSED" → continue
+- "## ISSUES FOUND" → revision loop
+
+# AGENT <output_contract> defines:
+- "## TASK COMPLETE"
+- "## TASK BLOCKED"
+```
+
+**Why it's wrong:** Command routes on markers. If markers don't match, routing breaks silently — command may hang or misinterpret results.
+
+**Detection:** Extract return marker strings from both sides, compare sets.
+
+### Pattern 5: Process Override
+
+**Symptom:** Prompt dictates step-by-step process.
+
+```
+# BAD — prompt overrides agent's process
+Agent({
+  subagent_type: "gsd-planner",
+  prompt: "Step 1: Read the roadmap. Step 2: Extract requirements.
+    Step 3: Create task breakdown. Step 4: Assign waves..."
+})
+
+# GOOD — prompt states objective, agent decides process
+Agent({
+  subagent_type: "gsd-planner",
+  prompt: "<objective>Create plans for phase 5</objective>
+    <files_to_read>...</files_to_read>"
+})
+```
+
+**Exception — Revision instructions:** `<instructions>` block in revision prompts is acceptable because it tells the agent *what changed* (checker issues), not *how to work*.
+
+```
+# OK — revision context, not process override
+<instructions>
+Make targeted updates to address checker issues.
+Do NOT replan from scratch unless issues are fundamental.
+Return what changed.
+</instructions>
+```
+
+**Detection:** "Step N:" / "First..." / "Then..." / "Finally..." patterns in prompt content outside `<instructions>` blocks.
+
+### Pattern 6: Scope Authority Conflict
+
+**Symptom:** Prompt makes domain decisions the agent should own.
+
+```
+# BAD — prompt decides implementation details
+Agent({
+  subagent_type: "gsd-planner",
+  prompt: "Use React Query for data fetching. Use Zustand for state management.
+    <objective>Plan the frontend architecture</objective>"
+})
+
+# GOOD — user decisions passed through from CONTEXT.md
+Agent({
+  subagent_type: "gsd-planner",
+  prompt: "<planning_context>
+    <files_to_read>
+    - {context_path} (USER DECISIONS - locked: React Query, Zustand)
+    </files_to_read>
+  </planning_context>"
+})
+```
+
+**Key distinction:**
+- **Prompt making decisions** = conflict (command shouldn't have domain opinion)
+- **Prompt passing through user decisions** = correct (user decisions flow through command to agent)
+- **Agent interpreting user decisions** = correct (agent's `<context_fidelity>` handles locked/deferred/discretion)
+
+**Detection:** Technical nouns (library names, architecture patterns) in prompt free text (not inside `<files_to_read>` path descriptions).
+
+### Pattern 7: Missing Contracts
+
+**Symptom:** Handoff points between command and agent are incomplete.
+
+| Missing Element | Impact |
+|-----------------|--------|
+| Agent has no `<output_contract>` | Command can't route on return markers |
+| Command doesn't handle all agent return markers | BLOCKED/CHECKPOINT silently ignored |
+| Agent expects `<files_to_read>` but prompt doesn't provide it | Agent starts without context |
+| Agent's "Spawned by:" doesn't list this command | Agent may not expect this invocation pattern |
+| Agent has `<upstream_input>` but prompt doesn't match structure | Agent misinterprets input |
+
+**Detection:** Cross-reference both sides for completeness.
+
+## The `<deep_work_rules>` Exception
+
+GSD's plan-phase uses `<deep_work_rules>` in delegation prompts. This is a deliberate design choice, not a violation:
+
+1. **It's cross-cutting policy**: applies to ALL planning agents equally
+2. **It's structural**: defines required fields (`<read_first>`, `<acceptance_criteria>`, `<action>` concreteness) — not domain expertise
+3. **It supplements agent quality**: agent's own `<quality_gate>` is self-check; deep_work_rules is command-imposed minimum standard
+4. **It's invocation-specific context**: different commands might impose different work rules
+
+**Rule:** `<deep_work_rules>` in a delegation prompt is `info` level, not error. Flag only if its content duplicates agent's domain sections verbatim.
+
+## Severity Classification
+
+| Severity | When | Action Required |
+|----------|------|-----------------|
+| `error` | Actual conflict: contradictory content between prompt and agent | Must fix — move content to correct owner |
+| `warning` | Duplication or boundary blur without contradiction | Should fix — consolidate to single source of truth |
+| `info` | Acceptable pattern that looks like violation but isn't | No action — document why it's OK |
+
+## Quick Reference: Is This Content in the Right Place?
+
+| Content | In Prompt? | In Agent? |
+|---------|-----------|-----------|
+| "You are a..." | ❌ Never | ✅ Always |
+| File paths for this invocation | ✅ Yes | ❌ No |
+| Phase number, mode | ✅ Yes | ❌ No |
+| Decision tables | ❌ Never | ✅ Always |
+| Good/bad examples | ❌ Never | ✅ Always |
+| "Write to: {path}" | ✅ Yes | ❌ No |
+| Return markers handling | ✅ Yes (routing) | ✅ Yes (definition) |
+| Quality gate | ✅ Per-invocation | ✅ Permanent self-check |
+| "MUST read files first" | ❌ Agent's `<role>` owns this | ✅ Always |
+| Anti-shallow rules | ⚠️ OK as cross-cutting policy | ✅ Preferred |
+| Revision instructions | ✅ Yes (what changed) | ❌ No |
+| Heuristics / philosophy | ❌ Never | ✅ Always |
+| Banner display | ✅ Yes | ❌ Never |
+| AskUserQuestion | ✅ Yes | ❌ Never |

.claude/skills/prompt-generator/SKILL.md

@@ -0,0 +1,463 @@
+---
+name: prompt-generator
+description: Generate or convert Claude Code prompt files — command orchestrators, skill files, agent role definitions, or style conversion of existing files. Follows GSD-style content separation with built-in quality gates. Triggers on "create command", "new command", "create skill", "new skill", "create agent", "new agent", "convert command", "convert skill", "convert agent", "prompt generator", "优化".
+allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion
+---
+
+<purpose>
+Generate or convert Claude Code prompt files with concrete, domain-specific content. Four modes:
+
+- **Create command** — new orchestration workflow at `.claude/commands/` or `~/.claude/commands/`
+- **Create skill** — new skill file at `.claude/skills/*/SKILL.md` (progressive loading, no @ refs)
+- **Create agent** — new role + expertise file at `.claude/agents/`
+- **Convert** — restyle existing command/skill/agent to GSD conventions with zero content loss
+
+Content separation principle (from GSD): commands/skills own orchestration flow; agents own domain knowledge. Skills are a variant of commands but loaded progressively inline — they CANNOT use `@` file references.
+
+Invoked when user requests "create command", "new command", "create skill", "new skill", "create agent", "new agent", "convert command", "convert skill", "convert agent", "prompt generator", or "优化".
+</purpose>
+
+<required_reading>
+- @.claude/skills/prompt-generator/specs/command-design-spec.md
+- @.claude/skills/prompt-generator/specs/agent-design-spec.md
+- @.claude/skills/prompt-generator/specs/conversion-spec.md
+- @.claude/skills/prompt-generator/templates/command-md.md
+- @.claude/skills/prompt-generator/templates/agent-md.md
+</required_reading>
+
+<process>
+
+## 1. Determine Artifact Type
+
+Parse `$ARGUMENTS` to determine what to generate.
+
+| Signal | Type |
+|--------|------|
+| "command", "workflow", "orchestrator" in args | `command` |
+| "skill", "SKILL.md" in args, or path contains `.claude/skills/` | `skill` |
+| "agent", "role", "worker" in args | `agent` |
+| "convert", "restyle", "refactor", "optimize", "优化" + file path in args | `convert` |
+| Ambiguous or missing | Ask user |
+
+**Convert mode detection:** If args contain a file path (`.md` extension) + conversion keywords, enter convert mode. Extract `$SOURCE_PATH` from args. Auto-detect source type from path:
+- `.claude/commands/` → command
+- `.claude/skills/*/SKILL.md` → skill
+- `.claude/agents/` → agent
+
+**Skill vs Command distinction:** Skills (`.claude/skills/*/SKILL.md`) are loaded **progressively inline** into the conversation context. They CANNOT use `@` file references — only `Read()` tool calls within process steps. See `@specs/command-design-spec.md` → "Skill Variant" section.
+
+If ambiguous:
+
+```
+AskUserQuestion(
+  header: "Artifact Type",
+  question: "What type of prompt file do you want to generate?",
+  options: [
+    { label: "Command", description: "New orchestration workflow — process steps, user interaction, agent spawning" },
+    { label: "Skill", description: "New skill file — progressive loading, no @ refs, inline Read() for external files" },
+    { label: "Agent", description: "New role definition — identity, domain expertise, behavioral rules" },
+    { label: "Convert", description: "Restyle existing command/agent/skill to GSD conventions (zero content loss)" }
+  ]
+)
+```
+
+Store as `$ARTIFACT_TYPE` (`command` | `skill` | `agent` | `convert`).
+
+## 2. Validate Parameters
+
+**If `$ARTIFACT_TYPE` is `convert`:** Skip to Step 2c.
+
+Extract from `$ARGUMENTS` or ask interactively:
+
+**Common parameters (create mode):**
+
+| Parameter | Required | Validation | Example |
+|-----------|----------|------------|---------|
+| `$NAME` | Yes | `/^[a-z][a-z0-9-]*$/` | `deploy`, `gsd-planner` |
+| `$DESCRIPTION` | Yes | min 10 chars | `"Deploy to production with rollback"` |
+
+**Command-specific parameters:**
+
+| Parameter | Required | Validation | Example |
+|-----------|----------|------------|---------|
+| `$LOCATION` | Yes | `"project"` or `"user"` | `project` |
+| `$GROUP` | No | `/^[a-z][a-z0-9-]*$/` | `issue`, `workflow` |
+| `$ARGUMENT_HINT` | No | any string | `"<phase> [--skip-verify]"` |
+
+**Agent-specific parameters:**
+
+| Parameter | Required | Validation | Example |
+|-----------|----------|------------|---------|
+| `$TOOLS` | No | comma-separated tool names | `Read, Write, Bash, Glob` |
+| `$SPAWNED_BY` | No | which command spawns this agent | `/plan-phase orchestrator` |
+
+Normalize: trim + lowercase for `$NAME`, `$LOCATION`, `$GROUP`.
+
+## 3. Resolve Target Path
+
+**Command:**
+
+| Location | Base |
+|----------|------|
+| `project` | `.claude/commands` |
+| `user` | `~/.claude/commands` |
+
+```
+If $GROUP:
+  $TARGET_PATH = {base}/{$GROUP}/{$NAME}.md
+Else:
+  $TARGET_PATH = {base}/{$NAME}.md
+```
+
+**Skill:**
+
+```
+$TARGET_PATH = .claude/skills/{$NAME}/SKILL.md
+```
+
+**Agent:**
+
+```
+$TARGET_PATH = .claude/agents/{$NAME}.md
+```
+
+Check if `$TARGET_PATH` exists → `$FILE_EXISTS`.
+
+## 4. Gather Requirements
+
+**4a. Pattern discovery** — Find 3+ similar files in the project for style reference:
+
+```bash
+# For commands: scan existing commands
+ls .claude/commands/**/*.md 2>/dev/null | head -5
+
+# For agents: scan existing agents
+ls .claude/agents/*.md 2>/dev/null | head -5
+```
+
+Read 1-2 similar files to extract patterns: section structure, naming conventions, XML tag usage, prompt style.
+
+**4b. Domain inference** from `$NAME`, `$DESCRIPTION`, and context:
+
+| Signal | Extract |
+|--------|---------|
+| `$NAME` | Action verb → step/section naming |
+| `$DESCRIPTION` | Domain keywords → content structure |
+| `$ARGUMENT_HINT` | Flags → parse_input logic (command only) |
+| `$SPAWNED_BY` | Upstream contract → role boundary (agent only) |
+
+**For commands — determine complexity:**
+
+| Complexity | Criteria | Steps |
+|------------|----------|-------|
+| Simple | Single action, no flags | 3-5 numbered steps |
+| Standard | 1-2 flags, clear workflow | 5-8 numbered steps |
+| Complex | Multiple flags, agent spawning | 8-14 numbered steps |
+
+**For agents — determine expertise scope:**
+
+| Scope | Criteria | Sections |
+|-------|----------|----------|
+| Focused | Single responsibility | `<role>` + 1-2 domain sections |
+| Standard | Multi-aspect domain | `<role>` + 2-4 domain sections |
+| Expert | Deep domain with rules | `<role>` + 4-6 domain sections |
+
+If unclear, ask user with AskUserQuestion.
+
+## 5. Generate Content
+
+Route to the appropriate generation logic based on `$ARTIFACT_TYPE`.
+
+### 5a. Command Generation
+
+Follow `@specs/command-design-spec.md` and `@templates/command-md.md`.
+
+Generate a complete command file with:
+
+1. **`<purpose>`** — 2-3 sentences: what + when + what it produces
+2. **`<required_reading>`** — @ references to context files
+3. **`<process>`** — numbered steps (GSD workflow style):
+   - Step 1: Initialize / parse arguments
+   - Steps 2-N: Domain-specific orchestration logic
+   - Each step: banner display, validation, agent spawning via `Agent()`, error handling
+   - Final step: status display + `<offer_next>` with next actions
+4. **`<success_criteria>`** — checkbox list of verifiable conditions
+
+**Command writing rules:**
+- Steps are **numbered** (`## 1.`, `## 2.`) — follow `plan-phase.md` and `new-project.md` style
+- Use banners for phase transitions: `━━━ SKILL ► ACTION ━━━`
+- Agent spawning uses `Agent({ subagent_type, prompt, description, run_in_background })` pattern
+- Prompt to agents uses `<objective>`, `<files_to_read>`, `<output>` blocks
+- Include `<offer_next>` block with formatted completion status
+- Handle agent return markers: `## TASK COMPLETE`, `## TASK BLOCKED`, `## CHECKPOINT REACHED`
+- Shell blocks use heredoc for multi-line, quote all variables
+- Include `<auto_mode>` section if command supports `--auto` flag
+
+### 5a-skill. Skill Generation (variant of command)
+
+Follow `@specs/command-design-spec.md` → "Skill Variant" section.
+
+Skills are command-like orchestrators but loaded **progressively inline** — they CANNOT use `@` file references.
+
+Generate a complete skill file with:
+
+1. **`<purpose>`** — 2-3 sentences: what + when + what it produces
+2. **NO `<required_reading>`** — skills cannot use `@` refs. External files loaded via `Read()` within process steps.
+3. **`<process>`** — numbered steps (GSD workflow style):
+   - Step 1: Initialize / parse arguments / set workflow preferences
+   - Steps 2-N: Domain-specific orchestration logic with inline `Read("phases/...")` for phase files
+   - Each step: validation, agent spawning via `Agent()`, error handling
+   - Final step: completion status or handoff to next skill via `Skill()`
+4. **`<success_criteria>`** — checkbox list of verifiable conditions
+
+**Skill-specific writing rules:**
+- **NO `<required_reading>` tag** — `@` syntax not supported in skills
+- **NO `@path` references** anywhere in the file — use `Read("path")` within `<process>` steps
+- Phase files loaded on-demand: `Read("phases/01-xxx.md")` within the step that needs it
+- Frontmatter uses `allowed-tools:` (not `argument-hint:`)
+- `<offer_next>` is optional — skills often chain via `Skill()` calls
+- `<auto_mode>` can be inline within `<process>` step 1 or as standalone section
+
+### 5b. Agent Generation
+
+Follow `@specs/agent-design-spec.md` and `@templates/agent-md.md`.
+
+Generate a complete agent definition with:
+
+1. **YAML frontmatter** — name, description, tools, color (optional)
+2. **`<role>`** — identity + spawned-by + core responsibilities + mandatory initial read
+3. **Domain sections** (2-6 based on scope):
+   - `<philosophy>` — guiding principles, anti-patterns
+   - `<context_fidelity>` — how to honor upstream decisions
+   - `<task_breakdown>` / `<output_format>` — concrete output rules with examples
+   - `<quality_gate>` — self-check criteria before returning
+   - Custom domain sections as needed
+4. **Output contract** — structured return markers to orchestrator
+
+**Agent writing rules:**
+- `<role>` is ALWAYS first after frontmatter — defines identity
+- Each section owns ONE concern — no cross-cutting
+- Include concrete examples (good vs bad comparison tables) in every domain section
+- Include decision/routing tables for conditional logic
+- Quality gate uses checkbox format for self-verification
+- Agent does NOT contain orchestration logic, user interaction, or argument parsing
+
+### 5c. Convert Mode (Restyle Existing File)
+
+**CRITICAL: Zero content loss.** Follow `@specs/conversion-spec.md`.
+
+**Step 5c.1: Read and inventory source file.**
+
+Read `$SOURCE_PATH` completely. Build content inventory:
+
+```
+$INVENTORY = {
+  frontmatter: { fields extracted },
+  sections: [ { name, tag, line_range, line_count, has_code_blocks, has_tables } ],
+  code_blocks: count,
+  tables: count,
+  total_lines: count
+}
+```
+
+**Step 5c.2: Classify source type.**
+
+| Signal | Type |
+|--------|------|
+| Path in `.claude/skills/*/SKILL.md` | skill |
+| `allowed-tools:` in frontmatter + path in `.claude/skills/` | skill |
+| Contains `<process>`, `<step>`, numbered `## N.` steps | command |
+| Contains `<role>`, `tools:` in frontmatter, domain sections | agent |
+| Flat markdown with `## Implementation`, `## Phase N` + in skills dir | skill (unstructured) |
+| Flat markdown with `## Implementation`, `## Phase N` + in commands dir | command (unstructured) |
+| Flat prose with role description, no process steps | agent (unstructured) |
+
+**Skill-specific conversion rules:**
+- **NO `<required_reading>`** — skills cannot use `@` file references (progressive loading)
+- **NO `@path` references** anywhere — replace with `Read("path")` within `<process>` steps
+- If source has `@specs/...` or `@phases/...` refs, convert to `Read("specs/...")` / `Read("phases/...")`
+- Follow `@specs/conversion-spec.md` → "Skill Conversion Rules" section
+
+**Step 5c.3: Build conversion map.**
+
+Map every source section to its target location. Follow `@specs/conversion-spec.md` transformation rules.
+
+**MANDATORY**: Every line of source content must appear in the conversion map. If a source section has no clear target, keep it as a custom section.
+
+**Step 5c.4: Generate converted content.**
+
+Apply structural transformations while preserving ALL content verbatim:
+- Rewrap into GSD XML tags
+- Restructure sections to match target template ordering
+- Add missing required sections (empty `<quality_gate>`, `<output_contract>`) with `TODO` markers
+- Preserve all code blocks, tables, examples, shell commands exactly as-is
+
+**Step 5c.5: Content loss verification (MANDATORY).**
+
+Compare source and output:
+
+| Metric | Source | Output | Pass? |
+|--------|--------|--------|-------|
+| Total lines | `$SRC_LINES` | `$OUT_LINES` | output >= source × 0.95 |
+| Code blocks | `$SRC_BLOCKS` | `$OUT_BLOCKS` | output >= source |
+| Tables | `$SRC_TABLES` | `$OUT_TABLES` | output >= source |
+| Sections | `$SRC_SECTIONS` | `$OUT_SECTIONS` | output >= source |
+
+If ANY metric fails → STOP, display diff, ask user before proceeding.
+
+Set `$TARGET_PATH = $SOURCE_PATH` (in-place conversion) unless user specifies output path.
+
+### Content quality rules (both types):
+- NO bracket placeholders (`[Describe...]`) — all content concrete
+- NO generic instructions ("handle errors appropriately") — be specific
+- Include domain-specific examples derived from `$DESCRIPTION`
+- Every shell block: heredoc for multi-line, quoted variables, error exits
+
+## 6. Quality Gate
+
+**MANDATORY before writing.** Read back the generated content and validate against type-specific checks.
+
+### 6a. Structural Validation (both types)
+
+| Check | Pass Condition |
+|-------|---------------|
+| YAML frontmatter | Has `name` + `description` |
+| No placeholders | Zero `[...]` or `{...}` bracket placeholders in prose |
+| Concrete content | Every section has actionable content, not descriptions of what to write |
+| Section count | Command: 3+ sections; Agent: 4+ sections |
+
+### 6b. Command-Specific Checks
+
+| Check | Pass Condition |
+|-------|---------------|
+| `<purpose>` | 2-3 sentences, no placeholders |
+| `<process>` with numbered steps | At least 3 `## N.` headers |
+| Step 1 is initialization | Parses args or loads context |
+| Last step is status/report | Displays results or routes to `<offer_next>` |
+| Agent spawning (if complex) | `Agent({` call with `subagent_type` |
+| Agent prompt structure | `<files_to_read>` + `<objective>` or `<output>` blocks |
+| Return handling | Routes on `## TASK COMPLETE` / `## TASK BLOCKED` markers |
+| `<offer_next>` | Banner + summary + next command suggestion |
+| `<success_criteria>` | 4+ checkbox items, all verifiable |
+| Content separation | No domain expertise embedded — only orchestration |
+
+### 6b-skill. Skill-Specific Checks
+
+| Check | Pass Condition |
+|-------|---------------|
+| `<purpose>` | 2-3 sentences, no placeholders |
+| **NO `<required_reading>`** | Must NOT contain `<required_reading>` tag |
+| **NO `@` file references** | Zero `@specs/`, `@phases/`, `@./` patterns in prose |
+| `<process>` with numbered steps | At least 3 `## N.` headers |
+| Step 1 is initialization | Parses args, sets workflow preferences |
+| Phase file loading | Uses `Read("phases/...")` within process steps (if has phases) |
+| `<success_criteria>` | 4+ checkbox items, all verifiable |
+| Frontmatter `allowed-tools` | Present and lists required tools |
+| Content separation | No domain expertise embedded — only orchestration |
+
+### 6c. Agent-Specific Checks
+
+| Check | Pass Condition |
+|-------|---------------|
+| YAML `tools` field | Lists tools agent needs |
+| `<role>` is first section | Appears before any domain section |
+| `<role>` has spawned-by | States which command spawns it |
+| `<role>` has mandatory read | `<files_to_read>` instruction present |
+| `<role>` has responsibilities | 3+ bullet points with verb phrases |
+| Domain sections named | After domain concepts, not generic (`<rules>`, `<guidelines>`) |
+| Examples present | Each domain section has 1+ comparison table or decision table |
+| `<output_contract>` | Defines return markers (COMPLETE/BLOCKED/CHECKPOINT) |
+| `<quality_gate>` | 3+ checkbox self-check items |
+| Content separation | No `AskUserQuestion`, no banner display, no argument parsing |
+
+### 6d. Quality Gate Result
+
+Count errors and warnings:
+
+| Gate | Condition | Action |
+|------|-----------|--------|
+| **PASS** | 0 errors, 0-2 warnings | Proceed to write |
+| **REVIEW** | 1-2 errors or 3+ warnings | Fix errors, display warnings |
+| **FAIL** | 3+ errors | Re-generate from step 5 |
+
+If FAIL and second attempt also fails:
+
+```
+AskUserQuestion(
+  header: "Quality Gate Failed",
+  question: "Generated content failed quality checks twice. How to proceed?",
+  options: [
+    { label: "Show issues and proceed", description: "Write as-is, fix manually" },
+    { label: "Provide more context", description: "I'll give additional details" },
+    { label: "Abort", description: "Cancel generation" }
+  ]
+)
+```
+
+## 7. Write and Verify
+
+**If `$FILE_EXISTS`:** Warn user before overwriting.
+
+```bash
+mkdir -p "$(dirname "$TARGET_PATH")"
+```
+
+Write content to `$TARGET_PATH` using Write tool.
+
+**Post-write verification** — Read back and confirm file integrity:
+- File exists and is non-empty
+- Content matches what was generated (no corruption)
+- File size is reasonable (command: 50-500 lines; agent: 80-600 lines)
+
+**If verification fails:** Fix in-place with Edit tool.
+
+## 8. Present Status
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PROMPT-GEN ► {COMMAND|AGENT} GENERATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Type: {command | agent}
+File: {$TARGET_PATH}
+Name: {$NAME}
+
+| Section | Status |
+|---------|--------|
+| {section 1} | concrete |
+| {section 2} | concrete |
+| ... | ... |
+
+Quality Gate: {PASS | REVIEW (N warnings)}
+
+───────────────────────────────────────────────────────
+
+## Next Up
+
+1. Review: cat {$TARGET_PATH}
+2. Test: /{invocation}
+
+**If command + needs an agent:**
+  /prompt-generator agent {agent-name} "{agent description}"
+
+**If agent + needs a command:**
+  /prompt-generator command {command-name} "{command description}"
+
+───────────────────────────────────────────────────────
+```
+
+</process>
+
+<success_criteria>
+- [ ] Artifact type determined (command or agent)
+- [ ] All required parameters validated
+- [ ] Target path resolved correctly
+- [ ] 1-2 similar existing files read for pattern reference
+- [ ] Domain requirements gathered from description
+- [ ] Content generated with concrete, domain-specific logic
+- [ ] GSD content separation respected (commands = orchestration, agents = expertise)
+- [ ] Quality gate passed (structural + type-specific checks)
+- [ ] No bracket placeholders in final output
+- [ ] File written and post-write verified
+- [ ] Status banner displayed with quality gate result
+</success_criteria>

.claude/skills/prompt-generator/specs/agent-design-spec.md

@@ -0,0 +1,299 @@
+# Agent Design Specification
+
+Guidelines for Claude Code **agent definition files** (role + domain expertise). Agents own identity, knowledge, and quality standards — NOT orchestration flow.
+
+## Content Separation Principle
+
+Agents are spawned by commands via `Agent()`. The agent file defines WHO the agent is and WHAT it knows. It does NOT define WHEN or HOW it gets invoked.
+
+| Concern | Belongs in Agent | Belongs in Command |
+|---------|-----------------|-------------------|
+| Role identity (`<role>`) | Yes | No |
+| Domain expertise | Yes | No |
+| Output format/structure | Yes | No |
+| Quality heuristics | Yes | No |
+| Self-check criteria | Yes | No |
+| Philosophy/principles | Yes | No |
+| Discovery protocol | Yes | No |
+| Specificity examples | Yes | No |
+| Argument parsing | No | Yes |
+| User interaction | No | Yes |
+| Flow control | No | Yes |
+| Agent spawning | No | Yes |
+| Status banners | No | Yes |
+| Revision loop logic | No | Yes |
+
+## YAML Frontmatter
+
+```yaml
+---
+name: agent-name
+description: One-line purpose. Spawned by /command-name orchestrator.
+tools: Read, Write, Bash, Glob, Grep    # Tools this agent needs
+color: green                             # Optional: terminal color
+---
+```
+
+**Naming convention:** `{domain}-{role}` or `{project}-{role}` — e.g., `gsd-planner`, `gsd-plan-checker`, `code-reviewer`.
+
+## Content Structure
+
+Agent files use XML semantic tags. `<role>` is ALWAYS first after frontmatter.
+
+### Section Catalog
+
+Derived from GSD agent patterns (`gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`):
+
+| Section | Purpose | When to Include |
+|---------|---------|-----------------|
+| `<role>` | Identity, spawner, responsibilities | **Always** |
+| `<project_context>` | How to discover project conventions | Agent reads project files |
+| `<philosophy>` | Guiding principles, anti-patterns | Agent has opinionated approach |
+| `<context_fidelity>` | Honor upstream decisions (locked/deferred/discretion) | Agent receives user decisions |
+| `<upstream_input>` | What the agent receives and how to use it | Agent has structured input |
+| `<discovery_levels>` | Research depth protocol (L0-L3) | Agent does research |
+| `<task_breakdown>` | Task anatomy, sizing, ordering | Agent produces tasks |
+| `<dependency_graph>` | How to build dependency graphs | Agent manages dependencies |
+| `<output_format>` | Exact output structure with templates | Agent produces structured output |
+| `<core_principle>` | Central verification or design principle | Agent has one key insight |
+| `<output_contract>` | Return markers to orchestrator | **Always** |
+| `<quality_gate>` | Self-check before returning | **Always** |
+
+### Section Ordering Convention
+
+```
+<role>              ← Identity (always first)
+<project_context>   ← How to orient in the project
+<philosophy>        ← Guiding beliefs
+<upstream_input>    ← What agent receives
+<context_fidelity>  ← How to honor decisions
+<core_principle>    ← Key insight
+... domain sections ← Expertise (2-6 sections)
+<output_contract>   ← Return protocol
+<quality_gate>      ← Self-check (always last content section)
+```
+
+## Section Writing Rules
+
+### `<role>` — Identity (ALWAYS FIRST)
+
+Pattern from `gsd-planner.md` and `gsd-plan-checker.md`:
+
+```markdown
+<role>
+You are a {role name}. You {primary action verb} {what you produce}.
+
+Spawned by:
+- `/{command}` orchestrator (standard mode)
+- `/{command} --flag` orchestrator (variant mode)
+- `/{command}` in revision mode (updating based on checker feedback)
+
+Your job: {One sentence — what downstream consumers get from you.}
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
+to load every file listed there before performing any other actions. This is your
+primary context.
+
+**Core responsibilities:**
+- **FIRST: {Most important action}** ({why it's first})
+- {Responsibility 2 — verb phrase}
+- {Responsibility 3 — verb phrase}
+- {Responsibility 4 — verb phrase}
+- Return structured results to orchestrator
+</role>
+```
+
+### `<project_context>` — Project Discovery
+
+Pattern from `gsd-planner.md`:
+
+```markdown
+<project_context>
+Before {acting}, discover project context:
+
+**Project instructions:** Read `./CLAUDE.md` if it exists. Follow all project-specific
+guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.claude/skills/` directory if exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill
+3. Load specific files as needed during {action}
+4. Ensure {output} accounts for project patterns
+</project_context>
+```
+
+### `<philosophy>` — Guiding Principles
+
+Pattern from `gsd-planner.md`:
+
+```markdown
+<philosophy>
+## {Principle Name}
+
+{Core belief about how this agent approaches work.}
+
+| Context Usage | Quality | Agent's State |
+|---------------|---------|---------------|
+| 0-30% | PEAK | Thorough |
+| 50-70% | DEGRADING | Efficiency mode |
+| 70%+ | POOR | Rushed |
+
+**Anti-patterns (delete if seen):**
+- {Anti-pattern 1 with specific indicator}
+- {Anti-pattern 2 with specific indicator}
+</philosophy>
+```
+
+### `<upstream_input>` — Structured Input Handling
+
+Pattern from `gsd-plan-checker.md`:
+
+```markdown
+<upstream_input>
+**{Input name}** (if exists) — {Source description}
+
+| Section | How You Use It |
+|---------|----------------|
+| `## Section A` | LOCKED — {must implement exactly}. Flag if contradicted. |
+| `## Section B` | Freedom areas — {can choose approach}, don't flag. |
+| `## Section C` | Out of scope — {must NOT include}. Flag if present. |
+</upstream_input>
+```
+
+### `<context_fidelity>` — Decision Honoring
+
+Pattern from `gsd-planner.md`:
+
+```markdown
+<context_fidelity>
+## CRITICAL: User Decision Fidelity
+
+**Before creating ANY {output}, verify:**
+
+1. **Locked Decisions** — MUST be implemented exactly as specified
+   - If user said "use library X" → {output} MUST use X, not alternative
+   - If user said "card layout" → {output} MUST implement cards
+
+2. **Deferred Ideas** — MUST NOT appear in {output}
+   - If user deferred "search" → NO search tasks allowed
+
+3. **Discretion Areas** — Use your judgment
+   - Make reasonable choices and document in {output}
+
+**Self-check before returning:**
+- [ ] Every locked decision has coverage
+- [ ] No deferred idea appears
+- [ ] Discretion areas handled reasonably
+
+**If conflict exists** (research vs user decision):
+- Honor the user's locked decision
+- Note: "Using X per user decision (research suggested Y)"
+</context_fidelity>
+```
+
+### Domain Sections — One Concern Each
+
+Name sections after the domain concept. Include concrete examples in EVERY section.
+
+**Required elements per domain section:**
+
+| Element | Minimum |
+|---------|---------|
+| Good vs bad comparison table | 1 per section |
+| Decision/routing table | 1 per section (if conditional logic exists) |
+| Format template | 1 per section (if structured output) |
+| Concrete example | 2+ per section |
+
+**Example from gsd-planner.md `<task_breakdown>`:**
+
+```markdown
+<task_breakdown>
+## Task Anatomy
+
+Every task has four required fields:
+
+**<files>:** Exact paths.
+- Good: `src/app/api/auth/login/route.ts`
+- Bad: "the auth files"
+
+**<action>:** Specific instructions.
+- Good: "Create POST endpoint accepting {email, password}, validates using bcrypt,
+  returns JWT in httpOnly cookie with 15-min expiry. Use jose library."
+- Bad: "Add authentication"
+
+## Specificity Examples
+
+| TOO VAGUE | JUST RIGHT |
+|-----------|------------|
+| "Add auth" | "Add JWT auth with refresh rotation, jose library, httpOnly cookie" |
+| "Style the dashboard" | "Tailwind: 3-col grid on lg, 1 on mobile, card shadows, hover states" |
+
+**Test:** Could a different agent execute without clarifying questions?
+</task_breakdown>
+```
+
+### `<output_contract>` — Return Protocol
+
+```markdown
+<output_contract>
+## Return Protocol
+
+Return ONE of these markers as the LAST section of output:
+
+### Success
+```
+## TASK COMPLETE
+
+{Summary of what was produced}
+{Artifact locations: file paths}
+{Key metrics: counts, coverage}
+```
+
+### Blocked
+```
+## TASK BLOCKED
+
+**Blocker:** {What's missing or preventing progress}
+**Need:** {Specific action/info that would unblock}
+**Attempted:** {What was tried before declaring blocked}
+```
+
+### Checkpoint (needs user decision)
+```
+## CHECKPOINT REACHED
+
+**Question:** {Decision needed from user}
+**Context:** {Why this matters}
+**Options:**
+1. {Option A} — {effect on output}
+2. {Option B} — {effect on output}
+```
+</output_contract>
+```
+
+### `<quality_gate>` — Self-Check (ALWAYS LAST)
+
+```markdown
+<quality_gate>
+Before returning, verify:
+- [ ] {Check 1 — concrete, grep-verifiable}
+- [ ] {Check 2 — concrete, counts/exists}
+- [ ] {Check 3 — concrete, structural}
+- [ ] {Check 4 — no prohibited content}
+</quality_gate>
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong | Correct Approach |
+|-------------|----------------|------------------|
+| Agent contains `AskUserQuestion` | Agents don't interact with users | Return `## CHECKPOINT REACHED` |
+| Agent parses `$ARGUMENTS` | Arguments belong to the command | Receive pre-parsed values in prompt |
+| Agent displays banners | UI is the command's job | Return structured data |
+| `<role>` is not first section | Identity must be established first | Always lead with `<role>` |
+| Generic section names | Hard to scan, unclear scope | Name after domain concept |
+| No examples in domain sections | Rules without examples are ambiguous | Include comparison tables |
+| Agent spawns other agents | Spawning belongs to commands | Request via `## CHECKPOINT REACHED` |
+| Agent defines its own invocation syntax | That's the command's responsibility | Document in `Spawned by:` only |
+| Domain section covers multiple concerns | Violates single-concern rule | Split into separate sections |

.claude/skills/prompt-generator/specs/command-design-spec.md

@@ -0,0 +1,367 @@
+# Command Design Specification
+
+Guidelines for Claude Code **command files** (orchestration workflows). Commands own process flow, user interaction, and agent coordination — NOT domain expertise.
+
+## Content Separation Principle
+
+| Concern | Belongs in Command | Belongs in Agent |
+|---------|-------------------|-----------------|
+| Argument parsing | Yes | No |
+| Path resolution | Yes | No |
+| User prompts (AskUserQuestion) | Yes | No |
+| Status banners | Yes | No |
+| Agent spawning (Task) | Yes | No |
+| Flow control (if/else routing) | Yes | No |
+| Init/context loading (CLI tools) | Yes | No |
+| Revision loops | Yes | No |
+| Domain knowledge | No | Yes |
+| Quality heuristics | No | Yes |
+| Output format rules | No | Yes |
+| Role identity | No | Yes |
+
+## YAML Frontmatter
+
+```yaml
+---
+name: command-name           # Required: lowercase with hyphens
+description: Description     # Required: brief purpose
+argument-hint: "[args]"      # Optional: argument format hint
+allowed-tools: Tool1, Tool2  # Optional: restricted tool set
+---
+```
+
+## Path Structure
+
+```
+.claude/commands/deploy.md           # Top-level command
+.claude/commands/issue/create.md     # Grouped command
+~/.claude/commands/global-status.md  # User-level command
+.claude/skills/my-skill/SKILL.md     # Skill file (see Skill Variant below)
+```
+
+## Content Structure
+
+Commands use XML semantic tags with process steps inside `<process>`:
+
+| Tag | Required | Purpose |
+|-----|----------|---------|
+| `<purpose>` | Yes | What + when + what it produces (2-3 sentences) |
+| `<required_reading>` | Commands only | @ file references loaded before execution |
+| `<process>` | Yes | Steps — numbered or named (see Step Styles below) |
+| `<auto_mode>` | Optional | Behavior when `--auto` flag present |
+| `<offer_next>` | Recommended | Formatted completion status + next actions |
+| `<success_criteria>` | Yes | Checkbox list of verifiable conditions |
+
+## Skill Variant
+
+Skills (`.claude/skills/*/SKILL.md`) follow command structure with critical differences due to **progressive loading** — skills are loaded inline into the conversation context, NOT via file resolution.
+
+### Key Differences: Skill vs Command
+
+| Aspect | Command | Skill |
+|--------|---------|-------|
+| Location | `.claude/commands/` | `.claude/skills/*/SKILL.md` |
+| Loading | Slash-command invocation, `@` refs resolved | Progressive inline loading into conversation |
+| `<required_reading>` | Yes — `@path` refs auto-resolved | **NO** — `@` refs do NOT work in skills |
+| External file access | `@` references | `Read()` tool calls within `<process>` steps |
+| Phase files | N/A | `Read("phases/01-xxx.md")` within process steps |
+| Frontmatter | `name`, `description`, `argument-hint` | `name`, `description`, `allowed-tools` |
+
+### Skill-Specific Rules
+
+1. **NO `<required_reading>` tag** — Skills cannot use `@` file references. All external context must be loaded via `Read()` tool calls within `<process>` steps.
+
+2. **Progressive phase loading** — For multi-phase skills with phase files in `phases/` subdirectory, use inline `Read()`:
+   ```javascript
+   // Within process step: Load phase doc on-demand
+   Read("phases/01-session-discovery.md")
+   // Execute phase logic...
+   ```
+
+3. **Self-contained content** — All instructions, rules, and logic must be directly in the SKILL.md or loaded via `Read()` at runtime. No implicit file dependencies.
+
+4. **Frontmatter uses `allowed-tools:`** instead of `argument-hint:`:
+   ```yaml
+   ---
+   name: my-skill
+   description: What this skill does
+   allowed-tools: Agent, Read, Write, Bash, Glob, Grep
+   ---
+   ```
+
+### Skill Content Structure
+
+| Tag | Required | Purpose |
+|-----|----------|---------|
+| `<purpose>` | Yes | What + when + what it produces (2-3 sentences) |
+| `<process>` | Yes | Steps with inline `Read()` for external files |
+| `<auto_mode>` | Optional | Behavior when `-y`/`--yes` flag present |
+| `<success_criteria>` | Yes | Checkbox list of verifiable conditions |
+
+**Note**: `<offer_next>` is less common in skills since skills often chain to other skills via `Skill()` calls.
+
+## Step Styles
+
+GSD uses two step styles. Choose based on command nature:
+
+### Style A: Numbered Steps (for complex orchestrators)
+
+Used by: `plan-phase.md`, `new-project.md`, `research-phase.md`
+
+Best for: Multi-agent orchestration, long workflows with branching, revision loops.
+
+```markdown
+<process>
+
+## 1. Initialize
+
+Load context, parse arguments.
+
+## 2. Validate Phase
+
+Check preconditions.
+
+## 3. Spawn Agent
+
+Display banner, construct prompt, spawn.
+
+## 4. Handle Result
+
+Route on return markers.
+
+## 5. Present Status
+
+Display offer_next.
+
+</process>
+```
+
+### Style B: Named `<step>` Blocks (for focused commands)
+
+Used by: `execute-phase.md`, `discuss-phase.md`, `verify-work.md`
+
+Best for: Sequential steps, clear atomic actions, step-level priority.
+
+```markdown
+<process>
+
+<step name="initialize" priority="first">
+Load context, parse arguments.
+</step>
+
+<step name="validate_phase">
+Check preconditions.
+</step>
+
+<step name="spawn_agent">
+Construct prompt, spawn agent.
+</step>
+
+<step name="report">
+Display results.
+</step>
+
+</process>
+```
+
+### Which style to use?
+
+| Criteria | Numbered | Named `<step>` |
+|----------|----------|----------------|
+| Agent spawning with revision loops | Yes | No |
+| Multiple conditional branches | Yes | No |
+| Sequential with clear boundaries | No | Yes |
+| Steps reference each other by number | Yes | No |
+| First step needs `priority="first"` | No | Yes |
+
+## Init Pattern
+
+Most GSD commands start by loading context via CLI tools:
+
+```bash
+INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init {command} "${ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+For non-GSD commands, the equivalent is reading config/state files:
+
+```bash
+# Read project state
+CONFIG=$(cat .claude/config.json 2>/dev/null || echo '{}')
+```
+
+## Banner Style
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SKILL ► ACTION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Display banners before major phase transitions (agent spawning, user decisions, completion).
+
+## Agent Spawning Pattern
+
+Commands spawn agents via `Agent()` with structured prompts:
+
+```javascript
+Agent({
+  subagent_type: "agent-name",
+  prompt: filled_prompt,
+  description: "Verb Phase {X}",
+  run_in_background: false
+})
+```
+
+### Prompt Structure for Agents
+
+The prompt passed to agents uses XML blocks:
+
+```markdown
+<objective>
+What to accomplish — specific and measurable.
+</objective>
+
+<files_to_read>
+- {path1} (description — what this file provides)
+- {path2} (description)
+</files_to_read>
+
+<additional_context>
+**Phase:** {number}
+**Mode:** {standard | revision | gap_closure}
+Extra info the agent needs.
+</additional_context>
+
+<output>
+Write to: {output_path}
+</output>
+```
+
+### Return Handling
+
+Commands route on agent return markers:
+
+```markdown
+## Handle Agent Return
+
+- **`## TASK COMPLETE`:** Display confirmation, continue to next step.
+- **`## TASK BLOCKED`:** Display blocker, offer user options:
+  1) Provide context  2) Skip  3) Abort
+- **`## CHECKPOINT REACHED`:** Present question to user, relay response.
+```
+
+## Revision Loop Pattern
+
+For commands that iterate between generation and verification:
+
+```markdown
+## N. Revision Loop (Max 3 Iterations)
+
+Track `iteration_count` (starts at 1).
+
+**If iteration_count < 3:**
+- Display: "Sending back for revision... (iteration {N}/3)"
+- Spawn agent with revision prompt + checker issues
+- After agent returns → spawn checker again, increment count
+
+**If iteration_count >= 3:**
+- Display remaining issues
+- Offer: 1) Force proceed  2) Provide guidance  3) Abandon
+```
+
+## Auto Mode Pattern
+
+Commands supporting `--auto` flag define behavior in `<auto_mode>`:
+
+```markdown
+<auto_mode>
+## Auto Mode Detection
+
+Check if `--auto` flag is present in $ARGUMENTS.
+
+**If auto mode:**
+- Skip confirmation prompts
+- Use smart defaults for optional choices
+- Auto-approve intermediate results
+- Chain to next command on success
+
+**Document requirement (if applicable):**
+- What --auto requires as input
+- Error message if requirements not met
+</auto_mode>
+```
+
+## offer_next Pattern
+
+```markdown
+<offer_next>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SKILL ► TASK COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**{Summary line}**
+
+| Key | Value |
+|-----|-------|
+| ... | ...   |
+
+Status: {metric 1} | {metric 2}
+
+───────────────────────────────────────────────────────
+
+## Next Up
+
+**{Primary next action}**
+
+/{next-command} {args}
+
+<sub>/clear first — fresh context window</sub>
+
+───────────────────────────────────────────────────────
+
+**Also available:**
+- /{alt-1} — description
+- /{alt-2} — description
+
+───────────────────────────────────────────────────────
+</offer_next>
+```
+
+## AskUserQuestion Pattern
+
+For user decisions within commands:
+
+```markdown
+AskUserQuestion(
+  header: "Context",
+  question: "Descriptive question?",
+  options: [
+    { label: "Option A", description: "Effect of choosing A" },
+    { label: "Option B", description: "Effect of choosing B" }
+  ]
+)
+
+If "Option A": {action}
+If "Option B": {action}
+```
+
+## Shell Correctness Rules
+
+| Rule | Wrong | Correct |
+|------|-------|---------|
+| Multi-line output | `echo "{ ... }"` | `cat <<'EOF' > file`...`EOF` |
+| Variable init | Use `$VAR` after conditional | Initialize BEFORE conditional |
+| Error exit | `echo "Error"` (no exit) | `echo "Error" && exit 1` |
+| Quoting | `$VAR` bare | `"$VAR"` quoted |
+| Prerequisites | Implicit tool usage | Declare in `<prerequisites>` |
+| File existence | Assume file exists | `test -f "$FILE" && ...` |
+
+## Step Naming Conventions
+
+| Domain | Typical Steps |
+|--------|--------------|
+| Multi-Agent Pipeline | Initialize, Validate, Spawn Agent A, Handle A Result, Spawn Agent B, Revision Loop, Present Status |
+| Deploy/Release | Initialize, Validate Config, Run Deployment, Verify Health, Present Status |
+| CRUD | Initialize, Validate Entity, Persist Changes, Present Status |
+| Analysis | Initialize, Gather Context, Spawn Analyzer, Present Findings |

.claude/skills/prompt-generator/specs/conversion-spec.md

@@ -0,0 +1,207 @@
+# Conversion Specification
+
+Rules for restyling existing command/agent files to GSD conventions. **Zero content loss is mandatory.**
+
+## Core Principle
+
+Conversion = structural transformation, NOT content rewriting. Every line of source content must appear in the output. Only the container (XML tags, section ordering, frontmatter format) changes.
+
+## Content Loss Prevention Protocol
+
+### Pre-conversion Inventory
+
+Before converting, count:
+- `$SRC_LINES` — total non-empty lines
+- `$SRC_BLOCKS` — code block count (``` pairs)
+- `$SRC_TABLES` — table count (lines starting with `|`)
+- `$SRC_SECTIONS` — section count (## headers)
+
+### Post-conversion Verification
+
+| Metric | Rule | Action on Fail |
+|--------|------|----------------|
+| Lines | output >= source × 0.95 | STOP — find missing content |
+| Code blocks | output >= source | STOP — find missing blocks |
+| Tables | output >= source | STOP — find missing tables |
+| Sections | output >= source | WARN — sections may have merged |
+
+### Diff Display
+
+After conversion, show summary:
+```
+Conversion Summary:
+  Source: {path} ({src_lines} lines, {src_blocks} code blocks)
+  Output: {path} ({out_lines} lines, {out_blocks} code blocks)
+  Delta:  {+/-} lines, {+/-} code blocks
+  New sections added: {list of TODO sections}
+```
+
+## Artifact Type Detection
+
+Before applying conversion rules, determine the source type:
+
+| Source Location | Type |
+|----------------|------|
+| `.claude/commands/**/*.md` | command |
+| `.claude/skills/*/SKILL.md` | skill |
+| `.claude/agents/*.md` | agent |
+
+**Skill detection signals**: `allowed-tools:` in frontmatter, located in `.claude/skills/` directory, progressive phase loading pattern (`Read("phases/...")`)
+
+## Skill Conversion Rules
+
+### Critical: No @ References
+
+Skills are loaded **progressively inline** into the conversation context. They CANNOT use `@` file references — these only work in commands.
+
+### Source Pattern → Target Pattern (Skill)
+
+| Source Style | Target Style |
+|-------------|-------------|
+| `# Title` + flat markdown overview | `<purpose>` (2-3 sentences) |
+| `## Implementation` / `## Execution Flow` / `## Phase Summary` | `<process>` with numbered `## N.` steps |
+| Phase file references as prose | `Read("phases/...")` calls within process steps |
+| `## Success Criteria` / `## Coordinator Checklist` | `<success_criteria>` with checkbox list |
+| `## Auto Mode` / `## Auto Mode Defaults` | `<auto_mode>` section |
+| `## Error Handling` | Preserve as-is within `<process>` or as standalone section |
+| Code blocks, tables, ASCII diagrams | **Preserve exactly** |
+
+### What NOT to Add (Skill-Specific)
+
+| Element | Why NOT |
+|---------|---------|
+| `<required_reading>` | Skills cannot use `@` refs — progressive loading |
+| `@specs/...` or `@phases/...` | `@` syntax not supported in skills |
+| `<offer_next>` | Skills chain via `Skill()` calls, not offer menus |
+
+### What to ADD (Skill-Specific)
+
+| Missing Element | Add |
+|----------------|-----|
+| `<purpose>` | Extract from overview/description |
+| `<process>` wrapper | Wrap implementation steps |
+| `<success_criteria>` | Generate from coordinator checklist or existing content |
+| `<auto_mode>` | If auto mode behavior exists, wrap in tag |
+
+### Frontmatter Conversion (Skill)
+
+| Source Field | Target Field | Transformation |
+|-------------|-------------|----------------|
+| `name` | `name` | Keep as-is |
+| `description` | `description` | Keep as-is |
+| `allowed-tools` | `allowed-tools` | Keep as-is |
+| Missing `allowed-tools` | `allowed-tools` | Infer from content |
+
+## Command Conversion Rules
+
+### Source Pattern → Target Pattern
+
+| Source Style | Target Style |
+|-------------|-------------|
+| `# Title` + `## Phase N:` flat markdown | `<purpose>` + `<process>` with numbered `## N.` steps |
+| `## Implementation` + `### Phase N` | `<process>` with numbered steps, content preserved |
+| `## Overview` / `## Core Principle` | `<purpose>` (merge into 2-3 sentences) + keep details in steps |
+| `## Usage` with examples | Keep as-is inside `<process>` step 1 or before `<process>` |
+| `## Auto Mode` / `## Auto Mode Defaults` | `<auto_mode>` section |
+| `## Quick Reference` | Preserve as-is within appropriate section |
+| Inline `AskUserQuestion` calls | Preserve verbatim — these belong in commands |
+| `Agent()` / agent spawning calls | Preserve verbatim within process steps |
+| Banner displays (`━━━`) | Preserve verbatim |
+| Code blocks (```bash, ```javascript, etc.) | **Preserve exactly** — never modify code content |
+| Tables | **Preserve exactly** — never reformat table content |
+
+### Frontmatter Conversion
+
+| Source Field | Target Field | Transformation |
+|-------------|-------------|----------------|
+| `name` | `name` | Keep as-is |
+| `description` | `description` | Keep as-is |
+| `argument-hint` | `argument-hint` | Keep as-is |
+| `allowed-tools` | `allowed-tools` | Keep as-is |
+| Missing `allowed-tools` | `allowed-tools` | Infer from content (Read, Write, etc.) |
+
+### Section Wrapping
+
+Content that was under plain `##` headers gets wrapped in XML tags:
+
+```
+## Overview / ## Core Principle  → content moves to <purpose>
+## Process / ## Implementation  → content moves to <process>
+## Success Criteria             → content moves to <success_criteria>
+## Error Codes                  → preserve as-is (optional section)
+```
+
+**Everything else**: Wrap in appropriate GSD tag or keep as custom section inside `<process>`.
+
+### What to ADD (with TODO markers)
+
+| Missing Element | Add |
+|----------------|-----|
+| `<purpose>` | Extract from overview/description, mark `<!-- TODO: refine -->` if uncertain |
+| `<success_criteria>` | Generate from existing content, mark `<!-- TODO: verify -->` |
+| `<offer_next>` | Add skeleton with `<!-- TODO: fill next commands -->` |
+| Banners | Add before major transitions if missing |
+
+## Agent Conversion Rules
+
+### Source Pattern → Target Pattern
+
+| Source Style | Target Style |
+|-------------|-------------|
+| Plain prose role description | `<role>` with structured format |
+| `## Core Philosophy` / `## Principles` | `<philosophy>` |
+| `## Execution Process` / `## How to` | Domain section with descriptive name |
+| `## Quality Gates` / `## Standards` | `<quality_gate>` with checkbox format |
+| Flat numbered list of responsibilities | `<role>` core responsibilities bullet list |
+| `## Examples` section | Move examples INTO relevant domain sections |
+
+### Frontmatter Conversion
+
+| Source Field | Target Field | Transformation |
+|-------------|-------------|----------------|
+| `name` | `name` | Keep as-is |
+| `description` | `description` | Append "Spawned by /command orchestrator." if missing |
+| `color` | `color` | Keep as-is |
+| Missing `tools` | `tools` | Infer from content (Read, Write, Bash, etc.) |
+
+### Section Restructuring
+
+1. **`<role>` MUST be first** — gather identity content from wherever it appears
+2. **Add "Spawned by:"** if missing — infer from description or mark `<!-- TODO: specify spawner -->`
+3. **Add "Mandatory Initial Read"** block if missing
+4. **Rename generic sections**: `<rules>` → descriptive name based on content
+5. **Add `<output_contract>`** if missing — with TODO marker
+6. **Add `<quality_gate>`** if missing — with TODO marker
+
+### What NOT to Change
+
+- Code blocks inside sections — preserve exactly
+- Tables — preserve exactly
+- Concrete examples (good/bad comparisons) — preserve exactly
+- Shell commands — preserve exactly
+- Agent prompts — preserve exactly
+- Domain-specific terminology — preserve exactly
+
+## Batch Conversion
+
+For converting multiple files:
+
+```bash
+# List candidates
+ls .claude/commands/**/*.md .claude/agents/*.md
+
+# Convert one at a time, verify each
+/prompt-generator convert .claude/commands/issue/new.md
+/prompt-generator convert .claude/agents/universal-executor.md
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong |
+|-------------|----------------|
+| Rewriting code blocks | Content loss — code is sacred |
+| Summarizing verbose sections | Content loss — preserve verbatim |
+| Removing "redundant" content | User may depend on it |
+| Merging sections without inventory | May lose content silently |
+| Adding content beyond structural tags | Conversion adds structure, not content |
+| Skipping post-conversion line count | Cannot verify zero content loss |

.claude/skills/prompt-generator/templates/agent-md.md

@@ -0,0 +1,145 @@
+# Agent Template — Structural Reference
+
+Defines the structural pattern for generated **agent definition files**. The generator uses this as a guide to produce concrete, domain-specific content — NOT as a literal copy target.
+
+## Required Structure
+
+```markdown
+---
+name: {$NAME}
+description: {One-line purpose. Spawned by /command-name orchestrator.}
+tools: {Read, Write, Bash, Glob, Grep}
+color: {green|blue|yellow|red}  # optional
+---
+
+<role>
+You are a {role name}. You {primary action} {what you produce}.
+
+Spawned by:
+- `/{command}` orchestrator (standard mode)
+- `/{command} --flag` orchestrator (variant mode)
+
+Your job: {One sentence — what downstream consumers get from you.}
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
+to load every file listed there before performing any other actions. This is your
+primary context.
+
+**Core responsibilities:**
+- {Verb phrase — primary task}
+- {Verb phrase — secondary task}
+- {Verb phrase — quality assurance}
+- Return structured results to orchestrator
+</role>
+
+<philosophy>
+## {Guiding Principle Name}
+
+{Core beliefs — 3-5 bullet points}
+
+**Anti-patterns (delete if seen):**
+- {Anti-pattern 1}
+- {Anti-pattern 2}
+</philosophy>
+
+<{domain_section_1}>
+## {Domain Concept Name}
+
+{Rules, heuristics, decision tables for this aspect.}
+
+| {Condition} | {Action} |
+|-------------|----------|
+| ...         | ...      |
+
+{Concrete examples — good vs bad:}
+
+| TOO VAGUE | JUST RIGHT |
+|-----------|------------|
+| "..." | "..." |
+</{domain_section_1}>
+
+<{domain_section_2}>
+## {Another Domain Concept}
+
+{Format templates, structural rules, required fields.}
+
+Every {output unit} has {N} required fields:
+- **<field_1>:** {What it contains, why it matters}
+- **<field_2>:** {What it contains, why it matters}
+</{domain_section_2}>
+
+<output_contract>
+## Return Protocol
+
+Agent returns one of these markers to the orchestrator:
+
+### Success
+```
+## TASK COMPLETE
+
+{Structured output summary}
+{Artifact locations}
+```
+
+### Blocked
+```
+## TASK BLOCKED
+
+**Blocker:** {What's missing}
+**Need:** {What would unblock}
+```
+
+### Checkpoint
+```
+## CHECKPOINT REACHED
+
+**Question:** {Decision needed from user}
+**Options:**
+1. {Option A} — {effect}
+2. {Option B} — {effect}
+```
+</output_contract>
+
+<quality_gate>
+Before returning, verify:
+- [ ] {Check 1 — concrete, verifiable}
+- [ ] {Check 2 — concrete, verifiable}
+- [ ] {Check 3 — concrete, verifiable}
+- [ ] {Check 4 — concrete, verifiable}
+</quality_gate>
+```
+
+## Section Design Guidelines
+
+### Section Naming
+
+Name sections after the domain concept they cover:
+
+| Good | Bad |
+|------|-----|
+| `<task_breakdown>` | `<rules>` |
+| `<dependency_graph>` | `<guidelines>` |
+| `<code_style>` | `<misc>` |
+| `<review_dimensions>` | `<other>` |
+
+### Section Independence
+
+Each section owns ONE concern. Test: can you explain the section's scope in one sentence?
+
+| One Concern | Multiple Concerns (split it) |
+|-------------|------------------------------|
+| How to size tasks | How to size tasks AND how to order them |
+| Review criteria | Review criteria AND how to present results |
+| Error handling rules | Error handling AND logging AND monitoring |
+
+### Example Density
+
+Domain sections MUST include concrete examples. Minimum per section:
+
+| Section Type | Minimum Examples |
+|-------------|-----------------|
+| Rules/heuristics | 1 good-vs-bad table |
+| Format definitions | 1 complete template |
+| Decision logic | 1 routing table |
+| Quality criteria | 3+ checkbox items |

.claude/skills/prompt-generator/templates/command-md.md

@@ -0,0 +1,118 @@
+# Command Template — Structural Reference
+
+Defines the structural pattern for generated **command files**. The generator uses this as a guide to produce concrete, domain-specific content — NOT as a literal copy target.
+
+## Required Structure
+
+```markdown
+---
+name: {$NAME}
+description: {$DESCRIPTION}
+argument-hint: {$ARGUMENT_HINT}  # omit if empty
+allowed-tools: {tools}           # omit if unrestricted
+---
+
+<purpose>
+{2-3 sentences: what it does + when invoked + what it produces}
+</purpose>
+
+<required_reading>
+{@ references to files needed before execution}
+</required_reading>
+
+<process>
+
+## 1. Initialize
+
+{Load context, parse $ARGUMENTS, validate preconditions.}
+
+{Argument table:}
+| Flag/Arg | Required | Description |
+|----------|----------|-------------|
+| `$ARG1`  | Yes      | ...         |
+| `--flag` | No       | ...         |
+
+{Validation: missing required → error, invalid → error with usage hint.}
+
+## 2. {Domain Action}
+
+{Display banner:}
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SKILL ► ACTION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+{Core orchestration logic — file checks, state validation, conditional routing.}
+
+## 3. Spawn Agent (if applicable)
+
+{Construct prompt with <files_to_read>, <objective>, <output> blocks.}
+
+```javascript
+Agent({
+  subagent_type: "{agent-name}",
+  prompt: filled_prompt,
+  description: "{Verb} {target}",
+  run_in_background: false
+})
+```
+
+## 4. Handle Result
+
+{Route on agent return markers:}
+- `## TASK COMPLETE` → continue to next step
+- `## TASK BLOCKED` → display blocker, offer options
+- `## CHECKPOINT REACHED` → present to user, relay response
+
+## N. Present Status
+
+{Route to <offer_next>.}
+
+</process>
+
+<offer_next>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SKILL ► TASK COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**{Summary line}**
+
+{Status table or key-value pairs}
+
+## Next Up
+
+/{next-command} {args}
+
+**Also available:**
+- /{alt-command-1} — description
+- /{alt-command-2} — description
+</offer_next>
+
+<success_criteria>
+- [ ] {Precondition validated}
+- [ ] {Core action completed}
+- [ ] {Agent spawned and returned (if applicable)}
+- [ ] {Output artifact produced / effect applied}
+- [ ] {Status displayed to user}
+</success_criteria>
+```
+
+## Step Naming Conventions
+
+| Domain | Typical Steps |
+|--------|--------------|
+| Deploy/Release | Initialize, Validate Config, Run Deployment, Verify Health, Present Status |
+| CRUD | Initialize, Validate Entity, Persist Changes, Present Status |
+| Analysis | Initialize, Gather Context, Spawn Analyzer, Present Findings |
+| Multi-Agent | Initialize, Spawn Agent A, Handle A Result, Spawn Agent B, Revision Loop, Present Status |
+| Pipeline | Initialize, Stage 1, Handle Stage 1, Stage 2, Handle Stage 2, Present Status |
+
+## Content Quality Rules
+
+| Rule | Bad | Good |
+|------|-----|------|
+| No placeholders | `[Describe purpose]` | `Deploy to target environment with rollback on failure.` |
+| Concrete steps | `Handle the deployment` | `Run kubectl apply, wait for rollout, check health endpoint` |
+| Specific errors | `Error: invalid` | `Error: --env must be "prod" or "staging"` |
+| Verifiable criteria | `Works correctly` | `Health endpoint returns 200 within 30s` |

.claude/skills/skill-iter-tune/SKILL.md

@@ -0,0 +1,382 @@
+---
+name: skill-iter-tune
+description: Iterative skill tuning via execute-evaluate-improve feedback loop. Uses ccw cli Claude to execute skill, Gemini to evaluate quality, and Agent to apply improvements. Iterates until quality threshold or max iterations. Triggers on "skill iter tune", "iterative skill tuning", "tune skill".
+allowed-tools: Skill, Agent, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Skill Iter Tune
+
+Iterative skill refinement through execute-evaluate-improve feedback loops. Each iteration runs the skill via Claude, evaluates output via Gemini, and applies improvements via Agent.
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  Skill Iter Tune Orchestrator (SKILL.md)                                 │
+│  → Parse input → Setup workspace → Iteration Loop → Final Report         │
+└────────────────────────────┬─────────────────────────────────────────────┘
+                             │
+         ┌───────────────────┼───────────────────────────────────┐
+         ↓                   ↓                                   ↓
+    ┌──────────┐      ┌─────────────────────────────┐     ┌──────────┐
+    │ Phase 1  │      │  Iteration Loop (2→3→4)     │     │ Phase 5  │
+    │ Setup    │      │  ┌─────┐  ┌─────┐  ┌─────┐ │     │ Report   │
+    │          │─────→│  │ P2  │→ │ P3  │→ │ P4  │ │────→│          │
+    │ Backup + │      │  │Exec │  │Eval │  │Impr │ │     │ History  │
+    │ Init     │      │  └─────┘  └─────┘  └─────┘ │     │ Summary  │
+    └──────────┘      │       ↑               │     │     └──────────┘
+                      │       └───────────────┘     │
+                      │    (if score < threshold    │
+                      │     AND iter < max)         │
+                      └─────────────────────────────┘
+```
+
+### Chain Mode Extension
+
+```
+Chain Mode (execution_mode === "chain"):
+
+Phase 2 runs per-skill in chain_order:
+  Skill A → ccw cli → artifacts/skill-A/
+       ↓ (artifacts as input)
+  Skill B → ccw cli → artifacts/skill-B/
+       ↓ (artifacts as input)
+  Skill C → ccw cli → artifacts/skill-C/
+
+Phase 3 evaluates entire chain output + per-skill scores
+Phase 4 improves weakest skill(s) in chain
+```
+
+## Key Design Principles
+
+1. **Iteration Loop**: Phases 2-3-4 repeat until quality threshold, max iterations, or convergence
+2. **Two-Tool Pipeline**: Claude (write/execute) + Gemini (analyze/evaluate) = complementary perspectives
+3. **Pure Orchestrator**: SKILL.md coordinates only — execution detail lives in phase files
+4. **Progressive Phase Loading**: Phase docs read only when that phase executes
+5. **Skill Versioning**: Each iteration snapshots skill state before execution
+6. **Convergence Detection**: Stop early if score stalls (no improvement in 2 consecutive iterations)
+
+## Interactive Preference Collection
+
+```javascript
+// ★ Auto mode detection
+const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)
+
+if (autoYes) {
+  workflowPreferences = {
+    autoYes: true,
+    maxIterations: 5,
+    qualityThreshold: 80,
+    executionMode: 'single'
+  }
+} else {
+  const prefResponse = AskUserQuestion({
+    questions: [
+      {
+        question: "选择迭代调优配置：",
+        header: "Tune Config",
+        multiSelect: false,
+        options: [
+          { label: "Quick (3 iter, 70)", description: "快速迭代，适合小幅改进" },
+          { label: "Standard (5 iter, 80) (Recommended)", description: "平衡方案，适合多数场景" },
+          { label: "Thorough (8 iter, 90)", description: "深度优化，适合生产级 skill" }
+        ]
+      }
+    ]
+  })
+
+  const configMap = {
+    "Quick": { maxIterations: 3, qualityThreshold: 70 },
+    "Standard": { maxIterations: 5, qualityThreshold: 80 },
+    "Thorough": { maxIterations: 8, qualityThreshold: 90 }
+  }
+  const selected = Object.keys(configMap).find(k =>
+    prefResponse["Tune Config"].startsWith(k)
+  ) || "Standard"
+  workflowPreferences = { autoYes: false, ...configMap[selected] }
+
+  // ★ Mode selection: chain vs single
+  const modeResponse = AskUserQuestion({
+    questions: [{
+      question: "选择调优模式：",
+      header: "Tune Mode",
+      multiSelect: false,
+      options: [
+        { label: "Single Skill (Recommended)", description: "独立调优每个 skill，适合单一 skill 优化" },
+        { label: "Skill Chain", description: "按链序执行，前一个 skill 的产出作为后一个的输入" }
+      ]
+    }]
+  });
+  workflowPreferences.executionMode = modeResponse["Tune Mode"].startsWith("Skill Chain")
+    ? "chain" : "single";
+}
+```
+
+## Input Processing
+
+```
+$ARGUMENTS → Parse:
+  ├─ Skill path(s): first arg, comma-separated for multiple
+  │   e.g., ".claude/skills/my-skill" or "my-skill" (auto-prefixed)
+  │   Chain mode: order preserved as chain_order
+  ├─ Test scenario: --scenario "description" or remaining text
+  └─ Flags: --max-iterations=N, --threshold=N, -y/--yes
+```
+
+## Execution Flow
+
+> **⚠️ COMPACT DIRECTIVE**: Context compression MUST check TodoWrite phase status.
+> The phase currently marked `in_progress` is the active execution phase — preserve its FULL content.
+> Only compress phases marked `completed` or `pending`.
+
+### Phase 1: Setup (one-time)
+
+Read and execute: `Ref: phases/01-setup.md`
+
+- Parse skill paths, validate existence
+- Create workspace at `.workflow/.scratchpad/skill-iter-tune-{ts}/`
+- Backup original skill files
+- Initialize iteration-state.json
+
+Output: `workDir`, `targetSkills[]`, `testScenario`, initialized state
+
+### Iteration Loop
+
+```javascript
+// Orchestrator iteration loop
+while (true) {
+  // Increment iteration
+  state.current_iteration++;
+  state.iterations.push({
+    round: state.current_iteration,
+    status: 'pending',
+    execution: null,
+    evaluation: null,
+    improvement: null
+  });
+
+  // Update TodoWrite
+  TaskUpdate(iterationTask, {
+    subject: `Iteration ${state.current_iteration}/${state.max_iterations}`,
+    status: 'in_progress',
+    activeForm: `Running iteration ${state.current_iteration}`
+  });
+
+  // === Phase 2: Execute ===
+  // Read: phases/02-execute.md
+  // Single mode: one ccw cli call for all skills
+  // Chain mode: sequential ccw cli per skill in chain_order, passing artifacts
+  // Snapshot skill → construct prompt → ccw cli --tool claude --mode write
+  // Collect artifacts
+
+  // === Phase 3: Evaluate ===
+  // Read: phases/03-evaluate.md
+  // Construct eval prompt → ccw cli --tool gemini --mode analysis
+  // Parse score → write iteration-N-eval.md → check termination
+
+  // Check termination
+  if (shouldTerminate(state)) {
+    break;  // → Phase 5
+  }
+
+  // === Phase 4: Improve ===
+  // Read: phases/04-improve.md
+  // Agent applies suggestions → write iteration-N-changes.md
+
+  // Update TodoWrite with score
+  // Continue loop
+}
+```
+
+### Phase 2: Execute Skill (per iteration)
+
+Read and execute: `Ref: phases/02-execute.md`
+
+- Snapshot skill → `iteration-{N}/skill-snapshot/`
+- Build execution prompt from skill content + test scenario
+- Execute: `ccw cli -p "..." --tool claude --mode write --cd "${iterDir}/artifacts"`
+- Collect artifacts
+
+### Phase 3: Evaluate Quality (per iteration)
+
+Read and execute: `Ref: phases/03-evaluate.md`
+
+- Build evaluation prompt with skill + artifacts + criteria + history
+- Execute: `ccw cli -p "..." --tool gemini --mode analysis`
+- Parse 5-dimension score (Clarity, Completeness, Correctness, Effectiveness, Efficiency)
+- Write `iteration-{N}-eval.md`
+- Check termination: score >= threshold | iter >= max | convergence | error limit
+
+### Phase 4: Apply Improvements (per iteration, skipped on termination)
+
+Read and execute: `Ref: phases/04-improve.md`
+
+- Read evaluation suggestions
+- Launch general-purpose Agent to apply changes
+- Write `iteration-{N}-changes.md`
+- Update state
+
+### Phase 5: Final Report (one-time)
+
+Read and execute: `Ref: phases/05-report.md`
+
+- Generate comprehensive report with score progression table
+- Write `final-report.md`
+- Display summary to user
+
+**Phase Reference Documents** (read on-demand when phase executes):
+
+| Phase | Document | Purpose | Compact |
+|-------|----------|---------|---------|
+| 1 | [phases/01-setup.md](phases/01-setup.md) | Initialize workspace and state | TodoWrite 驱动 |
+| 2 | [phases/02-execute.md](phases/02-execute.md) | Execute skill via ccw cli Claude | TodoWrite 驱动 + 🔄 sentinel |
+| 3 | [phases/03-evaluate.md](phases/03-evaluate.md) | Evaluate via ccw cli Gemini | TodoWrite 驱动 + 🔄 sentinel |
+| 4 | [phases/04-improve.md](phases/04-improve.md) | Apply improvements via Agent | TodoWrite 驱动 + 🔄 sentinel |
+| 5 | [phases/05-report.md](phases/05-report.md) | Generate final report | TodoWrite 驱动 |
+
+**Compact Rules**:
+1. **TodoWrite `in_progress`** → 保留完整内容，禁止压缩
+2. **TodoWrite `completed`** → 可压缩为摘要
+3. **🔄 sentinel fallback** → 若 compact 后仅存 sentinel 而无完整 Step 协议，立即 `Read()` 恢复
+
+## Core Rules
+
+1. **Start Immediately**: First action is preference collection → Phase 1 setup
+2. **Progressive Loading**: Read phase doc ONLY when that phase is about to execute
+3. **Snapshot Before Execute**: Always snapshot skill state before each iteration
+4. **Background CLI**: ccw cli runs in background, wait for hook callback before proceeding
+5. **Parse Every Output**: Extract structured JSON from CLI outputs for state updates
+6. **DO NOT STOP**: Continuous iteration until termination condition met
+7. **Single State Source**: `iteration-state.json` is the only source of truth
+
+## Data Flow
+
+```
+User Input (skill paths + test scenario)
+    ↓ (+ execution_mode + chain_order if chain mode)
+    ↓
+Phase 1: Setup
+    ↓ workDir, targetSkills[], testScenario, iteration-state.json
+    ↓
+┌─→ Phase 2: Execute (ccw cli claude)
+│   ↓ artifacts/ (skill execution output)
+│   ↓
+│   Phase 3: Evaluate (ccw cli gemini)
+│   ↓ score, dimensions[], suggestions[], iteration-N-eval.md
+│   ↓
+│   [Terminate?]─── YES ──→ Phase 5: Report → final-report.md
+│   ↓ NO
+│   ↓
+│   Phase 4: Improve (Agent)
+│   ↓ modified skill files, iteration-N-changes.md
+│   ↓
+└───┘ next iteration
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initial state
+TaskCreate({ subject: "Phase 1: Setup workspace", activeForm: "Setting up workspace" })
+TaskCreate({ subject: "Iteration Loop", activeForm: "Running iterations" })
+TaskCreate({ subject: "Phase 5: Final Report", activeForm: "Generating report" })
+
+// Chain mode: create per-skill tracking tasks
+if (state.execution_mode === 'chain') {
+  for (const skillName of state.chain_order) {
+    TaskCreate({
+      subject: `Chain: ${skillName}`,
+      activeForm: `Tracking ${skillName}`,
+      description: `Skill chain member position ${state.chain_order.indexOf(skillName) + 1}`
+    })
+  }
+}
+
+// During iteration N
+// Single mode: one score per iteration (existing behavior)
+// Chain mode: per-skill status updates
+if (state.execution_mode === 'chain') {
+  // After each skill executes in Phase 2:
+  TaskUpdate(chainSkillTask, {
+    subject: `Chain: ${skillName} — Iter ${N} executed`,
+    activeForm: `${skillName} iteration ${N}`
+  })
+  // After Phase 3 evaluates:
+  TaskUpdate(chainSkillTask, {
+    subject: `Chain: ${skillName} — Score ${chainScores[skillName]}/100`,
+    activeForm: `${skillName} scored`
+  })
+} else {
+  // Single mode (existing)
+  TaskCreate({
+    subject: `Iteration ${N}: Score ${score}/100`,
+    activeForm: `Iteration ${N} complete`,
+    description: `Strengths: ... | Weaknesses: ... | Suggestions: ${count}`
+  })
+}
+
+// Completed — collapse
+TaskUpdate(iterLoop, {
+  subject: `Iteration Loop (${totalIters} iters, final: ${finalScore})`,
+  status: 'completed'
+})
+```
+
+## Termination Logic
+
+```javascript
+function shouldTerminate(state) {
+  // 1. Quality threshold met
+  if (state.latest_score >= state.quality_threshold) {
+    return { terminate: true, reason: 'quality_threshold_met' };
+  }
+  // 2. Max iterations reached
+  if (state.current_iteration >= state.max_iterations) {
+    return { terminate: true, reason: 'max_iterations_reached' };
+  }
+  // 3. Convergence: ≤2 points improvement over last 2 iterations
+  if (state.score_trend.length >= 3) {
+    const last3 = state.score_trend.slice(-3);
+    if (last3[2] - last3[0] <= 2) {
+      state.converged = true;
+      return { terminate: true, reason: 'convergence_detected' };
+    }
+  }
+  // 4. Error limit
+  if (state.error_count >= state.max_errors) {
+    return { terminate: true, reason: 'error_limit_reached' };
+  }
+  return { terminate: false };
+}
+```
+
+## Error Handling
+
+| Phase | Error | Recovery |
+|-------|-------|----------|
+| 2: Execute | CLI timeout/crash | Retry once with simplified prompt, then skip |
+| 3: Evaluate | CLI fails | Retry once, then use score 50 with warning |
+| 3: Evaluate | JSON parse fails | Extract score heuristically, save raw output |
+| 4: Improve | Agent fails | Rollback from `iteration-{N}/skill-snapshot/` |
+| Any | 3+ consecutive errors | Terminate with error report |
+
+**Error Budget**: Each phase gets 1 retry. 3 consecutive failed iterations triggers termination.
+
+## Coordinator Checklist
+
+### Pre-Phase Actions
+- [ ] Read iteration-state.json for current state
+- [ ] Verify workspace directory exists
+- [ ] Check error count hasn't exceeded limit
+
+### Per-Iteration Actions
+- [ ] Increment current_iteration in state
+- [ ] Create iteration-{N} subdirectory
+- [ ] Update TodoWrite with iteration status
+- [ ] After Phase 3: check termination before Phase 4
+- [ ] After Phase 4: write state, proceed to next iteration
+
+### Post-Workflow Actions
+- [ ] Execute Phase 5 (Report)
+- [ ] Display final summary to user
+- [ ] Update all TodoWrite tasks to completed

.claude/skills/skill-iter-tune/phases/01-setup.md

@@ -0,0 +1,144 @@
+# Phase 1: Setup
+
+Initialize workspace, backup skills, parse inputs.
+
+## Objective
+
+- Parse skill path(s) and test scenario from user input
+- Validate all skill paths exist and contain SKILL.md
+- Create isolated workspace directory structure
+- Backup original skill files
+- Initialize iteration-state.json
+
+## Execution
+
+### Step 1.1: Parse Input
+
+Parse `$ARGUMENTS` to extract skill paths and test scenario.
+
+```javascript
+// Parse skill paths (first argument or comma-separated)
+const args = $ARGUMENTS.trim();
+const pathMatch = args.match(/^([^\s]+)/);
+const rawPaths = pathMatch ? pathMatch[1].split(',') : [];
+
+// Parse test scenario
+const scenarioMatch = args.match(/(?:--scenario|--test)\s+"([^"]+)"/);
+const scenarioText = scenarioMatch ? scenarioMatch[1] : args.replace(rawPaths.join(','), '').trim();
+
+// Record chain order (preserves input order for chain mode)
+const chainOrder = rawPaths.map(p => p.startsWith('.claude/') ? p.split('/').pop() : p);
+
+// If no scenario, ask user
+if (!scenarioText) {
+  const response = AskUserQuestion({
+    questions: [{
+      question: "Please describe the test scenario for evaluating this skill:",
+      header: "Test Scenario",
+      multiSelect: false,
+      options: [
+        { label: "General quality test", description: "Evaluate overall skill quality with a generic task" },
+        { label: "Specific scenario", description: "I'll describe a specific test case" }
+      ]
+    }]
+  });
+  // Use response to construct testScenario
+}
+```
+
+### Step 1.2: Validate Skill Paths
+
+```javascript
+const targetSkills = [];
+for (const rawPath of rawPaths) {
+  const skillPath = rawPath.startsWith('.claude/') ? rawPath : `.claude/skills/${rawPath}`;
+
+  // Validate SKILL.md exists
+  const skillFiles = Glob(`${skillPath}/SKILL.md`);
+  if (skillFiles.length === 0) {
+    throw new Error(`Skill not found at: ${skillPath} -- SKILL.md missing`);
+  }
+
+  // Collect all skill files
+  const allFiles = Glob(`${skillPath}/**/*.md`);
+  targetSkills.push({
+    name: skillPath.split('/').pop(),
+    path: skillPath,
+    files: allFiles.map(f => f.replace(skillPath + '/', '')),
+    primary_file: 'SKILL.md'
+  });
+}
+```
+
+### Step 1.3: Create Workspace
+
+```javascript
+const ts = Date.now();
+const workDir = `.workflow/.scratchpad/skill-iter-tune-${ts}`;
+
+Bash(`mkdir -p "${workDir}/backups" "${workDir}/iterations"`);
+```
+
+### Step 1.4: Backup Original Skills
+
+```javascript
+for (const skill of targetSkills) {
+  Bash(`cp -r "${skill.path}" "${workDir}/backups/${skill.name}"`);
+}
+```
+
+### Step 1.5: Initialize State
+
+Write `iteration-state.json` with initial state:
+
+```javascript
+const initialState = {
+  status: 'running',
+  started_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+  target_skills: targetSkills,
+  test_scenario: {
+    description: scenarioText,
+    // Parse --requirements and --input-args from $ARGUMENTS if provided
+    // e.g., --requirements "clear output,no errors" --input-args "my-skill --scenario test"
+    requirements: parseListArg(args, '--requirements') || [],
+    input_args: parseStringArg(args, '--input-args') || '',
+    success_criteria: parseStringArg(args, '--success-criteria') || 'Produces correct, high-quality output'
+  },
+  execution_mode: workflowPreferences.executionMode || 'single',
+  chain_order: workflowPreferences.executionMode === 'chain'
+    ? targetSkills.map(s => s.name)
+    : [],
+  current_iteration: 0,
+  max_iterations: workflowPreferences.maxIterations,
+  quality_threshold: workflowPreferences.qualityThreshold,
+  latest_score: 0,
+  score_trend: [],
+  converged: false,
+  iterations: [],
+  errors: [],
+  error_count: 0,
+  max_errors: 3,
+  work_dir: workDir,
+  backup_dir: `${workDir}/backups`
+};
+
+Write(`${workDir}/iteration-state.json`, JSON.stringify(initialState, null, 2));
+
+// Chain mode: create per-skill tracking tasks
+if (initialState.execution_mode === 'chain') {
+  for (const skill of targetSkills) {
+    TaskCreate({
+      subject: `Chain: ${skill.name}`,
+      activeForm: `Tracking ${skill.name}`,
+      description: `Skill chain member: ${skill.path} | Position: ${targetSkills.indexOf(skill) + 1}/${targetSkills.length}`
+    });
+  }
+}
+```
+
+## Output
+
+- **Variables**: `workDir`, `targetSkills[]`, `testScenario`, `chainOrder` (chain mode)
+- **Files**: `iteration-state.json`, `backups/` directory with skill copies
+- **TodoWrite**: Mark Phase 1 completed, start Iteration Loop. Chain mode: per-skill tracking tasks created

.claude/skills/skill-iter-tune/phases/02-execute.md

@@ -0,0 +1,292 @@
+# Phase 2: Execute Skill
+
+> **COMPACT SENTINEL [Phase 2: Execute]**
+> This phase contains 4 execution steps (Step 2.1 -- 2.4).
+> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
+> Recovery: `Read("phases/02-execute.md")`
+
+Execute the target skill against the test scenario using `ccw cli --tool claude --mode write`. Claude receives the full skill definition and simulates producing its expected output artifacts.
+
+## Objective
+
+- Snapshot current skill version before execution
+- Construct execution prompt with full skill content + test scenario
+- Execute via ccw cli Claude
+- Collect output artifacts
+
+## Execution
+
+### Step 2.1: Snapshot Current Skill
+
+```javascript
+const N = state.current_iteration;
+const iterDir = `${state.work_dir}/iterations/iteration-${N}`;
+Bash(`mkdir -p "${iterDir}/skill-snapshot" "${iterDir}/artifacts"`);
+
+// Chain mode: create per-skill artifact directories
+if (state.execution_mode === 'chain') {
+  for (const skillName of state.chain_order) {
+    Bash(`mkdir -p "${iterDir}/artifacts/${skillName}"`);
+  }
+}
+
+// Snapshot current skill state (so we can compare/rollback)
+for (const skill of state.target_skills) {
+  Bash(`cp -r "${skill.path}" "${iterDir}/skill-snapshot/${skill.name}"`);
+}
+```
+
+### Step 2.2: Construct Execution Prompt (Single Mode)
+
+Read the execute-prompt template and substitute variables.
+
+> Skip to Step 2.2b if `state.execution_mode === 'chain'`.
+
+```javascript
+// Ref: templates/execute-prompt.md
+
+// Build skillContent by reading only executable skill files (SKILL.md, phases/, specs/)
+// Exclude README.md, docs/, and other non-executable files to save tokens
+const skillContent = state.target_skills.map(skill => {
+  const skillMd = Read(`${skill.path}/SKILL.md`);
+  const phaseFiles = Glob(`${skill.path}/phases/*.md`).sort().map(f => ({
+    relativePath: f.replace(skill.path + '/', ''),
+    content: Read(f)
+  }));
+  const specFiles = Glob(`${skill.path}/specs/*.md`).map(f => ({
+    relativePath: f.replace(skill.path + '/', ''),
+    content: Read(f)
+  }));
+
+  return `### File: SKILL.md\n${skillMd}\n\n` +
+    phaseFiles.map(f => `### File: ${f.relativePath}\n${f.content}`).join('\n\n') +
+    (specFiles.length > 0 ? '\n\n' + specFiles.map(f => `### File: ${f.relativePath}\n${f.content}`).join('\n\n') : '');
+}).join('\n\n---\n\n');
+
+// Construct full prompt using template
+const executePrompt = `PURPOSE: Simulate executing the following workflow skill against a test scenario. Produce all expected output artifacts as if the skill were invoked with the given input.
+
+SKILL CONTENT:
+${skillContent}
+
+TEST SCENARIO:
+Description: ${state.test_scenario.description}
+Input Arguments: ${state.test_scenario.input_args}
+Requirements: ${state.test_scenario.requirements.join('; ')}
+Success Criteria: ${state.test_scenario.success_criteria}
+
+TASK:
+1. Study the complete skill structure (SKILL.md + all phase files)
+2. Follow the skill execution flow sequentially
+3. For each phase, produce the artifacts that phase would generate
+4. Write all output artifacts to the current working directory
+5. Create a manifest.json listing all produced artifacts
+
+MODE: write
+CONTEXT: @**/*
+EXPECTED: All artifacts written to disk + manifest.json
+CONSTRAINTS: Follow skill flow exactly, produce realistic output, not placeholders`;
+```
+
+### Step 2.3: Execute via ccw cli
+
+> **CHECKPOINT**: Before executing CLI, verify:
+> 1. This phase is TodoWrite `in_progress`
+> 2. `iterDir/artifacts/` directory exists
+> 3. Prompt is properly escaped
+
+```javascript
+function escapeForShell(str) {
+  return str.replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`');
+}
+
+const cliCommand = `ccw cli -p "${escapeForShell(executePrompt)}" --tool claude --mode write --cd "${iterDir}/artifacts"`;
+
+// Execute in background, wait for hook callback
+Bash({
+  command: cliCommand,
+  run_in_background: true,
+  timeout: 600000  // 10 minutes max
+});
+
+// STOP HERE -- wait for hook callback to resume
+// After callback, verify artifacts were produced
+```
+
+### Step 2.2b: Chain Execution Path
+
+> Skip this step if `state.execution_mode === 'single'`.
+
+In chain mode, execute each skill sequentially. Each skill receives the previous skill's artifacts as input context.
+
+```javascript
+// Chain execution: iterate through chain_order
+let previousArtifacts = '';  // Accumulates upstream output
+
+for (let i = 0; i < state.chain_order.length; i++) {
+  const skillName = state.chain_order[i];
+  const skill = state.target_skills.find(s => s.name === skillName);
+  const skillArtifactDir = `${iterDir}/artifacts/${skillName}`;
+
+  // Build this skill's content
+  const skillMd = Read(`${skill.path}/SKILL.md`);
+  const phaseFiles = Glob(`${skill.path}/phases/*.md`).sort().map(f => ({
+    relativePath: f.replace(skill.path + '/', ''),
+    content: Read(f)
+  }));
+  const specFiles = Glob(`${skill.path}/specs/*.md`).map(f => ({
+    relativePath: f.replace(skill.path + '/', ''),
+    content: Read(f)
+  }));
+
+  const singleSkillContent = `### File: SKILL.md\n${skillMd}\n\n` +
+    phaseFiles.map(f => `### File: ${f.relativePath}\n${f.content}`).join('\n\n') +
+    (specFiles.length > 0 ? '\n\n' + specFiles.map(f => `### File: ${f.relativePath}\n${f.content}`).join('\n\n') : '');
+
+  // Build chain context from previous skill's artifacts
+  const chainInputContext = previousArtifacts
+    ? `\nPREVIOUS CHAIN OUTPUT (from upstream skill "${state.chain_order[i - 1]}"):\n${previousArtifacts}\n\nIMPORTANT: Use the above output as input context for this skill's execution.\n`
+    : '';
+
+  // Construct per-skill execution prompt
+  // Ref: templates/execute-prompt.md
+  const chainPrompt = `PURPOSE: Simulate executing the following workflow skill against a test scenario. Produce all expected output artifacts.
+
+SKILL CONTENT (${skillName} — chain position ${i + 1}/${state.chain_order.length}):
+${singleSkillContent}
+${chainInputContext}
+TEST SCENARIO:
+Description: ${state.test_scenario.description}
+Input Arguments: ${state.test_scenario.input_args}
+Requirements: ${state.test_scenario.requirements.join('; ')}
+Success Criteria: ${state.test_scenario.success_criteria}
+
+TASK:
+1. Study the complete skill structure
+2. Follow the skill execution flow sequentially
+3. Produce all expected artifacts
+4. Write output to the current working directory
+5. Create manifest.json listing all produced artifacts
+
+MODE: write
+CONTEXT: @**/*
+CONSTRAINTS: Follow skill flow exactly, produce realistic output`;
+
+  function escapeForShell(str) {
+    return str.replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`');
+  }
+
+  const cliCommand = `ccw cli -p "${escapeForShell(chainPrompt)}" --tool claude --mode write --cd "${skillArtifactDir}"`;
+
+  // Execute in background
+  Bash({
+    command: cliCommand,
+    run_in_background: true,
+    timeout: 600000
+  });
+
+  // STOP -- wait for hook callback
+
+  // After callback: collect artifacts for next skill in chain
+  const artifacts = Glob(`${skillArtifactDir}/**/*`);
+  const skillSuccess = artifacts.length > 0;
+
+  if (skillSuccess) {
+    previousArtifacts = artifacts.slice(0, 10).map(f => {
+      const relPath = f.replace(skillArtifactDir + '/', '');
+      const content = Read(f, { limit: 100 });
+      return `--- ${relPath} ---\n${content}`;
+    }).join('\n\n');
+  } else {
+    // Mid-chain failure: keep previous artifacts for downstream skills
+    // Log warning but continue chain — downstream skills receive last successful output
+    state.errors.push({
+      phase: 'execute',
+      message: `Chain skill "${skillName}" (position ${i + 1}) produced no artifacts. Downstream skills will receive upstream output from "${state.chain_order[i - 1] || 'none'}" instead.`,
+      timestamp: new Date().toISOString()
+    });
+    state.error_count++;
+    // previousArtifacts remains from last successful skill (or empty if first)
+  }
+
+  // Update per-skill TodoWrite
+  // TaskUpdate chain skill task with execution status
+
+  // Record per-skill execution
+  if (!state.iterations[N - 1].execution.chain_executions) {
+    state.iterations[N - 1].execution.chain_executions = [];
+  }
+  state.iterations[N - 1].execution.chain_executions.push({
+    skill_name: skillName,
+    cli_command: cliCommand,
+    artifacts_dir: skillArtifactDir,
+    success: skillSuccess
+  });
+
+  // Check error budget: abort chain if too many consecutive failures
+  if (state.error_count >= 3) {
+    state.errors.push({
+      phase: 'execute',
+      message: `Chain execution aborted at skill "${skillName}" — error limit reached (${state.error_count} errors).`,
+      timestamp: new Date().toISOString()
+    });
+    break;
+  }
+}
+```
+
+### Step 2.4: Collect Artifacts
+
+After CLI completes (hook callback received):
+
+```javascript
+// List produced artifacts
+const artifactFiles = Glob(`${iterDir}/artifacts/**/*`);
+
+// Chain mode: check per-skill artifacts
+if (state.execution_mode === 'chain') {
+  const chainSuccess = state.iterations[N - 1].execution.chain_executions?.every(e => e.success) ?? false;
+  state.iterations[N - 1].execution.success = chainSuccess;
+  state.iterations[N - 1].execution.artifacts_dir = `${iterDir}/artifacts`;
+} else {
+
+if (artifactFiles.length === 0) {
+  // Execution produced nothing -- record error
+  state.iterations[N - 1].execution = {
+    cli_command: cliCommand,
+    started_at: new Date().toISOString(),
+    completed_at: new Date().toISOString(),
+    artifacts_dir: `${iterDir}/artifacts`,
+    success: false
+  };
+  state.error_count++;
+  // Continue to Phase 3 anyway -- Gemini can evaluate the skill even without artifacts
+} else {
+  state.iterations[N - 1].execution = {
+    cli_command: cliCommand,
+    started_at: new Date().toISOString(),
+    completed_at: new Date().toISOString(),
+    artifacts_dir: `${iterDir}/artifacts`,
+    success: true
+  };
+}
+
+} // end single mode branch
+
+// Update state
+Write(`${state.work_dir}/iteration-state.json`, JSON.stringify(state, null, 2));
+```
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| CLI timeout (10min) | Record failure, continue to Phase 3 without artifacts |
+| CLI crash | Retry once with simplified prompt (SKILL.md only, no phase files) |
+| No artifacts produced | Continue to Phase 3, evaluation focuses on skill definition quality |
+
+## Output
+
+- **Files**: `iteration-{N}/skill-snapshot/`, `iteration-{N}/artifacts/`
+- **State**: `iterations[N-1].execution` updated
+- **Next**: Phase 3 (Evaluate)

.claude/skills/skill-iter-tune/phases/03-evaluate.md

@@ -0,0 +1,312 @@
+# Phase 3: Evaluate Quality
+
+> **COMPACT SENTINEL [Phase 3: Evaluate]**
+> This phase contains 5 execution steps (Step 3.1 -- 3.5).
+> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
+> Recovery: `Read("phases/03-evaluate.md")`
+
+Evaluate skill quality using `ccw cli --tool gemini --mode analysis`. Gemini scores the skill across 5 dimensions and provides improvement suggestions.
+
+## Objective
+
+- Construct evaluation prompt with skill + artifacts + criteria
+- Execute via ccw cli Gemini
+- Parse multi-dimensional score
+- Write iteration-{N}-eval.md
+- Check termination conditions
+
+## Execution
+
+### Step 3.1: Prepare Evaluation Context
+
+```javascript
+const N = state.current_iteration;
+const iterDir = `${state.work_dir}/iterations/iteration-${N}`;
+
+// Read evaluation criteria
+// Ref: specs/evaluation-criteria.md
+const evaluationCriteria = Read('.claude/skills/skill-iter-tune/specs/evaluation-criteria.md');
+
+// Build skillContent (same pattern as Phase 02 — only executable files)
+const skillContent = state.target_skills.map(skill => {
+  const skillMd = Read(`${skill.path}/SKILL.md`);
+  const phaseFiles = Glob(`${skill.path}/phases/*.md`).sort().map(f => ({
+    relativePath: f.replace(skill.path + '/', ''),
+    content: Read(f)
+  }));
+  const specFiles = Glob(`${skill.path}/specs/*.md`).map(f => ({
+    relativePath: f.replace(skill.path + '/', ''),
+    content: Read(f)
+  }));
+  return `### File: SKILL.md\n${skillMd}\n\n` +
+    phaseFiles.map(f => `### File: ${f.relativePath}\n${f.content}`).join('\n\n') +
+    (specFiles.length > 0 ? '\n\n' + specFiles.map(f => `### File: ${f.relativePath}\n${f.content}`).join('\n\n') : '');
+}).join('\n\n---\n\n');
+
+// Build artifacts summary
+let artifactsSummary = 'No artifacts produced (execution may have failed)';
+
+if (state.execution_mode === 'chain') {
+  // Chain mode: group artifacts by skill
+  const chainSummaries = state.chain_order.map(skillName => {
+    const skillArtifactDir = `${iterDir}/artifacts/${skillName}`;
+    const files = Glob(`${skillArtifactDir}/**/*`);
+    if (files.length === 0) return `### ${skillName} (no artifacts)`;
+    const filesSummary = files.map(f => {
+      const relPath = f.replace(`${skillArtifactDir}/`, '');
+      const content = Read(f, { limit: 200 });
+      return `--- ${relPath} ---\n${content}`;
+    }).join('\n\n');
+    return `### ${skillName} (chain position ${state.chain_order.indexOf(skillName) + 1})\n${filesSummary}`;
+  });
+  artifactsSummary = chainSummaries.join('\n\n---\n\n');
+} else {
+  // Single mode (existing)
+  const artifactFiles = Glob(`${iterDir}/artifacts/**/*`);
+  if (artifactFiles.length > 0) {
+    artifactsSummary = artifactFiles.map(f => {
+      const relPath = f.replace(`${iterDir}/artifacts/`, '');
+      const content = Read(f, { limit: 200 });
+      return `--- ${relPath} ---\n${content}`;
+    }).join('\n\n');
+  }
+}
+
+// Build previous evaluation context
+const previousEvalContext = state.iterations.filter(i => i.evaluation).length > 0
+  ? `PREVIOUS ITERATIONS:\n` + state.iterations.filter(i => i.evaluation).map(iter =>
+    `Iteration ${iter.round}: Score ${iter.evaluation.score}\n` +
+    `  Applied: ${iter.improvement?.changes_applied?.map(c => c.summary).join('; ') || 'none'}\n` +
+    `  Weaknesses: ${iter.evaluation.weaknesses?.slice(0, 3).join('; ') || 'none'}`
+  ).join('\n') + '\nIMPORTANT: Focus on NEW issues not yet addressed.'
+  : '';
+```
+
+### Step 3.2: Construct Evaluation Prompt
+
+```javascript
+// Ref: templates/eval-prompt.md
+const evalPrompt = `PURPOSE: Evaluate the quality of a workflow skill by examining its definition and produced artifacts.
+
+SKILL DEFINITION:
+${skillContent}
+
+TEST SCENARIO:
+${state.test_scenario.description}
+Requirements: ${state.test_scenario.requirements.join('; ')}
+Success Criteria: ${state.test_scenario.success_criteria}
+
+ARTIFACTS PRODUCED:
+${artifactsSummary}
+
+EVALUATION CRITERIA:
+${evaluationCriteria}
+
+${previousEvalContext}
+
+${state.execution_mode === 'chain' ? `
+CHAIN CONTEXT:
+This skill chain contains ${state.chain_order.length} skills executed in order:
+${state.chain_order.map((s, i) => `${i+1}. ${s}`).join('\n')}
+Current evaluation covers the entire chain output.
+Please provide per-skill quality scores in an additional "chain_scores" field: { "${state.chain_order[0]}": <score>, ... }
+` : ''}
+
+TASK:
+1. Score each dimension (Clarity 0.20, Completeness 0.25, Correctness 0.25, Effectiveness 0.20, Efficiency 0.10) on 0-100
+2. Calculate weighted composite score
+3. List top 3 strengths
+4. List top 3-5 weaknesses with file:section references
+5. Provide 3-5 prioritized improvement suggestions with concrete changes
+
+EXPECTED OUTPUT (strict JSON, no markdown):
+{
+  "composite_score": <0-100>,
+  "dimensions": [
+    {"name":"Clarity","id":"clarity","score":<0-100>,"weight":0.20,"feedback":"..."},
+    {"name":"Completeness","id":"completeness","score":<0-100>,"weight":0.25,"feedback":"..."},
+    {"name":"Correctness","id":"correctness","score":<0-100>,"weight":0.25,"feedback":"..."},
+    {"name":"Effectiveness","id":"effectiveness","score":<0-100>,"weight":0.20,"feedback":"..."},
+    {"name":"Efficiency","id":"efficiency","score":<0-100>,"weight":0.10,"feedback":"..."}
+  ],
+  "strengths": ["...", "...", "..."],
+  "weaknesses": ["...with file:section ref...", "..."],
+  "suggestions": [
+    {"priority":"high|medium|low","target_file":"...","description":"...","rationale":"...","code_snippet":"..."}
+  ]
+}
+
+CONSTRAINTS: Be rigorous, reference exact files, focus on highest-impact changes, output ONLY JSON`;
+```
+
+### Step 3.3: Execute via ccw cli Gemini
+
+> **CHECKPOINT**: Verify evaluation prompt is properly constructed before CLI execution.
+
+```javascript
+// Shell escape utility (same as Phase 02)
+function escapeForShell(str) {
+  return str.replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`');
+}
+
+const skillPath = state.target_skills[0].path;  // Primary skill for --cd
+
+const cliCommand = `ccw cli -p "${escapeForShell(evalPrompt)}" --tool gemini --mode analysis --cd "${skillPath}"`;
+
+// Execute in background
+Bash({
+  command: cliCommand,
+  run_in_background: true,
+  timeout: 300000  // 5 minutes
+});
+
+// STOP -- wait for hook callback
+```
+
+### Step 3.4: Parse Score and Write Eval File
+
+After CLI completes:
+
+```javascript
+// Parse JSON from Gemini output
+// The output may contain markdown wrapping -- extract JSON
+const rawOutput = /* CLI output from callback */;
+const jsonMatch = rawOutput.match(/\{[\s\S]*\}/);
+let evaluation;
+
+if (jsonMatch) {
+  try {
+    evaluation = JSON.parse(jsonMatch[0]);
+    // Extract chain_scores if present
+    if (state.execution_mode === 'chain' && evaluation.chain_scores) {
+      state.iterations[N - 1].evaluation.chain_scores = evaluation.chain_scores;
+    }
+  } catch (e) {
+    // Fallback: try to extract score heuristically
+    const scoreMatch = rawOutput.match(/"composite_score"\s*:\s*(\d+)/);
+    evaluation = {
+      composite_score: scoreMatch ? parseInt(scoreMatch[1]) : 50,
+      dimensions: [],
+      strengths: [],
+      weaknesses: ['Evaluation output parsing failed -- raw output saved'],
+      suggestions: []
+    };
+  }
+} else {
+  evaluation = {
+    composite_score: 50,
+    dimensions: [],
+    strengths: [],
+    weaknesses: ['No structured evaluation output -- defaulting to 50'],
+    suggestions: []
+  };
+}
+
+// Write iteration-N-eval.md
+const evalReport = `# Iteration ${N} Evaluation
+
+**Composite Score**: ${evaluation.composite_score}/100
+**Date**: ${new Date().toISOString()}
+
+## Dimension Scores
+
+| Dimension | Score | Weight | Feedback |
+|-----------|-------|--------|----------|
+${(evaluation.dimensions || []).map(d =>
+  `| ${d.name} | ${d.score} | ${d.weight} | ${d.feedback} |`
+).join('\n')}
+
+${(state.execution_mode === 'chain' && evaluation.chain_scores) ? `
+## Chain Scores
+
+| Skill | Score | Chain Position |
+|-------|-------|----------------|
+${state.chain_order.map((s, i) => `| ${s} | ${evaluation.chain_scores[s] || '-'} | ${i + 1} |`).join('\n')}
+` : ''}
+
+## Strengths
+${(evaluation.strengths || []).map(s => `- ${s}`).join('\n')}
+
+## Weaknesses
+${(evaluation.weaknesses || []).map(w => `- ${w}`).join('\n')}
+
+## Improvement Suggestions
+${(evaluation.suggestions || []).map((s, i) =>
+  `### ${i + 1}. [${s.priority}] ${s.description}\n- **Target**: ${s.target_file}\n- **Rationale**: ${s.rationale}\n${s.code_snippet ? `- **Suggested**:\n\`\`\`\n${s.code_snippet}\n\`\`\`` : ''}`
+).join('\n\n')}
+`;
+
+Write(`${iterDir}/iteration-${N}-eval.md`, evalReport);
+
+// Update state
+state.iterations[N - 1].evaluation = {
+  score: evaluation.composite_score,
+  dimensions: evaluation.dimensions || [],
+  strengths: evaluation.strengths || [],
+  weaknesses: evaluation.weaknesses || [],
+  suggestions: evaluation.suggestions || [],
+  chain_scores: evaluation.chain_scores || null,
+  eval_file: `${iterDir}/iteration-${N}-eval.md`
+};
+state.latest_score = evaluation.composite_score;
+state.score_trend.push(evaluation.composite_score);
+
+Write(`${state.work_dir}/iteration-state.json`, JSON.stringify(state, null, 2));
+```
+
+### Step 3.5: Check Termination
+
+```javascript
+function shouldTerminate(state) {
+  // 1. Quality threshold met
+  if (state.latest_score >= state.quality_threshold) {
+    return { terminate: true, reason: 'quality_threshold_met' };
+  }
+
+  // 2. Max iterations reached
+  if (state.current_iteration >= state.max_iterations) {
+    return { terminate: true, reason: 'max_iterations_reached' };
+  }
+
+  // 3. Convergence: no improvement in last 2 iterations
+  if (state.score_trend.length >= 3) {
+    const last3 = state.score_trend.slice(-3);
+    const improvement = last3[2] - last3[0];
+    if (improvement <= 2) {
+      state.converged = true;
+      return { terminate: true, reason: 'convergence_detected' };
+    }
+  }
+
+  // 4. Error limit
+  if (state.error_count >= state.max_errors) {
+    return { terminate: true, reason: 'error_limit_reached' };
+  }
+
+  return { terminate: false };
+}
+
+const termination = shouldTerminate(state);
+if (termination.terminate) {
+  state.termination_reason = termination.reason;
+  Write(`${state.work_dir}/iteration-state.json`, JSON.stringify(state, null, 2));
+  // Skip Phase 4, go directly to Phase 5 (Report)
+} else {
+  // Continue to Phase 4 (Improve)
+}
+```
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| CLI timeout | Retry once, if still fails use score 50 with warning |
+| JSON parse failure | Extract score heuristically, save raw output |
+| No output | Default score 50, note in weaknesses |
+
+## Output
+
+- **Files**: `iteration-{N}-eval.md`
+- **State**: `iterations[N-1].evaluation`, `latest_score`, `score_trend` updated
+- **Decision**: terminate -> Phase 5, continue -> Phase 4
+- **TodoWrite**: Update current iteration score display

.claude/skills/skill-iter-tune/phases/04-improve.md

@@ -0,0 +1,186 @@
+# Phase 4: Apply Improvements
+
+> **COMPACT SENTINEL [Phase 4: Improve]**
+> This phase contains 4 execution steps (Step 4.1 -- 4.4).
+> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
+> Recovery: `Read("phases/04-improve.md")`
+
+Apply targeted improvements to skill files based on evaluation suggestions. Uses a general-purpose Agent to make changes, ensuring only suggested modifications are applied.
+
+## Objective
+
+- Read evaluation suggestions from current iteration
+- Launch Agent to apply improvements in priority order
+- Document all changes made
+- Update iteration state
+
+## Execution
+
+### Step 4.1: Prepare Improvement Context
+
+```javascript
+const N = state.current_iteration;
+const iterDir = `${state.work_dir}/iterations/iteration-${N}`;
+const evaluation = state.iterations[N - 1].evaluation;
+
+// Verify we have suggestions to apply
+if (!evaluation.suggestions || evaluation.suggestions.length === 0) {
+  // No suggestions -- skip improvement, mark iteration complete
+  state.iterations[N - 1].improvement = {
+    changes_applied: [],
+    changes_file: null,
+    improvement_rationale: 'No suggestions provided by evaluation'
+  };
+  state.iterations[N - 1].status = 'completed';
+  Write(`${state.work_dir}/iteration-state.json`, JSON.stringify(state, null, 2));
+  // -> Return to orchestrator for next iteration
+  return;
+}
+
+// Build file inventory for agent context
+const skillFileInventory = state.target_skills.map(skill => {
+  return `Skill: ${skill.name} (${skill.path})\nFiles:\n` +
+    skill.files.map(f => `  - ${f}`).join('\n');
+}).join('\n\n');
+
+// Chain mode: add chain relationship context
+const chainContext = state.execution_mode === 'chain'
+  ? `\nChain Order: ${state.chain_order.join(' -> ')}\n` +
+    `Chain Scores: ${state.chain_order.map(s =>
+      `${s}: ${state.iterations[N-1].evaluation?.chain_scores?.[s] || 'N/A'}`
+    ).join(', ')}\n` +
+    `Weakest Link: ${state.chain_order.reduce((min, s) => {
+      const score = state.iterations[N-1].evaluation?.chain_scores?.[s] || 100;
+      return score < (state.iterations[N-1].evaluation?.chain_scores?.[min] || 100) ? s : min;
+    }, state.chain_order[0])}`
+  : '';
+```
+
+### Step 4.2: Launch Improvement Agent
+
+> **CHECKPOINT**: Before launching agent, verify:
+> 1. evaluation.suggestions is non-empty
+> 2. All target_file paths in suggestions are valid
+
+```javascript
+const suggestionsText = evaluation.suggestions.map((s, i) =>
+  `${i + 1}. [${s.priority.toUpperCase()}] ${s.description}\n` +
+  `   Target: ${s.target_file}\n` +
+  `   Rationale: ${s.rationale}\n` +
+  (s.code_snippet ? `   Suggested change:\n   ${s.code_snippet}\n` : '')
+).join('\n');
+
+Agent({
+  subagent_type: 'general-purpose',
+  run_in_background: false,
+  description: `Apply skill improvements iteration ${N}`,
+  prompt: `## Task: Apply Targeted Improvements to Skill Files
+
+You are improving a workflow skill based on evaluation feedback. Apply ONLY the suggested changes -- do not refactor, add features, or "improve" beyond what is explicitly suggested.
+
+## Current Score: ${evaluation.score}/100
+Dimension breakdown:
+${evaluation.dimensions.map(d => `- ${d.name}: ${d.score}/100`).join('\n')}
+
+## Skill File Inventory
+${skillFileInventory}
+
+${chainContext ? `## Chain Context\n${chainContext}\n\nPrioritize improvements on the weakest skill in the chain. Also consider interface compatibility between adjacent skills in the chain.\n` : ''}
+
+## Improvement Suggestions (apply in priority order)
+${suggestionsText}
+
+## Rules
+1. Read each target file BEFORE modifying it
+2. Apply ONLY the suggested changes -- no unsolicited modifications
+3. If a suggestion's target_file doesn't exist, skip it and note in summary
+4. If a suggestion conflicts with existing patterns, adapt it to fit (note adaptation)
+5. Preserve existing code style, naming conventions, and structure
+6. After all changes, write a change summary to: ${iterDir}/iteration-${N}-changes.md
+
+## Changes Summary Format (write to ${iterDir}/iteration-${N}-changes.md)
+
+# Iteration ${N} Changes
+
+## Applied Suggestions
+- [high] description: what was changed in which file
+- [medium] description: what was changed in which file
+
+## Files Modified
+- path/to/file.md: brief description of changes
+
+## Skipped Suggestions (if any)
+- description: reason for skipping
+
+## Notes
+- Any adaptations or considerations
+
+## Success Criteria
+- All high-priority suggestions applied
+- Medium-priority suggestions applied if feasible
+- Low-priority suggestions applied if trivial
+- Changes summary written to ${iterDir}/iteration-${N}-changes.md
+`
+});
+```
+
+### Step 4.3: Verify Changes
+
+After agent completes:
+
+```javascript
+// Verify changes summary was written
+const changesFile = `${iterDir}/iteration-${N}-changes.md`;
+const changesExist = Glob(changesFile).length > 0;
+
+if (!changesExist) {
+  // Agent didn't write summary -- create a minimal one
+  Write(changesFile, `# Iteration ${N} Changes\n\n## Notes\nAgent completed but did not produce changes summary.\n`);
+}
+
+// Read changes summary to extract applied changes
+const changesContent = Read(changesFile);
+
+// Parse applied changes (heuristic: count lines starting with "- [")
+const appliedMatches = changesContent.match(/^- \[.+?\]/gm) || [];
+const changes_applied = appliedMatches.map(m => ({
+  summary: m.replace(/^- /, ''),
+  file: '' // Extracted from context
+}));
+```
+
+### Step 4.4: Update State
+
+```javascript
+state.iterations[N - 1].improvement = {
+  changes_applied: changes_applied,
+  changes_file: changesFile,
+  improvement_rationale: `Applied ${changes_applied.length} improvements based on evaluation score ${evaluation.score}`
+};
+state.iterations[N - 1].status = 'completed';
+state.updated_at = new Date().toISOString();
+
+// Also update the skill files list in case new files were created
+for (const skill of state.target_skills) {
+  skill.files = Glob(`${skill.path}/**/*.md`).map(f => f.replace(skill.path + '/', ''));
+}
+
+Write(`${state.work_dir}/iteration-state.json`, JSON.stringify(state, null, 2));
+
+// -> Return to orchestrator for next iteration (Phase 2) or termination check
+```
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| Agent fails to complete | Rollback from skill-snapshot: `cp -r "${iterDir}/skill-snapshot/${skill.name}/*" "${skill.path}/"` |
+| Agent corrupts files | Same rollback from snapshot |
+| Changes summary missing | Create minimal summary, continue |
+| target_file not found | Agent skips suggestion, notes in summary |
+
+## Output
+
+- **Files**: `iteration-{N}-changes.md`, modified skill files
+- **State**: `iterations[N-1].improvement` and `.status` updated
+- **Next**: Return to orchestrator, begin next iteration (Phase 2) or terminate

.claude/skills/skill-iter-tune/phases/05-report.md

@@ -0,0 +1,166 @@
+# Phase 5: Final Report
+
+> **COMPACT SENTINEL [Phase 5: Report]**
+> This phase contains 4 execution steps (Step 5.1 -- 5.4).
+> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
+> Recovery: `Read("phases/05-report.md")`
+
+Generate comprehensive iteration history report and display results to user.
+
+## Objective
+
+- Read complete iteration state
+- Generate formatted final report with score progression
+- Write final-report.md
+- Display summary to user
+
+## Execution
+
+### Step 5.1: Read Complete State
+
+```javascript
+const state = JSON.parse(Read(`${state.work_dir}/iteration-state.json`));
+state.status = 'completed';
+state.updated_at = new Date().toISOString();
+```
+
+### Step 5.2: Generate Report
+
+```javascript
+// Determine outcome
+const outcomeMap = {
+  quality_threshold_met: 'PASSED -- Quality threshold reached',
+  max_iterations_reached: 'MAX ITERATIONS -- Threshold not reached',
+  convergence_detected: 'CONVERGED -- Score stopped improving',
+  error_limit_reached: 'FAILED -- Too many errors'
+};
+const outcome = outcomeMap[state.termination_reason] || 'COMPLETED';
+
+// Build score progression table
+const scoreTable = state.iterations
+  .filter(i => i.evaluation)
+  .map(i => {
+    const dims = i.evaluation.dimensions || [];
+    const dimScores = ['clarity', 'completeness', 'correctness', 'effectiveness', 'efficiency']
+      .map(id => {
+        const dim = dims.find(d => d.id === id);
+        return dim ? dim.score : '-';
+      });
+    return `| ${i.round} | ${i.evaluation.score} | ${dimScores.join(' | ')} |`;
+  }).join('\n');
+
+// Build iteration details
+const iterationDetails = state.iterations.map(iter => {
+  const evalSection = iter.evaluation
+    ? `**Score**: ${iter.evaluation.score}/100\n` +
+      `**Strengths**: ${iter.evaluation.strengths?.join(', ') || 'N/A'}\n` +
+      `**Weaknesses**: ${iter.evaluation.weaknesses?.slice(0, 3).join(', ') || 'N/A'}`
+    : '**Evaluation**: Skipped or failed';
+
+  const changesSection = iter.improvement
+    ? `**Changes Applied**: ${iter.improvement.changes_applied?.length || 0}\n` +
+      (iter.improvement.changes_applied?.map(c => `  - ${c.summary}`).join('\n') || '  None')
+    : '**Improvements**: None';
+
+  return `### Iteration ${iter.round}\n${evalSection}\n${changesSection}`;
+}).join('\n\n');
+
+const report = `# Skill Iter Tune -- Final Report
+
+## Summary
+
+| Field | Value |
+|-------|-------|
+| **Target Skills** | ${state.target_skills.map(s => s.name).join(', ')} |
+| **Execution Mode** | ${state.execution_mode} |
+${state.execution_mode === 'chain' ? `| **Chain Order** | ${state.chain_order.join(' -> ')} |` : ''}
+| **Test Scenario** | ${state.test_scenario.description} |
+| **Iterations** | ${state.iterations.length} |
+| **Initial Score** | ${state.score_trend[0] || 'N/A'} |
+| **Final Score** | ${state.latest_score}/100 |
+| **Quality Threshold** | ${state.quality_threshold} |
+| **Outcome** | ${outcome} |
+| **Started** | ${state.started_at} |
+| **Completed** | ${state.updated_at} |
+
+## Score Progression
+
+| Iter | Composite | Clarity | Completeness | Correctness | Effectiveness | Efficiency |
+|------|-----------|---------|--------------|-------------|---------------|------------|
+${scoreTable}
+
+**Trend**: ${state.score_trend.join(' -> ')}
+
+${state.execution_mode === 'chain' ? `
+## Chain Score Progression
+
+| Iter | ${state.chain_order.join(' | ')} |
+|------|${state.chain_order.map(() => '------').join('|')}|
+${state.iterations.filter(i => i.evaluation?.chain_scores).map(i => {
+  const scores = state.chain_order.map(s => i.evaluation.chain_scores[s] || '-');
+  return `| ${i.round} | ${scores.join(' | ')} |`;
+}).join('\n')}
+` : ''}
+
+## Iteration Details
+
+${iterationDetails}
+
+## Remaining Weaknesses
+
+${state.iterations.length > 0 && state.iterations[state.iterations.length - 1].evaluation
+  ? state.iterations[state.iterations.length - 1].evaluation.weaknesses?.map(w => `- ${w}`).join('\n') || 'None identified'
+  : 'No evaluation data available'}
+
+## Artifact Locations
+
+| Path | Description |
+|------|-------------|
+| \`${state.work_dir}/iteration-state.json\` | Complete state history |
+| \`${state.work_dir}/iterations/iteration-{N}/iteration-{N}-eval.md\` | Per-iteration evaluations |
+| \`${state.work_dir}/iterations/iteration-{N}/iteration-{N}-changes.md\` | Per-iteration change logs |
+| \`${state.work_dir}/final-report.md\` | This report |
+| \`${state.backup_dir}/\` | Original skill backups |
+
+## Restore Original
+
+To revert all changes and restore the original skill files:
+
+\`\`\`bash
+${state.target_skills.map(s => `cp -r "${state.backup_dir}/${s.name}"/* "${s.path}/"`).join('\n')}
+\`\`\`
+`;
+```
+
+### Step 5.3: Write Report and Update State
+
+```javascript
+Write(`${state.work_dir}/final-report.md`, report);
+
+state.status = 'completed';
+Write(`${state.work_dir}/iteration-state.json`, JSON.stringify(state, null, 2));
+```
+
+### Step 5.4: Display Summary to User
+
+Output to user:
+
+```
+Skill Iter Tune Complete!
+
+Target: {skill names}
+Iterations: {count}
+Score: {initial} -> {final} ({outcome})
+Threshold: {threshold}
+
+Score trend: {score1} -> {score2} -> ... -> {scoreN}
+
+Full report: {workDir}/final-report.md
+Backups: {backupDir}/
+```
+
+## Output
+
+- **Files**: `final-report.md`
+- **State**: `status = completed`
+- **Next**: Workflow complete. Return control to user.

.claude/skills/skill-iter-tune/specs/evaluation-criteria.md

@@ -0,0 +1,63 @@
+# Evaluation Criteria
+
+Skill 质量评估标准，由 Phase 03 (Evaluate) 引用。Gemini 按此标准对 skill 产出物进行多维度评分。
+
+## Dimensions
+
+| Dimension | Weight | ID | Description |
+|-----------|--------|----|-------------|
+| Clarity | 0.20 | clarity | 指令清晰无歧义，结构良好，易于遵循。Phase 文件有明确的 Step 划分、输入输出说明 |
+| Completeness | 0.25 | completeness | 覆盖所有必要阶段、边界情况、错误处理。没有遗漏关键执行路径 |
+| Correctness | 0.25 | correctness | 逻辑正确，数据流一致，Phase 间无矛盾。State schema 与实际使用匹配 |
+| Effectiveness | 0.20 | effectiveness | 在给定测试场景下能产出高质量输出。产物满足用户需求和成功标准 |
+| Efficiency | 0.10 | efficiency | 无冗余内容，上下文使用合理，不浪费 token。Phase 职责清晰无重叠 |
+
+## Scoring Guide
+
+| Range | Level | Description |
+|-------|-------|-------------|
+| 90-100 | Excellent | 生产级别，几乎无改进空间 |
+| 80-89 | Good | 可投入使用，仅需微调 |
+| 70-79 | Adequate | 功能可用，有明显可改进区域 |
+| 60-69 | Needs Work | 存在影响产出质量的显著问题 |
+| 0-59 | Poor | 结构或逻辑存在根本性问题 |
+
+## Composite Score Calculation
+
+```
+composite = sum(dimension.score * dimension.weight)
+```
+
+## Output JSON Schema
+
+```json
+{
+  "composite_score": 75,
+  "dimensions": [
+    { "name": "Clarity", "id": "clarity", "score": 80, "weight": 0.20, "feedback": "..." },
+    { "name": "Completeness", "id": "completeness", "score": 70, "weight": 0.25, "feedback": "..." },
+    { "name": "Correctness", "id": "correctness", "score": 78, "weight": 0.25, "feedback": "..." },
+    { "name": "Effectiveness", "id": "effectiveness", "score": 72, "weight": 0.20, "feedback": "..." },
+    { "name": "Efficiency", "id": "efficiency", "score": 85, "weight": 0.10, "feedback": "..." }
+  ],
+  "strengths": ["...", "...", "..."],
+  "weaknesses": ["...", "...", "..."],
+  "suggestions": [
+    {
+      "priority": "high",
+      "target_file": "phases/02-execute.md",
+      "description": "Add explicit error handling for CLI timeout",
+      "rationale": "Current phase has no recovery path when CLI execution exceeds timeout",
+      "code_snippet": "optional suggested replacement code"
+    }
+  ]
+}
+```
+
+## Evaluation Focus by Iteration
+
+| Iteration | Primary Focus |
+|-----------|--------------|
+| 1 | 全面评估，建立 baseline |
+| 2-3 | 重点关注上一轮 weaknesses 是否改善，避免重复已解决的问题 |
+| 4+ | 精细化改进，关注 Effectiveness 和 Efficiency |

.claude/skills/skill-iter-tune/templates/eval-prompt.md

@@ -0,0 +1,134 @@
+# Evaluation Prompt Template
+
+Phase 03 使用此模板构造 ccw cli 提示词，让 Gemini 按多维度评估 skill 质量。
+
+## Template
+
+```
+PURPOSE: Evaluate the quality of a workflow skill by examining both its definition files and the artifacts it produced when executed against a test scenario. Provide a structured multi-dimensional score with actionable improvement suggestions.
+
+SKILL DEFINITION:
+${skillContent}
+
+TEST SCENARIO:
+${testScenario.description}
+Requirements: ${testScenario.requirements}
+Success Criteria: ${testScenario.success_criteria}
+
+ARTIFACTS PRODUCED:
+${artifactsSummary}
+
+EVALUATION CRITERIA:
+${evaluationCriteria}
+
+${previousEvalContext}
+
+TASK:
+1. Read all skill definition files and produced artifacts carefully
+2. Score each dimension on 0-100 based on the evaluation criteria:
+   - Clarity (weight 0.20): Instructions unambiguous, well-structured, easy to follow
+   - Completeness (weight 0.25): All phases, edge cases, error handling covered
+   - Correctness (weight 0.25): Logic sound, data flow consistent, no contradictions
+   - Effectiveness (weight 0.20): Produces high-quality output for the test scenario
+   - Efficiency (weight 0.10): Minimal redundancy, appropriate context usage
+3. Calculate weighted composite score
+4. List top 3 strengths
+5. List top 3-5 weaknesses with specific file:section references
+6. Provide 3-5 prioritized improvement suggestions with concrete changes
+
+MODE: analysis
+
+EXPECTED OUTPUT FORMAT (strict JSON, no markdown wrapping):
+{
+  "composite_score": <number 0-100>,
+  "dimensions": [
+    { "name": "Clarity", "id": "clarity", "score": <0-100>, "weight": 0.20, "feedback": "<specific feedback>" },
+    { "name": "Completeness", "id": "completeness", "score": <0-100>, "weight": 0.25, "feedback": "<specific feedback>" },
+    { "name": "Correctness", "id": "correctness", "score": <0-100>, "weight": 0.25, "feedback": "<specific feedback>" },
+    { "name": "Effectiveness", "id": "effectiveness", "score": <0-100>, "weight": 0.20, "feedback": "<specific feedback>" },
+    { "name": "Efficiency", "id": "efficiency", "score": <0-100>, "weight": 0.10, "feedback": "<specific feedback>" }
+  ],
+  "strengths": ["<strength 1>", "<strength 2>", "<strength 3>"],
+  "weaknesses": ["<weakness 1 with file:section reference>", "..."],
+  "suggestions": [
+    {
+      "priority": "high|medium|low",
+      "target_file": "<relative path to skill file>",
+      "description": "<what to change>",
+      "rationale": "<why this improves quality>",
+      "code_snippet": "<optional: suggested replacement content>"
+    }
+  ],
+  "chain_scores": {
+    "<skill_name>": "<number 0-100, per-skill score — only present in chain mode>"
+  }
+}
+
+CONSTRAINTS:
+- Be rigorous and specific — reference exact file paths and sections
+- Each suggestion MUST include a target_file that maps to a skill file
+- Focus suggestions on highest-impact changes first
+- Do NOT suggest changes already addressed in previous iterations
+- Output ONLY the JSON object, no surrounding text or markdown
+```
+
+## Variable Substitution
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `${skillContent}` | Same as execute-prompt.md | 完整 skill 文件内容 |
+| `${testScenario.*}` | iteration-state.json | 测试场景信息 |
+| `${artifactsSummary}` | Phase 03 reads artifacts/ dir | 产出物文件列表 + 内容摘要 |
+| `${evaluationCriteria}` | specs/evaluation-criteria.md | 评分标准全文 |
+| `${previousEvalContext}` | 历史迭代记录 | 前几轮评估摘要（避免重复建议） |
+| `${chainContext}` | Phase 03 constructs | chain 模式下的链上下文信息 |
+
+## previousEvalContext Construction
+
+```javascript
+// Build context from prior iterations to avoid repeating suggestions
+const previousEvalContext = state.iterations.length > 0
+  ? `PREVIOUS ITERATIONS (context for avoiding duplicate suggestions):
+${state.iterations.map(iter => `
+Iteration ${iter.round}: Score ${iter.evaluation?.score || 'N/A'}
+  Applied changes: ${iter.improvement?.changes_applied?.map(c => c.summary).join('; ') || 'none'}
+  Remaining weaknesses: ${iter.evaluation?.weaknesses?.slice(0, 3).join('; ') || 'none'}
+`).join('')}
+IMPORTANT: Focus on NEW issues or issues NOT adequately addressed in previous improvements.`
+  : '';
+```
+
+## chainContext Construction
+
+```javascript
+// Build chain context for evaluation (chain mode only)
+const chainContext = state.execution_mode === 'chain'
+  ? `CHAIN CONTEXT:
+This skill chain contains ${state.chain_order.length} skills executed in order:
+${state.chain_order.map((s, i) => `${i+1}. ${s}`).join('\n')}
+Current evaluation covers the entire chain output.
+Please provide per-skill quality scores in an additional "chain_scores" field.`
+  : '';
+```
+
+## artifactsSummary Construction
+
+```javascript
+// Read manifest.json if available, otherwise list files
+const manifestPath = `${iterDir}/artifacts/manifest.json`;
+let artifactsSummary;
+
+if (fileExists(manifestPath)) {
+  const manifest = JSON.parse(Read(manifestPath));
+  artifactsSummary = manifest.artifacts.map(a =>
+    `- ${a.path}: ${a.description} (Phase ${a.phase})`
+  ).join('\n');
+} else {
+  // Fallback: list all files with first 200 lines each
+  const files = Glob(`${iterDir}/artifacts/**/*`);
+  artifactsSummary = files.map(f => {
+    const content = Read(f, { limit: 200 });
+    return `--- ${f.replace(iterDir + '/artifacts/', '')} ---\n${content}`;
+  }).join('\n\n');
+}
+```

.claude/skills/skill-iter-tune/templates/execute-prompt.md

@@ -0,0 +1,97 @@
+# Execute Prompt Template
+
+Phase 02 使用此模板构造 ccw cli 提示词，让 Claude 模拟执行 skill 并产出所有预期产物。
+
+## Template
+
+```
+PURPOSE: Simulate executing the following workflow skill against a test scenario. Produce all expected output artifacts as if the skill were invoked with the given input. This is for evaluating skill quality.
+
+SKILL CONTENT:
+${skillContent}
+
+TEST SCENARIO:
+Description: ${testScenario.description}
+Input Arguments: ${testScenario.input_args}
+Requirements: ${testScenario.requirements}
+Success Criteria: ${testScenario.success_criteria}
+
+TASK:
+1. Study the complete skill structure (SKILL.md + all phase files)
+2. Follow the skill's execution flow sequentially (Phase 1 → Phase N)
+3. For each phase, produce the artifacts that phase would generate
+4. Write all output artifacts to the current working directory
+5. Create a manifest.json listing all produced artifacts with descriptions
+
+MODE: write
+
+CONTEXT: @**/*
+
+EXPECTED:
+- All artifacts the skill would produce for this test scenario
+- Each artifact in its correct relative path
+- A manifest.json at root: { "artifacts": [{ "path": "...", "description": "...", "phase": N }] }
+
+CONSTRAINTS:
+- Follow the skill execution flow exactly — do not skip or reorder phases
+- Produce realistic, high-quality output (not placeholder content)
+- If the skill requires user interaction (AskUserQuestion), use reasonable defaults
+- If the skill invokes external tools/CLIs, document what would be called but produce expected output directly
+```
+
+## Variable Substitution
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `${skillContent}` | Phase 02 reads all skill files | 完整 SKILL.md + phase 文件内容，用 markdown headers 分隔 |
+| `${testScenario.description}` | iteration-state.json | 用户描述的测试场景 |
+| `${testScenario.input_args}` | iteration-state.json | 模拟传给 skill 的参数 |
+| `${testScenario.requirements}` | iteration-state.json | 质量要求列表 |
+| `${testScenario.success_criteria}` | iteration-state.json | 成功标准定义 |
+
+## Chain Mode Extension
+
+When running in chain mode, the template is invoked once per skill in `chain_order`. Each invocation includes:
+
+### Additional Variable
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `${previousChainOutput}` | Phase 02 chain loop | 前序 skill 的 artifacts 摘要 (chain 模式下非首个 skill) |
+
+### Chain Prompt Modification
+
+When `execution_mode === 'chain'`, the prompt includes:
+
+```
+PREVIOUS CHAIN OUTPUT (from upstream skill "${previousSkillName}"):
+${previousChainOutput}
+
+IMPORTANT: Use the above output as input context for this skill's execution.
+```
+
+This section is only added for skills at position 2+ in the chain. The first skill in the chain receives no upstream context.
+
+## skillContent Construction
+
+```javascript
+// Read only executable skill files and format with consistent headers
+const skillMd = Read(`${skill.path}/SKILL.md`);
+const phaseFiles = Glob(`${skill.path}/phases/*.md`).map(f => ({
+  relativePath: f.replace(skill.path + '/', ''),
+  content: Read(f)
+}));
+const specFiles = Glob(`${skill.path}/specs/*.md`).map(f => ({
+  relativePath: f.replace(skill.path + '/', ''),
+  content: Read(f)
+}));
+
+const skillContent = `
+### File: SKILL.md
+${skillMd}
+
+${phaseFiles.map(f => `### File: ${f.relativePath}\n${f.content}`).join('\n\n')}
+
+${specFiles.length > 0 ? specFiles.map(f => `### File: ${f.relativePath}\n${f.content}`).join('\n\n') : ''}
+`.trim();
+```

.claude/skills/team-arch-opt/SKILL.md

@@ -44,7 +44,7 @@ Skill(skill="team-arch-opt", args="task description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -66,14 +66,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-arch-opt/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: arch-opt
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-arch-opt/roles/coordinator/role.md

@@ -46,7 +46,7 @@ When coordinator needs to execute a specific phase:
 | Interrupted session | Active session in .workflow/.team/TAO-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/consensus/adapt/complete: load commands/monitor.md, execute handler, STOP.
+For callback/check/resume/consensus/adapt/complete: load @commands/monitor.md, execute handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -81,11 +81,14 @@ TEXT-LEVEL ONLY. No source code reading.
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: `TAO-<slug>-<date>`
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure
+   - `project_root` = result of `Bash({ command: "pwd" })`
-3. TeamCreate with team name `arch-opt`
+   - `skill_root` = `<project_root>/.claude/skills/team-arch-opt`
-4. Write session.json with parallel_mode, max_branches, branches, independent_targets, fix_cycles
+2. Generate session ID: `TAO-<slug>-<date>`
-5. Initialize meta.json via team_msg state_update:
+3. Create session folder structure
+4. TeamCreate with team name `arch-opt`
+5. Write session.json with parallel_mode, max_branches, branches, independent_targets, fix_cycles
+6. Initialize meta.json via team_msg state_update:
    ```
    mcp__ccw-tools__team_msg({
      operation: "log", session_id: "<id>", from: "coordinator",
@@ -93,11 +96,11 @@ TEXT-LEVEL ONLY. No source code reading.
      data: { pipeline_mode: "<mode>", pipeline_stages: ["analyzer","designer","refactorer","validator","reviewer"], team_name: "arch-opt" }
    })
    ```
-6. Write session.json
+7. Write session.json
 
 ## Phase 3: Create Task Chain
 
-Delegate to commands/dispatch.md:
+Delegate to @commands/dispatch.md:
 1. Read dependency graph and parallel mode from session.json
 2. Topological sort tasks
 3. Create tasks via TaskCreate with blockedBy
@@ -105,7 +108,7 @@ Delegate to commands/dispatch.md:
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-brainstorm/SKILL.md

@@ -43,7 +43,7 @@ Skill(skill="team-brainstorm", args="topic description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -65,14 +65,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-brainstorm/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: brainstorm
 requirement: <topic-description>
 inner_loop: false
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```
@@ -89,7 +89,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: ideator
-role_spec: ~  or <project>/.claude/skills/team-brainstorm/roles/ideator/role.md
+role_spec: <skill_root>/roles/ideator/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: brainstorm
@@ -97,7 +97,7 @@ requirement: <topic-description>
 agent_name: ideator-<N>
 inner_loop: false
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/ideator/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery, owner=ideator-<N>) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-brainstorm/roles/coordinator/role.md

@@ -44,7 +44,7 @@ When coordinator needs to execute a specific phase:
 | Interrupted session | Active session in .workflow/.team/BRS-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/consensus/adapt/complete: load commands/monitor.md, execute handler, STOP.
+For callback/check/resume/consensus/adapt/complete: load @commands/monitor.md, execute handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -78,11 +78,14 @@ TEXT-LEVEL ONLY. No source code reading.
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: `BRS-<topic-slug>-<date>`
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure: ideas/, critiques/, synthesis/, evaluation/, wisdom/, .msg/
+   - `project_root` = result of `Bash({ command: "pwd" })`
-3. TeamCreate with team name `brainstorm`
+   - `skill_root` = `<project_root>/.claude/skills/team-brainstorm`
-4. Write session.json with pipeline, angles, gc_round=0, max_gc_rounds=2
+2. Generate session ID: `BRS-<topic-slug>-<date>`
-5. Initialize meta.json via team_msg state_update:
+3. Create session folder structure: ideas/, critiques/, synthesis/, evaluation/, wisdom/, .msg/
+4. TeamCreate with team name `brainstorm`
+5. Write session.json with pipeline, angles, gc_round=0, max_gc_rounds=2
+6. Initialize meta.json via team_msg state_update:
    ```
    mcp__ccw-tools__team_msg({
      operation: "log", session_id: "<id>", from: "coordinator",
@@ -90,18 +93,18 @@ TEXT-LEVEL ONLY. No source code reading.
      data: { pipeline_mode: "<mode>", pipeline_stages: ["ideator","challenger","synthesizer","evaluator"], team_name: "brainstorm", topic: "<topic>", angles: [...], gc_round: 0 }
    })
    ```
-6. Write session.json
+7. Write session.json
 
 ## Phase 3: Create Task Chain
 
-Delegate to commands/dispatch.md:
+Delegate to @commands/dispatch.md:
 1. Read pipeline mode and angles from session.json
 2. Create tasks for selected pipeline with correct blockedBy
 3. Update session.json with task count
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-coordinate/SKILL.md

@@ -32,6 +32,18 @@ Universal team coordination skill: analyze task -> generate role-specs -> dispat
     ccw cli --mode write     - code generation and modification
 ```
 
+## Shared Constants
+
+| Constant | Value |
+|----------|-------|
+| Session prefix | `TC` |
+| Session path | `.workflow/.team/TC-<slug>-<date>/` |
+| Worker agent | `team-worker` |
+| Message bus | `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)` |
+| CLI analysis | `ccw cli --mode analysis` |
+| CLI write | `ccw cli --mode write` |
+| Max roles | 5 |
+
 ## Role Router
 
 This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
@@ -85,6 +97,9 @@ User provides task description
 |---------|--------|
 | `check` / `status` | Output execution status graph, no advancement |
 | `resume` / `continue` | Check worker states, advance next step |
+| `revise <TASK-ID> [feedback]` | Revise specific task with optional feedback |
+| `feedback <text>` | Inject feedback into active pipeline |
+| `improve [dimension]` | Auto-improve weakest quality dimension |
 
 ---
 
@@ -150,6 +165,17 @@ AskUserQuestion({
 
 ---
 
+## Specs Reference
+
+| Spec | Purpose |
+|------|---------|
+| [specs/pipelines.md](specs/pipelines.md) | Dynamic pipeline model, task naming, dependency graph |
+| [specs/role-spec-template.md](specs/role-spec-template.md) | Template for dynamic role-spec generation |
+| [specs/quality-gates.md](specs/quality-gates.md) | Quality thresholds and scoring dimensions |
+| [specs/knowledge-transfer.md](specs/knowledge-transfer.md) | Context transfer protocols between roles |
+
+---
+
 ## Session Directory
 
 ```

.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md

@@ -16,6 +16,20 @@ Parse user task description -> detect required capabilities -> build dependency
 
 If task context requires codebase knowledge, set `needs_research: true`. Phase 2 will spawn researcher worker.
 
+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| New task | Coordinator Phase 1 receives task description |
+| Re-analysis | User provides revised requirements |
+| Adapt | handleAdapt extends analysis for new capability |
+
+## Strategy
+
+- **Delegation**: Inline execution (coordinator processes directly)
+- **Mode**: Text-level analysis only (no codebase reading)
+- **Output**: `<session>/task-analysis.json`
+
 ## Phase 2: Context Loading
 
 | Input | Source | Required |

.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md

@@ -4,6 +4,20 @@
 
 Create task chains from dynamic dependency graphs. Builds pipelines from the task-analysis.json produced by Phase 1. Workers are spawned as team-worker agents with role-spec paths.
 
+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| After analysis | Phase 1 complete, task-analysis.json exists |
+| After adapt | handleAdapt created new roles, needs new tasks |
+| Re-dispatch | Pipeline restructuring (rare) |
+
+## Strategy
+
+- **Delegation**: Inline execution (coordinator processes directly)
+- **Inputs**: task-analysis.json + team-session.json
+- **Output**: TaskCreate calls with dependency chains
+
 ## Phase 2: Context Loading
 
 | Input | Source | Required |

.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md

@@ -4,6 +4,22 @@
 
 Event-driven pipeline coordination with Spawn-and-Stop pattern. Role names are read from `team-session.json#roles`. Workers are spawned as `team-worker` agents with role-spec paths. Includes `handleComplete` for pipeline completion action and `handleAdapt` for mid-pipeline capability gap handling.
 
+## When to Use
+
+| Trigger | Condition |
+|---------|-----------|
+| Worker callback | Message contains [role-name] from session roles |
+| User command | "check", "status", "resume", "continue" |
+| Capability gap | Worker reports capability_gap |
+| Pipeline spawn | After dispatch, initial spawn needed |
+| Pipeline complete | All tasks done |
+
+## Strategy
+
+- **Delegation**: Inline execution with handler routing
+- **Beat model**: ONE_STEP_PER_INVOCATION — one handler then STOP
+- **Workers**: Spawned as team-worker via Agent() in background
+
 ## Constants
 
 | Constant | Value | Description |

.claude/skills/team-coordinate/roles/coordinator/role.md

@@ -1,3 +1,7 @@
+---
+role: coordinator
+---
+
 # Coordinator Role
 
 Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec generation, task dispatching, progress monitoring, session state, and completion action. The sole built-in role -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent.
@@ -33,6 +37,30 @@ Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec gener
 
 ---
 
+## Message Types
+
+| Type | Direction | Trigger |
+|------|-----------|---------|
+| state_update | outbound | Session init, pipeline progress |
+| task_unblocked | outbound | Task ready for execution |
+| fast_advance | inbound | Worker skipped coordinator |
+| capability_gap | inbound | Worker needs new capability |
+| error | inbound | Worker failure |
+| impl_complete | inbound | Worker task done |
+| consensus_blocked | inbound | Discussion verdict conflict |
+
+## Message Bus Protocol
+
+All coordinator state changes MUST be logged to team_msg BEFORE SendMessage:
+
+1. `team_msg(operation="log", ...)` — log the event
+2. `SendMessage(...)` — communicate to worker/user
+3. `TaskUpdate(...)` — update task state
+
+Read state before every handler: `team_msg(operation="get_state", session_id=<session-id>)`
+
+---
+
 ## Command Execution Protocol
 
 When coordinator needs to execute a command (analyze-task, dispatch, monitor):
@@ -52,6 +80,20 @@ Phase 1 needs task analysis
   -> Continue to Phase 2
 ```
 
+## Toolbox
+
+| Tool | Type | Purpose |
+|------|------|---------|
+| commands/analyze-task.md | Command | Task analysis and role design |
+| commands/dispatch.md | Command | Task chain creation |
+| commands/monitor.md | Command | Pipeline monitoring and handlers |
+| team-worker | Subagent | Worker spawning |
+| TeamCreate / TeamDelete | System | Team lifecycle |
+| TaskCreate / TaskList / TaskGet / TaskUpdate | System | Task lifecycle |
+| team_msg | System | Message bus operations |
+| SendMessage | System | Inter-agent communication |
+| AskUserQuestion | System | User interaction |
+
 ---
 
 ## Entry Router
@@ -68,7 +110,7 @@ When coordinator is invoked, first detect the invocation type:
 | Interrupted session | Active/paused session exists in `.workflow/.team/TC-*` | -> Phase 0 (Resume Check) |
 | New session | None of above | -> Phase 1 (Task Analysis) |
 
-For callback/check/resume/adapt/complete: load `commands/monitor.md` and execute the appropriate handler, then STOP.
+For callback/check/resume/adapt/complete: load `@commands/monitor.md` and execute the appropriate handler, then STOP.
 
 ### Router Implementation
 
@@ -124,7 +166,7 @@ For callback/check/resume/adapt/complete: load `commands/monitor.md` and execute
    - What deliverables are expected? (documents, code, analysis reports)
    - Any constraints? (timeline, technology, style)
 
-3. **Delegate to `commands/analyze-task.md`**:
+3. **Delegate to `@commands/analyze-task.md`**:
    - Signal detection: scan keywords -> infer capabilities
    - Artifact inference: each capability -> default output type (.md)
    - Dependency graph: build DAG of work streams
@@ -161,15 +203,19 @@ Regardless of complexity score or role count, coordinator MUST:
 
 **Workflow**:
 
-1. **Check `needs_research` flag** from task-analysis.json:
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-coordinate`
+
+2. **Check `needs_research` flag** from task-analysis.json:
    - If `true`: **Spawn researcher worker first** to gather codebase context
      - Wait for researcher callback
      - Merge research findings into task context
      - Update task-analysis.json with enriched context
 
-2. **Generate session ID**: `TC-<slug>-<date>` (slug from first 3 meaningful words of task)
+3. **Generate session ID**: `TC-<slug>-<date>` (slug from first 3 meaningful words of task)
 
-3. **Create session folder structure**:
+4. **Create session folder structure**:
    ```
    .workflow/.team/<session-id>/
    +-- role-specs/
@@ -180,11 +226,11 @@ Regardless of complexity score or role count, coordinator MUST:
    +-- .msg/
    ```
 
-4. **Call TeamCreate** with team name derived from session ID
+5. **Call TeamCreate** with team name derived from session ID
 
-5. **Read `specs/role-spec-template.md`** for Behavioral Traits + Reference Patterns
+6. **Read `specs/role-spec-template.md`** for Behavioral Traits + Reference Patterns
 
-6. **For each role in task-analysis.json#roles**:
+7. **For each role in task-analysis.json#roles**:
    - Fill YAML frontmatter: role, prefix, inner_loop, additional_members, message_types
    - **Compose Phase 2-4 content** (NOT copy from template):
      - Phase 2: Derive input sources and context loading steps from **task description + upstream dependencies**
@@ -193,14 +239,14 @@ Regardless of complexity score or role count, coordinator MUST:
      - Reference Patterns may guide phase structure, but task description determines specific content
    - Write generated role-spec to `<session>/role-specs/<role-name>.md`
 
-7. **Register roles** in team-session.json#roles (with `role_spec` path instead of `role_file`)
+8. **Register roles** in team-session.json#roles (with `role_spec` path instead of `role_file`)
 
-8. **Initialize shared infrastructure**:
+9. **Initialize shared infrastructure**:
    - `wisdom/learnings.md`, `wisdom/decisions.md`, `wisdom/issues.md` (empty with headers)
    - `explorations/cache-index.json` (`{ "entries": [] }`)
    - `discussions/` (empty directory)
 
-9. **Initialize pipeline metadata** via team_msg:
+10. **Initialize pipeline metadata** via team_msg:
 ```typescript
 // 使用 team_msg 将 pipeline 元数据写入 .msg/meta.json
 // 注意: 此处为动态角色，执行时需将 <placeholders> 替换为 task-analysis.json 中生成的实际角色列表
@@ -219,7 +265,7 @@ mcp__ccw-tools__team_msg({
 })
 ```
 
-10. **Write team-session.json** with: session_id, task_description, status="active", roles, pipeline (empty), active_workers=[], completion_action="interactive", created_at
+11. **Write team-session.json** with: session_id, task_description, status="active", roles, pipeline (empty), active_workers=[], completion_action="interactive", created_at
 
 **Success**: Session created, role-spec files generated, shared infrastructure initialized.
 
@@ -229,7 +275,7 @@ mcp__ccw-tools__team_msg({
 
 **Objective**: Dispatch tasks based on dependency graph with proper dependencies.
 
-Delegate to `commands/dispatch.md` which creates the full task chain:
+Delegate to `@commands/dispatch.md` which creates the full task chain:
 1. Reads dependency_graph from task-analysis.json
 2. Topological sorts tasks
 3. Creates tasks via TaskCreate with correct blockedBy
@@ -249,7 +295,7 @@ Delegate to `commands/dispatch.md` which creates the full task chain:
 **Design**: Spawn-and-Stop + Callback pattern, with worker fast-advance.
 
 **Workflow**:
-1. Load `commands/monitor.md`
+1. Load `@commands/monitor.md`
 2. Find tasks with: status=pending, blockedBy all resolved, owner assigned
 3. For each ready task -> spawn team-worker (see SKILL.md Coordinator Spawn Template)
 4. Output status summary with execution graph

.claude/skills/team-coordinate/specs/knowledge-transfer.md

@@ -0,0 +1,111 @@
+# Knowledge Transfer Protocols
+
+## 1. Transfer Channels
+
+| Channel | Scope | Mechanism | When to Use |
+|---------|-------|-----------|-------------|
+| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
+| **State Updates** | Cross-role | `team_msg(operation="log", type="state_update", data={...})` / `team_msg(operation="get_state", session_id=<session-id>)` | Key findings, decisions, metadata (small, structured data) |
+| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
+| **Context Accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
+| **Exploration Cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
+
+## 2. Context Loading Protocol (Phase 2)
+
+Every role MUST load context in this order before starting work.
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Extract session path from task description | Yes |
+| 2 | `team_msg(operation="get_state", session_id=<session-id>)` | Yes |
+| 3 | Read artifact files from upstream state's `ref` paths | Yes |
+| 4 | Read `<session>/wisdom/*.md` if exists | Yes |
+| 5 | Check `<session>/explorations/cache-index.json` before new exploration | If exploring |
+| 6 | For inner_loop roles: load context_accumulator from prior tasks | If inner_loop |
+
+**Loading rules**:
+- Never skip step 2 -- state contains key decisions and findings
+- If `ref` path in state does not exist, log warning and continue
+- Wisdom files are append-only -- read all entries, newest last
+
+## 3. Context Publishing Protocol (Phase 4)
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Write deliverable to `<session>/artifacts/<task-id>-<name>.md` | Yes |
+| 2 | Send `team_msg(type="state_update")` with payload (see schema below) | Yes |
+| 3 | Append wisdom entries for learnings, decisions, issues found | If applicable |
+
+## 4. State Update Schema
+
+Sent via `team_msg(type="state_update")` on task completion.
+
+```json
+{
+  "status": "task_complete",
+  "task_id": "<TASK-NNN>",
+  "ref": "<session>/artifacts/<filename>",
+  "key_findings": [
+    "Finding 1",
+    "Finding 2"
+  ],
+  "decisions": [
+    "Decision with rationale"
+  ],
+  "files_modified": [
+    "path/to/file.ts"
+  ],
+  "verification": "self-validated | peer-reviewed | tested"
+}
+```
+
+**Field rules**:
+- `ref`: Always an artifact path, never inline content
+- `key_findings`: Max 5 items, each under 100 chars
+- `decisions`: Include rationale, not just the choice
+- `files_modified`: Only for implementation tasks
+- `verification`: One of `self-validated`, `peer-reviewed`, `tested`
+
+**Write state** (namespaced by role):
+```
+team_msg(operation="log", session_id=<session-id>, from=<role>, type="state_update", data={
+  "<role_name>": { "key_findings": [...], "scope": "..." }
+})
+```
+
+**Read state**:
+```
+team_msg(operation="get_state", session_id=<session-id>)
+// Returns merged state from all state_update messages
+```
+
+## 5. Exploration Cache Protocol
+
+Prevents redundant research across tasks and discussion rounds.
+
+| Step | Action |
+|------|--------|
+| 1 | Read `<session>/explorations/cache-index.json` |
+| 2 | If angle already explored, read cached result from `explore-<angle>.json` |
+| 3 | If not cached, perform exploration |
+| 4 | Write result to `<session>/explorations/explore-<angle>.json` |
+| 5 | Update `cache-index.json` with new entry |
+
+**cache-index.json format**:
+```json
+{
+  "entries": [
+    {
+      "angle": "competitor-analysis",
+      "file": "explore-competitor-analysis.json",
+      "created_by": "RESEARCH-001",
+      "timestamp": "2026-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+**Rules**:
+- Cache key is the exploration `angle` (normalized to kebab-case)
+- Cache entries never expire within a session
+- Any role can read cached explorations; only the creator updates them

.claude/skills/team-coordinate/specs/pipelines.md

@@ -81,3 +81,17 @@ message_types:
 ## Specs Reference
 
 - [role-spec-template.md](role-spec-template.md) — Template for generating dynamic role-specs
+- [quality-gates.md](quality-gates.md) — Quality thresholds and scoring dimensions
+- [knowledge-transfer.md](knowledge-transfer.md) — Context transfer protocols between roles
+
+## Quality Gate Integration
+
+Dynamic pipelines reference quality thresholds from [specs/quality-gates.md](quality-gates.md).
+
+| Gate Point | Trigger | Criteria Source |
+|------------|---------|----------------|
+| After artifact production | Producer role Phase 4 | Behavioral Traits in role-spec |
+| After validation tasks | Tester/analyst completion | quality-gates.md thresholds |
+| Pipeline completion | All tasks done | Aggregate scoring |
+
+Issue classification: Error (blocks) > Warning (proceed with justification) > Info (log for future).

.claude/skills/team-coordinate/specs/quality-gates.md

@@ -0,0 +1,112 @@
+# Quality Gates
+
+## 1. Quality Thresholds
+
+| Result | Score | Action |
+|--------|-------|--------|
+| Pass | >= 80% | Report completed |
+| Review | 60-79% | Report completed with warnings |
+| Fail | < 60% | Retry Phase 3 (max 2 retries) |
+
+## 2. Scoring Dimensions
+
+| Dimension | Weight | Criteria |
+|-----------|--------|----------|
+| Completeness | 25% | All required outputs present with substantive content |
+| Consistency | 25% | Terminology, formatting, cross-references are uniform |
+| Accuracy | 25% | Outputs are factually correct and verifiable against sources |
+| Depth | 25% | Sufficient detail for downstream consumers to act on deliverables |
+
+**Score** = weighted average of all dimensions (0-100 per dimension).
+
+## 3. Dynamic Role Quality Checks
+
+Quality checks vary by `output_type` (from task-analysis.json role metadata).
+
+### output_type: artifact
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Artifact exists | File written to `<session>/artifacts/` |
+| Content non-empty | Substantive content, not just headers |
+| Format correct | Expected format (MD, JSON) matches deliverable |
+| Cross-references | All references to upstream artifacts resolve |
+
+### output_type: codebase
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Files modified | Claimed files actually changed (Read to confirm) |
+| Syntax valid | No syntax errors in modified files |
+| No regressions | Existing functionality preserved |
+| Summary artifact | Implementation summary written to artifacts/ |
+
+### output_type: mixed
+
+All checks from both `artifact` and `codebase` apply.
+
+## 4. Verification Protocol
+
+Derived from Behavioral Traits in [role-spec-template.md](role-spec-template.md).
+
+| Step | Action | Required |
+|------|--------|----------|
+| 1 | Verify all claimed files exist via Read | Yes |
+| 2 | Confirm artifact written to `<session>/artifacts/` | Yes |
+| 3 | Check verification summary fields present | Yes |
+| 4 | Score against quality dimensions | Yes |
+| 5 | Apply threshold -> Pass/Review/Fail | Yes |
+
+**On Fail**: Retry Phase 3 (max 2 retries). After 2 retries, report `partial_completion`.
+
+**On Review**: Proceed with warnings logged to `<session>/wisdom/issues.md`.
+
+## 5. Code Review Dimensions
+
+For REVIEW-* or validation tasks during implementation pipelines.
+
+### Quality
+
+| Check | Severity |
+|-------|----------|
+| Empty catch blocks | Error |
+| `as any` type casts | Warning |
+| `@ts-ignore` / `@ts-expect-error` | Warning |
+| `console.log` in production code | Warning |
+| Unused imports/variables | Info |
+
+### Security
+
+| Check | Severity |
+|-------|----------|
+| Hardcoded secrets/credentials | Error |
+| SQL injection vectors | Error |
+| `eval()` or `Function()` usage | Error |
+| `innerHTML` assignment | Warning |
+| Missing input validation | Warning |
+
+### Architecture
+
+| Check | Severity |
+|-------|----------|
+| Circular dependencies | Error |
+| Deep cross-boundary imports (3+ levels) | Warning |
+| Files > 500 lines | Warning |
+| Functions > 50 lines | Info |
+
+### Requirements Coverage
+
+| Check | Severity |
+|-------|----------|
+| Core functionality implemented | Error if missing |
+| Acceptance criteria covered | Error if missing |
+| Edge cases handled | Warning |
+| Error states handled | Warning |
+
+## 6. Issue Classification
+
+| Class | Label | Action |
+|-------|-------|--------|
+| Error | Must fix | Blocks progression, must resolve before proceeding |
+| Warning | Should fix | Should resolve, can proceed with justification |
+| Info | Nice to have | Optional improvement, log for future |

.claude/skills/team-coordinate/specs/role-spec-template.md

@@ -46,6 +46,7 @@ message_types:
 | `prefix` | Yes | Task prefix to filter (e.g., RESEARCH, DRAFT, IMPL) |
 | `inner_loop` | Yes | Whether team-worker loops through same-prefix tasks |
 | `CLI tools` | No | Array of CLI tool types this role may call |
+| `output_tag` | Yes | Output tag for all messages, e.g., `[researcher]` |
 | `message_types` | Yes | Message type mapping for team_msg |
 | `message_types.success` | Yes | Type string for successful completion |
 | `message_types.error` | Yes | Type string for errors (usually "error") |
@@ -63,6 +64,29 @@ message_types:
 | `<placeholder>` notation | Use angle brackets for variable substitution |
 | Reference CLI tools by name | team-worker resolves invocation from its delegation templates |
 
+## Generated Role-Spec Structure
+
+Every generated role-spec MUST include these blocks:
+
+### Identity Block (mandatory — first section of generated spec)
+
+```
+Tag: [<role_name>] | Prefix: <PREFIX>-*
+Responsibility: <one-line from task analysis>
+```
+
+### Boundaries Block (mandatory — after Identity)
+
+```
+### MUST
+- <3-5 rules derived from task analysis>
+
+### MUST NOT
+- Execute work outside assigned prefix
+- Modify artifacts from other roles
+- Skip Phase 4 verification
+```
+
 ## Behavioral Traits
 
 All dynamically generated role-specs MUST embed these traits into Phase 4. Coordinator copies this section verbatim into every generated role-spec as a Phase 4 appendix.
@@ -93,6 +117,11 @@ Phase 4 must produce a verification summary with these fields:
 - Still fails → report `partial_completion` with details, NOT `completed`
 - Update shared state via `team_msg(operation="log", type="state_update", data={...})` after verification passes
 
+Quality thresholds from [specs/quality-gates.md](quality-gates.md):
+- Pass >= 80%: report completed
+- Review 60-79%: report completed with warnings
+- Fail < 60%: retry Phase 3 (max 2)
+
 ### Error Protocol
 
 - Primary approach fails → try alternative (different CLI tool / different tool)
@@ -139,48 +168,25 @@ Coordinator MAY reference these patterns when composing Phase 2-4 content for a
 
 ## Knowledge Transfer Protocol
 
-How context flows between roles. Coordinator MUST reference this when composing Phase 2 of any role-spec.
+Full protocol: [specs/knowledge-transfer.md](knowledge-transfer.md)
 
-### Transfer Channels
+Generated role-specs Phase 2 MUST declare which upstream sources to load.
+Generated role-specs Phase 4 MUST include state update and artifact publishing.
 
-| Channel | Scope | Mechanism | When to Use |
+---
-|---------|-------|-----------|-------------|
-| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
-| **State Updates** | Cross-role | `team_msg(operation="log", type="state_update", data={...})` / `team_msg(operation="get_state", session_id=<session-id>)` | Key findings, decisions, metadata (small, structured data) |
-| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
-| **context_accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
-| **Exploration cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
 
-### Phase 2 Context Loading (role-spec must specify)
+## Generated Role-Spec Validation
 
-Every generated role-spec Phase 2 MUST declare which upstream sources to load:
+Coordinator verifies before writing each role-spec:
 
-```
+| Check | Criteria |
-1. Extract session path from task description
+|-------|----------|
-2. Read upstream artifacts: <list which artifacts from which upstream role>
+| Frontmatter complete | All required fields present (role, prefix, inner_loop, output_tag, message_types, CLI tools) |
-3. Read cross-role state via `team_msg(operation="get_state", session_id=<session-id>)`
+| Identity block | Tag, prefix, responsibility defined |
-4. Load wisdom files for accumulated knowledge
+| Boundaries | MUST and MUST NOT rules present |
-5. For inner_loop roles: load context_accumulator from prior tasks
+| Phase 2 | Context loading sources specified |
-6. Check exploration cache before running new explorations
+| Phase 3 | Execution goal clear, not prescriptive about tools |
-```
+| Phase 4 | Behavioral Traits copied verbatim |
-
+| Error Handling | Table with 3+ scenarios |
-### State Update Convention
+| Line count | Target ~80 lines (max 120) |
-
+| No built-in overlap | No Phase 1/5, no message bus code, no consensus handling |
-Cross-role state is managed via `team_msg` state updates instead of a separate file:
-
-- **Write state**: `team_msg(operation="log", session_id=<session-id>, from=<role>, type="state_update", data={ "<role_name>": { ... } })`
-- **Read state**: `team_msg(operation="get_state", session_id=<session-id>)`
-- **Namespaced keys**: Each role writes under its own namespace key in `data`
-- **Small data only**: Key findings, decision summaries, metadata. NOT full documents
-- **State stored in**: `.msg/meta.json` (auto-managed by team_msg)
-- **Example write**:
-  ```
-  team_msg(operation="log", session_id="TC-auth-2026-03-03", from="researcher", type="state_update", data={
-    "researcher": { "key_findings": [...], "scope": "..." }
-  })
-  ```
-- **Example read**:
-  ```
-  team_msg(operation="get_state", session_id="TC-auth-2026-03-03")
-  // Returns merged state from all state_update messages
-  ```

.claude/skills/team-frontend-debug/SKILL.md

@@ -54,7 +54,7 @@ Skill(skill="team-frontend-debug", args="feature list or bug description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -63,6 +63,20 @@ Parse `$ARGUMENTS`:
 - **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
 - **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
 
+## Workspace Resolution
+
+Coordinator MUST resolve paths at Phase 2 before TeamCreate:
+
+1. Run `Bash({ command: "pwd" })` → capture `project_root` (absolute path)
+2. `skill_root = <project_root>/.claude/skills/team-frontend-debug`
+3. Store in `team-session.json`:
+   ```json
+   { "project_root": "/abs/path/to/project", "skill_root": "/abs/path/to/skill" }
+   ```
+4. All worker `role_spec` values MUST use `<skill_root>/roles/<role>/role.md` (absolute)
+
+This ensures workers spawned with `run_in_background: true` always receive an absolute, resolvable path regardless of their working directory.
+
 ## Chrome DevTools MCP Tools
 
 All browser inspection operations use Chrome DevTools MCP. Reproducer and Verifier are primary consumers.
@@ -99,14 +113,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-frontend-debug/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-frontend-debug/roles/coordinator/role.md

@@ -67,14 +67,17 @@ TEXT-LEVEL ONLY. No source code reading.
    - Test mode: base URL, feature list
    - Debug mode: bug description, URL, reproduction steps
 3. Clarify if ambiguous (AskUserQuestion)
-4. Delegate to commands/analyze.md
+4. Delegate to @commands/analyze.md
 5. Output: task-analysis.json
 6. CRITICAL: Always proceed to Phase 2, never skip team workflow
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: TFD-<slug>-<date>
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure:
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-frontend-debug`
+2. Generate session ID: TFD-<slug>-<date>
+3. Create session folder structure:
    ```
    .workflow/.team/TFD-<slug>-<date>/
    ├── team-session.json
@@ -91,7 +94,7 @@ TEXT-LEVEL ONLY. No source code reading.
 
 ## Phase 3: Create Task Chain
 
-Delegate to commands/dispatch.md:
+Delegate to @commands/dispatch.md:
 1. Read dependency graph from task-analysis.json
 2. Read specs/pipelines.md for debug-pipeline task registry
 3. Topological sort tasks
@@ -100,7 +103,7 @@ Delegate to commands/dispatch.md:
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-frontend/SKILL.md

@@ -44,7 +44,7 @@ Skill(skill="team-frontend", args="task description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -66,14 +66,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-frontend/roles/<role>/role.md
+role_spec: <skill_root>/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.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-frontend/roles/coordinator/role.md

@@ -42,7 +42,7 @@ When coordinator needs to execute a command:
 | Interrupted session | Active/paused session in .workflow/.team/FE-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/complete: load commands/monitor.md, execute handler, STOP.
+For callback/check/resume/complete: load @commands/monitor.md, execute handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -56,7 +56,7 @@ For callback/check/resume/complete: load commands/monitor.md, execute handler, S
 TEXT-LEVEL ONLY. No source code reading.
 
 1. Parse task description from $ARGUMENTS
-2. Delegate to commands/analyze.md -> produces task-analysis.json
+2. Delegate to @commands/analyze.md -> produces task-analysis.json
 3. Ask for missing parameters via AskUserQuestion:
 
    **Scope Selection**:
@@ -83,15 +83,18 @@ TEXT-LEVEL ONLY. No source code reading.
 
 ## Phase 2: Session & Team Setup
 
-1. Generate session ID: `FE-<slug>-<YYYY-MM-DD>`
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure:
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-frontend`
+3. Generate session ID: `FE-<slug>-<YYYY-MM-DD>`
+4. Create session folder structure:
 ```
 mkdir -p .workflow/.team/<session-id>/{.msg,wisdom,analysis,architecture,qa,build}
 ```
-3. TeamCreate with team name: `TeamCreate({ team_name: "frontend" })`
+5. TeamCreate with team name: `TeamCreate({ team_name: "frontend" })`
-4. Read specs/pipelines.md -> select pipeline based on scope
+6. Read specs/pipelines.md -> select pipeline based on scope
-5. Register roles in session state
+7. Register roles in session state
-6. Initialize meta.json with pipeline metadata:
+8. Initialize meta.json with pipeline metadata:
 ```typescript
 mcp__ccw-tools__team_msg({
   operation: "log", session_id: "<id>", from: "coordinator",
@@ -106,18 +109,18 @@ mcp__ccw-tools__team_msg({
   }
 })
 ```
-7. Write session.json
+9. Write session.json
 
 ## Phase 3: Task Chain Creation
 
-Delegate to commands/dispatch.md:
+Delegate to @commands/dispatch.md:
 1. Read specs/pipelines.md for selected pipeline task registry
 2. Create tasks via TaskCreate with blockedBy
 3. Update session.json
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-issue/SKILL.md

@@ -44,7 +44,7 @@ Skill(skill="team-issue", args="<issue-ids> [--mode=<mode>]")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -67,14 +67,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-issue/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: issue
 requirement: <task-description>
 inner_loop: false
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```
@@ -89,7 +89,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-issue/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: issue
@@ -97,7 +97,7 @@ requirement: <task-description>
 agent_name: <role>-<N>
 inner_loop: false
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery, owner=<role>-<N>) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-issue/roles/coordinator/role.md

@@ -49,7 +49,7 @@ When coordinator needs to execute a specific phase:
 | Interrupted session | Active session in .workflow/.team/TISL-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/consensus/adapt/complete: load `commands/monitor.md`, execute handler, STOP.
+For callback/check/resume/consensus/adapt/complete: load `@commands/monitor.md`, execute handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -95,14 +95,17 @@ TEXT-LEVEL ONLY. No source code reading.
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: `TISL-<issue-slug>-<date>`
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure:
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-issue`
+2. Generate session ID: `TISL-<issue-slug>-<date>`
+3. Create session folder structure:
    ```
    Bash("mkdir -p .workflow/.team/TISL-<slug>-<date>/{explorations,solutions,audits,queue,builds,wisdom,.msg}")
    ```
-3. TeamCreate with team name `issue`
+4. TeamCreate with team name `issue`
-4. Write session.json with pipeline_mode, issue_ids, execution_method, fix_cycles=0, max_fix_cycles=2
+5. Write session.json with pipeline_mode, issue_ids, execution_method, fix_cycles=0, max_fix_cycles=2
-5. Initialize meta.json via team_msg state_update:
+6. Initialize meta.json via team_msg state_update:
    ```
    mcp__ccw-tools__team_msg({
      operation: "log", session_id: "<id>", from: "coordinator",
@@ -110,18 +113,18 @@ TEXT-LEVEL ONLY. No source code reading.
      data: { pipeline_mode: "<mode>", pipeline_stages: ["explorer","planner","reviewer","integrator","implementer"], team_name: "issue", issue_ids: [...], fix_cycles: 0 }
    })
    ```
-6. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md)
+7. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md)
 
 ## Phase 3: Create Task Chain
 
-Delegate to commands/dispatch.md:
+Delegate to @commands/dispatch.md:
 1. Read pipeline mode and issue IDs from session.json
 2. Create tasks for selected pipeline with correct blockedBy
 3. Update session.json with task count
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-iterdev/SKILL.md

@@ -44,7 +44,7 @@ Skill(skill="team-iterdev", args="task description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -66,14 +66,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-iterdev/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: iterdev
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-iterdev/roles/coordinator/role.md

@@ -43,7 +43,7 @@ When coordinator needs to execute a command:
 | Interrupted session | Active/paused session in .workflow/.team/IDS-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/complete: load commands/monitor.md, execute handler, STOP.
+For callback/check/resume/complete: load @commands/monitor.md, execute handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -57,7 +57,7 @@ For callback/check/resume/complete: load commands/monitor.md, execute handler, S
 TEXT-LEVEL ONLY. No source code reading.
 
 1. Parse user task description from $ARGUMENTS
-2. Delegate to commands/analyze.md
+2. Delegate to @commands/analyze.md
 3. Assess complexity for pipeline selection:
 
 | Signal | Weight |
@@ -80,17 +80,20 @@ TEXT-LEVEL ONLY. No source code reading.
 
 ## Phase 2: Session & Team Setup
 
-1. Generate session ID: `IDS-<slug>-<YYYY-MM-DD>`
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure:
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-iterdev`
+2. Generate session ID: `IDS-<slug>-<YYYY-MM-DD>`
+3. Create session folder structure:
 ```
 mkdir -p .workflow/.team/<session-id>/{design,code,verify,review,wisdom}
 ```
-3. Create team: `TeamCreate({ team_name: "iterdev" })`
+4. Create team: `TeamCreate({ team_name: "iterdev" })`
-4. Read specs/pipelines.md -> select pipeline based on complexity
+5. Read specs/pipelines.md -> select pipeline based on complexity
-5. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
+6. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
-6. Write session.json
+7. Write session.json
-7. Initialize task-ledger.json
+8. Initialize task-ledger.json
-8. Initialize meta.json with pipeline metadata:
+9. Initialize meta.json with pipeline metadata:
 ```typescript
 mcp__ccw-tools__team_msg({
   operation: "log", session_id: "<id>", from: "coordinator",
@@ -106,14 +109,14 @@ mcp__ccw-tools__team_msg({
 
 ## Phase 3: Task Chain Creation
 
-Delegate to commands/dispatch.md:
+Delegate to @commands/dispatch.md:
 1. Read specs/pipelines.md for selected pipeline task registry
 2. Create tasks via TaskCreate with blockedBy
 3. Update task-ledger.json
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-lifecycle-v4/SKILL.md

@@ -49,7 +49,7 @@ Skill(skill="team-lifecycle-v4", args="task description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -71,14 +71,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-lifecycle-v4/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```
@@ -98,13 +98,13 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: supervisor
-role_spec: ~  or <project>/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md
+role_spec: <skill_root>/roles/supervisor/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>
 requirement: <task-description>
 
-Read role_spec file to load checkpoint definitions.
+Read role_spec file (@<skill_root>/roles/supervisor/role.md) to load checkpoint definitions.
 Init: load baseline context, report ready, go idle.
 Wake cycle: coordinator sends checkpoint requests via SendMessage.`
 })

.claude/skills/team-lifecycle-v4/roles/coordinator/role.md

@@ -43,7 +43,7 @@ When coordinator needs to execute a specific phase:
 | Interrupted session | Active session in .workflow/.team/TLV4-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/adapt/complete: load commands/monitor.md, execute handler, STOP.
+For callback/check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -64,19 +64,22 @@ TEXT-LEVEL ONLY. No source code reading.
 
 1. Parse task description
 2. Clarify if ambiguous (AskUserQuestion: scope, deliverables, constraints)
-3. Delegate to commands/analyze.md
+3. Delegate to @commands/analyze.md
 4. Output: task-analysis.json
 5. CRITICAL: Always proceed to Phase 2, never skip team workflow
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: TLV4-<slug>-<date>
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure
+   - `project_root` = result of `Bash({ command: "pwd" })`
-3. TeamCreate with team name
+   - `skill_root` = `<project_root>/.claude/skills/team-lifecycle-v4`
-4. Read specs/pipelines.md -> select pipeline
+2. Generate session ID: TLV4-<slug>-<date>
-5. Register roles in team-session.json
+3. Create session folder structure
-6. Initialize shared infrastructure (wisdom/*.md, explorations/cache-index.json)
+4. TeamCreate with team name
-7. Initialize pipeline via team_msg state_update:
+5. Read specs/pipelines.md -> select pipeline
+6. Register roles in team-session.json
+7. Initialize shared infrastructure (wisdom/*.md, explorations/cache-index.json)
+8. Initialize pipeline via team_msg state_update:
    ```
    mcp__ccw-tools__team_msg({
      operation: "log", session_id: "<id>", from: "coordinator",
@@ -84,15 +87,15 @@ TEXT-LEVEL ONLY. No source code reading.
      data: { pipeline_mode: "<mode>", pipeline_stages: [...], team_name: "<name>" }
    })
    ```
-8. Write team-session.json
+9. Write team-session.json
-9. Spawn resident supervisor (if pipeline has CHECKPOINT tasks AND `supervision !== false`):
+10. Spawn resident supervisor (if pipeline has CHECKPOINT tasks AND `supervision !== false`):
    - Use SKILL.md Supervisor Spawn Template (subagent_type: "team-supervisor")
    - Wait for "[supervisor] Ready" callback before proceeding to Phase 3
    - Record supervisor in active_workers with `resident: true` flag
 
 ## Phase 3: Create Task Chain
 
-Delegate to commands/dispatch.md:
+Delegate to @commands/dispatch.md:
 1. Read dependency graph from task-analysis.json
 2. Read specs/pipelines.md for selected pipeline's task registry
 3. Topological sort tasks
@@ -101,7 +104,7 @@ Delegate to commands/dispatch.md:
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-perf-opt/SKILL.md

@@ -55,7 +55,7 @@ Pipeline (Independent mode):
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -78,14 +78,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-perf-opt/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: perf-opt
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-perf-opt/roles/coordinator/role.md

@@ -54,7 +54,7 @@ When coordinator is invoked, detect invocation type:
 | Interrupted session | Active/paused session exists | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
+For callback/check/resume/complete: load `@commands/monitor.md` and execute matched handler, then STOP.
 
 ### Router Implementation
 
@@ -94,16 +94,19 @@ Triggered when an active/paused session is detected on coordinator entry.
 
 ## Phase 2: Session & Team Setup
 
-1. Create session directory with artifacts/, explorations/, wisdom/, discussions/ subdirs
+1. Resolve workspace paths (MUST do first):
-2. Write session.json with extended fields (parallel_mode, max_branches, branches, fix_cycles)
+   - `project_root` = result of `Bash({ command: "pwd" })`
-3. Initialize meta.json with pipeline metadata via team_msg
+   - `skill_root` = `<project_root>/.claude/skills/team-perf-opt`
-4. Call `TeamCreate({ team_name: "perf-opt" })`
+2. Create session directory with artifacts/, explorations/, wisdom/, discussions/ subdirs
+3. Write session.json with extended fields (parallel_mode, max_branches, branches, fix_cycles)
+4. Initialize meta.json with pipeline metadata via team_msg
+5. Call `TeamCreate({ team_name: "perf-opt" })`
 
 ---
 
 ## Phase 3: Create Task Chain
 
-Execute `commands/dispatch.md` inline (Command Execution Protocol).
+Execute `@commands/dispatch.md` inline (Command Execution Protocol).
 
 ---
 
@@ -112,14 +115,14 @@ Execute `commands/dispatch.md` inline (Command Execution Protocol).
 ### Initial Spawn
 
 Find first unblocked task and spawn its worker using SKILL.md Worker Spawn Template with:
-- `role_spec: ~  or <project>/.claude/skills/team-perf-opt/roles/<role>/role.md`
+- `role_spec: <skill_root>/roles/<role>/role.md`
 - `team_name: perf-opt`
 
 **STOP** after spawning. Wait for worker callback.
 
 ### Coordination (via monitor.md handlers)
 
-All subsequent coordination handled by `commands/monitor.md`.
+All subsequent coordination handled by `@commands/monitor.md`.
 
 ---
 

.claude/skills/team-planex/SKILL.md

@@ -43,7 +43,7 @@ Skill(skill="team-planex", args="task description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -65,7 +65,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-planex/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: planex
@@ -73,7 +73,7 @@ requirement: <task-description>
 inner_loop: <true|false>
 execution_method: <codex|gemini>
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-planex/roles/coordinator/role.md

@@ -40,7 +40,7 @@ When coordinator needs to execute a command:
 | Interrupted session | Active/paused session exists in `.workflow/.team/PEX-*` | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume: load `commands/monitor.md` and execute the appropriate handler, then STOP.
+For callback/check/resume: load `@commands/monitor.md` and execute the appropriate handler, then STOP.
 
 ### handleAdd
 
@@ -67,7 +67,7 @@ For callback/check/resume: load `commands/monitor.md` and execute the appropriat
 
 TEXT-LEVEL ONLY. No source code reading.
 
-1. Delegate to commands/analyze.md -> produces task-analysis.json
+1. Delegate to @commands/analyze.md -> produces task-analysis.json
 2. Parse arguments: Extract input type (Issue IDs / --text / --plan) and optional flags (--exec, -y)
 3. Determine execution method (see specs/pipelines.md Selection Decision Table):
    - Explicit `--exec` flag -> use specified method
@@ -78,12 +78,15 @@ TEXT-LEVEL ONLY. No source code reading.
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: `PEX-<slug>-<date>`
+1. Resolve workspace paths (MUST do first):
-2. Create session folder: `.workflow/.team/<session-id>/`
+   - `project_root` = result of `Bash({ command: "pwd" })`
-3. Create subdirectories: `artifacts/solutions/`, `wisdom/`
+   - `skill_root` = `<project_root>/.claude/skills/team-planex`
-4. Call `TeamCreate` with team name (default: "planex")
+2. Generate session ID: `PEX-<slug>-<date>`
-5. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md)
+3. Create session folder: `.workflow/.team/<session-id>/`
-6. Initialize meta.json with pipeline metadata:
+4. Create subdirectories: `artifacts/solutions/`, `wisdom/`
+5. Call `TeamCreate` with team name (default: "planex")
+6. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md)
+7. Initialize meta.json with pipeline metadata:
 ```typescript
 mcp__ccw-tools__team_msg({
   operation: "log", session_id: "<id>", from: "coordinator",
@@ -101,14 +104,14 @@ mcp__ccw-tools__team_msg({
 
 ## Phase 3: Create Task Chain
 
-Delegate to `commands/dispatch.md`:
+Delegate to `@commands/dispatch.md`:
 1. Read `roles/coordinator/commands/dispatch.md`
 2. Execute its workflow to create PLAN-001 task
 3. PLAN-001 contains input info + execution method in description
 
 ## Phase 4: Spawn-and-Stop
 
-1. Load `commands/monitor.md`
+1. Load `@commands/monitor.md`
 2. Execute `handleSpawnNext` to find ready tasks and spawn planner worker
 3. Output status summary
 4. STOP (idle, wait for worker callback)

.claude/skills/team-quality-assurance/SKILL.md

@@ -45,7 +45,7 @@ Skill(skill="team-quality-assurance", args="task description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` -> Read `roles/coordinator/role.md`, execute entry router
+- No `--role` -> `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -68,14 +68,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-quality-assurance/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: quality-assurance
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-quality-assurance/roles/coordinator/role.md

@@ -43,7 +43,7 @@ When coordinator needs to execute a specific phase:
 | Interrupted session | Active session in .workflow/.team/QA-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/adapt/complete: load commands/monitor.md, execute handler, STOP.
+For callback/check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -69,19 +69,22 @@ TEXT-LEVEL ONLY. No source code reading.
 | No explicit flag and no keyword match | full (default) |
 
 3. Clarify if ambiguous (AskUserQuestion: scope, deliverables, constraints)
-4. Delegate to commands/analyze.md
+4. Delegate to @commands/analyze.md
 5. Output: task-analysis.json
 6. CRITICAL: Always proceed to Phase 2, never skip team workflow
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: QA-<slug>-<date>
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure
+   - `project_root` = result of `Bash({ command: "pwd" })`
-3. TeamCreate with team name "quality-assurance"
+   - `skill_root` = `<project_root>/.claude/skills/team-quality-assurance`
-4. Read specs/pipelines.md -> select pipeline based on mode
+2. Generate session ID: QA-<slug>-<date>
-5. Register roles in session.json
+3. Create session folder structure
-6. Initialize shared infrastructure (wisdom/*.md)
+4. TeamCreate with team name "quality-assurance"
-7. Initialize pipeline via team_msg state_update:
+5. Read specs/pipelines.md -> select pipeline based on mode
+6. Register roles in session.json
+7. Initialize shared infrastructure (wisdom/*.md)
+8. Initialize pipeline via team_msg state_update:
    ```
    mcp__ccw-tools__team_msg({
      operation: "log", session_id: "<id>", from: "coordinator",
@@ -100,11 +103,11 @@ TEXT-LEVEL ONLY. No source code reading.
      }
    })
    ```
-8. Write session.json
+9. Write session.json
 
 ## Phase 3: Create Task Chain
 
-Delegate to commands/dispatch.md:
+Delegate to @commands/dispatch.md:
 1. Read dependency graph from task-analysis.json
 2. Read specs/pipelines.md for selected pipeline's task registry
 3. Topological sort tasks
@@ -113,7 +116,7 @@ Delegate to commands/dispatch.md:
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-review/SKILL.md

@@ -43,7 +43,7 @@ Skill(skill="team-review", args="task description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` -> Read `roles/coordinator/role.md`, execute entry router
+- No `--role` -> `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -66,14 +66,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-review/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: review
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-review/roles/coordinator/role.md

@@ -43,7 +43,7 @@ When coordinator needs to execute a specific phase:
 | Interrupted session | Active session in .workflow/.team/RV-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/adapt/complete: load commands/monitor.md, execute handler, STOP.
+For callback/check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -67,17 +67,20 @@ TEXT-LEVEL ONLY. No source code reading.
 
 2. Extract parameters: target, dimensions, auto-confirm flag
 3. Clarify if ambiguous (AskUserQuestion for target path)
-4. Delegate to commands/analyze.md
+4. Delegate to @commands/analyze.md
 5. Output: task-analysis.json
 6. CRITICAL: Always proceed to Phase 2, never skip team workflow
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: RV-<slug>-<date>
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure (scan/, review/, fix/, wisdom/)
+   - `project_root` = result of `Bash({ command: "pwd" })`
-3. TeamCreate with team name "review"
+   - `skill_root` = `<project_root>/.claude/skills/team-review`
-4. Read specs/pipelines.md -> select pipeline based on mode
+2. Generate session ID: RV-<slug>-<date>
-5. Initialize pipeline via team_msg state_update:
+3. Create session folder structure (scan/, review/, fix/, wisdom/)
+4. TeamCreate with team name "review"
+5. Read specs/pipelines.md -> select pipeline based on mode
+6. Initialize pipeline via team_msg state_update:
    ```
    mcp__ccw-tools__team_msg({
      operation: "log", session_id: "<id>", from: "coordinator",
@@ -92,18 +95,18 @@ TEXT-LEVEL ONLY. No source code reading.
      }
    })
    ```
-6. Write session meta.json
+7. Write session meta.json
 
 ## Phase 3: Create Task Chain
 
-Delegate to commands/dispatch.md:
+Delegate to @commands/dispatch.md:
 1. Read specs/pipelines.md for selected pipeline's task registry
 2. Create tasks via TaskCreate with blockedBy
 3. Update session meta.json with pipeline.tasks_total
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-roadmap-dev/SKILL.md

@@ -49,7 +49,7 @@ Multi-phase:
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -72,14 +72,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-roadmap-dev/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: roadmap-dev
 requirement: <task-description>
 inner_loop: true
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```
@@ -148,7 +148,7 @@ AskUserQuestion({
 |----------|------------|
 | Unknown --role value | Error with role registry list |
 | Role file not found | Error with expected path (roles/{name}/role.md) |
-| project-tech.json missing | Coordinator invokes /workflow:init |
+| project-tech.json missing | Coordinator invokes /workflow:spec:setup  |
 | Phase verification fails with gaps | Coordinator triggers gap closure loop (max 3 iterations) |
 | Max gap closure iterations (3) | Report to user, ask for guidance |
 | Worker crash | Respawn worker, reassign task |

.claude/skills/team-roadmap-dev/roles/coordinator/role.md

@@ -65,14 +65,14 @@ When coordinator is invoked, detect invocation type:
 | Detection | Condition | Handler |
 |-----------|-----------|---------|
 | Worker callback | Message contains role tag [planner], [executor], [verifier] | -> handleCallback |
-| Resume mode | Arguments contain `--resume` | -> commands/resume.md: load session, re-enter monitor |
+| Resume mode | Arguments contain `--resume` | -> @commands/resume.md: load session, re-enter monitor |
 | Status check | Arguments contain "check" or "status" | -> handleCheck |
 | Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
 | Pipeline complete | All tasks have status "completed" | -> handleComplete |
 | Interrupted session | Active/paused session exists | -> Phase 0 (Session Resume Check) |
 | New session | None of above | -> Phase 1 (Init Prerequisites) |
 
-For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
+For callback/check/resume/complete: load `@commands/monitor.md` and execute matched handler, then STOP.
 
 ### Router Implementation
 
@@ -86,7 +86,7 @@ For callback/check/resume/complete: load `commands/monitor.md` and execute match
 
 3. **Route to handler**:
    - For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
-   - For --resume: Read `commands/resume.md`, execute resume flow
+   - For --resume: Read `@commands/resume.md`, execute resume flow
    - For Phase 0: Execute Session Resume Check
    - For Phase 1: Execute Init Prerequisites below
 
@@ -160,7 +160,7 @@ Bash("ccw team log --session-id <session-id> --from coordinator --type <type> --
 **Workflow**:
 
 1. Parse arguments for flags: `--resume`, `--yes`, task description
-2. If `--resume` present -> load commands/resume.md and execute resume flow
+2. If `--resume` present -> load @commands/resume.md and execute resume flow
 3. Ensure project-tech.json exists:
 
 | Condition | Action |
@@ -178,7 +178,7 @@ Bash("ccw team log --session-id <session-id> --from coordinator --type <type> --
 
 **Objective**: Discuss roadmap with user and generate phase plan.
 
-Delegate to `commands/roadmap-discuss.md`:
+Delegate to `@commands/roadmap-discuss.md`:
 
 | Step | Action |
 |------|--------|
@@ -198,9 +198,13 @@ Delegate to `commands/roadmap-discuss.md`:
 
 **Workflow**:
 
-1. Call `TeamCreate({ team_name: "roadmap-dev" })`
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-roadmap-dev`
 
-2. Initialize meta.json with pipeline metadata:
+2. Call `TeamCreate({ team_name: "roadmap-dev" })`
+
+3. Initialize meta.json with pipeline metadata:
 ```typescript
 // Use team_msg to write pipeline metadata to .msg/meta.json
 mcp__ccw-tools__team_msg({
@@ -218,8 +222,8 @@ mcp__ccw-tools__team_msg({
 })
 ```
 
-3. Spawn worker roles (see SKILL.md Coordinator Spawn Template)
+4. Spawn worker roles (see SKILL.md Coordinator Spawn Template)
-4. Load `commands/dispatch.md` for task chain creation
+5. Load `@commands/dispatch.md` for task chain creation
 
 | Step | Action |
 |------|--------|
@@ -242,7 +246,7 @@ mcp__ccw-tools__team_msg({
 - User can use "check" / "resume" to manually advance
 - Coordinator does one operation per invocation, then STOPS
 
-Delegate to `commands/monitor.md`:
+Delegate to `@commands/monitor.md`:
 
 | Step | Action |
 |------|--------|
@@ -284,7 +288,7 @@ Delegate to `commands/monitor.md`:
 
 | Scenario | Resolution |
 |----------|------------|
-| project-tech.json missing | Invoke /workflow:init automatically |
+| project-tech.json missing | Invoke /workflow:spec:setup  automatically |
 | User cancels roadmap discussion | Save session state, exit gracefully |
 | Planner fails | Retry once, then ask user for guidance |
 | Executor fails on plan | Mark plan as failed, continue with next |

.claude/skills/team-roadmap-dev/specs/team-config.json

@@ -85,7 +85,7 @@
   "init_prerequisite": {
     "required_files": [".workflow/project-tech.json"],
     "optional_files": [".workflow/specs/*.md"],
-    "init_command": "/workflow:init"
+    "init_command": "/workflow:spec:setup "
   },
   "_metadata": {
     "created_at": "2026-02-24",

.claude/skills/team-tech-debt/SKILL.md

@@ -45,7 +45,7 @@ Skill(skill="team-tech-debt", args="task description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -68,14 +68,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-tech-debt/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: tech-debt
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-tech-debt/roles/coordinator/role.md

@@ -44,7 +44,7 @@ When coordinator needs to execute a command (analyze, dispatch, monitor):
 | Interrupted session | Active/paused session exists in .workflow/.team/TD-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/complete: load `commands/monitor.md`, execute matched handler, STOP.
+For callback/check/resume/complete: load `@commands/monitor.md`, execute matched handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -70,19 +70,22 @@ TEXT-LEVEL ONLY. No source code reading.
 3. Ask for missing parameters (skip if auto mode):
    - AskUserQuestion: Tech Debt Target (自定义 / 全项目扫描 / 完整治理 / 定向修复)
 4. Store: mode, scope, focus, constraints
-5. Delegate to commands/analyze.md -> output task-analysis context
+5. Delegate to @commands/analyze.md -> output task-analysis context
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: `TD-<slug>-<YYYY-MM-DD>`
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure (scan/, assessment/, plan/, fixes/, validation/, wisdom/)
+   - `project_root` = result of `Bash({ command: "pwd" })`
-3. Initialize .msg/meta.json via team_msg state_update with pipeline metadata
+   - `skill_root` = `<project_root>/.claude/skills/team-tech-debt`
-4. TeamCreate(team_name="tech-debt")
+2. Generate session ID: `TD-<slug>-<YYYY-MM-DD>`
-5. Do NOT spawn workers yet - deferred to Phase 4
+3. Create session folder structure (scan/, assessment/, plan/, fixes/, validation/, wisdom/)
+4. Initialize .msg/meta.json via team_msg state_update with pipeline metadata
+5. TeamCreate(team_name="tech-debt")
+6. Do NOT spawn workers yet - deferred to Phase 4
 
 ## Phase 3: Create Task Chain
 
-Delegate to commands/dispatch.md. Task chain by mode:
+Delegate to @commands/dispatch.md. Task chain by mode:
 
 | Mode | Task Chain |
 |------|------------|
@@ -92,7 +95,7 @@ Delegate to commands/dispatch.md. Task chain by mode:
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-testing/SKILL.md

@@ -44,7 +44,7 @@ Skill(skill="team-testing", args="task description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` -> Read `roles/coordinator/role.md`, execute entry router
+- No `--role` -> `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -67,14 +67,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-testing/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: testing
 requirement: <task-description>
 inner_loop: <true|false>
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-testing/roles/coordinator/role.md

@@ -42,7 +42,7 @@ When coordinator needs to execute a specific phase:
 | Interrupted session | Active session in .workflow/.team/TST-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/adapt/complete: load commands/monitor.md, execute handler, STOP.
+For callback/check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -69,17 +69,20 @@ TEXT-LEVEL ONLY. No source code reading.
 | Otherwise | comprehensive |
 
 4. Clarify if ambiguous (AskUserQuestion for scope)
-5. Delegate to commands/analyze.md
+5. Delegate to @commands/analyze.md
 6. Output: task-analysis.json
 7. CRITICAL: Always proceed to Phase 2, never skip team workflow
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: TST-<slug>-<date>
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure (strategy/, tests/L1-unit/, tests/L2-integration/, tests/L3-e2e/, results/, analysis/, wisdom/)
+   - `project_root` = result of `Bash({ command: "pwd" })`
-3. TeamCreate with team name "testing"
+   - `skill_root` = `<project_root>/.claude/skills/team-testing`
-4. Read specs/pipelines.md -> select pipeline based on mode
+2. Generate session ID: TST-<slug>-<date>
-5. Initialize pipeline via team_msg state_update:
+3. Create session folder structure (strategy/, tests/L1-unit/, tests/L2-integration/, tests/L3-e2e/, results/, analysis/, wisdom/)
+4. TeamCreate with team name "testing"
+5. Read specs/pipelines.md -> select pipeline based on mode
+6. Initialize pipeline via team_msg state_update:
    ```
    mcp__ccw-tools__team_msg({
      operation: "log", session_id: "<id>", from: "coordinator",
@@ -93,11 +96,11 @@ TEXT-LEVEL ONLY. No source code reading.
      }
    })
    ```
-6. Write session.json
+7. Write session.json
 
 ## Phase 3: Create Task Chain
 
-Delegate to commands/dispatch.md:
+Delegate to @commands/dispatch.md:
 1. Read specs/pipelines.md for selected pipeline's task registry
 2. Topological sort tasks
 3. Create tasks via TaskCreate with blockedBy
@@ -105,7 +108,7 @@ Delegate to commands/dispatch.md:
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to commands/monitor.md#handleSpawnNext:
+Delegate to @commands/monitor.md#handleSpawnNext:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-uidesign/SKILL.md

@@ -44,7 +44,7 @@ Skill(skill="team-uidesign", args="task description")
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -67,14 +67,14 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-uidesign/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: uidesign
 requirement: <task-description>
 inner_loop: false
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-uidesign/roles/coordinator/role.md

@@ -45,7 +45,7 @@ When coordinator needs to execute a command (analyze, dispatch, monitor):
 | Interrupted session | Active/paused session exists in .workflow/.team/UDS-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/adapt/complete: load `commands/monitor.md`, execute matched handler, STOP.
+For callback/check/resume/adapt/complete: load `@commands/monitor.md`, execute matched handler, STOP.
 
 ## Phase 0: Session Resume Check
 
@@ -84,13 +84,16 @@ TEXT-LEVEL ONLY. No source code reading.
      ]
    })
    ```
-4. Delegate to `commands/analyze.md` -> output scope context
+4. Delegate to `@commands/analyze.md` -> output scope context
 5. Record: pipeline_mode, industry, complexity
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: `UDS-<slug>-<YYYY-MM-DD>`
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure:
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-uidesign`
+2. Generate session ID: `UDS-<slug>-<YYYY-MM-DD>`
+3. Create session folder structure:
    ```
    .workflow/.team/UDS-<slug>-<date>/research/
    .workflow/.team/UDS-<slug>-<date>/design/component-specs/
@@ -101,13 +104,13 @@ TEXT-LEVEL ONLY. No source code reading.
    .workflow/.team/UDS-<slug>-<date>/wisdom/
    .workflow/.team/UDS-<slug>-<date>/.msg/
    ```
-3. Initialize `.msg/meta.json` via team_msg state_update with pipeline metadata
+4. Initialize `.msg/meta.json` via team_msg state_update with pipeline metadata
-4. TeamCreate(team_name="uidesign")
+5. TeamCreate(team_name="uidesign")
-5. Do NOT spawn workers yet - deferred to Phase 4
+6. Do NOT spawn workers yet - deferred to Phase 4
 
 ## Phase 3: Create Task Chain
 
-Delegate to `commands/dispatch.md`. Task chains by mode:
+Delegate to `@commands/dispatch.md`. Task chains by mode:
 
 | Mode | Task Chain |
 |------|------------|
@@ -117,7 +120,7 @@ Delegate to `commands/dispatch.md`. Task chains by mode:
 
 ## Phase 4: Spawn-and-Stop
 
-Delegate to `commands/monitor.md#handleSpawnNext`:
+Delegate to `@commands/monitor.md#handleSpawnNext`:
 1. Find ready tasks (pending + blockedBy resolved)
 2. Spawn team-worker agents (see SKILL.md Spawn Template)
 3. Output status summary

.claude/skills/team-ultra-analyze/SKILL.md

@@ -52,7 +52,7 @@ Pipeline (Quick mode):
 
 Parse `$ARGUMENTS`:
 - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → Read `roles/coordinator/role.md`, execute entry router
+- No `--role` → `@roles/coordinator/role.md`, execute entry router
 
 ## Shared Constants
 
@@ -75,7 +75,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: ~  or <project>/.claude/skills/team-ultra-analyze/roles/<role>/role.md
+role_spec: <skill_root>/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: ultra-analyze
@@ -83,7 +83,7 @@ requirement: <topic-description>
 agent_name: <agent-name>
 inner_loop: false
 
-Read role_spec file to load Phase 2-4 domain instructions.
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
 Execute built-in Phase 1 (task discovery, owner=<agent-name>) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

.claude/skills/team-ultra-analyze/roles/coordinator/role.md

@@ -51,7 +51,7 @@ When coordinator is invoked, detect invocation type:
 | Interrupted session | Active/paused session exists | -> Phase 0 |
 | New session | None of above | -> Phase 1 |
 
-For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
+For callback/check/resume/complete: load `@commands/monitor.md` and execute matched handler, then STOP.
 
 ### Router Implementation
 
@@ -95,15 +95,18 @@ TEXT-LEVEL ONLY. No source code reading.
 
 1. Parse user task description from $ARGUMENTS
 2. Extract explicit settings: `--mode`, scope, focus areas
-3. Delegate to `commands/analyze.md` for signal detection and pipeline mode selection
+3. Delegate to `@commands/analyze.md` for signal detection and pipeline mode selection
 4. **Interactive clarification** (non-auto mode): AskUserQuestion for focus, perspectives, depth.
 
 ---
 
 ## Phase 2: Create Team + Initialize Session
 
-1. Generate session ID: `UAN-{slug}-{YYYY-MM-DD}`
+1. Resolve workspace paths (MUST do first):
-2. Create session folder structure:
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-ultra-analyze`
+3. Generate session ID: `UAN-{slug}-{YYYY-MM-DD}`
+4. Create session folder structure:
 
 ```
 .workflow/.team/UAN-{slug}-{date}/
@@ -117,8 +120,8 @@ TEXT-LEVEL ONLY. No source code reading.
     +-- learnings.md, decisions.md, conventions.md, issues.md
 ```
 
-3. Write session.json with mode, requirement, timestamp
+5. Write session.json with mode, requirement, timestamp
-4. Initialize .msg/meta.json with pipeline metadata via team_msg:
+6. Initialize .msg/meta.json with pipeline metadata via team_msg:
 ```typescript
 mcp__ccw-tools__team_msg({
   operation: "log",
@@ -134,13 +137,13 @@ mcp__ccw-tools__team_msg({
   }
 })
 ```
-5. Call `TeamCreate({ team_name: "ultra-analyze" })`
+7. Call `TeamCreate({ team_name: "ultra-analyze" })`
 
 ---
 
 ## Phase 3: Create Task Chain
 
-Execute `commands/dispatch.md` inline (Command Execution Protocol):
+Execute `@commands/dispatch.md` inline (Command Execution Protocol):
 1. Read `roles/coordinator/commands/dispatch.md`
 2. Follow dispatch Phase 2 -> Phase 3 -> Phase 4
 3. Result: all pipeline tasks created with correct blockedBy dependencies
@@ -152,7 +155,7 @@ Execute `commands/dispatch.md` inline (Command Execution Protocol):
 ### Initial Spawn
 
 Find first unblocked tasks and spawn their workers. Use SKILL.md Worker Spawn Template with:
-- `role_spec: ~  or <project>/.claude/skills/team-ultra-analyze/roles/<role>/role.md`
+- `role_spec: <skill_root>/roles/<role>/role.md`
 - `team_name: ultra-analyze`
 - `inner_loop: false`