Enhance UX and Coordinator Role Constraints in Skills Documentation

- Added detailed constraints for the Coordinator role in the team UX improvement skill, emphasizing orchestration responsibilities and workflow management. - Updated test cases in DashboardToolbar, useIssues, and useWebSocket to improve reliability and clarity. - Introduced new tests for configStore and ignore patterns in Codex Lens to ensure proper functionality and configuration handling. - Enhanced smart search functionality with improved embedding selection logic and added tests for various scenarios. - Updated installation and usage documentation to reflect changes in directory structure and role specifications.
2026-03-11 17:21:03 +08:00 · 2026-03-08 23:43:44 +08:00
parent f3ae78f95e
commit 61ea9d47a6
110 changed files with 1516 additions and 218 deletions
--- a/.claude/agents/team-worker.md
+++ b/.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
--- a/.claude/skills/team-arch-opt/SKILL.md
+++ b/.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
--- a/.claude/skills/team-arch-opt/roles/coordinator/commands/monitor.md
+++ b/.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
--- a/.claude/skills/team-arch-opt/specs/team-config.json
+++ b/.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,
--- a/.claude/skills/team-brainstorm/SKILL.md
+++ b/.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
--- a/.claude/skills/team-brainstorm/roles/coordinator/commands/monitor.md
+++ b/.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
--- a/.claude/skills/team-designer/SKILL.md
+++ b/.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>/
--- a/.claude/skills/team-designer/phases/03-content-generation.md
+++ b/.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

--- a/.claude/skills/team-edict/SKILL.md
+++ b/.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>
--- a/.claude/skills/team-edict/role-specs/xingbu.md
+++ b/.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: 质量审查
--- a/.claude/skills/team-edict/roles/coordinator/role.md
+++ b/.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>
--- a/.claude/skills/team-frontend-debug/SKILL.md
+++ b/.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>
--- a/.claude/skills/team-frontend-debug/roles/coordinator/commands/dispatch.md
+++ b/.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
--- a/.claude/skills/team-frontend/SKILL.md
+++ b/.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
--- a/.claude/skills/team-frontend/roles/coordinator/commands/monitor.md
+++ b/.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
--- a/.claude/skills/team-issue/SKILL.md
+++ b/.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
--- a/.claude/skills/team-issue/roles/coordinator/commands/monitor.md
+++ b/.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
--- a/.claude/skills/team-iterdev/SKILL.md
+++ b/.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
--- a/.claude/skills/team-iterdev/roles/coordinator/commands/monitor.md
+++ b/.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
--- a/.claude/skills/team-lifecycle-v4/SKILL.md
+++ b/.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>
--- a/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md
+++ b/.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

--- a/.claude/skills/team-perf-opt/SKILL.md
+++ b/.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
--- a/.claude/skills/team-perf-opt/roles/coordinator/commands/monitor.md
+++ b/.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
--- a/.claude/skills/team-perf-opt/roles/coordinator/role.md
+++ b/.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.
--- a/.claude/skills/team-perf-opt/specs/team-config.json
+++ b/.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",
--- a/.claude/skills/team-planex/SKILL.md
+++ b/.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
--- a/.claude/skills/team-planex/roles/coordinator/commands/monitor.md
+++ b/.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>
--- a/.claude/skills/team-quality-assurance/SKILL.md
+++ b/.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
--- a/.claude/skills/team-quality-assurance/roles/coordinator/commands/dispatch.md
+++ b/.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
--- a/.claude/skills/team-quality-assurance/roles/coordinator/commands/monitor.md
+++ b/.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
--- a/.claude/skills/team-review/SKILL.md
+++ b/.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
--- a/.claude/skills/team-review/roles/coordinator/commands/dispatch.md
+++ b/.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
--- a/.claude/skills/team-review/roles/coordinator/commands/monitor.md
+++ b/.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 |
-| REV-* | reviewer | `.claude/skills/team-review/roles/reviewer/role.md` | false |
-| FIX-* | fixer | `.claude/skills/team-review/roles/fixer/role.md` | true |
+| SCAN-* | scanner | `~  or <project>/.claude/skills/team-review/roles/scanner/role.md` | false |
+| REV-* | reviewer | `~  or <project>/.claude/skills/team-review/roles/reviewer/role.md` | false |
+| 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
--- a/.claude/skills/team-roadmap-dev/SKILL.md
+++ b/.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
--- a/.claude/skills/team-roadmap-dev/roles/coordinator/commands/monitor.md
+++ b/.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) |
-| EXEC | executor | `.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 |
+| PLAN | planner | `~  or <project>/.claude/skills/team-roadmap-dev/roles/planner/role.md` | true (cli_tools: gemini --mode analysis) |
+| EXEC | executor | `~  or <project>/.claude/skills/team-roadmap-dev/roles/executor/role.md` | true (cli_tools: gemini --mode write) |
+| 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
--- a/.claude/skills/team-roadmap-dev/specs/pipelines.md
+++ b/.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 |
-| EXEC | executor | `.claude/skills/team-roadmap-dev/roles/executor/role.md` | true |
-| VERIFY | verifier | `.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |
+| PLAN | planner | `~  or <project>/.claude/skills/team-roadmap-dev/roles/planner/role.md` | true |
+| EXEC | executor | `~  or <project>/.claude/skills/team-roadmap-dev/roles/executor/role.md` | true |
+| VERIFY | verifier | `~  or <project>/.claude/skills/team-roadmap-dev/roles/verifier/role.md` | true |
--- a/.claude/skills/team-roadmap-dev/specs/team-config.json
+++ b/.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": {
--- a/.claude/skills/team-tech-debt/SKILL.md
+++ b/.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
--- a/.claude/skills/team-tech-debt/roles/coordinator/commands/monitor.md
+++ b/.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
--- a/.claude/skills/team-testing/SKILL.md
+++ b/.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
--- a/.claude/skills/team-testing/roles/coordinator/commands/dispatch.md
+++ b/.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
--- a/.claude/skills/team-testing/roles/coordinator/commands/monitor.md
+++ b/.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 |
-| TESTGEN-* | generator | `.claude/skills/team-testing/roles/generator/role.md` | true |
-| TESTRUN-* | executor | `.claude/skills/team-testing/roles/executor/role.md` | true |
-| TESTANA-* | analyst | `.claude/skills/team-testing/roles/analyst/role.md` | false |
+| STRATEGY-* | strategist | `~  or <project>/.claude/skills/team-testing/roles/strategist/role.md` | false |
+| TESTGEN-* | generator | `~  or <project>/.claude/skills/team-testing/roles/generator/role.md` | true |
+| TESTRUN-* | executor | `~  or <project>/.claude/skills/team-testing/roles/executor/role.md` | true |
+| 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
--- a/.claude/skills/team-uidesign/SKILL.md
+++ b/.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
--- a/.claude/skills/team-uidesign/roles/coordinator/commands/monitor.md
+++ b/.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
--- a/.claude/skills/team-ultra-analyze/SKILL.md
+++ b/.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
--- a/.claude/skills/team-ultra-analyze/roles/coordinator/commands/monitor.md
+++ b/.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` |
-| `ANALYZE-*` | analyst | `.claude/skills/team-ultra-analyze/role-specs/analyst.md` |
-| `DISCUSS-*` | discussant | `.claude/skills/team-ultra-analyze/role-specs/discussant.md` |
-| `SYNTH-*` | synthesizer | `.claude/skills/team-ultra-analyze/role-specs/synthesizer.md` |
+| `EXPLORE-*` | explorer | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/explorer.md` |
+| `ANALYZE-*` | analyst | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/analyst.md` |
+| `DISCUSS-*` | discussant | `~  or <project>/.claude/skills/team-ultra-analyze/role-specs/discussant.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
--- a/.claude/skills/team-ultra-analyze/roles/coordinator/role.md
+++ b/.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`

--- a/.claude/skills/team-ux-improve/SKILL.md
+++ b/.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
--- a/.claude/skills/team-ux-improve/roles/coordinator/commands/monitor.md
+++ b/.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
--- a/.claude/skills/team-ux-improve/roles/coordinator/role.md
+++ b/.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
--- a/.claude/skills/team-ux-improve/specs/pipelines.md
+++ b/.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 |
 |-----------|---------|
--- a/.claude/skills/team-ux-improve/specs/team-config.json
+++ b/.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",