chore: release v7.2.5

Update DDD commands (doc-generate, doc-refresh, sync), workflow commands
(session/sync, spec/add, spec/setup, spec/load), ccw specs, personal
preferences, and add generate-ddd-docs tool.

.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
 

.claude/agents/team-worker.md

@@ -8,12 +8,12 @@ description: |
 
   Examples:
   - Context: Coordinator spawns analyst worker
-    user: "role: analyst\nrole_spec: .claude/skills/team-lifecycle/role-specs/analyst.md\nsession: .workflow/.team/TLS-xxx"
+    user: "role: analyst\nrole_spec: ~  or <project>/.claude/skills/team-lifecycle/role-specs/analyst.md\nsession: .workflow/.team/TLS-xxx"
     assistant: "Loading role spec, discovering RESEARCH-* tasks, executing Phase 2-4 domain logic"
     commentary: Agent parses prompt, loads role spec, runs built-in Phase 1 then role-specific Phase 2-4 then built-in Phase 5
 
   - Context: Coordinator spawns writer worker with inner loop
-    user: "role: writer\nrole_spec: .claude/skills/team-lifecycle/role-specs/writer.md\ninner_loop: true"
+    user: "role: writer\nrole_spec: ~  or <project>/.claude/skills/team-lifecycle/role-specs/writer.md\ninner_loop: true"
     assistant: "Loading role spec, processing all DRAFT-* tasks in inner loop"
     commentary: Agent detects inner_loop=true, loops Phase 1-5 for each same-prefix task
 color: green

.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/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/team-arch-opt/SKILL.md

@@ -66,7 +66,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-arch-opt/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-arch-opt/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: arch-opt

.claude/skills/team-arch-opt/roles/coordinator/commands/monitor.md

@@ -95,7 +95,7 @@ Find ready tasks, spawn workers, STOP.
         run_in_background: true,
         prompt: `## Role Assignment
       role: <role>
-      role_spec: .claude/skills/team-arch-opt/roles/<role>/role.md
+      role_spec: ~  or <project>/.claude/skills/team-arch-opt/roles/<role>/role.md
       session: <session-folder>
       session_id: <session-id>
       team_name: arch-opt

.claude/skills/team-arch-opt/specs/team-config.json

@@ -3,7 +3,7 @@
   "team_name": "arch-opt",
   "team_display_name": "Architecture Optimization",
   "skill_name": "team-arch-opt",
-  "skill_path": ".claude/skills/team-arch-opt/",
+  "skill_path": "~  or <project>/.claude/skills/team-arch-opt/",
   "pipeline_type": "Linear with Review-Fix Cycle (Parallel-Capable)",
   "completion_action": "interactive",
   "has_inline_discuss": true,

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

@@ -65,7 +65,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-brainstorm/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-brainstorm/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: brainstorm
@@ -89,7 +89,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: ideator
-role_spec: .claude/skills/team-brainstorm/roles/ideator/role.md
+role_spec: ~  or <project>/.claude/skills/team-brainstorm/roles/ideator/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: brainstorm

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

@@ -91,7 +91,7 @@ Find ready tasks, spawn workers, STOP.
         run_in_background: true,
         prompt: `## Role Assignment
       role: <role>
-      role_spec: .claude/skills/team-brainstorm/roles/<role>/role.md
+      role_spec: ~  or <project>/.claude/skills/team-brainstorm/roles/<role>/role.md
       session: <session-folder>
       session_id: <session-id>
       team_name: brainstorm

.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

.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-designer/SKILL.md

@@ -32,7 +32,7 @@ Generate complete team skills following the team-lifecycle-v4 architecture: SKIL
 ## Key Design Principles
 
 1. **v4 Architecture Compliance**: Generated skills follow team-lifecycle-v4 pattern — SKILL.md = pure router, beat model = coordinator-only, unified structure (roles/ + specs/ + templates/)
-2. **Golden Sample Reference**: Uses `team-lifecycle-v4` as reference implementation at `.claude/skills/team-lifecycle-v4/`
+2. **Golden Sample Reference**: Uses `team-lifecycle-v4` as reference implementation at `~  or <project>/.claude/skills/team-lifecycle-v4/`
 3. **Intelligent Commands Distribution**: Auto-determines which roles need `commands/` (2+ commands) vs inline logic (1 command)
 4. **team-worker Compatibility**: Role.md files include correct YAML frontmatter for team-worker agent parsing
 
@@ -76,7 +76,7 @@ Return:
 
 ## Golden Sample
 
-Generated skills follow the architecture of `.claude/skills/team-lifecycle-v4/`:
+Generated skills follow the architecture of `~  or <project>/.claude/skills/team-lifecycle-v4/`:
 
 ```
 .claude/skills/<skill-name>/

.claude/skills/team-designer/phases/03-content-generation.md

@@ -12,7 +12,7 @@ Generate all role files, specs, and templates based on `teamConfig` and the gene
 
 ## Golden Sample Reference
 
-Read the golden sample at `.claude/skills/team-lifecycle-v4/` for each file type before generating. This ensures pattern fidelity.
+Read the golden sample at `~  or <project>/.claude/skills/team-lifecycle-v4/` for each file type before generating. This ensures pattern fidelity.
 
 ## Step 3.1: Generate Coordinator
 
@@ -305,7 +305,7 @@ For each additional spec in `teamConfig.specs` (beyond pipelines), generate doma
 
 For each template in `teamConfig.templates`:
 
-1. Check if golden sample has matching template at `.claude/skills/team-lifecycle-v4/templates/`
+1. Check if golden sample has matching template at `~  or <project>/.claude/skills/team-lifecycle-v4/templates/`
 2. If exists: copy and adapt for new domain
 3. If not: generate domain-appropriate template structure
 

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

@@ -193,7 +193,7 @@ Agent({
   name: "<role>",
   team_name: "<team_name>",
   prompt: `role: <role>
-role_spec: .claude/skills/team-edict/role-specs/<role>.md
+role_spec: ~  or <project>/.claude/skills/team-edict/role-specs/<role>.md
 session: <session_path>
 session_id: <session_id>
 team_name: <team_name>

.claude/skills/team-edict/role-specs/xingbu.md

@@ -24,7 +24,7 @@ team_msg(operation="log", session_id=<session_id>, from="xingbu",
 
 1. 读取当前任务（QA-* task description）
 2. 读取 `<session_path>/plan/dispatch-plan.md` 获取验收标准
-3. 读取 `.claude/skills/team-edict/specs/quality-gates.md` 获取质量门标准
+3. 读取 `~  or <project>/.claude/skills/team-edict/specs/quality-gates.md` 获取质量门标准
 4. 读取被测部门（通常为工部）的产出报告
 
 ## Phase 3: 质量审查

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

@@ -18,7 +18,7 @@
 
 ```javascript
 // Phase 0/1 启动时执行
-Read(".claude/skills/team-edict/specs/team-config.json")  // 加载路由规则和artifact路径
+Read("~  or <project>/.claude/skills/team-edict/specs/team-config.json")  // 加载路由规则和artifact路径
 ```
 
 ---
@@ -106,7 +106,7 @@ Read(".claude/skills/team-edict/specs/team-config.json")  // 加载路由规则
      name: "zhongshu",
      team_name: <team_name>,
      prompt: `role: zhongshu
-role_spec: .claude/skills/team-edict/role-specs/zhongshu.md
+role_spec: ~  or <project>/.claude/skills/team-edict/role-specs/zhongshu.md
 session: <session_path>
 session_id: <session_id>
 team_name: <team_name>
@@ -138,7 +138,7 @@ inner_loop: false`,
      name: "menxia",
      team_name: <team_name>,
      prompt: `role: menxia
-role_spec: .claude/skills/team-edict/role-specs/menxia.md
+role_spec: ~  or <project>/.claude/skills/team-edict/role-specs/menxia.md
 session: <session_path>
 session_id: <session_id>
 team_name: <team_name>
@@ -177,7 +177,7 @@ inner_loop: false`,
      name: "shangshu",
      team_name: <team_name>,
      prompt: `role: shangshu
-role_spec: .claude/skills/team-edict/role-specs/shangshu.md
+role_spec: ~  or <project>/.claude/skills/team-edict/role-specs/shangshu.md
 session: <session_path>
 session_id: <session_id>
 team_name: <team_name>

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

@@ -99,7 +99,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-frontend-debug/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-frontend-debug/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>

.claude/skills/team-frontend-debug/roles/coordinator/commands/dispatch.md

@@ -29,7 +29,7 @@ EXPECTED: <artifact path> + <quality criteria>
 CONSTRAINTS: <scope limits>
 ---
 InnerLoop: <true|false>
-RoleSpec: .claude/skills/team-frontend-debug/roles/<role>/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/<role>/role.md
 ```
 
 ---
@@ -55,7 +55,7 @@ EXPECTED: <session>/artifacts/TEST-001-report.md + <session>/artifacts/TEST-001-
 CONSTRAINTS: Use Chrome DevTools MCP only | Do not modify any code | Test all listed features
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-frontend-debug/roles/tester/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/tester/role.md
 ```
 
 ### ANALYZE-001 (Test Mode): Analyze Discovered Issues
@@ -75,7 +75,7 @@ EXPECTED: <session>/artifacts/ANALYZE-001-rca.md with root causes for all issues
 CONSTRAINTS: Read-only analysis | Skip low-severity warnings unless user requests
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/analyzer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/analyzer/role.md
 ```
 
 **Conditional**: If TEST-001 reports zero issues → skip ANALYZE-001, FIX-001, VERIFY-001. Pipeline completes.
@@ -96,7 +96,7 @@ EXPECTED: Modified source files + <session>/artifacts/FIX-001-changes.md
 CONSTRAINTS: Minimal changes per issue | Follow existing code style
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-frontend-debug/roles/fixer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/fixer/role.md
 ```
 
 ### VERIFY-001 (Test Mode): Re-Test After Fix
@@ -117,7 +117,7 @@ EXPECTED: <session>/artifacts/VERIFY-001-report.md with pass/fail per previously
 CONSTRAINTS: Only re-test failed scenarios | Use Chrome DevTools MCP only
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/verifier/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/verifier/role.md
 ```
 
 ---
@@ -143,7 +143,7 @@ EXPECTED: <session>/evidence/ directory with all captures + reproduction report
 CONSTRAINTS: Use Chrome DevTools MCP only | Do not modify any code
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/reproducer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/reproducer/role.md
 ```
 
 ### ANALYZE-001 (Debug Mode): Root Cause Analysis
@@ -164,7 +164,7 @@ EXPECTED: <session>/artifacts/ANALYZE-001-rca.md with root cause, file:line, fix
 CONSTRAINTS: Read-only analysis | Request more evidence if inconclusive
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/analyzer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/analyzer/role.md
 ```
 
 ### FIX-001 (Debug Mode): Code Fix
@@ -183,7 +183,7 @@ EXPECTED: Modified source files + <session>/artifacts/FIX-001-changes.md
 CONSTRAINTS: Minimal changes | Follow existing code style | No breaking changes
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-frontend-debug/roles/fixer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/fixer/role.md
 ```
 
 ### VERIFY-001 (Debug Mode): Fix Verification
@@ -203,7 +203,7 @@ EXPECTED: <session>/artifacts/VERIFY-001-report.md with pass/fail verdict
 CONSTRAINTS: Use Chrome DevTools MCP only | Same steps as reproduction
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/verifier/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/verifier/role.md
 ```
 
 ---
@@ -219,7 +219,7 @@ TASK: <specific evidence requests from Analyzer>
 CONTEXT: Session + Analyzer request
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-frontend-debug/roles/reproducer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/reproducer/role.md
 ```
 
 ### FIX-002 (Either Mode): Re-Fix After Failed Verification
@@ -231,7 +231,7 @@ TASK: Review VERIFY-001 failure details, apply corrective fix
 CONTEXT: Session + VERIFY-001-report.md
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-frontend-debug/roles/fixer/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/fixer/role.md
 ```
 
 ## Conditional Skip Rules

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

@@ -66,7 +66,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-frontend/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-frontend/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: frontend

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

@@ -129,7 +129,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-frontend/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-frontend/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: frontend

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

@@ -67,7 +67,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-issue/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-issue/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: issue
@@ -89,7 +89,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-issue/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-issue/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: issue

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

@@ -101,7 +101,7 @@ Find ready tasks, spawn workers, STOP.
         run_in_background: true,
         prompt: `## Role Assignment
       role: <role>
-      role_spec: .claude/skills/team-issue/roles/<role>/role.md
+      role_spec: ~  or <project>/.claude/skills/team-issue/roles/<role>/role.md
       session: <session-folder>
       session_id: <session-id>
       team_name: issue
@@ -133,7 +133,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-issue/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-issue/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: issue

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

@@ -66,7 +66,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-iterdev/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-iterdev/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: iterdev

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

@@ -101,7 +101,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-iterdev/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-iterdev/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: iterdev

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

@@ -71,7 +71,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-lifecycle-v4/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-lifecycle-v4/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>
@@ -98,7 +98,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: supervisor
-role_spec: .claude/skills/team-lifecycle-v4/roles/supervisor/role.md
+role_spec: ~  or <project>/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>

.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md

@@ -29,7 +29,7 @@ EXPECTED: <artifact path> + <quality criteria>
 CONSTRAINTS: <scope limits>
 ---
 InnerLoop: <true|false>
-RoleSpec: .claude/skills/team-lifecycle-v4/roles/<role>/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-lifecycle-v4/roles/<role>/role.md
 ```
 
 ## InnerLoop Flag Rules
@@ -45,7 +45,7 @@ CHECKPOINT tasks are dispatched like regular tasks but handled differently at sp
 - Owner: supervisor
 - **NOT spawned as team-worker** — coordinator wakes the resident supervisor via SendMessage
 - If `supervision: false` in team-session.json, skip creating CHECKPOINT tasks entirely
-- RoleSpec in description: `.claude/skills/team-lifecycle-v4/roles/supervisor/role.md`
+- RoleSpec in description: `~  or <project>/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md`
 
 ## Dependency Validation
 

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

@@ -78,7 +78,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-perf-opt/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-perf-opt/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: perf-opt

.claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md

@@ -73,7 +73,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-perf-opt/role-specs/<role>.md
+role_spec: ~  or <project>/.claude/skills/team-perf-opt/role-specs/<role>.md
 session: <session-folder>
 session_id: <session-id>
 team_name: perf-opt

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

@@ -112,7 +112,7 @@ 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: .claude/skills/team-perf-opt/roles/<role>/role.md`
+- `role_spec: ~  or <project>/.claude/skills/team-perf-opt/roles/<role>/role.md`
 - `team_name: perf-opt`
 
 **STOP** after spawning. Wait for worker callback.

.claude/skills/team-perf-opt/specs/team-config.json

@@ -3,7 +3,7 @@
   "team_name": "perf-opt",
   "team_display_name": "Performance Optimization",
   "skill_name": "team-perf-opt",
-  "skill_path": ".claude/skills/team-perf-opt/",
+  "skill_path": "~  or <project>/.claude/skills/team-perf-opt/",
   "worker_agent": "team-worker",
   "pipeline_type": "Linear with Review-Fix Cycle (Parallel-Capable)",
   "completion_action": "interactive",

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

@@ -65,7 +65,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-planex/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-planex/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: planex

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

@@ -125,7 +125,7 @@ Collect task states from TaskList()
            run_in_background: true,
            prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-planex/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-planex/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: <team-name>

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

@@ -68,7 +68,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-quality-assurance/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-quality-assurance/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: quality-assurance

.claude/skills/team-quality-assurance/roles/coordinator/commands/dispatch.md

@@ -30,7 +30,7 @@ EXPECTED: <artifact path> + <quality criteria>
 CONSTRAINTS: <scope limits>
 ---
 InnerLoop: <true|false>
-RoleSpec: .claude/skills/team-quality-assurance/roles/<role>/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-quality-assurance/roles/<role>/role.md
 ```
 
 ## Pipeline Task Registry

.claude/skills/team-quality-assurance/roles/coordinator/commands/monitor.md

@@ -59,7 +59,7 @@ EXPECTED: Fixed test files | Improved coverage
 CONSTRAINTS: Only modify test files | No source changes
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-quality-assurance/roles/generator/role.md"
+RoleSpec: ~  or <project>/.claude/skills/team-quality-assurance/roles/generator/role.md"
 })
 TaskCreate({
   subject: "QARUN-gc-<round>: Re-execute <layer> (GC #<round>)",
@@ -72,7 +72,7 @@ EXPECTED: <session>/results/run-<layer>-gc-<round>.json
 CONSTRAINTS: Read-only execution
 ---
 InnerLoop: false
-RoleSpec: .claude/skills/team-quality-assurance/roles/executor/role.md",
+RoleSpec: ~  or <project>/.claude/skills/team-quality-assurance/roles/executor/role.md",
   blockedBy: ["QAGEN-fix-<round>"]
 })
 ```
@@ -149,7 +149,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-quality-assurance/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-quality-assurance/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: quality-assurance

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

@@ -66,7 +66,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-review/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-review/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: review

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

@@ -30,7 +30,7 @@ EXPECTED: <artifact path> + <quality criteria>
 CONSTRAINTS: <scope limits>
 ---
 InnerLoop: <true|false>
-RoleSpec: .claude/skills/team-review/roles/<role>/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-review/roles/<role>/role.md
 ```
 
 ## Pipeline Task Registry

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

@@ -24,9 +24,9 @@ Event-driven pipeline coordination. Beat model: coordinator wake -> process -> s
 
 | Prefix | Role | Role Spec | inner_loop |
 |--------|------|-----------|------------|
-| SCAN-* | scanner | `.claude/skills/team-review/roles/scanner/role.md` | false |
+| SCAN-* | scanner | `~  or <project>/.claude/skills/team-review/roles/scanner/role.md` | false |
-| REV-* | reviewer | `.claude/skills/team-review/roles/reviewer/role.md` | false |
+| REV-* | reviewer | `~  or <project>/.claude/skills/team-review/roles/reviewer/role.md` | false |
-| FIX-* | fixer | `.claude/skills/team-review/roles/fixer/role.md` | true |
+| FIX-* | fixer | `~  or <project>/.claude/skills/team-review/roles/fixer/role.md` | true |
 
 ## handleCallback
 
@@ -123,7 +123,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-review/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-review/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: review

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

@@ -72,7 +72,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-roadmap-dev/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-roadmap-dev/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: roadmap-dev

.claude/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md

@@ -15,9 +15,9 @@ Handle all coordinator monitoring events for the roadmap-dev pipeline using the
 
 | Prefix | Role | Role Spec | inner_loop |
 |--------|------|-----------|------------|
-| PLAN | planner | `.claude/skills/team-roadmap-dev/roles/planner/role.md` | true (cli_tools: gemini --mode analysis) |
+| PLAN | planner | `~  or <project>/.claude/skills/team-roadmap-dev/roles/planner/role.md` | true (cli_tools: gemini --mode analysis) |
-| EXEC | executor | `.claude/skills/team-roadmap-dev/roles/executor/role.md` | true (cli_tools: gemini --mode write) |
+| EXEC | executor | `~  or <project>/.claude/skills/team-roadmap-dev/roles/executor/role.md` | true (cli_tools: gemini --mode write) |
-| VERIFY | verifier | `.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |
+| VERIFY | verifier | `~  or <project>/.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |
 
 ### Pipeline Structure
 
@@ -247,7 +247,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-roadmap-dev/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-roadmap-dev/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: roadmap-dev

.claude/skills/team-roadmap-dev/specs/pipelines.md

@@ -88,6 +88,6 @@ Phase N: PLAN-N01 --> EXEC-N01 --> VERIFY-N01
 
 | Prefix | Role | Role Spec | Inner Loop |
 |--------|------|-----------|------------|
-| PLAN | planner | `.claude/skills/team-roadmap-dev/roles/planner/role.md` | true |
+| PLAN | planner | `~  or <project>/.claude/skills/team-roadmap-dev/roles/planner/role.md` | true |
-| EXEC | executor | `.claude/skills/team-roadmap-dev/roles/executor/role.md` | true |
+| EXEC | executor | `~  or <project>/.claude/skills/team-roadmap-dev/roles/executor/role.md` | true |
-| VERIFY | verifier | `.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |
+| VERIFY | verifier | `~  or <project>/.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |

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

@@ -2,7 +2,7 @@
   "team_name": "roadmap-dev",
   "team_display_name": "Roadmap Dev",
   "skill_name": "team-roadmap-dev",
-  "skill_path": ".claude/skills/team-roadmap-dev/",
+  "skill_path": "~  or <project>/.claude/skills/team-roadmap-dev/",
   "design_source": "roadmap-driven development workflow design (2026-02-24)",
   "pipeline_type": "Phased",
   "pipeline": {

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

@@ -68,7 +68,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-tech-debt/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-tech-debt/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: tech-debt

.claude/skills/team-tech-debt/roles/coordinator/commands/monitor.md

@@ -123,7 +123,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-tech-debt/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-tech-debt/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: tech-debt

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

@@ -67,7 +67,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-testing/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-testing/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: testing

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

@@ -31,7 +31,7 @@ EXPECTED: <deliverable path> + <quality criteria>
 CONSTRAINTS: <scope limits, focus areas>
 ---
 InnerLoop: <true|false>
-RoleSpec: .claude/skills/team-testing/roles/<role>/role.md
+RoleSpec: ~  or <project>/.claude/skills/team-testing/roles/<role>/role.md
 ```
 
 ## Pipeline Task Registry

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

@@ -25,10 +25,10 @@ Event-driven pipeline coordination. Beat model: coordinator wake -> process -> s
 
 | Prefix | Role | Role Spec | inner_loop |
 |--------|------|-----------|------------|
-| STRATEGY-* | strategist | `.claude/skills/team-testing/roles/strategist/role.md` | false |
+| STRATEGY-* | strategist | `~  or <project>/.claude/skills/team-testing/roles/strategist/role.md` | false |
-| TESTGEN-* | generator | `.claude/skills/team-testing/roles/generator/role.md` | true |
+| TESTGEN-* | generator | `~  or <project>/.claude/skills/team-testing/roles/generator/role.md` | true |
-| TESTRUN-* | executor | `.claude/skills/team-testing/roles/executor/role.md` | true |
+| TESTRUN-* | executor | `~  or <project>/.claude/skills/team-testing/roles/executor/role.md` | true |
-| TESTANA-* | analyst | `.claude/skills/team-testing/roles/analyst/role.md` | false |
+| TESTANA-* | analyst | `~  or <project>/.claude/skills/team-testing/roles/analyst/role.md` | false |
 
 ## handleCallback
 
@@ -68,7 +68,7 @@ EXPECTED: Revised test files in <session>/tests/<layer>/
 CONSTRAINTS: Only modify test files
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-testing/roles/generator/role.md"
+RoleSpec: ~  or <project>/.claude/skills/team-testing/roles/generator/role.md"
 })
 TaskCreate({
   subject: "TESTRUN-<layer>-fix-<round>: Re-execute <layer> (GC #<round>)",
@@ -80,7 +80,7 @@ CONTEXT:
 EXPECTED: <session>/results/run-<N>-gc.json
 ---
 InnerLoop: true
-RoleSpec: .claude/skills/team-testing/roles/executor/role.md",
+RoleSpec: ~  or <project>/.claude/skills/team-testing/roles/executor/role.md",
   blockedBy: ["TESTGEN-<layer>-fix-<round>"]
 })
 ```
@@ -150,7 +150,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-testing/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-testing/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: testing

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

@@ -67,7 +67,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-uidesign/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-uidesign/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: uidesign

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

@@ -127,7 +127,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-uidesign/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-uidesign/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: uidesign

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

@@ -75,7 +75,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-ultra-analyze/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-ultra-analyze/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: ultra-analyze

.claude/skills/team-ultra-analyze/roles/coordinator/commands/monitor.md

@@ -211,10 +211,10 @@ Find and spawn the next ready tasks.
 
 | Task Prefix | Role | Role Spec |
 |-------------|------|-----------|
-| `EXPLORE-*` | explorer | `.claude/skills/team-ultra-analyze/role-specs/explorer.md` |
+| `EXPLORE-*` | explorer | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/explorer.md` |
-| `ANALYZE-*` | analyst | `.claude/skills/team-ultra-analyze/role-specs/analyst.md` |
+| `ANALYZE-*` | analyst | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/analyst.md` |
-| `DISCUSS-*` | discussant | `.claude/skills/team-ultra-analyze/role-specs/discussant.md` |
+| `DISCUSS-*` | discussant | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/discussant.md` |
-| `SYNTH-*` | synthesizer | `.claude/skills/team-ultra-analyze/role-specs/synthesizer.md` |
+| `SYNTH-*` | synthesizer | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/synthesizer.md` |
 
 3. Spawn team-worker for each ready task:
 
@@ -227,7 +227,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-ultra-analyze/role-specs/<role>.md
+role_spec: ~  or <project>/.claude/skills/team-ultra-analyze/role-specs/<role>.md
 session: <session-folder>
 session_id: <session-id>
 team_name: ultra-analyze

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

@@ -152,7 +152,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: .claude/skills/team-ultra-analyze/roles/<role>/role.md`
+- `role_spec: ~  or <project>/.claude/skills/team-ultra-analyze/roles/<role>/role.md`
 - `team_name: ultra-analyze`
 - `inner_loop: false`
 

.claude/skills/team-ux-improve/SKILL.md

@@ -76,7 +76,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-ux-improve/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-ux-improve/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: ux-improve

.claude/skills/team-ux-improve/roles/coordinator/commands/monitor.md

@@ -102,7 +102,7 @@ Agent({
   run_in_background: true,
   prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-ux-improve/roles/<role>/role.md
+role_spec: ~  or <project>/.claude/skills/team-ux-improve/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: ux-improve

.claude/skills/team-ux-improve/roles/coordinator/role.md

@@ -76,7 +76,7 @@ TEXT-LEVEL ONLY. No source code reading.
    ├── explorations/
    └── wisdom/contributions/
    ```
-3. **Wisdom Initialization**: Copy `.claude/skills/team-ux-improve/wisdom/` to `<session>/wisdom/`
+3. **Wisdom Initialization**: Copy `~  or <project>/.claude/skills/team-ux-improve/wisdom/` to `<session>/wisdom/`
 4. Initialize `.msg/meta.json` via team_msg state_update with pipeline metadata
 5. TeamCreate(team_name="ux-improve")
 6. Do NOT spawn workers yet - deferred to Phase 4
@@ -110,7 +110,7 @@ Delegate to `commands/monitor.md#handleSpawnNext`:
 
 3. **Wisdom Consolidation**: Check `<session>/wisdom/contributions/` for worker contributions
    - If contributions exist -> AskUserQuestion to merge to permanent wisdom
-   - If approved -> copy to `.claude/skills/team-ux-improve/wisdom/`
+   - If approved -> copy to `~  or <project>/.claude/skills/team-ux-improve/wisdom/`
 
 4. Calculate: completed_tasks, total_issues_found, issues_fixed, test_pass_rate
 5. Output pipeline summary with [coordinator] prefix

.claude/skills/team-ux-improve/specs/pipelines.md

@@ -44,7 +44,7 @@ UX improvement pipeline modes and task registry.
 
 ## Wisdom System
 
-Workers contribute learnings to `<session>/wisdom/contributions/`. On pipeline completion, coordinator asks user to merge approved contributions to permanent wisdom at `.claude/skills/team-ux-improve/wisdom/`.
+Workers contribute learnings to `<session>/wisdom/contributions/`. On pipeline completion, coordinator asks user to merge approved contributions to permanent wisdom at `~  or <project>/.claude/skills/team-ux-improve/wisdom/`.
 
 | Directory | Purpose |
 |-----------|---------|

.claude/skills/team-ux-improve/specs/team-config.json

@@ -4,7 +4,7 @@
   "team_display_name": "UX Improve",
   "team_purpose": "Systematically discover and fix UI/UX interaction issues including unresponsive buttons, missing feedback, and state refresh problems",
   "skill_name": "team-ux-improve",
-  "skill_path": ".claude/skills/team-ux-improve/",
+  "skill_path": "~  or <project>/.claude/skills/team-ux-improve/",
   "worker_agent": "team-worker",
   "pipeline_type": "Standard",
   "completion_action": "interactive",

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

@@ -658,3 +658,41 @@ All agents (csv-wave and interactive) share a single `discoveries.ndjson` file f
 8. **Max 3 Fix Cycles**: Review-fix cycle capped at 3 iterations; escalate to user after
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

.codex/skills/team-arch-opt/instructions/agent-instruction.md

@@ -3,7 +3,7 @@
 ### MANDATORY FIRST STEPS
 1. Read shared discoveries: {session_folder}/discoveries.ndjson (if exists, skip if not)
 2. Read project context: .workflow/project-tech.json (if exists)
-3. Read task schema: .codex/skills/team-arch-opt/schemas/tasks-schema.md
+3. Read task schema: ~  or <project>/.codex/skills/team-arch-opt/schemas/tasks-schema.md
 
 ---
 

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

@@ -233,7 +233,7 @@ const clarifier = spawn_agent({
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-brainstorm/agents/topic-clarifier.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-brainstorm/agents/topic-clarifier.md (MUST read first)
 2. Read: .workflow/project-tech.json (if exists)
 
 ---
@@ -478,7 +478,7 @@ for (let wave = 1; wave <= maxWave; wave++) {
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-brainstorm/agents/gc-controller.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-brainstorm/agents/gc-controller.md (MUST read first)
 2. Read: ${sessionFolder}/discoveries.ndjson (shared discoveries)
 
 ---
@@ -685,3 +685,41 @@ When the challenger returns critique results with severity-graded verdicts:
 8. **Lifecycle Balance**: Every spawn_agent MUST have a matching close_agent
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

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

@@ -627,3 +627,41 @@ See `instructions/agent-instruction.md` for the base instruction template that i
 8. **Dynamic Roles**: All worker roles are generated at runtime from task analysis -- no static role registry
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

.codex/skills/team-designer/SKILL.md

@@ -595,7 +595,7 @@ All agents (csv-wave and interactive) share a single `discoveries.ndjson` file f
 **Format**: One JSON object per line (NDJSON):
 
 ```jsonl
-{"ts":"2026-03-08T10:00:00Z","worker":"SCAFFOLD-001","type":"dir_created","data":{"path":".codex/skills/team-code-review/","description":"Created skill directory structure"}}
+{"ts":"2026-03-08T10:00:00Z","worker":"SCAFFOLD-001","type":"dir_created","data":{"path":"~  or <project>/.codex/skills/team-code-review/","description":"Created skill directory structure"}}
 {"ts":"2026-03-08T10:05:00Z","worker":"ROLE-001","type":"file_generated","data":{"file":"roles/coordinator/role.md","gen_type":"role-bundle","sections":["entry-router","commands"]}}
 {"ts":"2026-03-08T10:10:00Z","worker":"SPEC-001","type":"pattern_found","data":{"pattern_name":"full-lifecycle","description":"Pipeline with analyst -> writer -> executor -> tester"}}
 ```
@@ -651,3 +651,41 @@ All agents (csv-wave and interactive) share a single `discoveries.ndjson` file f
 8. **Golden Sample Fidelity**: Generated files must match existing team skill patterns
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

.codex/skills/team-designer/schemas/tasks-schema.md

@@ -78,8 +78,8 @@ Interactive tasks appear in master CSV for dependency tracking but are NOT inclu
 
 ```csv
 id,title,description,role,file_target,gen_type,deps,context_from,exec_mode,wave,status,findings,files_produced,error
-"SCAFFOLD-001","Create directory structure","Create complete directory structure for team-code-review skill:\n- .codex/skills/team-code-review/\n- roles/coordinator/ + commands/\n- roles/analyst/\n- roles/reviewer/\n- specs/\n- templates/","scaffolder","skill-dir","directory","","","csv-wave","1","pending","","",""
+"SCAFFOLD-001","Create directory structure","Create complete directory structure for team-code-review skill:\n- ~  or <project>/.codex/skills/team-code-review/\n- roles/coordinator/ + commands/\n- roles/analyst/\n- roles/reviewer/\n- specs/\n- templates/","scaffolder","skill-dir","directory","","","csv-wave","1","pending","","",""
-"ROUTER-001","Generate SKILL.md","Generate .codex/skills/team-code-review/SKILL.md with:\n- Frontmatter (name, description, allowed-tools)\n- Architecture diagram\n- Role registry table\n- CSV schema reference\n- Session structure\n- Wave execution engine\nUse teamConfig.json for role list and pipeline definitions","router-writer","SKILL.md","router","SCAFFOLD-001","SCAFFOLD-001","csv-wave","2","pending","","",""
+"ROUTER-001","Generate SKILL.md","Generate ~  or <project>/.codex/skills/team-code-review/SKILL.md with:\n- Frontmatter (name, description, allowed-tools)\n- Architecture diagram\n- Role registry table\n- CSV schema reference\n- Session structure\n- Wave execution engine\nUse teamConfig.json for role list and pipeline definitions","router-writer","SKILL.md","router","SCAFFOLD-001","SCAFFOLD-001","csv-wave","2","pending","","",""
 "SPEC-001","Generate pipelines spec","Generate specs/pipelines.md with:\n- Pipeline definitions from teamConfig\n- Task registry with PREFIX-NNN format\n- Conditional routing rules\n- Dynamic specialist injection\nRoles: analyst(ANALYSIS-*), reviewer(REVIEW-*)","spec-writer","specs/pipelines.md","spec","SCAFFOLD-001","SCAFFOLD-001","csv-wave","2","pending","","",""
 "ROLE-001","Generate coordinator","Generate roles/coordinator/role.md with entry router and commands/analyze.md, commands/dispatch.md, commands/monitor.md. Coordinator orchestrates the analysis pipeline","role-writer","roles/coordinator/","role-bundle","SCAFFOLD-001;SPEC-001","SPEC-001","csv-wave","3","pending","","",""
 "ROLE-002","Generate analyst role","Generate roles/analyst/role.md with Phase 2 (context loading), Phase 3 (analysis execution), Phase 4 (output). Prefix: ANALYSIS, inner_loop: false","role-writer","roles/analyst/role.md","role-inline","SCAFFOLD-001;SPEC-001","SPEC-001","csv-wave","3","pending","","",""
@@ -144,7 +144,7 @@ Interactive tasks output via structured text or JSON written to `interactive/{id
 ### Discovery NDJSON Format
 
 ```jsonl
-{"ts":"2026-03-08T10:00:00Z","worker":"SCAFFOLD-001","type":"dir_created","data":{"path":".codex/skills/team-code-review/roles/","description":"Created roles directory with coordinator, analyst, reviewer subdirs"}}
+{"ts":"2026-03-08T10:00:00Z","worker":"SCAFFOLD-001","type":"dir_created","data":{"path":"~  or <project>/.codex/skills/team-code-review/roles/","description":"Created roles directory with coordinator, analyst, reviewer subdirs"}}
 {"ts":"2026-03-08T10:05:00Z","worker":"ROLE-001","type":"file_generated","data":{"file":"roles/coordinator/role.md","gen_type":"role-bundle","sections":["entry-router","phase-0","phase-1","phase-2","phase-3"]}}
 {"ts":"2026-03-08T10:10:00Z","worker":"SPEC-001","type":"config_decision","data":{"decision":"full-lifecycle pipeline","rationale":"Both analyst and reviewer roles present","impact":"4-tier dependency graph"}}
 ```

.codex/skills/team-edict/SKILL.md

@@ -217,8 +217,8 @@ Each wave generates a temporary `wave-{N}.csv` with extra `prev_context` column
 4. Create subdirectories: plan/, review/, artifacts/, interactive/, agents/
 5. Initialize registry.json: { "active": [], "closed": [] }
 6. Initialize discoveries.ndjson (empty file)
-7. Read specs: .codex/skills/team-edict/specs/team-config.json
+7. Read specs: ~  or <project>/.codex/skills/team-edict/specs/team-config.json
-8. Read quality gates: .codex/skills/team-edict/specs/quality-gates.md
+8. Read quality gates: ~  or <project>/.codex/skills/team-edict/specs/quality-gates.md
 9. Log session start to context.md
 ```
 
@@ -236,9 +236,9 @@ const zhongshu = spawn_agent({
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-edict/agents/zhongshu-planner.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-edict/agents/zhongshu-planner.md (MUST read first)
 2. Read: ${sessionDir}/discoveries.ndjson (shared discoveries, skip if not exists)
-3. Read: .codex/skills/team-edict/specs/team-config.json (routing rules)
+3. Read: ~  or <project>/.codex/skills/team-edict/specs/team-config.json (routing rules)
 
 ---
 
@@ -285,7 +285,7 @@ while (!approved && reviewRound < 3) {
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-edict/agents/menxia-reviewer.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-edict/agents/menxia-reviewer.md (MUST read first)
 2. Read: ${sessionDir}/plan/zhongshu-plan.md (plan to review)
 3. Read: ${sessionDir}/discoveries.ndjson (shared discoveries)
 
@@ -336,10 +336,10 @@ const shangshu = spawn_agent({
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-edict/agents/shangshu-dispatcher.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-edict/agents/shangshu-dispatcher.md (MUST read first)
 2. Read: ${sessionDir}/plan/zhongshu-plan.md (approved plan)
 3. Read: ${sessionDir}/review/menxia-review.md (review conditions)
-4. Read: .codex/skills/team-edict/specs/team-config.json (routing rules)
+4. Read: ~  or <project>/.codex/skills/team-edict/specs/team-config.json (routing rules)
 
 ---
 
@@ -416,8 +416,8 @@ For each wave W in 1..max_wave:
   5. EXECUTE csv-wave tasks:
      spawn_agents_on_csv({
        task_csv_path: "${sessionDir}/wave-{W}.csv",
-       instruction_path: ".codex/skills/team-edict/instructions/agent-instruction.md",
+       instruction_path: "~  or <project>/.codex/skills/team-edict/instructions/agent-instruction.md",
-       schema_path: ".codex/skills/team-edict/schemas/tasks-schema.md",
+       schema_path: "~  or <project>/.codex/skills/team-edict/schemas/tasks-schema.md",
        additional_instructions: "Session directory: ${sessionDir}. Department: {department}. Priority: {priority}.",
        concurrency: CONCURRENCY
      })
@@ -457,10 +457,10 @@ const aggregator = spawn_agent({
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-edict/agents/aggregator.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-edict/agents/aggregator.md (MUST read first)
 2. Read: ${sessionDir}/tasks.csv (master state)
 3. Read: ${sessionDir}/discoveries.ndjson (all discoveries)
-4. Read: .codex/skills/team-edict/specs/quality-gates.md (quality standards)
+4. Read: ~  or <project>/.codex/skills/team-edict/specs/quality-gates.md (quality standards)
 
 ---
 
@@ -472,7 +472,7 @@ Deliverables: ${sessionDir}/context.md (final report)
 ${listAllArtifacts()}
 
 ### Quality Gate Standards
-Read from: .codex/skills/team-edict/specs/quality-gates.md
+Read from: ~  or <project>/.codex/skills/team-edict/specs/quality-gates.md
 `
 })
 
@@ -609,9 +609,9 @@ const agent = spawn_agent({
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-edict/agents/qa-verifier.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-edict/agents/qa-verifier.md (MUST read first)
 2. Read: ${sessionDir}/discoveries.ndjson (shared discoveries)
-3. Read: .codex/skills/team-edict/specs/quality-gates.md (quality standards)
+3. Read: ~  or <project>/.codex/skills/team-edict/specs/quality-gates.md (quality standards)
 
 ---
 
@@ -740,3 +740,42 @@ spawn_agent({
 12. **Rejection Loop Max 3**: Menxia can reject max 3 times before escalating to user
 13. **Kanban is Mandatory**: All agents must report state transitions via discoveries.ndjson
 14. **Quality Gates Apply**: Phase 3 aggregator validates all outputs against specs/quality-gates.md
+
+---
+
+## Coordinator Role Constraints (Crown Prince / Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned agents (Three Departments and Six Ministries). The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results into master CSV
+    - Coordinates workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms (600s for planning, 300s for execution)
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages (e.g., jumping from Zhongshu directly to Shangshu)
+    - Bypass the Three Departments serial pipeline
+    - Execute wave N before wave N-1 completes
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time: 30-90 minutes for typical edicts
+    - Phase 0 (Three Departments): 15-30 minutes
+    - Phase 2 (Wave Execution): 10-20 minutes per wave
+    - Phase 3 (Aggregation): 5-10 minutes
+    - The coordinator must remain active and attentive throughout the entire process
+

.codex/skills/team-edict/agents/aggregator.md

@@ -68,7 +68,7 @@ Post-wave aggregation agent -- collects all ministry outputs, validates against
 4. Use Glob to find all files in `<session>/interactive/`
 5. Read each interactive result file
 6. Read `<session>/discoveries.ndjson` (all entries)
-7. Read `.codex/skills/team-edict/specs/quality-gates.md`
+7. Read `~  or <project>/.codex/skills/team-edict/specs/quality-gates.md`
 
 **Output**: All artifacts and status data collected
 

.codex/skills/team-edict/agents/qa-verifier.md

@@ -64,7 +64,7 @@ Xingbu (Ministry of Justice / Quality Assurance) -- executes quality verificatio
 
 **Steps**:
 
-1. Read `.codex/skills/team-edict/specs/quality-gates.md`
+1. Read `~  or <project>/.codex/skills/team-edict/specs/quality-gates.md`
 2. Read `<session>/plan/dispatch-plan.md` for acceptance criteria
 3. Read implementation artifacts from `<session>/artifacts/`
 4. Read `<session>/discoveries.ndjson` for implementation notes

.codex/skills/team-edict/agents/shangshu-dispatcher.md

@@ -62,7 +62,7 @@ Shangshu (Department of State Affairs / Dispatch) -- parses the approved plan, r
 
 1. Read `<session>/plan/zhongshu-plan.md`
 2. Read `<session>/review/menxia-review.md`
-3. Read `.codex/skills/team-edict/specs/team-config.json`
+3. Read `~  or <project>/.codex/skills/team-edict/specs/team-config.json`
 4. Extract subtask list from plan
 5. Extract conditions from review
 6. Report state "Doing":

.codex/skills/team-edict/agents/zhongshu-planner.md

@@ -64,7 +64,7 @@ Zhongshu (Central Secretariat) -- analyzes the edict, explores the codebase, and
 **Steps**:
 
 1. Parse the edict text from the spawn message
-2. Read `.codex/skills/team-edict/specs/team-config.json` for routing rules
+2. Read `~  or <project>/.codex/skills/team-edict/specs/team-config.json` for routing rules
 3. If revision round: Read `<session>/review/menxia-review.md` for rejection feedback
 4. Read `<session>/discoveries.ndjson` if it exists
 

.codex/skills/team-edict/instructions/agent-instruction.md

@@ -4,8 +4,8 @@
 1. Read shared discoveries: .workflow/.csv-wave/{session-id}/discoveries.ndjson (if exists, skip if not)
 2. Read dispatch plan: .workflow/.csv-wave/{session-id}/plan/dispatch-plan.md (task details and acceptance criteria)
 3. Read approved plan: .workflow/.csv-wave/{session-id}/plan/zhongshu-plan.md (overall strategy and context)
-4. Read quality gates: .codex/skills/team-edict/specs/quality-gates.md (quality standards)
+4. Read quality gates: ~  or <project>/.codex/skills/team-edict/specs/quality-gates.md (quality standards)
-5. Read team config: .codex/skills/team-edict/specs/team-config.json (routing rules and artifact paths)
+5. Read team config: ~  or <project>/.codex/skills/team-edict/specs/team-config.json (routing rules and artifact paths)
 
 > **Note**: The session directory path is provided by the orchestrator in `additional_instructions`. Use it to resolve the paths above.
 

.codex/skills/team-executor/SKILL.md

@@ -475,3 +475,41 @@ if (action === "Archive & Clean") {
 8. **Lifecycle Balance**: Every spawn_agent MUST have a matching close_agent (tracked in registry.json)
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

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

@@ -781,3 +781,41 @@ After TEST-001 completes, evaluate issues:
 9. **Iteration Bounds**: Max 2 reproduction rounds, max 3 fix rounds
 10. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 11. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

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

@@ -710,3 +710,41 @@ Convergence: qa.score >= 8 && qa.critical_count === 0
 8. **GC Loop Cap**: Max 2 generator-critic rounds between developer and qa
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

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

@@ -389,7 +389,7 @@ for (let wave = 1; wave <= maxWave; wave++) {
     spawn_agents_on_csv({
       csv_path: `${sessionFolder}/wave-${wave}.csv`,
       id_column: "id",
-      instruction: Read(".codex/skills/team-issue/instructions/agent-instruction.md"),
+      instruction: Read("~  or <project>/.codex/skills/team-issue/instructions/agent-instruction.md"),
       max_concurrency: maxConcurrency,
       max_runtime_seconds: 1200,
       output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
@@ -420,7 +420,7 @@ for (let wave = 1; wave <= maxWave; wave++) {
   const pendingInteractive = interactiveTasks.filter(t => t.status === 'pending')
   for (const task of pendingInteractive) {
     // Read agent definition
-    const agentDef = Read(`.codex/skills/team-issue/agents/reviewer.md`)
+    const agentDef = Read(`~  or <project>/.codex/skills/team-issue/agents/reviewer.md`)
 
     // Build context from upstream tasks
     const contextIds = (task.context_from || '').split(';').filter(Boolean)
@@ -434,7 +434,7 @@ for (let wave = 1; wave <= maxWave; wave++) {
       message: `## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-issue/agents/reviewer.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-issue/agents/reviewer.md (MUST read first)
 2. Read: ${sessionFolder}/discoveries.ndjson (shared discoveries)
 3. Read: .workflow/project-tech.json (if exists)
 
@@ -700,3 +700,41 @@ Both csv-wave and interactive agents share the same discoveries.ndjson file:
 8. **Lifecycle Balance**: Every spawn_agent MUST have a matching close_agent
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

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

@@ -290,7 +290,7 @@ const analyzer = spawn_agent({
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-iterdev/agents/task-analyzer.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-iterdev/agents/task-analyzer.md (MUST read first)
 2. Read: .workflow/project-tech.json (if exists)
 
 ---
@@ -484,7 +484,7 @@ for (let wave = 1; wave <= maxWave; wave++) {
     const waveResult = spawn_agents_on_csv({
       csv_path: `${sessionFolder}/wave-${wave}.csv`,
       id_column: "id",
-      instruction: Read(`.codex/skills/team-iterdev/instructions/agent-instruction.md`),
+      instruction: Read(`~  or <project>/.codex/skills/team-iterdev/instructions/agent-instruction.md`),
       max_concurrency: maxConcurrency,
       max_runtime_seconds: 900,
       output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
@@ -533,7 +533,7 @@ for (let wave = 1; wave <= maxWave; wave++) {
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-iterdev/agents/gc-controller.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-iterdev/agents/gc-controller.md (MUST read first)
 2. Read: ${sessionFolder}/discoveries.ndjson (shared discoveries)
 
 ---
@@ -786,3 +786,41 @@ When the reviewer returns review results with severity-graded verdicts:
 8. **Lifecycle Balance**: Every spawn_agent MUST have a matching close_agent
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

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

@@ -254,7 +254,7 @@ const clarifier = spawn_agent({
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-lifecycle-v4/agents/requirement-clarifier.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-lifecycle-v4/agents/requirement-clarifier.md (MUST read first)
 2. Read: .workflow/project-tech.json (if exists)
 
 ---
@@ -436,7 +436,7 @@ for (let wave = 1; wave <= maxWave; wave++) {
     const waveResult = spawn_agents_on_csv({
       csv_path: `${sessionFolder}/wave-${wave}.csv`,
       id_column: "id",
-      instruction: Read(`.codex/skills/team-lifecycle-v4/instructions/agent-instruction.md`)
+      instruction: Read(`~  or <project>/.codex/skills/team-lifecycle-v4/instructions/agent-instruction.md`)
         .replace(/{session-id}/g, sessionId),
       max_concurrency: maxConcurrency,
       max_runtime_seconds: 900,
@@ -486,7 +486,7 @@ for (let wave = 1; wave <= maxWave; wave++) {
 ## TASK ASSIGNMENT
 
 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: .codex/skills/team-lifecycle-v4/agents/supervisor.md (MUST read first)
+1. **Read role definition**: ~  or <project>/.codex/skills/team-lifecycle-v4/agents/supervisor.md (MUST read first)
 2. Read: ${sessionFolder}/discoveries.ndjson (shared discoveries)
 
 ---
@@ -735,3 +735,41 @@ All agents across all waves share `discoveries.ndjson`. This enables cross-role
 8. **Lifecycle Balance**: Every spawn_agent MUST have a matching close_agent
 9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
 10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

.codex/skills/team-lifecycle/SKILL.md

@@ -866,3 +866,41 @@ The orchestrator dynamically adds DEV-FE-NNN and QA-FE-NNN tasks to the state fi
 | Requirements Template | templates/requirements-prd.md | DRAFT-002 |
 | Architecture Template | templates/architecture-doc.md | DRAFT-003 |
 | Epics Template | templates/epics-template.md | DRAFT-004 |
+
+
+---
+
+## Coordinator Role Constraints (Main Agent)
+
+**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
+
+15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
+    - Spawns agents with task assignments
+    - Waits for agent callbacks
+    - Merges results and coordinates workflow
+    - Manages workflow transitions between phases
+
+16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
+    - Wait patiently for `wait()` calls to complete
+    - NOT skip workflow steps due to perceived delays
+    - NOT assume agents have failed just because they're taking time
+    - Trust the timeout mechanisms defined in the skill
+
+17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
+    - Use `send_input()` to ask questions or provide clarification
+    - NOT skip the agent or move to next phase prematurely
+    - Give agents opportunity to respond before escalating
+    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
+
+18. **No Workflow Shortcuts**: The coordinator MUST NOT:
+    - Skip phases or stages defined in the workflow
+    - Bypass required approval or review steps
+    - Execute dependent tasks before prerequisites complete
+    - Assume task completion without explicit agent callback
+    - Make up or fabricate agent results
+
+19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
+    - Total execution time may range from 30-90 minutes or longer
+    - Each phase may take 10-30 minutes depending on complexity
+    - The coordinator must remain active and attentive throughout the entire process
+    - Do not terminate or skip steps due to time concerns

.codex/skills/team-lifecycle/agents/analyst.md

@@ -5,7 +5,7 @@ Seed analysis, codebase exploration (via shared explore subagent), and multi-dim
 ## Identity
 
 - **Type**: `produce`
-- **Role File**: `~/.codex/skills/team-lifecycle/agents/analyst.md`
+- **Role File**: `~/~  or <project>/.codex/skills/team-lifecycle/agents/analyst.md`
 - **Prefix**: `RESEARCH-*`
 - **Tag**: `[analyst]`
 - **Responsibility**: Seed Analysis -> Codebase Exploration -> Context Packaging -> Inline Discuss -> Report
@@ -168,7 +168,7 @@ if (cached) {
   // Cache MISS - spawn explore subagent
   const explorer = spawn_agent({
     message: `### MANDATORY FIRST STEPS
-1. Read: ~/.codex/skills/team-lifecycle/agents/explore-agent.md
+1. Read: ~/~  or <project>/.codex/skills/team-lifecycle/agents/explore-agent.md
 
 ---
 
@@ -253,7 +253,7 @@ After packaging, spawn discuss subagent (Pattern 2.8):
 ```javascript
 const critic = spawn_agent({
   message: `### MANDATORY FIRST STEPS
-1. Read: ~/.codex/skills/team-lifecycle/agents/discuss-agent.md
+1. Read: ~/~  or <project>/.codex/skills/team-lifecycle/agents/discuss-agent.md
 
 ## Multi-Perspective Critique: DISCUSS-001
 
@@ -297,7 +297,7 @@ This agent spawns two utility subagents during its execution:
 ### Explore Subagent (Phase 3)
 
 **When**: After seed analysis, when project files detected
-**Agent File**: `~/.codex/skills/team-lifecycle/agents/explore-agent.md`
+**Agent File**: `~/~  or <project>/.codex/skills/team-lifecycle/agents/explore-agent.md`
 **Pattern**: 2.9 (Cache-Aware Exploration)
 
 See Phase 3 code block above. Cache is checked before spawning. If cache hit, the spawn is skipped entirely.
@@ -305,7 +305,7 @@ See Phase 3 code block above. Cache is checked before spawning. If cache hit, th
 ### Discuss Subagent (Phase 4b)
 
 **When**: After context packaging (spec-config.json + discovery-context.json written)
-**Agent File**: `~/.codex/skills/team-lifecycle/agents/discuss-agent.md`
+**Agent File**: `~/~  or <project>/.codex/skills/team-lifecycle/agents/discuss-agent.md`
 **Pattern**: 2.8 (Inline Subagent)
 
 See Phase 4b code block above.
@@ -342,7 +342,7 @@ if (cached) {
   // Cache MISS - spawn explore subagent, result cached by explore-agent
   const explorer = spawn_agent({
     message: `### MANDATORY FIRST STEPS
-1. Read: ~/.codex/skills/team-lifecycle/agents/explore-agent.md
+1. Read: ~/~  or <project>/.codex/skills/team-lifecycle/agents/explore-agent.md
 
 ---
 

.codex/skills/team-lifecycle/agents/discuss-agent.md

@@ -5,7 +5,7 @@ Lightweight multi-perspective critique engine. Called inline by produce agents (
 ## Identity
 
 - **Type**: `utility`
-- **Role File**: `~/.codex/skills/team-lifecycle/agents/discuss-agent.md`
+- **Role File**: `~/~  or <project>/.codex/skills/team-lifecycle/agents/discuss-agent.md`
 - **Tag**: `[discuss]`
 - **Responsibility**: Read Artifact -> Multi-CLI Perspective Analysis -> Divergence Detection -> Consensus Determination -> Write Discussion Record -> Return Verdict
 

.codex/skills/team-lifecycle/agents/explore-agent.md

@@ -5,7 +5,7 @@ Shared codebase exploration utility with centralized caching. Callable by any ag
 ## Identity
 
 - **Type**: `utility`
-- **Role File**: `~/.codex/skills/team-lifecycle/agents/explore-agent.md`
+- **Role File**: `~/~  or <project>/.codex/skills/team-lifecycle/agents/explore-agent.md`
 - **Tag**: `[explore]`
 - **Responsibility**: Cache Check -> Codebase Exploration -> Cache Update -> Return Structured Results
 
@@ -382,7 +382,7 @@ if (cached && !forceRefresh) {
 // After seed analysis, explore codebase context (Pattern 2.9 in analyst)
 const explorer = spawn_agent({
   message: `### MANDATORY FIRST STEPS
-1. Read: ~/.codex/skills/team-lifecycle/agents/explore-agent.md
+1. Read: ~/~  or <project>/.codex/skills/team-lifecycle/agents/explore-agent.md
 
 ---
 
@@ -405,7 +405,7 @@ for (const angle of angles) {
   // Cache check happens inside explore-agent
   const explorer = spawn_agent({
     message: `### MANDATORY FIRST STEPS
-1. Read: ~/.codex/skills/team-lifecycle/agents/explore-agent.md
+1. Read: ~/~  or <project>/.codex/skills/team-lifecycle/agents/explore-agent.md
 
 ---
 

.codex/skills/team-lifecycle/agents/writer.md

@@ -5,7 +5,7 @@ Product Brief, Requirements/PRD, Architecture, and Epics & Stories document gene
 ## Identity
 
 - **Type**: `produce`
-- **Role File**: `~/.codex/skills/team-lifecycle/agents/writer.md`
+- **Role File**: `~/~  or <project>/.codex/skills/team-lifecycle/agents/writer.md`
 - **Prefix**: `DRAFT-*`
 - **Tag**: `[writer]`
 - **Responsibility**: Load Context -> Generate Document -> Self-Validation -> Inline Discuss -> Report
@@ -382,7 +382,7 @@ After validation, spawn discuss subagent (Pattern 2.8) for this task's discuss r
 ```javascript
 const critic = spawn_agent({
   message: `### MANDATORY FIRST STEPS
-1. Read: ~/.codex/skills/team-lifecycle/agents/discuss-agent.md
+1. Read: ~/~  or <project>/.codex/skills/team-lifecycle/agents/discuss-agent.md
 
 ## Multi-Perspective Critique: <DISCUSS-NNN>
 
@@ -435,7 +435,7 @@ This agent spawns the discuss subagent during Phase 4b:
 ### Discuss Subagent (Phase 4b)
 
 **When**: After self-validation of generated document
-**Agent File**: `~/.codex/skills/team-lifecycle/agents/discuss-agent.md`
+**Agent File**: `~/~  or <project>/.codex/skills/team-lifecycle/agents/discuss-agent.md`
 **Pattern**: 2.8 (Inline Subagent)
 
 See Phase 4b code block above. The round ID and perspectives vary per doc type -- use the Inline Discuss Mapping table.

.codex/skills/team-lifecycle/phases/01-requirement-clarification.md

@@ -1,6 +1,6 @@
 # Phase 1: Requirement Clarification
 
-> **COMPACT PROTECTION**: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via `Read("~/.codex/skills/team-lifecycle/phases/01-requirement-clarification.md")` before continuing. Never execute based on summaries.
+> **COMPACT PROTECTION**: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via `Read("~/~  or <project>/.codex/skills/team-lifecycle/phases/01-requirement-clarification.md")` before continuing. Never execute based on summaries.
 
 ## Objective
 

.codex/skills/team-lifecycle/phases/02-team-initialization.md

@@ -1,6 +1,6 @@
 # Phase 2: Team Initialization
 
-> **COMPACT PROTECTION**: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via `Read("~/.codex/skills/team-lifecycle/phases/02-team-initialization.md")` before continuing. Never execute based on summaries.
+> **COMPACT PROTECTION**: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via `Read("~/~  or <project>/.codex/skills/team-lifecycle/phases/02-team-initialization.md")` before continuing. Never execute based on summaries.
 
 ## Objective
 

.codex/skills/team-lifecycle/phases/03-task-chain-creation.md

@@ -1,6 +1,6 @@
 # Phase 3: Task Chain Creation
 
-> **COMPACT PROTECTION**: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via `Read("~/.codex/skills/team-lifecycle/phases/03-task-chain-creation.md")` before continuing. Never execute based on summaries.
+> **COMPACT PROTECTION**: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via `Read("~/~  or <project>/.codex/skills/team-lifecycle/phases/03-task-chain-creation.md")` before continuing. Never execute based on summaries.
 
 ## Objective
 

.codex/skills/team-lifecycle/phases/04-pipeline-coordination.md

@@ -1,6 +1,6 @@
 # Phase 4: Pipeline Coordination
 
-> **COMPACT PROTECTION**: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via `Read("~/.codex/skills/team-lifecycle/phases/04-pipeline-coordination.md")` before continuing. Never execute based on summaries.
+> **COMPACT PROTECTION**: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via `Read("~/~  or <project>/.codex/skills/team-lifecycle/phases/04-pipeline-coordination.md")` before continuing. Never execute based on summaries.
 
 ## Objective
 

.codex/skills/team-lifecycle/phases/05-completion-report.md

@@ -1,6 +1,6 @@
 # Phase 5: Completion Report
 
-> **COMPACT PROTECTION**: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via `Read("~/.codex/skills/team-lifecycle/phases/05-completion-report.md")` before continuing. Never execute based on summaries.
+> **COMPACT PROTECTION**: This is an execution document. After context compression, phase instructions become summaries only. You MUST immediately re-read this file via `Read("~/~  or <project>/.codex/skills/team-lifecycle/phases/05-completion-report.md")` before continuing. Never execute based on summaries.
 
 ## Objective