fix: 为所有 skill 的 .workflow/ 路径添加 projectRoot 前缀

从子目录执行 skill 时，相对路径 .workflow/ 会导致产物落到错误位置。
通过 git rev-parse --show-toplevel || pwd 检测项目根目录，
所有 .workflow/ 路径引用统一加上 {projectRoot} 前缀确保路径正确。

涉及 72 个文件，覆盖 20+ 个 skill。

.codex/skills/analyze-with-file/EXECUTE.md

@@ -0,0 +1,245 @@
+# Analyze Quick Execute
+
+> **Trigger**: User selects "Quick Execute" after Phase 4 completion
+> **Prerequisites**: `conclusions.json` + `explorations.json`/`perspectives.json` already exist
+> **Core Principle**: No additional agent exploration - analysis phase has already gathered sufficient context
+
+## Execution Flow
+
+```
+conclusions.json → quick-plan.json → User Confirmation → Serial Execution → execution-log.md
+```
+
+---
+
+## Step 1: Generate quick-plan.json
+
+Convert `conclusions.json` recommendations directly into executable tasks.
+
+**Conversion Logic**:
+```javascript
+const quickPlan = {
+  session_id: sessionId,
+  source: "analysis",
+  source_file: `${sessionFolder}/conclusions.json`,
+  generated_at: new Date().toISOString(),
+
+  tasks: conclusions.recommendations.map((rec, index) => ({
+    id: `TASK-${String(index + 1).padStart(3, '0')}`,
+    title: rec.action,
+    description: rec.rationale,
+    priority: rec.priority,  // high/medium/low
+    status: "pending",
+    files_to_modify: extractFilesFromEvidence(rec, explorations),
+    depends_on: [],  // Serial execution - no dependencies needed
+    context: {
+      source_conclusions: conclusions.key_conclusions,
+      evidence: explorations.relevant_files || perspectives.aggregated_findings
+    }
+  })),
+
+  execution_mode: "serial",
+  total_tasks: conclusions.recommendations.length
+}
+```
+
+**File Extraction Logic**:
+- Parse evidence from `explorations.json` or `perspectives.json`
+- Match recommendation action keywords to relevant_files
+- If no specific files, use pattern matching from findings
+
+**Output**: `${sessionFolder}/quick-plan.json`
+
+---
+
+## Step 2: User Confirmation
+
+Present generated plan for user approval before execution.
+
+**Confirmation Display**:
+- Total tasks to execute
+- Task list with IDs, titles, priorities
+- Files to be modified
+- Execution mode: Serial
+
+**User Options** (ASK_USER - single select):
+
+| Option | Action |
+|--------|--------|
+| **Start Execution** | Proceed with serial execution |
+| **Adjust Tasks** | Allow user to modify/remove tasks |
+| **Cancel** | Cancel execution, keep quick-plan.json |
+
+**Adjustment Mode** (if selected):
+- Display task list with checkboxes
+- User can deselect tasks to skip
+- User can reorder priorities
+- Regenerate quick-plan.json with adjustments
+
+---
+
+## Step 3: Serial Task Execution
+
+Execute tasks one by one without spawning subagents.
+
+**IMPORTANT**: This phase does NOT use spawn_agent. Main process executes tasks directly via CLI.
+
+**Execution Loop**:
+```
+For each task in quick-plan.tasks:
+  ├─ Update task status: "in_progress"
+  ├─ Execute via CLI (synchronous)
+  ├─ Record result to execution-log.md
+  ├─ Update task status: "completed" | "failed"
+  └─ Continue to next task
+```
+
+**CLI Execution Pattern**:
+```bash
+ccw cli -p "PURPOSE: Execute task from analysis
+TASK ID: ${task.id}
+TASK: ${task.title}
+DESCRIPTION: ${task.description}
+FILES: ${task.files_to_modify.join(', ')}
+CONTEXT: ${JSON.stringify(task.context)}
+MODE: write
+EXPECTED: Task completed, files modified as specified
+" --tool codex --mode write
+```
+
+**Execution Behavior**:
+- One task at a time (serial, no parallel agents)
+- Wait for CLI completion before next task
+- Record result immediately after completion
+- Stop on critical failure (user can choose to continue)
+
+---
+
+## Step 4: Record Execution Log
+
+Maintain `execution-log.md` as unified execution history.
+
+**Output**: `${sessionFolder}/execution-log.md`
+
+**execution-log.md Structure**:
+
+```markdown
+# Execution Log
+
+## Session Info
+- **Session ID**: ${sessionId}
+- **Plan Source**: quick-plan.json (from analysis)
+- **Started**: ${startTime}
+- **Mode**: Serial Execution
+
+## Task Execution Timeline
+
+### ${timestamp} - TASK-001: ${title}
+- **Status**: completed | failed
+- **Duration**: ${duration}s
+- **Files Modified**: ${files.join(', ')}
+- **Summary**: ${resultSummary}
+- **Notes**: ${issues or discoveries}
+
+### ${timestamp} - TASK-002: ${title}
+...
+
+## Execution Summary
+- **Total Tasks**: ${total}
+- **Completed**: ${completed}
+- **Failed**: ${failed}
+- **Success Rate**: ${rate}%
+- **Total Duration**: ${duration}
+```
+
+**Log Entry Fields**:
+
+| Field | Content |
+|-------|---------|
+| Timestamp | ISO format execution time |
+| Task ID | TASK-XXX identifier |
+| Title | Task title from plan |
+| Status | completed / failed |
+| Duration | Execution time in seconds |
+| Files Modified | List of changed files |
+| Summary | Brief result description |
+| Notes | Issues discovered or special conditions |
+
+---
+
+## Step 5: Update quick-plan.json
+
+After each task, update plan with execution results.
+
+**Task Status Updates**:
+```javascript
+task.status = "completed" | "failed"
+task.executed_at = timestamp
+task.duration = seconds
+task.result = {
+  success: boolean,
+  files_modified: string[],
+  summary: string,
+  error: string | null
+}
+```
+
+---
+
+## Step 6: Completion Summary
+
+Present final execution results.
+
+**Summary Display**:
+- Session ID and folder path
+- Execution statistics (completed/failed/total)
+- Success rate percentage
+- Failed tasks requiring attention (if any)
+- Link to execution-log.md for details
+
+**Post-Execution Options** (ASK_USER - single select):
+
+| Option | Action |
+|--------|--------|
+| **Retry Failed** | Re-execute only failed tasks |
+| **View Log** | Display execution-log.md content |
+| **Create Issue** | Create issue from failed tasks |
+| **Done** | End workflow |
+
+**Retry Logic**:
+- Filter tasks with status: "failed"
+- Re-execute in original order
+- Append retry results to execution-log.md
+
+---
+
+## Output Structure
+
+When Quick Execute is activated, session folder expands with:
+
+```
+{projectRoot}/.workflow/.analysis/ANL-{slug}-{date}/
+├── ...                          # Phase 1-4 artifacts
+├── quick-plan.json              # Executable task plan
+└── execution-log.md             # Execution history
+```
+
+---
+
+## Error Handling
+
+| Situation | Action | Recovery |
+|-----------|--------|----------|
+| Task execution fails | Record failure in execution-log.md, ask user | Retry, skip, or abort remaining tasks |
+| CLI timeout | Mark task as failed with timeout reason | User can retry or skip |
+| No recommendations in conclusions | Cannot generate quick-plan.json | Inform user, suggest using lite-plan instead |
+| File conflict during execution | Document in execution-log.md | Resolve manually or adjust task order |
+
+---
+
+## Success Criteria
+
+- All tasks executed (or explicitly skipped)
+- `quick-plan.json` updated with final statuses
+- `execution-log.md` contains complete history
+- User informed of results and next steps

.codex/skills/analyze-with-file/SKILL.md

@@ -10,7 +10,7 @@ argument-hint: "TOPIC=\"<question or topic>\" [--depth=quick|standard|deep] [--c
 
 Interactive collaborative analysis workflow with **documented discussion process**. Records understanding evolution, facilitates multi-round Q&A, and uses **parallel subagent exploration** for deep analysis.
 
-**Core workflow**: Topic → Parallel Explore → Discuss → Document → Refine → Conclude
+**Core workflow**: Topic → Parallel Explore → Discuss → Document → Refine → Conclude → (Optional) Quick Execute
 
 ## Overview
 
@@ -20,6 +20,7 @@ This workflow enables iterative exploration and refinement of complex topics thr
 2. **Parallel Exploration** - Gather codebase context via parallel subagents (up to 4)
 3. **Interactive Discussion** - Multi-round Q&A with user feedback and direction adjustments
 4. **Synthesis & Conclusion** - Consolidate insights and generate actionable recommendations
+5. **Quick Execute** *(Optional)* - Convert conclusions to plan.json and execute serially with logging
 
 The key innovation is **documented discussion timeline** that captures the evolution of understanding across all phases, enabling users to track how insights develop and assumptions are corrected.
 
@@ -62,13 +63,20 @@ Phase 4: Synthesis & Conclusion
    ├─ Consolidate all insights and discussion rounds
    ├─ Generate final conclusions with recommendations
    ├─ Update discussion.md with synthesis
-   └─ Offer follow-up options (create issue, generate task, export report)
+   └─ Offer follow-up options (quick execute, create issue, generate task, export report)
+
+Phase 5: Quick Execute (Optional - user selects "简要执行")
+   ├─ Convert conclusions.recommendations → quick-plan.json
+   ├─ Present plan for user confirmation
+   ├─ Serial task execution via CLI (no agent exploration)
+   ├─ Record each task result to execution-log.md
+   └─ Report completion summary with statistics
 ```
 
 ## Output Structure
 
 ```
-.workflow/.analysis/ANL-{slug}-{date}/
+{projectRoot}/.workflow/.analysis/ANL-{slug}-{date}/
 ├── discussion.md                # ⭐ Evolution of understanding & discussions
 ├── exploration-codebase.json    # Phase 2: Codebase context (single perspective)
 ├── explorations/                # Phase 2: Multi-perspective explorations (if selected)
@@ -77,7 +85,9 @@ Phase 4: Synthesis & Conclusion
 │   └── ...
 ├── explorations.json            # Phase 2: Single perspective findings
 ├── perspectives.json            # Phase 2: Multi-perspective findings with synthesis
-└── conclusions.json             # Phase 4: Final synthesis with recommendations
+├── conclusions.json             # Phase 4: Final synthesis with recommendations
+├── quick-plan.json              # Phase 5: Executable task plan (if quick execute)
+└── execution-log.md             # Phase 5: Execution history (if quick execute)
 ```
 
 ## Output Artifacts
@@ -113,19 +123,37 @@ Phase 4: Synthesis & Conclusion
 | `conclusions.json` | Final synthesis: key conclusions, recommendations, open questions |
 | Final `discussion.md` | Complete analysis timeline with conclusions and final understanding |
 
+### Phase 5: Quick Execute (Optional)
+
+| Artifact | Purpose |
+|----------|---------|
+| `quick-plan.json` | Executable task plan converted from recommendations |
+| `execution-log.md` | Unified execution history with task results and statistics |
+
 ---
 
 ## Implementation Details
 
 ### Session Initialization
 
+##### Step 0: Determine Project Root
+
+检测项目根目录，确保 `.workflow/` 产物位置正确：
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+优先通过 git 获取仓库根目录；非 git 项目回退到 `pwd` 取当前绝对路径。
+存储为 `{projectRoot}`，后续所有 `.workflow/` 路径必须以此为前缀。
+
 The workflow automatically generates a unique session identifier and directory structure based on the topic and current date (UTC+8).
 
 **Session ID Format**: `ANL-{slug}-{date}`
 - `slug`: Lowercase alphanumeric + Chinese characters, max 40 chars (derived from topic)
 - `date`: YYYY-MM-DD format (UTC+8)
 
-**Session Directory**: `.workflow/.analysis/{sessionId}/`
+**Session Directory**: `{projectRoot}/.workflow/.analysis/{sessionId}/`
 
 **Auto-Detection**: If session folder exists with discussion.md, automatically enters continue mode. Otherwise, creates new session.
 
@@ -243,8 +271,8 @@ const explorationAgent = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -297,8 +325,8 @@ const agentIds = selectedPerspectives.map(perspective => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -515,7 +543,7 @@ const deepeningAgent = spawn_agent({
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
 2. Read: ${sessionFolder}/explorations.json (prior findings)
-3. Read: .workflow/project-tech.json
+3. Read: ${projectRoot}/.workflow/project-tech.json
 
 ---
 
@@ -557,7 +585,7 @@ const adjustedAgent = spawn_agent({
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
 2. Read: ${sessionFolder}/explorations.json (prior findings)
-3. Read: .workflow/project-tech.json
+3. Read: ${projectRoot}/.workflow/project-tech.json
 
 ---
 
@@ -764,6 +792,7 @@ Offer user follow-up actions based on analysis results.
 
 | Option | Purpose | Action |
 |--------|---------|--------|
+| **简要执行** | Quick execute from analysis | Jump to Phase 5: Generate quick-plan.json and execute serially |
 | **创建Issue** | Create actionable issue from findings | Launch `issue:new` with conclusions summary |
 | **生成任务** | Generate implementation task | Launch `workflow:lite-plan` for task breakdown |
 | **导出报告** | Generate standalone analysis report | Create formatted report document |
@@ -777,6 +806,35 @@ Offer user follow-up actions based on analysis results.
 
 ---
 
+## Phase 5: Quick Execute (简要执行)
+
+**Objective**: Convert analysis conclusions directly into executable tasks and run them serially without additional exploration.
+
+**Trigger**: User selects "简要执行" in Phase 4 post-completion options.
+
+**Key Principle**: **No additional agent exploration** - analysis phase has already collected all necessary context.
+
+**详细规范**: 📖 [EXECUTE.md](./EXECUTE.md)
+
+**Flow Summary**:
+```
+conclusions.json → quick-plan.json → 用户确认 → 串行CLI执行 → execution-log.md
+```
+
+**Steps**:
+1. **Generate quick-plan.json** - Convert `conclusions.recommendations` to executable tasks
+2. **User Confirmation** - Present plan, user approves / adjusts / cancels
+3. **Serial Execution** - Execute tasks via CLI `--mode write`, one at a time
+4. **Record Log** - Each task result appended to `execution-log.md`
+5. **Update Plan** - Update `quick-plan.json` with execution statuses
+6. **Completion** - Report statistics, offer retry/view log/create issue
+
+**Output**:
+- `${sessionFolder}/quick-plan.json` - Executable task plan with statuses
+- `${sessionFolder}/execution-log.md` - Unified execution history
+
+---
+
 ## Configuration
 
 ### Analysis Perspectives
@@ -841,6 +899,9 @@ Common focus areas that guide the analysis direction:
 | **User disengaged** | Summarize progress and offer break point | Save state, keep agents alive for resume |
 | **Max rounds reached (5)** | Force synthesis phase | Highlight remaining questions in conclusions |
 | **Session folder conflict** | Append timestamp suffix to session ID | Create unique folder and continue |
+| **Quick execute: task fails** | Record failure in execution-log.md, ask user | Retry, skip, or abort remaining tasks |
+| **Quick execute: CLI timeout** | Mark task as failed with timeout reason | User can retry or skip |
+| **Quick execute: no recommendations** | Cannot generate quick-plan.json | Inform user, suggest using lite-plan instead |
 
 ### Codex-Specific Error Patterns
 
@@ -954,6 +1015,28 @@ Final synthesis:
    └─ Archive session artifacts
 ```
 
+### Quick Execute Flow (Phase 5)
+
+```
+User selects "简要执行":
+   ├─ Read conclusions.json + explorations.json/perspectives.json
+   ├─ Convert recommendations → quick-plan.json
+   │   └─ No agent exploration (context already gathered)
+   ├─ Present plan to user for confirmation
+   │   ├─ 开始执行 → proceed
+   │   ├─ 调整任务 → modify and regenerate
+   │   └─ 取消 → keep plan, exit
+   │
+   ├─ Serial task execution:
+   │   ├─ TASK-001: CLI --mode write → record to execution-log.md
+   │   ├─ TASK-002: CLI --mode write → record to execution-log.md
+   │   └─ (repeat for all tasks)
+   │
+   ├─ Update quick-plan.json with statuses
+   ├─ Finalize execution-log.md with summary
+   └─ Offer post-execution options (retry/view log/create issue/done)
+```
+
 ---
 
 ## Best Practices
@@ -1054,6 +1137,12 @@ Each discussion round follows a consistent structure:
 - Building shared understanding before implementation
 - Want to document how understanding evolved
 
+### Use Quick Execute (Phase 5) when:
+- Analysis conclusions contain clear, actionable recommendations
+- Context is already sufficient - no additional exploration needed
+- Want a streamlined analyze → plan → execute pipeline in one session
+- Tasks are relatively independent and can be executed serially
+
 ### Use direct execution when:
 - Short, focused analysis tasks (single component)
 - Clear, well-defined topics with limited scope

.codex/skills/brainstorm-to-cycle/SKILL.md

@@ -57,8 +57,20 @@ Phase 4: Cycle Launch
 
 ### Phase 1: Session Loading
 
+##### Step 0: Determine Project Root
+
+检测项目根目录，确保 `.workflow/` 产物位置正确：
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+优先通过 git 获取仓库根目录；非 git 项目回退到 `pwd` 取当前绝对路径。
+存储为 `{projectRoot}`，后续所有 `.workflow/` 路径必须以此为前缀。
+
 ```javascript
 const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+const projectRoot = bash('git rev-parse --show-toplevel 2>/dev/null || pwd').trim()
 
 // Parse arguments
 const args = "$ARGUMENTS"
@@ -68,7 +80,7 @@ const preSelectedIdea = ideaIndexMatch ? parseInt(ideaIndexMatch[1]) : null
 const isAutoMode = args.includes('--auto')
 
 // Validate session
-const sessionFolder = `.workflow/.brainstorm/${sessionId}`
+const sessionFolder = `${projectRoot}/.workflow/.brainstorm/${sessionId}`
 const synthesisPath = `${sessionFolder}/synthesis.json`
 const brainstormPath = `${sessionFolder}/brainstorm.md`
 
@@ -85,7 +97,7 @@ Expected path: ${synthesisPath}
 
 **Available sessions**:
 `)
-  bash(`ls -1 .workflow/.brainstorm/ 2>/dev/null | head -10`)
+  bash(`ls -1 ${projectRoot}/.workflow/.brainstorm/ 2>/dev/null | head -10`)
   return { status: 'error', message: 'Session not found' }
 }
 
@@ -366,7 +378,7 @@ To launch manually:
 After execution:
 
 ```
-.workflow/.brainstorm/{session-id}/
+{projectRoot}/.workflow/.brainstorm/{session-id}/
 ├── brainstorm.md        # Original brainstorm
 ├── synthesis.json       # Synthesis data (input)
 ├── perspectives.json    # Perspectives data

.codex/skills/brainstorm-with-file/SKILL.md

@@ -38,7 +38,7 @@ The key innovation is **documented thought evolution** that captures how ideas d
 ## Output Structure
 
 ```
-.workflow/.brainstorm/BS-{slug}-{date}/
+{projectRoot}/.workflow/.brainstorm/BS-{slug}-{date}/
 ├── brainstorm.md                  # ⭐ Complete thought evolution timeline
 ├── exploration-codebase.json      # Phase 2: Codebase context
 ├── perspectives/                  # Phase 2: Individual perspective outputs
@@ -91,13 +91,24 @@ The key innovation is **documented thought evolution** that captures how ideas d
 
 ### Session Initialization
 
+##### Step 0: Determine Project Root
+
+检测项目根目录，确保 `.workflow/` 产物位置正确：
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+优先通过 git 获取仓库根目录；非 git 项目回退到 `pwd` 取当前绝对路径。
+存储为 `{projectRoot}`，后续所有 `.workflow/` 路径必须以此为前缀。
+
 The workflow automatically generates a unique session identifier and directory structure based on the topic and current date (UTC+8).
 
 **Session ID Format**: `BS-{slug}-{date}`
 - `slug`: Lowercase alphanumeric + Chinese characters, max 40 chars
 - `date`: YYYY-MM-DD format (UTC+8)
 
-**Session Directory**: `.workflow/.brainstorm/{sessionId}/`
+**Session Directory**: `{projectRoot}/.workflow/.brainstorm/{sessionId}/`
 
 **Auto-Detection**: If session folder exists with brainstorm.md, automatically enters continue mode. Otherwise, creates new session.
 
@@ -271,7 +282,7 @@ Use built-in tools to understand the codebase structure before spawning perspect
 **Context Gathering Activities**:
 1. **Get project structure** - Execute `ccw tool exec get_modules_by_depth '{}'`
 2. **Search for related code** - Use Grep/Glob to find files matching topic keywords
-3. **Read project tech context** - Load `.workflow/project-tech.json` if available
+3. **Read project tech context** - Load `{projectRoot}/.workflow/project-tech.json` if available
 4. **Analyze patterns** - Identify common code patterns and architecture decisions
 
 **exploration-codebase.json Structure**:
@@ -347,8 +358,8 @@ const agentIds = perspectives.map(perspective => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -555,7 +566,7 @@ const deepDiveAgent = spawn_agent({
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
 2. Read: ${sessionFolder}/perspectives.json (prior findings)
-3. Read: .workflow/project-tech.json
+3. Read: ${projectRoot}/.workflow/project-tech.json
 
 ---
 

.codex/skills/ccw-loop-b/README.md

@@ -91,7 +91,7 @@ Spawn multiple workers simultaneously, batch wait for results.
 ## Session Structure
 
 ```
-.workflow/.loop/
+{projectRoot}/.workflow/.loop/
 +-- {loopId}.json                    # Master state
 +-- {loopId}.workers/                # Worker outputs
 |   +-- init.output.json
@@ -184,7 +184,7 @@ Coordinator adapts to mode:
 
 ### 3. State Management
 
-Unified state at `.workflow/.loop/{loopId}.json`:
+Unified state at `{projectRoot}/.workflow/.loop/{loopId}.json`:
 - **API compatible**: Works with CCW API
 - **Extension fields**: Skill-specific data in `skill_state`
 - **Worker outputs**: Structured JSON for each action

.codex/skills/ccw-loop-b/SKILL.md

@@ -142,7 +142,7 @@ return finalState
 ## Session Structure
 
 ```
-.workflow/.loop/
+{projectRoot}/.workflow/.loop/
 ├── {loopId}.json                    # Master state (API + Skill shared)
 ├── {loopId}.workers/                # Worker structured outputs
 │   ├── init.output.json
@@ -159,7 +159,7 @@ return finalState
 
 ## State Management
 
-Master state file: `.workflow/.loop/{loopId}.json`
+Master state file: `{projectRoot}/.workflow/.loop/{loopId}.json`
 
 ```json
 {
@@ -233,8 +233,8 @@ function buildWorkerPrompt(action, loopId, state) {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/ccw-loop-b-${action}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -247,9 +247,9 @@ Scope:
 
 Context:
 - Loop ID: ${loopId}
-- State: .workflow/.loop/${loopId}.json
+- State: ${projectRoot}/.workflow/.loop/${loopId}.json
-- Output: .workflow/.loop/${loopId}.workers/${action}.output.json
+- Output: ${projectRoot}/.workflow/.loop/${loopId}.workers/${action}.output.json
-- Progress: .workflow/.loop/${loopId}.progress/${action}.md
+- Progress: ${projectRoot}/.workflow/.loop/${loopId}.progress/${action}.md
 
 Deliverables:
 - 按 WORKER_RESULT 格式输出
@@ -374,7 +374,7 @@ function mergeWorkerOutputs(outputs) {
 2. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
 3. **Parse Every Output**: Extract WORKER_RESULT from worker output for next decision
 4. **Worker 生命周期**: spawn → wait → [send_input if needed] → close，不长期保留 worker
-5. **结果持久化**: Worker 输出写入 `.workflow/.loop/{loopId}.workers/`
+5. **结果持久化**: Worker 输出写入 `{projectRoot}/.workflow/.loop/{loopId}.workers/`
 6. **状态同步**: 每次 worker 完成后更新 master state
 7. **超时处理**: send_input 请求收敛，再超时则使用已有结果继续
 8. **DO NOT STOP**: Continuous execution until completed, paused, or max iterations

.codex/skills/ccw-loop-b/phases/01-session-init.md

@@ -12,6 +12,13 @@ Create or resume a development loop, initialize state file and directory structu
 
 ## Execution
 
+### Step 0: Determine Project Root
+
+```javascript
+// Step 0: Determine Project Root
+const projectRoot = Bash('git rev-parse --show-toplevel 2>/dev/null || pwd').trim()
+```
+
 ### Step 1.1: Parse Arguments
 
 ```javascript
@@ -37,14 +44,14 @@ if (!validModes.includes(mode)) {
 const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
 
 function readState(loopId) {
-  const stateFile = `.workflow/.loop/${loopId}.json`
+  const stateFile = `${projectRoot}/.workflow/.loop/${loopId}.json`
   if (!fs.existsSync(stateFile)) return null
   return JSON.parse(Read(stateFile))
 }
 
 function saveState(loopId, state) {
   state.updated_at = getUtc8ISOString()
-  Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+  Write(`${projectRoot}/.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 }
 ```
 
@@ -63,8 +70,8 @@ console.log(`Creating new loop: ${loopId}`)
 #### Create Directory Structure
 
 ```bash
-mkdir -p .workflow/.loop/${loopId}.workers
+mkdir -p ${projectRoot}/.workflow/.loop/${loopId}.workers
-mkdir -p .workflow/.loop/${loopId}.progress
+mkdir -p ${projectRoot}/.workflow/.loop/${loopId}.progress
 ```
 
 #### Initialize State File
@@ -95,7 +102,7 @@ function createState(loopId, taskDescription, mode) {
     }
   }
 
-  Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+  Write(`${projectRoot}/.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
   return state
 }
 ```
@@ -146,8 +153,8 @@ function checkControlSignals(loopId) {
 
 - **Variable**: `loopId` - Unique loop identifier
 - **Variable**: `state` - Initialized or resumed loop state object
-- **Variable**: `progressDir` - `.workflow/.loop/${loopId}.progress`
+- **Variable**: `progressDir` - `${projectRoot}/.workflow/.loop/${loopId}.progress`
-- **Variable**: `workersDir` - `.workflow/.loop/${loopId}.workers`
+- **Variable**: `workersDir` - `${projectRoot}/.workflow/.loop/${loopId}.workers`
 - **Variable**: `mode` - `'interactive'` / `'auto'` / `'parallel'`
 - **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
 

.codex/skills/ccw-loop-b/phases/02-orchestration-loop.md

@@ -227,8 +227,8 @@ function buildWorkerPrompt(action, loopId, state) {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ${roleFiles[action]} (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -242,9 +242,9 @@ Scope:
 Context:
 - Loop ID: ${loopId}
 - Action: ${action}
-- State File: .workflow/.loop/${loopId}.json
+- State File: ${projectRoot}/.workflow/.loop/${loopId}.json
-- Output File: .workflow/.loop/${loopId}.workers/${action}.output.json
+- Output File: ${projectRoot}/.workflow/.loop/${loopId}.workers/${action}.output.json
-- Progress File: .workflow/.loop/${loopId}.progress/${action}.md
+- Progress File: ${projectRoot}/.workflow/.loop/${loopId}.progress/${action}.md
 
 Deliverables:
 - WORKER_RESULT 格式输出
@@ -432,7 +432,7 @@ async function showMenuAndGetChoice(state) {
 
 ```javascript
 function persistWorkerOutput(loopId, action, workerResult) {
-  const outputPath = `.workflow/.loop/${loopId}.workers/${action}.output.json`
+  const outputPath = `${projectRoot}/.workflow/.loop/${loopId}.workers/${action}.output.json`
   Write(outputPath, JSON.stringify({
     ...workerResult,
     timestamp: getUtc8ISOString()

.codex/skills/ccw-loop-b/phases/orchestrator.md

@@ -14,7 +14,7 @@ Read state -> Select mode -> Spawn workers -> Wait results -> Merge -> Update st
 
 ```javascript
 function readState(loopId) {
-  const stateFile = `.workflow/.loop/${loopId}.json`
+  const stateFile = `${projectRoot}/.workflow/.loop/${loopId}.json`
   return fs.existsSync(stateFile)
     ? JSON.parse(Read(stateFile))
     : null
@@ -178,8 +178,8 @@ function buildWorkerPrompt(action, loopId, state) {
 
 ### MANDATORY FIRST STEPS
 1. **Read role definition**: ${roleFiles[action]}
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -252,6 +252,6 @@ function parseWorkerResult(output) {
 ## Best Practices
 
 1. **Worker 生命周期**: spawn → wait → close，不保留 worker
-2. **结果持久化**: Worker 输出写入 `.workflow/.loop/{loopId}.workers/`
+2. **结果持久化**: Worker 输出写入 `{projectRoot}/.workflow/.loop/{loopId}.workers/`
 3. **状态同步**: 每次 worker 完成后更新 state
 4. **超时处理**: send_input 请求收敛，再超时则跳过

.codex/skills/ccw-loop-b/phases/state-schema.md

@@ -56,7 +56,7 @@
 
 ## Worker Output Structure
 
-Each worker writes to `.workflow/.loop/{loopId}.workers/{action}.output.json`:
+Each worker writes to `{projectRoot}/.workflow/.loop/{loopId}.workers/{action}.output.json`:
 
 ```json
 {
@@ -81,7 +81,7 @@ Each worker writes to `.workflow/.loop/{loopId}.workers/{action}.output.json`:
 
 ## Progress File Structure
 
-Human-readable progress in `.workflow/.loop/{loopId}.progress/{action}.md`:
+Human-readable progress in `{projectRoot}/.workflow/.loop/{loopId}.progress/{action}.md`:
 
 ```markdown
 # Develop Progress
@@ -165,7 +165,7 @@ When `mode === 'parallel'`:
 ## Directory Structure
 
 ```
-.workflow/.loop/
+{projectRoot}/.workflow/.loop/
 +-- loop-b-20260122-abc123.json          # Master state
 +-- loop-b-20260122-abc123.workers/
 |   +-- init.output.json

.codex/skills/ccw-loop-b/specs/action-catalog.md

@@ -29,8 +29,8 @@ Complete reference of worker actions and their capabilities.
 ```
 
 **Execution**:
-1. Read `.workflow/project-tech.json`
+1. Read `{projectRoot}/.workflow/project-tech.json`
-2. Read `.workflow/project-guidelines.json`
+2. Read `{projectRoot}/.workflow/project-guidelines.json`
 3. Parse task into phases
 4. Create task breakdown
 5. Generate execution plan

.codex/skills/ccw-loop-b/workers/worker-init.md

@@ -21,8 +21,8 @@ Session initialization worker. Parse requirements, create execution plan.
 ```javascript
 // MANDATORY FIRST STEPS (already in prompt)
 // 1. Read role definition
-// 2. Read .workflow/project-tech.json
+// 2. Read ${projectRoot}/.workflow/project-tech.json
-// 3. Read .workflow/project-guidelines.json
+// 3. Read ${projectRoot}/.workflow/project-guidelines.json
 ```
 
 ### Step 2: Analyze Task

.codex/skills/ccw-loop/SKILL.md

@@ -20,8 +20,8 @@ Stateless iterative development loop using Codex single-agent deep interaction p
 +-------------------------------------------------------------+
 |              loop-v2-routes.ts (Control Plane)               |
 |                                                              |
-|  State: .workflow/.loop/{loopId}.json (MASTER)               |
+|  State: {projectRoot}/.workflow/.loop/{loopId}.json (MASTER)  |
-|  Tasks: .workflow/.loop/{loopId}.tasks.jsonl                 |
+|  Tasks: {projectRoot}/.workflow/.loop/{loopId}.tasks.jsonl   |
 |                                                              |
 |  /start  -> Trigger ccw-loop skill with --loop-id           |
 |  /pause  -> Set status='paused' (skill checks before action) |
@@ -43,9 +43,9 @@ Stateless iterative development loop using Codex single-agent deep interaction p
 ## Key Design Principles
 
 1. **Single Agent Deep Interaction**: One agent handles entire loop lifecycle via `send_input` (no multi-agent overhead)
-2. **Unified State**: API and Skill share `.workflow/.loop/{loopId}.json` state file
+2. **Unified State**: API and Skill share `{projectRoot}/.workflow/.loop/{loopId}.json` state file
 3. **Control Signals**: Skill checks `status` field before each action (paused/stopped → graceful exit)
-4. **File-Driven Progress**: All progress documented in `.workflow/.loop/{loopId}.progress/`
+4. **File-Driven Progress**: All progress documented in `{projectRoot}/.workflow/.loop/{loopId}.progress/`
 5. **Resumable**: Continue any loop with `--loop-id`
 6. **Dual Trigger**: Supports API trigger (`--loop-id`) and direct call (task description)
 
@@ -134,7 +134,7 @@ close_agent → return finalState
 ## Session Structure
 
 ```
-.workflow/.loop/
+{projectRoot}/.workflow/.loop/
 ├── {loopId}.json              # Master state file (API + Skill shared)
 ├── {loopId}.tasks.jsonl       # Task list (API managed)
 └── {loopId}.progress/         # Skill progress files
@@ -151,7 +151,7 @@ close_agent → return finalState
 
 ## State Management
 
-Master state file: `.workflow/.loop/{loopId}.json`
+Master state file: `{projectRoot}/.workflow/.loop/{loopId}.json`
 
 ```json
 {
@@ -203,7 +203,7 @@ Master state file: `.workflow/.loop/{loopId}.json`
 - `failed` → terminate
 - Other → stop
 
-**Recovery**: If state corrupted, rebuild `skill_state` from `.progress/` markdown files and logs.
+**Recovery**: If state corrupted, rebuild `skill_state` from `{projectRoot}/.workflow/.loop/{loopId}.progress/` markdown files and logs.
 
 ## Action Catalog
 

.codex/skills/ccw-loop/actions/action-complete.md

@@ -20,7 +20,7 @@ Complete CCW Loop session and generate summary report.
 ### Step 1: Verify Control Signals
 
 ```javascript
-const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
+const state = JSON.parse(Read(`${projectRoot}/.workflow/.loop/${loopId}.json`))
 
 if (state.status !== 'running') {
   return {
@@ -174,7 +174,7 @@ state.updated_at = timestamp
 state.skill_state.last_action = 'COMPLETE'
 state.skill_state.summary = stats
 
-Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`${projectRoot}/.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ## Output Format
@@ -190,8 +190,8 @@ ACTION_RESULT:
   }
 
 FILES_UPDATED:
-- .workflow/.loop/{loopId}.json: Status set to completed
+- {projectRoot}/.workflow/.loop/{loopId}.json: Status set to completed
-- .workflow/.loop/{loopId}.progress/summary.md: Summary report generated
+- {projectRoot}/.workflow/.loop/{loopId}.progress/summary.md: Summary report generated
 
 NEXT_ACTION_NEEDED: COMPLETED
 ```

.codex/skills/ccw-loop/actions/action-debug.md

@@ -233,7 +233,7 @@ if (confirmedHypothesis) {
 
 state.skill_state.last_action = 'DEBUG'
 state.updated_at = timestamp
-Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`${projectRoot}/.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ## Output Format
@@ -249,8 +249,8 @@ ACTION_RESULT:
   }
 
 FILES_UPDATED:
-- .workflow/.loop/{loopId}.progress/debug.md: Understanding updated
+- {projectRoot}/.workflow/.loop/{loopId}.progress/debug.md: Understanding updated
-- .workflow/.loop/{loopId}.progress/hypotheses.json: Hypotheses updated
+- {projectRoot}/.workflow/.loop/{loopId}.progress/hypotheses.json: Hypotheses updated
 - [Source files]: Instrumentation added
 
 NEXT_ACTION_NEEDED: {DEBUG | VALIDATE | DEVELOP | MENU}

.codex/skills/ccw-loop/actions/action-develop.md

@@ -20,7 +20,7 @@ Execute development task and record progress to develop.md.
 ### Step 1: Verify Control Signals
 
 ```javascript
-const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
+const state = JSON.parse(Read(`${projectRoot}/.workflow/.loop/${loopId}.json`))
 
 if (state.status !== 'running') {
   return {
@@ -133,7 +133,7 @@ state.skill_state.last_action = 'DEVELOP'
 state.skill_state.completed_actions.push('DEVELOP')
 state.updated_at = timestamp
 
-Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`${projectRoot}/.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ## Output Format
@@ -149,9 +149,9 @@ ACTION_RESULT:
   }
 
 FILES_UPDATED:
-- .workflow/.loop/{loopId}.json: Task status updated
+- {projectRoot}/.workflow/.loop/{loopId}.json: Task status updated
-- .workflow/.loop/{loopId}.progress/develop.md: Progress entry added
+- {projectRoot}/.workflow/.loop/{loopId}.progress/develop.md: Progress entry added
-- .workflow/.loop/{loopId}.progress/changes.log: Change entry added
+- {projectRoot}/.workflow/.loop/{loopId}.progress/changes.log: Change entry added
 
 NEXT_ACTION_NEEDED: {DEVELOP | DEBUG | VALIDATE | MENU}
 ```

.codex/skills/ccw-loop/actions/action-init.md

@@ -19,7 +19,7 @@ Initialize CCW Loop session, create directory structure and initial state.
 ### Step 1: Verify Control Signals
 
 ```javascript
-const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
+const state = JSON.parse(Read(`${projectRoot}/.workflow/.loop/${loopId}.json`))
 
 if (state.status !== 'running') {
   return {
@@ -34,7 +34,7 @@ if (state.status !== 'running') {
 ### Step 2: Create Directory Structure
 
 ```javascript
-const progressDir = `.workflow/.loop/${loopId}.progress`
+const progressDir = `${projectRoot}/.workflow/.loop/${loopId}.progress`
 
 // Directories created by orchestrator, verify they exist
 // mkdir -p ${progressDir}
@@ -131,7 +131,7 @@ const skillState = {
 
 state.skill_state = skillState
 state.updated_at = getUtc8ISOString()
-Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`${projectRoot}/.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ## Output Format
@@ -143,8 +143,8 @@ ACTION_RESULT:
 - message: Session initialized with {N} development tasks
 
 FILES_UPDATED:
-- .workflow/.loop/{loopId}.json: skill_state initialized
+- {projectRoot}/.workflow/.loop/{loopId}.json: skill_state initialized
-- .workflow/.loop/{loopId}.progress/develop.md: Progress document created
+- {projectRoot}/.workflow/.loop/{loopId}.progress/develop.md: Progress document created
 
 NEXT_ACTION_NEEDED: {DEVELOP (auto) | MENU (interactive)}
 ```

.codex/skills/ccw-loop/actions/action-menu.md

@@ -20,7 +20,7 @@ Display interactive action menu for user selection.
 ### Step 1: Verify Control Signals
 
 ```javascript
-const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
+const state = JSON.parse(Read(`${projectRoot}/.workflow/.loop/${loopId}.json`))
 
 if (state.status !== 'running') {
   return {
@@ -172,7 +172,7 @@ If user selects "exit":
 // Save current state
 state.status = 'user_exit'
 state.updated_at = getUtc8ISOString()
-Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`${projectRoot}/.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 
 return {
   action: 'MENU',

.codex/skills/ccw-loop/actions/action-validate.md

@@ -21,7 +21,7 @@ Run tests and verify implementation, record results to validate.md.
 ### Step 1: Verify Control Signals
 
 ```javascript
-const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
+const state = JSON.parse(Read(`${projectRoot}/.workflow/.loop/${loopId}.json`))
 
 if (state.status !== 'running') {
   return {
@@ -174,7 +174,7 @@ state.skill_state.validate.last_run_at = timestamp
 
 state.skill_state.last_action = 'VALIDATE'
 state.updated_at = timestamp
-Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`${projectRoot}/.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ## Output Format
@@ -191,9 +191,9 @@ ACTION_RESULT:
   }
 
 FILES_UPDATED:
-- .workflow/.loop/{loopId}.progress/validate.md: Validation report created
+- {projectRoot}/.workflow/.loop/{loopId}.progress/validate.md: Validation report created
-- .workflow/.loop/{loopId}.progress/test-results.json: Test results saved
+- {projectRoot}/.workflow/.loop/{loopId}.progress/test-results.json: Test results saved
-- .workflow/.loop/{loopId}.progress/coverage.json: Coverage data saved (if available)
+- {projectRoot}/.workflow/.loop/{loopId}.progress/coverage.json: Coverage data saved (if available)
 
 NEXT_ACTION_NEEDED: {COMPLETE | DEBUG | DEVELOP | MENU}
 ```

.codex/skills/ccw-loop/phases/01-session-init.md

@@ -12,6 +12,13 @@ Create or resume a development loop, initialize state file and directory structu
 
 ## Execution
 
+### Step 0: Determine Project Root
+
+```javascript
+// Step 0: Determine Project Root
+const projectRoot = Bash('git rev-parse --show-toplevel 2>/dev/null || pwd').trim()
+```
+
 ### Step 1.1: Parse Arguments
 
 ```javascript
@@ -33,7 +40,7 @@ const executionMode = options['--auto'] ? 'auto' : 'interactive'
 const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
 
 function readLoopState(loopId) {
-  const stateFile = `.workflow/.loop/${loopId}.json`
+  const stateFile = `${projectRoot}/.workflow/.loop/${loopId}.json`
   if (!fs.existsSync(stateFile)) {
     return null
   }
@@ -57,14 +64,14 @@ console.log(`Creating new loop: ${loopId}`)
 #### Create Directory Structure
 
 ```bash
-mkdir -p .workflow/.loop/${loopId}.progress
+mkdir -p ${projectRoot}/.workflow/.loop/${loopId}.progress
 ```
 
 #### Initialize State File
 
 ```javascript
 function createLoopState(loopId, taskDescription) {
-  const stateFile = `.workflow/.loop/${loopId}.json`
+  const stateFile = `${projectRoot}/.workflow/.loop/${loopId}.json`
   const now = getUtc8ISOString()
 
   const state = {
@@ -129,7 +136,7 @@ function checkControlSignals(loopId) {
 
 - **Variable**: `loopId` - Unique loop identifier
 - **Variable**: `state` - Initialized or resumed loop state object
-- **Variable**: `progressDir` - `.workflow/.loop/${loopId}.progress`
+- **Variable**: `progressDir` - `${projectRoot}/.workflow/.loop/${loopId}.progress`
 - **Variable**: `mode` - `'interactive'` or `'auto'`
 - **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
 

.codex/skills/ccw-loop/phases/02-orchestration-loop.md

@@ -23,15 +23,15 @@ const agent = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/ccw-loop-executor.md (MUST read first)
-2. Read: .workflow/project-tech.json (if exists)
+2. Read: ${projectRoot}/.workflow/project-tech.json (if exists)
-3. Read: .workflow/project-guidelines.json (if exists)
+3. Read: ${projectRoot}/.workflow/project-guidelines.json (if exists)
 
 ---
 
 ## LOOP CONTEXT
 
 - **Loop ID**: ${loopId}
-- **State File**: .workflow/.loop/${loopId}.json
+- **State File**: ${projectRoot}/.workflow/.loop/${loopId}.json
 - **Progress Dir**: ${progressDir}
 - **Mode**: ${mode}
 
@@ -48,7 +48,7 @@ ${state.description || task}
 You are executing CCW Loop orchestrator. Your job:
 
 1. **Check Control Signals**
-   - Read .workflow/.loop/${loopId}.json
+   - Read ${projectRoot}/.workflow/.loop/${loopId}.json
    - If status === 'paused' -> Output "PAUSED" and stop
    - If status === 'failed' -> Output "STOPPED" and stop
    - If status === 'running' -> Continue
@@ -62,7 +62,7 @@ You are executing CCW Loop orchestrator. Your job:
 3. **Execute Action**
    - Follow action instructions from ~/.codex/skills/ccw-loop/actions/
    - Update progress files in ${progressDir}/
-   - Update state in .workflow/.loop/${loopId}.json
+   - Update state in ${projectRoot}/.workflow/.loop/${loopId}.json
 
 4. **Output Format**
    \`\`\`
@@ -123,7 +123,7 @@ Execution timeout reached. Please:
   state = readLoopState(loopId)
   state.current_iteration = iteration
   state.updated_at = getUtc8ISOString()
-  Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+  Write(`${projectRoot}/.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 
   // Handle different outcomes
   switch (actionResult.next_action) {

.codex/skills/clean/SKILL.md

@@ -59,6 +59,17 @@ Phase 4: Execution
 
 ### Phase 0: Initialization
 
+##### Step 0: Determine Project Root
+
+检测项目根目录，确保 `.workflow/` 产物位置正确：
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+优先通过 git 获取仓库根目录；非 git 项目回退到 `pwd` 取当前绝对路径。
+存储为 `{projectRoot}`，后续所有 `.workflow/` 路径必须以此为前缀。
+
 ```javascript
 const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
 
@@ -71,9 +82,9 @@ const focusArea = focusMatch ? focusMatch[1] : "$FOCUS" !== "$" + "FOCUS" ? "$FO
 // Session setup
 const dateStr = getUtc8ISOString().substring(0, 10)
 const sessionId = `clean-${dateStr}`
-const sessionFolder = `.workflow/.clean/${sessionId}`
+const sessionFolder = `${projectRoot}/.workflow/.clean/${sessionId}`
 const trashFolder = `${sessionFolder}/.trash`
-const projectRoot = process.cwd()
+const projectRoot = bash('git rev-parse --show-toplevel 2>/dev/null || pwd').trim()
 
 bash(`mkdir -p ${sessionFolder}`)
 bash(`mkdir -p ${trashFolder}`)
@@ -153,7 +164,7 @@ try {
 
 ### MANDATORY FIRST STEPS
 1. Read: ~/.codex/agents/cli-explore-agent.md
-2. Read: .workflow/project-tech.json (if exists)
+2. Read: ${projectRoot}/.workflow/project-tech.json (if exists)
 
 ## Task Objective
 Discover stale artifacts for cleanup.
@@ -165,11 +176,11 @@ Discover stale artifacts for cleanup.
 ## Discovery Categories
 
 ### 1. Stale Workflow Sessions
-Scan: .workflow/active/WFS-*, .workflow/archives/WFS-*, .workflow/.lite-plan/*, .workflow/.debug/DBG-*
+Scan: ${projectRoot}/.workflow/active/WFS-*, ${projectRoot}/.workflow/archives/WFS-*, ${projectRoot}/.workflow/.lite-plan/*, ${projectRoot}/.workflow/.debug/DBG-*
 Criteria: No modification >7 days + no related git commits
 
 ### 2. Drifted Documents
-Scan: .claude/rules/tech/*, .workflow/.scratchpad/*
+Scan: .claude/rules/tech/*, ${projectRoot}/.workflow/.scratchpad/*
 Criteria: >30% broken references to non-existent files
 
 ### 3. Dead Code
@@ -355,7 +366,7 @@ Write(`${sessionFolder}/cleanup-report.json`, JSON.stringify({
 ## Session Folder
 
 ```
-.workflow/.clean/clean-{YYYY-MM-DD}/
+{projectRoot}/.workflow/.clean/clean-{YYYY-MM-DD}/
 ├── mainline-profile.json     # Git history analysis
 ├── cleanup-manifest.json     # Discovery results
 ├── cleanup-report.json       # Execution results

.codex/skills/collaborative-plan-with-file/SKILL.md

@@ -38,7 +38,7 @@ The key innovation is the **Plan Note** architecture - a shared collaborative do
 ## Output Structure
 
 ```
-.workflow/.planning/CPLAN-{slug}-{date}/
+{projectRoot}/.workflow/.planning/CPLAN-{slug}-{date}/
 ├── plan-note.md                  # ⭐ Core: Requirements + Tasks + Conflicts
 ├── requirement-analysis.json     # Phase 1: Sub-domain assignments
 ├── agents/                       # Phase 2: Per-domain plans (serial)
@@ -86,13 +86,24 @@ The key innovation is the **Plan Note** architecture - a shared collaborative do
 
 ### Session Initialization
 
+##### Step 0: Determine Project Root
+
+检测项目根目录，确保 `.workflow/` 产物位置正确：
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+优先通过 git 获取仓库根目录；非 git 项目回退到 `pwd` 取当前绝对路径。
+存储为 `{projectRoot}`，后续所有 `.workflow/` 路径必须以此为前缀。
+
 The workflow automatically generates a unique session identifier and directory structure.
 
 **Session ID Format**: `CPLAN-{slug}-{date}`
 - `slug`: Lowercase alphanumeric, max 30 chars
 - `date`: YYYY-MM-DD format (UTC+8)
 
-**Session Directory**: `.workflow/.planning/{sessionId}/`
+**Session Directory**: `{projectRoot}/.workflow/.planning/{sessionId}/`
 
 **Auto-Detection**: If session folder exists with plan-note.md, automatically enters continue mode.
 
@@ -214,8 +225,8 @@ const agentIds = subDomains.map(sub => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-lite-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 4. Read: ${sessionFolder}/plan-note.md (understand template structure)
 5. Read: ${sessionFolder}/requirement-analysis.json (understand full context)
 

.codex/skills/debug-with-file/SKILL.md

@@ -61,14 +61,26 @@ Fix & Cleanup:
 
 ### Session Setup & Mode Detection
 
+##### Step 0: Determine Project Root
+
+检测项目根目录，确保 `.workflow/` 产物位置正确：
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+优先通过 git 获取仓库根目录；非 git 项目回退到 `pwd` 取当前绝对路径。
+存储为 `{projectRoot}`，后续所有 `.workflow/` 路径必须以此为前缀。
+
 ```javascript
 const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+const projectRoot = bash('git rev-parse --show-toplevel 2>/dev/null || pwd').trim()
 
 const bugSlug = "$BUG".toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30)
 const dateStr = getUtc8ISOString().substring(0, 10)
 
 const sessionId = `DBG-${bugSlug}-${dateStr}`
-const sessionFolder = `.workflow/.debug/${sessionId}`
+const sessionFolder = `${projectRoot}/.workflow/.debug/${sessionId}`
 const debugLogPath = `${sessionFolder}/debug.log`
 const understandingPath = `${sessionFolder}/understanding.md`
 const hypothesesPath = `${sessionFolder}/hypotheses.json`
@@ -429,7 +441,7 @@ for (const file of instrumentedFiles) {
 ## Session Folder Structure
 
 ```
-.workflow/.debug/DBG-{slug}-{date}/
+{projectRoot}/.workflow/.debug/DBG-{slug}-{date}/
 ├── debug.log           # NDJSON log (execution evidence)
 ├── understanding.md    # Exploration timeline + consolidated understanding
 └── hypotheses.json     # Hypothesis history with verdicts
@@ -530,9 +542,9 @@ After Reproduction (BUG="error"):
        └─ All rejected → Assisted new hypotheses
 
 Output:
-   ├─ .workflow/.debug/DBG-{slug}-{date}/debug.log
+   ├─ {projectRoot}/.workflow/.debug/DBG-{slug}-{date}/debug.log
-   ├─ .workflow/.debug/DBG-{slug}-{date}/understanding.md (evolving document)
+   ├─ {projectRoot}/.workflow/.debug/DBG-{slug}-{date}/understanding.md (evolving document)
-   └─ .workflow/.debug/DBG-{slug}-{date}/hypotheses.json (history)
+   └─ {projectRoot}/.workflow/.debug/DBG-{slug}-{date}/hypotheses.json (history)
 ```
 
 ## Error Handling

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

@@ -218,8 +218,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ## TASK CONTEXT
 ${taskContext}

.codex/skills/issue-discover/phases/01-issue-new.md

@@ -210,7 +210,7 @@ if (publishToGitHub) {
 
 **Workflow:**
 ```
-1. Create local issue (ISS-YYYYMMDD-NNN) → stored in .workflow/issues.jsonl
+1. Create local issue (ISS-YYYYMMDD-NNN) → stored in {projectRoot}/.workflow/issues.jsonl
 2. If publishToGitHub:
    a. gh issue create → returns GitHub URL
    b. Update local issue with github_url + github_number binding

.codex/skills/issue-discover/phases/02-discover.md

@@ -9,7 +9,7 @@ Multi-perspective issue discovery orchestrator that explores code from different
 **Core workflow**: Initialize → Select Perspectives → Parallel Analysis → Aggregate → Generate Issues → User Action
 
 **Discovery Scope**: Specified modules/files only
-**Output Directory**: `.workflow/issues/discoveries/{discovery-id}/`
+**Output Directory**: `{projectRoot}/.workflow/issues/discoveries/{discovery-id}/`
 **Available Perspectives**: bug, ux, test, quality, security, performance, maintainability, best-practices
 **Exa Integration**: Auto-enabled for security and best-practices perspectives
 **CLI Tools**: Gemini → Qwen → Codex (fallback chain)
@@ -60,7 +60,7 @@ if (resolvedFiles.length === 0) {
 const discoveryId = `DSC-${formatDate(new Date(), 'YYYYMMDD-HHmmss')}`;
 
 // Create output directory
-const outputDir = `.workflow/issues/discoveries/${discoveryId}`;
+const outputDir = `${projectRoot}/.workflow/issues/discoveries/${discoveryId}`;
 await mkdir(outputDir, { recursive: true });
 await mkdir(`${outputDir}/perspectives`, { recursive: true });
 
@@ -117,8 +117,8 @@ selectedPerspectives.forEach(perspective => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -195,8 +195,8 @@ if (selectedPerspectives.includes('security') || selectedPerspectives.includes('
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -204,7 +204,7 @@ if (selectedPerspectives.includes('security') || selectedPerspectives.includes('
 Research industry best practices for ${perspective} using Exa search
 
 ## Research Steps
-1. Read project tech stack: .workflow/project-tech.json
+1. Read project tech stack: {projectRoot}/.workflow/project-tech.json
 2. Use Exa to search for best practices
 3. Synthesize findings relevant to this project
 
@@ -287,7 +287,7 @@ await ASK_USER([{
 }]);  // BLOCKS (wait for user response)
 
 if (response === "Export to Issues") {
-  await appendJsonl('.workflow/issues/issues.jsonl', issues);
+  await appendJsonl(`${projectRoot}/.workflow/issues/issues.jsonl`, issues);
 }
 ```
 
@@ -320,7 +320,7 @@ function getPerspectiveGuidance(perspective) {
 ## Output File Structure
 
 ```
-.workflow/issues/discoveries/
+{projectRoot}/.workflow/issues/discoveries/
 ├── index.json                           # Discovery session index
 └── {discovery-id}/
     ├── discovery-state.json             # Unified state

.codex/skills/issue-discover/phases/03-discover-by-prompt.md

@@ -56,7 +56,7 @@ const { prompt, scope, depth, maxIterations } = parseArgs(args);
 const discoveryId = `DBP-${formatDate(new Date(), 'YYYYMMDD-HHmmss')}`;
 
 // Create output directory
-const outputDir = `.workflow/issues/discoveries/${discoveryId}`;
+const outputDir = `${projectRoot}/.workflow/issues/discoveries/${discoveryId}`;
 await mkdir(outputDir, { recursive: true });
 await mkdir(`${outputDir}/iterations`, { recursive: true });
 
@@ -415,8 +415,8 @@ function buildDimensionPromptWithACE(dimension, iteration, previousFindings, ace
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -467,7 +467,7 @@ ${dimension.agent_prompt}
 ## Output File Structure
 
 ```
-.workflow/issues/discoveries/
+{projectRoot}/.workflow/issues/discoveries/
 └── {DBP-YYYYMMDD-HHmmss}/
     ├── discovery-state.json          # Session state with iteration tracking
     ├── iterations/

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

@@ -53,8 +53,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ## TASK CONTEXT
 ${taskContext}

.codex/skills/issue-resolve/phases/01-issue-plan.md

@@ -13,7 +13,7 @@ Batch plan issue resolution using **issue-plan-agent** that combines exploration
 
 - Issue IDs provided (comma-separated) or `--all-pending` flag
 - `ccw issue` CLI available
-- `.workflow/issues/` directory exists or will be created
+- `{projectRoot}/.workflow/issues/` directory exists or will be created
 
 ## Auto Mode
 
@@ -95,7 +95,7 @@ update_plan({
 ### Step 1.2: Unified Explore + Plan (issue-plan-agent) - PARALLEL
 
 ```javascript
-Bash(`mkdir -p .workflow/issues/solutions`);
+Bash(`mkdir -p ${projectRoot}/.workflow/issues/solutions`);
 const pendingSelections = [];  // Collect multi-solution issues for user selection
 const agentResults = [];       // Collect all agent results for conflict aggregation
 
@@ -109,8 +109,8 @@ const agentTasks = batches.map((batch, batchIndex) => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/issue-plan-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -122,8 +122,8 @@ ${issueList}
 **Project Root**: ${process.cwd()}
 
 ### Project Context (MANDATORY)
-1. Read: .workflow/project-tech.json (technology stack, architecture)
+1. Read: {projectRoot}/.workflow/project-tech.json (technology stack, architecture)
-2. Read: .workflow/project-guidelines.json (constraints and conventions)
+2. Read: {projectRoot}/.workflow/project-guidelines.json (constraints and conventions)
 
 ### Workflow
 1. Fetch issue details: ccw issue status <id> --json
@@ -138,7 +138,7 @@ ${issueList}
    - **If previous solution failed**: Reference failure analysis in solution.approach
    -  Add explicit verification steps to prevent same failure mode
 6. **If github_url exists**: Add final task to comment on GitHub issue
-7. Write solution to: .workflow/issues/solutions/{issue-id}.jsonl
+7. Write solution to: ${projectRoot}/.workflow/issues/solutions/{issue-id}.jsonl
 8. **CRITICAL - Binding Decision**:
    - Single solution → **MUST execute**: ccw issue bind <issue-id> <solution-id>
    - Multiple solutions → Return pending_selection only (no bind)

.codex/skills/issue-resolve/phases/02-convert-to-plan.md

@@ -5,8 +5,8 @@
 Converts various planning artifact formats into issue workflow solutions with intelligent detection and automatic binding.
 
 **Supported Sources** (auto-detected):
-- **lite-plan**: `.workflow/.lite-plan/{slug}/plan.json`
+- **lite-plan**: `{projectRoot}/.workflow/.lite-plan/{slug}/plan.json`
-- **workflow-session**: `WFS-xxx` ID or `.workflow/active/{session}/` folder
+- **workflow-session**: `WFS-xxx` ID or `{projectRoot}/.workflow/active/{session}/` folder
 - **markdown**: Any `.md` file with implementation/task content
 - **json**: Direct JSON files matching plan-json-schema
 
@@ -14,7 +14,7 @@ Converts various planning artifact formats into issue workflow solutions with in
 
 - Source artifact path or WFS-xxx ID provided
 - `ccw issue` CLI available
-- `.workflow/issues/` directory exists or will be created
+- `{projectRoot}/.workflow/issues/` directory exists or will be created
 
 ## Auto Mode
 
@@ -91,7 +91,7 @@ const source = extractSourceArg(input);
 function detectSourceType(source) {
   // Check for WFS-xxx pattern (workflow session ID)
   if (source.match(/^WFS-[\w-]+$/)) {
-    return { type: 'workflow-session-id', path: `.workflow/active/${source}` };
+    return { type: 'workflow-session-id', path: `${projectRoot}/.workflow/active/${source}` };
   }
 
   // Check if directory
@@ -591,9 +591,9 @@ if (!flags.yes && !flags.y) {
 }
 
 // Persist solution (following issue-plan-agent pattern)
-Bash(`mkdir -p .workflow/issues/solutions`);
+Bash(`mkdir -p ${projectRoot}/.workflow/issues/solutions`);
 
-const solutionFile = `.workflow/issues/solutions/${issueId}.jsonl`;
+const solutionFile = `${projectRoot}/.workflow/issues/solutions/${issueId}.jsonl`;
 
 if (flags.supplement) {
   // Supplement mode: update existing solution line atomically
@@ -686,6 +686,6 @@ console.log(`
 
 After conversion completion:
 - Issue created/updated with `status: planned` and `bound_solution_id` set
-- Solution persisted in `.workflow/issues/solutions/{issue-id}.jsonl`
+- Solution persisted in `{projectRoot}/.workflow/issues/solutions/{issue-id}.jsonl`
 - Report: issue ID, solution ID, task count, mode (new/supplement)
 - Recommend next step: Form execution queue via Phase 4

.codex/skills/issue-resolve/phases/03-from-brainstorm.md

@@ -29,7 +29,7 @@ When `--yes` or `-y`: Auto-select highest-scored idea, skip confirmations, creat
 
 | Argument | Required | Type | Default | Description |
 |----------|----------|------|---------|-------------|
-| SESSION | Yes | String | - | Session ID or path to `.workflow/.brainstorm/BS-xxx` |
+| SESSION | Yes | String | - | Session ID or path to `{projectRoot}/.workflow/.brainstorm/BS-xxx` |
 | --idea | No | Integer | - | Pre-select idea by index (0-based) |
 | --auto | No | Flag | false | Auto-select highest-scored idea |
 | -y, --yes | No | Flag | false | Skip all confirmations |
@@ -157,7 +157,7 @@ Phase 5: Generate Solution Tasks
 
 ```
 Phase 6: Bind Solution
-   ├─ Write solution to .workflow/issues/solutions/{issue-id}.jsonl
+   ├─ Write solution to {projectRoot}/.workflow/issues/solutions/{issue-id}.jsonl
    ├─ Bind via: ccw issue bind {issue-id} {solution-id}
    ├─ Update issue status to 'planned'
    └─ Returns: SOL-{issue-id}-{uid}
@@ -277,7 +277,7 @@ EOF
 ### Solution Binding
 ```bash
 # Append solution to JSONL file
-echo '{"id":"SOL-xxx","tasks":[...]}' >> .workflow/issues/solutions/{issue-id}.jsonl
+echo '{"id":"SOL-xxx","tasks":[...]}' >> ${projectRoot}/.workflow/issues/solutions/{issue-id}.jsonl
 
 # Bind to issue
 ccw issue bind {issue-id} {solution-id}
@@ -361,7 +361,7 @@ brainstorm-with-file
 ### Input Files
 
 ```
-.workflow/.brainstorm/BS-{slug}-{date}/
+{projectRoot}/.workflow/.brainstorm/BS-{slug}-{date}/
 ├── synthesis.json           # REQUIRED - Top ideas with scores
 ├── perspectives.json        # OPTIONAL - Multi-CLI insights
 ├── brainstorm.md           # Reference only
@@ -376,7 +376,7 @@ brainstorm-with-file
 ### Output Files
 
 ```
-.workflow/issues/
+{projectRoot}/.workflow/issues/
 ├── solutions/
 │   └── ISS-YYYYMMDD-001.jsonl  # Created solution (JSONL)
 └── (managed by ccw issue CLI)

.codex/skills/issue-resolve/phases/04-issue-queue.md

@@ -9,7 +9,7 @@ Queue formation command using **issue-queue-agent** that analyzes all bound solu
 ## Prerequisites
 
 - Issues with `status: planned` and `bound_solution_id` exist
-- Solutions written in `.workflow/issues/solutions/{issue-id}.jsonl`
+- Solutions written in `{projectRoot}/.workflow/issues/solutions/{issue-id}.jsonl`
 - `ccw issue` CLI available
 
 ## Auto Mode
@@ -117,8 +117,8 @@ const queueIds = numQueues === 1
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/issue-queue-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -145,8 +145,8 @@ Step 6: Write queue JSON + update index
 ### Output Requirements
 
 **Write files** (exactly 2):
-- `.workflow/issues/queues/${queueId}.json` - Full queue with solutions, conflicts, groups
+- `${projectRoot}/.workflow/issues/queues/${queueId}.json` - Full queue with solutions, conflicts, groups
-- `.workflow/issues/queues/index.json` - Update with new queue entry
+- `${projectRoot}/.workflow/issues/queues/index.json` - Update with new queue entry
 
 **Return JSON**:
 \`\`\`json
@@ -267,8 +267,8 @@ if (allClarifications.length > 0) {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/issue-queue-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -278,7 +278,7 @@ if (allClarifications.length > 0) {
 **Conflict**: ${clarification.conflict_id} resolved: ${answer.selected}
 
 ### Instructions
-1. Read existing queue file: .workflow/issues/queues/${clarification.queue_id}.json
+1. Read existing queue file: ${projectRoot}/.workflow/issues/queues/${clarification.queue_id}.json
 2. Update conflict resolution with user decision
 3. Re-order affected solutions if needed
 4. Write updated queue file
@@ -370,7 +370,7 @@ ASK_USER([{
 ## Storage Structure (Queue History)
 
 ```
-.workflow/issues/
+{projectRoot}/.workflow/issues/
 ├── issues.jsonl              # All issues (one per line)
 ├── queues/                   # Queue history directory
 │   ├── index.json            # Queue index (active + history)

.codex/skills/parallel-dev-cycle/SKILL.md

@@ -147,7 +147,7 @@ Return: cycle_id, iterations, final_state
 ## Session Structure
 
 ```
-.workflow/.cycle/
+{projectRoot}/.workflow/.cycle/
 ├── {cycleId}.json                                 # Master state file
 ├── {cycleId}.progress/
     ├── ra/
@@ -176,7 +176,7 @@ Return: cycle_id, iterations, final_state
 
 ## State Management
 
-Master state file: `.workflow/.cycle/{cycleId}.json`
+Master state file: `{projectRoot}/.workflow/.cycle/{cycleId}.json`
 
 ```json
 {

.codex/skills/parallel-dev-cycle/phases/01-session-init.md

@@ -30,7 +30,7 @@ if (!existingCycleId && !task) {
 const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
 
 function readCycleState(cycleId) {
-  const stateFile = `.workflow/.cycle/${cycleId}.json`
+  const stateFile = `${projectRoot}/.workflow/.cycle/${cycleId}.json`
   if (!fs.existsSync(stateFile)) {
     return null
   }
@@ -54,18 +54,18 @@ console.log(`Creating new cycle: ${cycleId}`)
 #### Create Directory Structure
 
 ```bash
-mkdir -p .workflow/.cycle/${cycleId}.progress/{ra,ep,cd,vas,coordination}
+mkdir -p ${projectRoot}/.workflow/.cycle/${cycleId}.progress/{ra,ep,cd,vas,coordination}
-mkdir -p .workflow/.cycle/${cycleId}.progress/ra/history
+mkdir -p ${projectRoot}/.workflow/.cycle/${cycleId}.progress/ra/history
-mkdir -p .workflow/.cycle/${cycleId}.progress/ep/history
+mkdir -p ${projectRoot}/.workflow/.cycle/${cycleId}.progress/ep/history
-mkdir -p .workflow/.cycle/${cycleId}.progress/cd/history
+mkdir -p ${projectRoot}/.workflow/.cycle/${cycleId}.progress/cd/history
-mkdir -p .workflow/.cycle/${cycleId}.progress/vas/history
+mkdir -p ${projectRoot}/.workflow/.cycle/${cycleId}.progress/vas/history
 ```
 
 #### Initialize State File
 
 ```javascript
 function createCycleState(cycleId, taskDescription) {
-  const stateFile = `.workflow/.cycle/${cycleId}.json`
+  const stateFile = `${projectRoot}/.workflow/.cycle/${cycleId}.json`
   const now = getUtc8ISOString()
 
   const state = {
@@ -151,7 +151,7 @@ function checkControlSignals(cycleId) {
 
 - **Variable**: `cycleId` - Unique cycle identifier
 - **Variable**: `state` - Initialized or resumed cycle state object
-- **Variable**: `progressDir` - `.workflow/.cycle/${cycleId}.progress`
+- **Variable**: `progressDir` - `${projectRoot}/.workflow/.cycle/${cycleId}.progress`
 - **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
 
 ## Next Phase

.codex/skills/parallel-dev-cycle/phases/02-agent-execution.md

@@ -33,9 +33,9 @@ function spawnRAAgent(cycleId, state, progressDir) {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/requirements-analyst.md
-2. Read: .workflow/project-tech.json (if exists)
+2. Read: ${projectRoot}/.workflow/project-tech.json (if exists)
-3. Read: .workflow/project-guidelines.json (if exists)
+3. Read: ${projectRoot}/.workflow/project-guidelines.json (if exists)
-4. Read: .workflow/.cycle/${cycleId}.progress/coordination/feedback.md (if exists)
+4. Read: ${projectRoot}/.workflow/.cycle/${cycleId}.progress/coordination/feedback.md (if exists)
 
 ---
 
@@ -94,8 +94,8 @@ function spawnEPAgent(cycleId, state, progressDir) {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/exploration-planner.md
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 4. Read: ${progressDir}/ra/requirements.md
 
 ---

.codex/skills/parallel-dev-cycle/phases/03-result-aggregation.md

@@ -83,7 +83,7 @@ state.completed_phases.push(...['ra', 'ep', 'cd', 'vas'])
 state.updated_at = getUtc8ISOString()
 
 // Persist state
-Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
+Write(`${projectRoot}/.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ### Step 3.4: Issue Detection

.codex/skills/parallel-dev-cycle/phases/04-completion-summary.md

@@ -16,7 +16,7 @@ Generate unified summary report, update final state, close all agents, and provi
 
 ```javascript
 function generateFinalSummary(cycleId, state) {
-  const summaryFile = `.workflow/.cycle/${cycleId}.progress/coordination/summary.md`
+  const summaryFile = `${projectRoot}/.workflow/.cycle/${cycleId}.progress/coordination/summary.md`
 
   const summary = `# Cycle Summary - ${cycleId}
 
@@ -40,10 +40,10 @@ function generateFinalSummary(cycleId, state) {
 - Test Results: ${state.test_results?.pass_rate || '0'}% passing
 
 ## Generated Files
-- .workflow/.cycle/${cycleId}.progress/ra/requirements.md
+- ${projectRoot}/.workflow/.cycle/${cycleId}.progress/ra/requirements.md
-- .workflow/.cycle/${cycleId}.progress/ep/plan.json
+- ${projectRoot}/.workflow/.cycle/${cycleId}.progress/ep/plan.json
-- .workflow/.cycle/${cycleId}.progress/cd/changes.log
+- ${projectRoot}/.workflow/.cycle/${cycleId}.progress/cd/changes.log
-- .workflow/.cycle/${cycleId}.progress/vas/summary.md
+- ${projectRoot}/.workflow/.cycle/${cycleId}.progress/vas/summary.md
 
 ## Continuation Instructions
 
@@ -65,7 +65,7 @@ This will spawn agents for iteration ${state.current_iteration + 1}.
 ```javascript
 state.status = 'completed'
 state.completed_at = getUtc8ISOString()
-Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
+Write(`${projectRoot}/.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ### Step 4.3: Close All Agents
@@ -95,13 +95,13 @@ return {
 
 ## Output
 
-- **File**: `.workflow/.cycle/{cycleId}.progress/coordination/summary.md`
+- **File**: `{projectRoot}/.workflow/.cycle/{cycleId}.progress/coordination/summary.md`
-- **File**: `.workflow/.cycle/{cycleId}.json` (final state)
+- **File**: `{projectRoot}/.workflow/.cycle/{cycleId}.json` (final state)
 - **TodoWrite**: Mark Phase 4 completed (all tasks done)
 
 ## Completion
 
-Parallel Dev Cycle has completed. The cycle report is at `.workflow/.cycle/{cycleId}.progress/coordination/summary.md`.
+Parallel Dev Cycle has completed. The cycle report is at `{projectRoot}/.workflow/.cycle/{cycleId}.progress/coordination/summary.md`.
 
 To continue iterating:
 ```bash

.codex/skills/parallel-dev-cycle/roles/code-developer.md

@@ -159,7 +159,7 @@ When tests fail during implementation, the CD agent MUST initiate the hypothesis
 
 ### Debug Log Format (NDJSON)
 
-File: `.workflow/.cycle/{cycleId}.progress/cd/debug-log.ndjson`
+File: `{projectRoot}/.workflow/.cycle/{cycleId}.progress/cd/debug-log.ndjson`
 
 Schema:
 ```json
@@ -191,7 +191,7 @@ Debug workflow generates an additional file:
 
 ### Phase 3: Output
 
-Generate files in `.workflow/.cycle/{cycleId}.progress/cd/`:
+Generate files in `{projectRoot}/.workflow/.cycle/{cycleId}.progress/cd/`:
 
 **implementation.md**:
 ```markdown

.codex/skills/parallel-dev-cycle/roles/exploration-planner.md

@@ -105,7 +105,7 @@ The Exploration & Planning Agent is responsible for understanding the codebase a
 
 ### Phase 3: Output
 
-Generate files in `.workflow/.cycle/{cycleId}.progress/ep/`:
+Generate files in `{projectRoot}/.workflow/.cycle/{cycleId}.progress/ep/`:
 
 **exploration.md**:
 ```markdown

.codex/skills/parallel-dev-cycle/roles/requirements-analyst.md

@@ -55,7 +55,7 @@ The Requirements Analyst maintains **a single file** (`requirements.md`) contain
 ### Phase 1: Initial Analysis (v1.0.0)
 
 1. **Read Context**
-   - Cycle state from `.workflow/.cycle/{cycleId}.json`
+   - Cycle state from `{projectRoot}/.workflow/.cycle/{cycleId}.json`
    - Task description from state
    - Project tech stack and guidelines
 
@@ -109,7 +109,7 @@ The Requirements Analyst maintains **a single file** (`requirements.md`) contain
 
 ### Phase 3: Output
 
-Generate/update two files in `.workflow/.cycle/{cycleId}.progress/ra/`:
+Generate/update two files in `{projectRoot}/.workflow/.cycle/{cycleId}.progress/ra/`:
 
 **requirements.md** (COMPLETE REWRITE):
 ```markdown

.codex/skills/parallel-dev-cycle/roles/validation-archivist.md

@@ -116,7 +116,7 @@ The Validation & Archival Agent is responsible for verifying implementation qual
 
 ### Phase 4: Output
 
-Generate files in `.workflow/.cycle/{cycleId}.progress/vas/`:
+Generate files in `{projectRoot}/.workflow/.cycle/{cycleId}.progress/vas/`:
 
 **validation.md**:
 ```markdown

.codex/skills/review-cycle/SKILL.md

@@ -80,7 +80,7 @@ review-cycle src/auth/**,src/payment/**                        # Module: multipl
 review-cycle src/auth/** --dimensions=security,architecture    # Module: custom dims
 review-cycle WFS-payment-integration                           # Session: specific
 review-cycle                                                   # Session: auto-detect
-review-cycle --fix .workflow/active/WFS-123/.review/           # Fix: from review dir
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/           # Fix: from review dir
 review-cycle --fix --resume                                    # Fix: resume session
 ```
 
@@ -244,8 +244,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -367,7 +367,7 @@ Gemini → Qwen → Codex → degraded mode
 ## Output File Structure
 
 ```
-.workflow/active/WFS-{session-id}/.review/
+{projectRoot}/.workflow/active/WFS-{session-id}/.review/
 ├── review-state.json                    # Orchestrator state machine
 ├── review-progress.json                 # Real-time progress
 ├── dimensions/                          # Per-dimension results (Phase 2)
@@ -408,5 +408,5 @@ ccw view
 review-cycle src/auth/**
 
 # Step 2: Fix (continue or standalone)
-review-cycle --fix .workflow/active/WFS-{session-id}/.review/
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-{session-id}/.review/
 ```

.codex/skills/review-cycle/phases/01-discovery-initialization.md

@@ -23,7 +23,7 @@ The review mode is determined by the input arguments:
 // If session ID not provided, auto-detect
 if (!providedSessionId) {
   // Check for active sessions
-  const activeSessions = Glob('.workflow/active/WFS-*');
+  const activeSessions = Glob('${projectRoot}/.workflow/active/WFS-*');
   if (activeSessions.length === 1) {
     sessionId = activeSessions[0].match(/WFS-[^/]+/)[0];
   } else if (activeSessions.length > 1) {
@@ -37,7 +37,7 @@ if (!providedSessionId) {
 }
 
 // Validate session exists
-Bash(`test -d .workflow/active/${sessionId} && echo "EXISTS"`);
+Bash(`test -d ${projectRoot}/.workflow/active/${sessionId} && echo "EXISTS"`);
 ```
 
 ### Step 1.2: Session Validation
@@ -62,11 +62,11 @@ git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u
 ```javascript
 // Create workflow session for this review (type: review)
 // Orchestrator handles session creation directly
-Bash(`mkdir -p .workflow/active/WFS-review-${Date.now()}`);
+Bash(`mkdir -p ${projectRoot}/.workflow/active/WFS-review-${Date.now()}`);
 
 // Initialize workflow-session.json
 const sessionId = `WFS-review-${Date.now()}`;
-Write(`.workflow/active/${sessionId}/workflow-session.json`, JSON.stringify({
+Write(`${projectRoot}/.workflow/active/${sessionId}/workflow-session.json`, JSON.stringify({
   session_id: sessionId,
   type: "review",
   description: `Code review for ${targetPattern}`,
@@ -117,7 +117,7 @@ done
 
 ### Step 1.4: Output Directory Setup
 
-- Output directory: `.workflow/active/${sessionId}/.review/`
+- Output directory: `${projectRoot}/.workflow/active/${sessionId}/.review/`
 - Create directory structure:
   ```bash
   mkdir -p ${sessionDir}/.review/{dimensions,iterations,reports}
@@ -295,7 +295,7 @@ done
 ## Output File Structure
 
 ```
-.workflow/active/WFS-{session-id}/.review/
+{projectRoot}/.workflow/active/WFS-{session-id}/.review/
 ├── review-state.json                    # Orchestrator state machine (includes metadata)
 ├── review-progress.json                 # Real-time progress for dashboard
 ├── dimensions/                          # Per-dimension results
@@ -319,7 +319,7 @@ done
 ## Session Context
 
 ```
-.workflow/active/WFS-{session-id}/
+{projectRoot}/.workflow/active/WFS-{session-id}/
 ├── workflow-session.json
 ├── IMPL_PLAN.md
 ├── TODO_LIST.md

.codex/skills/review-cycle/phases/02-parallel-review.md

@@ -94,8 +94,8 @@ dimensions.forEach(dimension => {
 3. Get target files: Read resolved_files from review-state.json
 4. Validate file access: bash(ls -la ${targetFiles.join(' ')})
 5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
-6. Read: .workflow/project-tech.json (technology stack and architecture context)
+6. Read: ${projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
-7. Read: .workflow/project-guidelines.json (user-defined constraints and conventions to validate against)
+7. Read: ${projectRoot}/.workflow/project-guidelines.json (user-defined constraints and conventions to validate against)
 
 ---
 
@@ -217,8 +217,8 @@ dimensions.forEach(dimension => {
 4. Get changed files: bash(cd ${workflowDir} && git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u)
 5. Read review state: ${reviewStateJsonPath}
 6. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
-7. Read: .workflow/project-tech.json (technology stack and architecture context)
+7. Read: ${projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
-8. Read: .workflow/project-guidelines.json (user-defined constraints and conventions to validate against)
+8. Read: ${projectRoot}/.workflow/project-guidelines.json (user-defined constraints and conventions to validate against)
 
 ---
 
@@ -336,8 +336,8 @@ const deepDiveAgentId = spawn_agent({
 4. Identify related code: bash(grep -r "import.*${basename(file)}" ${projectDir}/src --include="*.ts")
 5. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f)
 6. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
-7. Read: .workflow/project-tech.json (technology stack and architecture context)
+7. Read: ${projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
-8. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance)
+8. Read: ${projectRoot}/.workflow/project-guidelines.json (user-defined constraints for remediation compliance)
 
 ---
 

.codex/skills/review-cycle/phases/04-iterative-deep-dive.md

@@ -89,8 +89,8 @@ selectedFindings.forEach(finding => {
 4. Identify related code: bash(grep -r "import.*${basename(finding.file)}" ${projectDir}/src --include="*.ts")
 5. Read test files: bash(find ${projectDir}/tests -name "*${basename(finding.file, '.ts')}*" -type f)
 6. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
-7. Read: .workflow/project-tech.json (technology stack and architecture context)
+7. Read: ${projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
-8. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance)
+8. Read: ${projectRoot}/.workflow/project-guidelines.json (user-defined constraints for remediation compliance)
 
 ---
 
@@ -200,8 +200,8 @@ selectedFindings.forEach(finding => {
 4. Identify related code: bash(grep -r "import.*${basename(finding.file)}" ${workflowDir}/src --include="*.ts")
 5. Read test files: bash(find ${workflowDir}/tests -name "*${basename(finding.file, '.ts')}*" -type f)
 6. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
-7. Read: .workflow/project-tech.json (technology stack and architecture context)
+7. Read: ${projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
-8. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance)
+8. Read: ${projectRoot}/.workflow/project-guidelines.json (user-defined constraints for remediation compliance)
 
 ---
 

.codex/skills/review-cycle/phases/05-review-completion.md

@@ -159,7 +159,7 @@ review-cycle src/auth/**
 review-cycle
 
 # Step 2: Run automated fixes using dimension findings
-review-cycle --fix .workflow/active/WFS-{session-id}/.review/
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-{session-id}/.review/
 ```
 
 ## Output

.codex/skills/review-cycle/phases/06-fix-discovery-batching.md

@@ -10,19 +10,19 @@ Validate fix input source, create fix session structure, and perform intelligent
 
 ```bash
 # Fix from exported findings file (session-based path)
-review-cycle --fix .workflow/active/WFS-123/.review/fix-export-1706184622000.json
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/fix-export-1706184622000.json
 
 # Fix from review directory (auto-discovers latest export)
-review-cycle --fix .workflow/active/WFS-123/.review/
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/
 
 # Resume interrupted fix session
 review-cycle --fix --resume
 
 # Custom max retry attempts per finding
-review-cycle --fix .workflow/active/WFS-123/.review/ --max-iterations=5
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/ --max-iterations=5
 
 # Custom batch size for parallel planning (default: 5 findings per batch)
-review-cycle --fix .workflow/active/WFS-123/.review/ --batch-size=3
+review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/ --batch-size=3
 ```
 
 **Fix Source**: Exported findings from review cycle dashboard
@@ -208,7 +208,7 @@ console.log(`Created ${batches.length} batches (${batchSize} findings per batch)
 ## Output File Structure
 
 ```
-.workflow/active/WFS-{session-id}/.review/
+{projectRoot}/.workflow/active/WFS-{session-id}/.review/
 ├── fix-export-{timestamp}.json     # Exported findings (input)
 └── fixes/{fix-session-id}/
     ├── partial-plan-1.json         # Batch 1 partial plan (planning agent 1 output)

.codex/skills/review-cycle/phases/07-fix-parallel-planning.md

@@ -105,8 +105,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 

.codex/skills/review-cycle/phases/08-fix-execution.md

@@ -60,8 +60,8 @@ const execAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-execution-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 

.codex/skills/unified-execute-with-file/SKILL.md

@@ -34,7 +34,7 @@ The key innovation is the **unified event log** that serves as both human-readab
 ## Output Structure
 
 ```
-.workflow/.execution/EXEC-{slug}-{date}-{random}/
+${projectRoot}/.workflow/.execution/EXEC-{slug}-{date}-{random}/
 ├── execution.md              # Plan overview + task table + timeline
 └── execution-events.md       # ⭐ Unified log (all executions) - SINGLE SOURCE OF TRUTH
 ```
@@ -46,7 +46,7 @@ The key innovation is the **unified event log** that serves as both human-readab
 | Artifact | Purpose |
 |----------|---------|
 | `execution.md` | Overview of plan source, task table, execution timeline |
-| Session folder | `.workflow/.execution/{sessionId}/` |
+| Session folder | `{projectRoot}/.workflow/.execution/{sessionId}/` |
 
 ### Phase 2: Pre-Execution Analysis
 
@@ -81,15 +81,15 @@ The workflow creates a unique session for tracking execution.
 - `date`: YYYY-MM-DD format (UTC+8)
 - `random`: 7-char random suffix for uniqueness
 
-**Session Directory**: `.workflow/.execution/{sessionId}/`
+**Session Directory**: `{projectRoot}/.workflow/.execution/{sessionId}/`
 
 **Plan Path Resolution**:
 1. If `$PLAN` provided explicitly, use it
 2. Otherwise, auto-detect from common locations:
-   - `.workflow/IMPL_PLAN.md`
+   - `{projectRoot}/.workflow/IMPL_PLAN.md`
-   - `.workflow/.planning/*/plan-note.md`
+   - `{projectRoot}/.workflow/.planning/*/plan-note.md`
-   - `.workflow/.brainstorm/*/synthesis.json`
+   - `{projectRoot}/.workflow/.brainstorm/*/synthesis.json`
-   - `.workflow/.analysis/*/conclusions.json`
+   - `{projectRoot}/.workflow/.analysis/*/conclusions.json`
 
 **Session Variables**:
 - `sessionId`: Unique session identifier
@@ -440,7 +440,7 @@ Complete
 ### Standard Execution
 
 ```bash
-PLAN=".workflow/.planning/CPLAN-auth-2025-01-27/plan-note.md"
+PLAN="${projectRoot}/.workflow/.planning/CPLAN-auth-2025-01-27/plan-note.md"
 ```
 
 Execute the plan with standard options.
@@ -448,7 +448,7 @@ Execute the plan with standard options.
 ### With Auto-Commit
 
 ```bash
-PLAN=".workflow/.planning/CPLAN-auth-2025-01-27/plan-note.md" \
+PLAN="${projectRoot}/.workflow/.planning/CPLAN-auth-2025-01-27/plan-note.md" \
   --auto-commit
 ```
 
@@ -457,7 +457,7 @@ Execute and automatically commit changes after each task.
 ### Dry-Run Mode
 
 ```bash
-PLAN=".workflow/.planning/CPLAN-auth-2025-01-27/plan-note.md" \
+PLAN="${projectRoot}/.workflow/.planning/CPLAN-auth-2025-01-27/plan-note.md" \
   --dry-run
 ```
 

.codex/skills/workflow-brainstorm-auto-parallel/SKILL.md

@@ -135,7 +135,7 @@ workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT
 **Parsing**:
 ```javascript
 // Read workflow-session.json after Phase 1
-const session_data = Read(".workflow/active/WFS-{topic}/workflow-session.json");
+const session_data = Read("${projectRoot}/.workflow/active/WFS-{topic}/workflow-session.json");
 const selected_roles = session_data.selected_roles;
 const session_id = session_data.session_id;
 const style_skill_package = session_data.style_skill_package || null;
@@ -189,8 +189,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -250,7 +250,7 @@ close_agent({ id: agentId })
 
 ## Session Management
 
-**⚡ FIRST ACTION**: Check `.workflow/active/` for existing sessions before Phase 1
+**⚡ FIRST ACTION**: Check `{projectRoot}/.workflow/active/` for existing sessions before Phase 1
 
 **Multiple Sessions Support**:
 - Different Codex instances can have different brainstorming sessions
@@ -266,15 +266,15 @@ close_agent({ id: agentId })
 ## Output Structure
 
 **Phase 1 Output**:
-- `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
+- `{projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
-- `.workflow/active/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package)
+- `{projectRoot}/.workflow/active/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package)
 
 **Phase 2 Output**:
-- `.workflow/active/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
+- `{projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
 - `.superdesign/design_iterations/` (ui-designer artifacts, if --style-skill provided)
 
 **Phase 3 Output**:
-- `.workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
+- `{projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
 - Updated `[role]/analysis*.md` with Enhancements + Clarifications sections
 
 **⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
@@ -307,7 +307,7 @@ close_agent({ id: agentId })
 
 **File Structure**:
 ```
-.workflow/active/WFS-[topic]/
+{projectRoot}/.workflow/active/WFS-[topic]/
 ├── workflow-session.json              # Session metadata ONLY
 └── .brainstorming/
     ├── guidance-specification.md      # Framework (Phase 1)
@@ -321,7 +321,7 @@ close_agent({ id: agentId })
 ```
 Brainstorming complete for session: {sessionId}
 Roles analyzed: {count}
-Synthesis: .workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md
+Synthesis: {projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md
 
 ✅ Next Steps:
 1. workflow:plan --session {sessionId}  # Generate implementation plan

.codex/skills/workflow-brainstorm-auto-parallel/phases/01-interactive-framework.md

@@ -5,7 +5,7 @@ Seven-phase workflow: **Context collection** → **Topic analysis** → **Role s
 All user interactions use ASK_USER / CONFIRM pseudo-code (implemented via AskUserQuestion tool) (max 4 questions per call, multi-round).
 
 **Input**: `"GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]`
-**Output**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md`
+**Output**: `{projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md`
 **Core Principle**: Questions dynamically generated from project context + topic keywords, NOT generic templates
 
 **Parameters**:
@@ -69,7 +69,7 @@ for (let i = 0; i < allQuestions.length; i += BATCH_SIZE) {
 
 ## Session Management
 
-- Check `.workflow/active/` for existing sessions
+- Check `{projectRoot}/.workflow/active/` for existing sessions
 - Multiple → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]`
 - Parse `--count N` parameter (default: 3)
 - Store decisions in `workflow-session.json`
@@ -85,7 +85,7 @@ for (let i = 0; i < allQuestions.length; i += BATCH_SIZE) {
 **Steps**:
 1. Check if `context-package.json` exists → Skip if valid
 2. Invoke `context-search-agent` (BRAINSTORM MODE - lightweight)
-3. Output: `.workflow/active/WFS-{session-id}/.process/context-package.json`
+3. Output: `{projectRoot}/.workflow/active/WFS-{session-id}/.process/context-package.json`
 
 **Graceful Degradation**: If agent fails, continue to Phase 1 without context
 
@@ -97,8 +97,8 @@ const contextAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/context-search-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -108,7 +108,7 @@ Execute context-search-agent in BRAINSTORM MODE (Phase 1-2 only).
 ## Assigned Context
 - **Session**: ${session_id}
 - **Task**: ${task_description}
-- **Output**: .workflow/${session_id}/.process/context-package.json
+- **Output**: ${projectRoot}/.workflow/${session_id}/.process/context-package.json
 
 ## Required Output Fields
 metadata, project_context, assets, dependencies, conflict_detection
@@ -322,7 +322,7 @@ ASK_USER([{
 
 ### Output Template
 
-**File**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md`
+**File**: `{projectRoot}/.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md`
 
 ```markdown
 # [Project] - Confirmed Guidance Specification
@@ -366,7 +366,7 @@ ASK_USER([{
 ### File Structure
 
 ```
-.workflow/active/WFS-[topic]/
+{projectRoot}/.workflow/active/WFS-[topic]/
 ├── workflow-session.json              # Metadata ONLY
 ├── .process/
 │   └── context-package.json           # Phase 0 output

.codex/skills/workflow-brainstorm-auto-parallel/phases/02-parallel-role-analysis.md

@@ -64,9 +64,9 @@ IF invalid:
 ```bash
 IF --session PROVIDED:
   session_id = --session
-  brainstorm_dir = .workflow/active/{session_id}/.brainstorming/
+  brainstorm_dir = ${projectRoot}/.workflow/active/{session_id}/.brainstorming/
 ELSE:
-  FIND .workflow/active/WFS-*/
+  FIND ${projectRoot}/.workflow/active/WFS-*/
   IF multiple:
     PROMPT user to select
   ELSE IF single:
@@ -274,7 +274,7 @@ Write(
 
 **Step 3.1: Load Session Metadata**
 ```bash
-session_metadata = Read(.workflow/active/{session_id}/workflow-session.json)
+session_metadata = Read(${projectRoot}/.workflow/active/{session_id}/workflow-session.json)
 original_topic = session_metadata.topic
 selected_roles = session_metadata.selected_roles
 ```
@@ -305,8 +305,8 @@ const roleAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -333,7 +333,7 @@ UPDATE_MODE: ${update_mode}
 
 3. **load_session_metadata**
    - Action: Load session metadata and user intent
-   - Command: Read(.workflow/active/${session_id}/workflow-session.json)
+   - Command: Read(${projectRoot}/.workflow/active/${session_id}/workflow-session.json)
    - Output: session_context
 
 4. **load_user_context** (if exists)
@@ -413,8 +413,8 @@ selected_roles.forEach((role_name, index) => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -552,7 +552,7 @@ ${selected_roles.length > 1 ? `
 ### Directory Layout
 
 ```
-.workflow/active/WFS-{session}/.brainstorming/
+{projectRoot}/.workflow/active/WFS-{session}/.brainstorming/
 ├── guidance-specification.md          # Framework (if exists)
 └── {role-name}/
     ├── {role-name}-context.md         # Interactive Q&A responses
@@ -751,7 +751,7 @@ try {
 - Format: `{role-name}.md` (e.g., `ux-expert.md`, `system-architect.md`)
 
 ### Context Package
-- Location: `.workflow/active/WFS-{session}/.process/context-package.json`
+- Location: `{projectRoot}/.workflow/active/WFS-{session}/.process/context-package.json`
 - Used by: `context-search-agent` (Phase 0 of artifacts)
 - Contains: Project context, tech stack, conflict risks
 

.codex/skills/workflow-brainstorm-auto-parallel/phases/03-synthesis-integration.md

@@ -62,7 +62,7 @@ ASK_USER([
 
 ### Phase 1: Discovery & Validation
 
-1. **Detect Session**: Use `--session` parameter or find `.workflow/active/WFS-*`
+1. **Detect Session**: Use `--session` parameter or find `{projectRoot}/.workflow/active/WFS-*`
 2. **Validate Files**:
    - `guidance-specification.md` (optional, warn if missing)
    - `*/analysis*.md` (required, error if empty)
@@ -73,7 +73,7 @@ ASK_USER([
 **Main flow prepares file paths for Agent**:
 
 1. **Discover Analysis Files**:
-   - Glob: `.workflow/active/WFS-{session}/.brainstorming/*/analysis*.md`
+   - Glob: `{projectRoot}/.workflow/active/WFS-{session}/.brainstorming/*/analysis*.md`
    - Supports: analysis.md + analysis-{slug}.md (max 5)
 
 2. **Extract Role Information**:
@@ -94,8 +94,8 @@ const analysisAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -276,8 +276,8 @@ participating_roles.forEach((role, index) => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/conceptual-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -351,7 +351,7 @@ console.log(`Updated: ${updatedRoles.length}/${participating_roles.length} roles
 
 ```javascript
 // Sync updated analyses to context-package.json
-const context_pkg = Read(".workflow/active/WFS-{session}/.process/context-package.json")
+const context_pkg = Read("${projectRoot}/.workflow/active/WFS-{session}/.process/context-package.json")
 
 // Update guidance-specification if exists
 // Update synthesis-specification if exists
@@ -404,7 +404,7 @@ Write(context_pkg_path, JSON.stringify(context_pkg))
 
 ## Output
 
-**Location**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md`
+**Location**: `{projectRoot}/.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md`
 
 **Updated Structure**:
 ```markdown

.codex/skills/workflow-execute/SKILL.md

@@ -148,8 +148,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ## TASK CONTEXT
 ${taskContext}
@@ -232,7 +232,7 @@ close_agent({ id: agentId })
 
 #### Step 1.1: Count Active Sessions
 ```bash
-bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)
+bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)
 ```
 
 #### Step 1.2: Handle Session Selection
@@ -245,7 +245,7 @@ Run workflow:plan "task description" to create a session
 
 **Case B: Single Session** (count = 1)
 ```bash
-bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
+bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
 ```
 Auto-select and continue to Phase 2.
 
@@ -253,7 +253,7 @@ Auto-select and continue to Phase 2.
 
 List sessions with metadata and prompt user selection:
 ```bash
-bash(for dir in .workflow/active/WFS-*/; do [ -d "$dir" ] || continue; session=$(basename "$dir"); project=$(jq -r '.project // "Unknown"' "${dir}workflow-session.json" 2>/dev/null || echo "Unknown"); total=$(grep -c '^\- \[' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); completed=$(grep -c '^\- \[x\]' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); if [ "$total" -gt 0 ]; then progress=$((completed * 100 / total)); else progress=0; fi; echo "$session | $project | $completed/$total tasks ($progress%)"; done)
+bash(for dir in ${projectRoot}/.workflow/active/WFS-*/; do [ -d "$dir" ] || continue; session=$(basename "$dir"); project=$(jq -r '.project // "Unknown"' "${dir}workflow-session.json" 2>/dev/null || echo "Unknown"); total=$(grep -c '^\- \[' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); completed=$(grep -c '^\- \[x\]' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); if [ "$total" -gt 0 ]; then progress=$((completed * 100 / total)); else progress=0; fi; echo "$session | $project | $completed/$total tasks ($progress%)"; done)
 ```
 
 **Parse --yes flag**:
@@ -296,7 +296,7 @@ Parse user input (supports: number "1", full ID "WFS-auth-system", or partial "a
 
 #### Step 1.3: Load Session Metadata
 ```bash
-bash(cat .workflow/active/${sessionId}/workflow-session.json)
+bash(cat ${projectRoot}/.workflow/active/${sessionId}/workflow-session.json)
 ```
 
 **Output**: Store session metadata in memory
@@ -326,8 +326,8 @@ Before generating TodoWrite, update session status from "planning" to "active":
 ```bash
 # Update session status (idempotent - safe to run if already active)
 jq '.status = "active" | .execution_started_at = (.execution_started_at // now | todate)' \
-  .workflow/active/${sessionId}/workflow-session.json > tmp.json && \
+  ${projectRoot}/.workflow/active/${sessionId}/workflow-session.json > tmp.json && \
-  mv tmp.json .workflow/active/${sessionId}/workflow-session.json
+  mv tmp.json ${projectRoot}/.workflow/active/${sessionId}/workflow-session.json
 ```
 This ensures the dashboard shows the session as "ACTIVE" during execution.
 
@@ -340,7 +340,7 @@ This ensures the dashboard shows the session as "ACTIVE" during execution.
 3. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
 
 **Resume Mode Behavior**:
-- Load existing TODO_LIST.md directly from `.workflow/active/{session-id}/`
+- Load existing TODO_LIST.md directly from `{projectRoot}/.workflow/active/{session-id}/`
 - Extract current progress from TODO_LIST.md
 - Generate TodoWrite from TODO_LIST.md state
 - Proceed immediately to agent execution (Phase 4)
@@ -366,7 +366,7 @@ If IMPL_PLAN.md lacks execution strategy, use intelligent fallback (analyze task
 ```
 while (TODO_LIST.md has pending tasks) {
   next_task_id = getTodoWriteInProgressTask()
-  task_json = Read(.workflow/active/{session}/.task/{next_task_id}.json)  // Lazy load
+  task_json = Read(${projectRoot}/.workflow/active/{session}/.task/{next_task_id}.json)  // Lazy load
   executeTaskWithAgent(task_json)  // spawn_agent → wait → close_agent
   updateTodoListMarkCompleted(next_task_id)
   advanceTodoWriteToNextTask()
@@ -486,8 +486,8 @@ parallelTasks.forEach(task => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/${task.meta.agent}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -629,8 +629,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/${meta.agent}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -702,7 +702,7 @@ Phase 5 (Completion) → updatedStatuses, userChoice (review|complete)
 
 ## Workflow File Structure Reference
 ```
-.workflow/active/WFS-[topic-slug]/
+{projectRoot}/.workflow/active/WFS-[topic-slug]/
 ├── workflow-session.json     # Session state and metadata
 ├── IMPL_PLAN.md             # Planning document and requirements
 ├── TODO_LIST.md             # Progress tracking (updated by agents)
@@ -745,8 +745,8 @@ Phase 5 (Completion) → updatedStatuses, userChoice (review|complete)
 | Error Type | Cause | Recovery Strategy | Max Attempts |
 |-----------|-------|------------------|--------------|
 | **Discovery Errors** |
-| No active session | No sessions in `.workflow/active/` | Create or resume session: `workflow:plan "project"` | N/A |
+| No active session | No sessions in `{projectRoot}/.workflow/active/` | Create or resume session: `workflow:plan "project"` | N/A |
-| Multiple sessions | Multiple sessions in `.workflow/active/` | Prompt user selection | N/A |
+| Multiple sessions | Multiple sessions in `{projectRoot}/.workflow/active/` | Prompt user selection | N/A |
 | Corrupted session | Invalid JSON files | Recreate session structure or validate files | N/A |
 | **Execution Errors** |
 | Agent failure | Agent crash/timeout | Retry with simplified context (close_agent first, then spawn new) | 2 |

.codex/skills/workflow-lite-plan-execute/SKILL.md

@@ -93,6 +93,7 @@ Read('phases/02-lite-execute.md')
 Required (minimum) fields:
 ```javascript
 {
+  projectRoot: string,  // 项目根目录绝对路径 (git rev-parse --show-toplevel || pwd)
   planObject: { summary, approach, tasks, complexity, estimated_time, recommended_execution },
   originalUserInput: string,
   executionMethod: "Agent" | "Codex" | "Auto",

.codex/skills/workflow-lite-plan-execute/phases/01-lite-plan.md

@@ -31,7 +31,7 @@ Intelligent lightweight planning command with dynamic workflow adaptation based
 | `planning-context.md` | Evidence paths + synthesized understanding |
 | `plan.json` | Structured implementation plan (plan-json-schema.json) |
 
-**Output Directory**: `.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/`
+**Output Directory**: `{projectRoot}/.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/`
 
 **Agent Usage**:
 - Low complexity → Direct Claude planning (no agent)
@@ -95,13 +95,26 @@ Phase 5: Execute
 
 #### Session Setup (MANDATORY)
 
+##### Step 0: Determine Project Root
+
+检测项目根目录，确保 `.workflow/` 产物位置正确：
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+优先通过 git 获取仓库根目录；非 git 项目回退到 `pwd` 取当前绝对路径。
+存储为 `{projectRoot}`，后续所有 `.workflow/` 路径必须以此为前缀。
+
+##### Step 1: Generate Session ID
+
 Generate session ID and create session folder:
 
 - **Session ID format**: `{task-slug}-{YYYY-MM-DD}`
   - `task-slug`: lowercase task description, non-alphanumeric replaced with `-`, max 40 chars
   - Date: UTC+8 (China Standard Time), format `2025-11-29`
   - Example: `implement-jwt-refresh-2025-11-29`
-- **Session Folder**: `.workflow/.lite-plan/{session-id}/`
+- **Session Folder**: `{projectRoot}/.workflow/.lite-plan/{session-id}/`
 - Create folder via `mkdir -p` and verify existence
 
 #### Exploration Decision
@@ -177,8 +190,8 @@ Display exploration plan summary (complexity, selected angles, planning strategy
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -200,8 +213,8 @@ Execute **{angle}** exploration for task planning context. Analyze codebase from
 1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
 2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
 3. Execute: cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)
-4. Read: .workflow/project-tech.json (technology stack and architecture context)
+4. Read: {projectRoot}/.workflow/project-tech.json (technology stack and architecture context)
-5. Read: .workflow/project-guidelines.json (user-defined constraints and conventions)
+5. Read: {projectRoot}/.workflow/project-guidelines.json (user-defined constraints and conventions)
 
 ## Exploration Strategy ({angle} focus)
 
@@ -405,8 +418,8 @@ Result: `executorAssignments` map — `{ taskId: { executor: 'gemini'|'codex'|'a
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-lite-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -424,8 +437,8 @@ Generate implementation plan and write plan.json.
 Execute: cat ~/.ccw/workflows/cli-templates/schemas/plan-json-schema.json (get schema reference before generating plan)
 
 ## Project Context (MANDATORY - Read Both Files)
-1. Read: .workflow/project-tech.json (technology stack, architecture, key components)
+1. Read: {projectRoot}/.workflow/project-tech.json (technology stack, architecture, key components)
-2. Read: .workflow/project-guidelines.json (user-defined constraints and conventions)
+2. Read: {projectRoot}/.workflow/project-guidelines.json (user-defined constraints and conventions)
 
 **CRITICAL**: All generated tasks MUST comply with constraints in project-guidelines.json
 
@@ -566,7 +579,7 @@ Assemble the complete execution context from all planning phase outputs:
 ## Session Folder Structure
 
 ```
-.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/
+{projectRoot}/.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/
 ├── exploration-{angle1}.json           # Exploration angle 1
 ├── exploration-{angle2}.json           # Exploration angle 2
 ├── exploration-{angle3}.json           # Exploration angle 3 (if applicable)
@@ -579,7 +592,7 @@ Assemble the complete execution context from all planning phase outputs:
 
 **Example**:
 ```
-.workflow/.lite-plan/implement-jwt-refresh-2025-11-25-14-30-25/
+{projectRoot}/.workflow/.lite-plan/implement-jwt-refresh-2025-11-25-14-30-25/
 ├── exploration-architecture.json
 ├── exploration-auth-patterns.json
 ├── exploration-security.json
@@ -603,6 +616,6 @@ Assemble the complete execution context from all planning phase outputs:
 
 After Phase 1 (Lite Plan) completes:
 - **Output Created**: `executionContext` with plan.json, explorations, clarifications, user selections
-- **Session Artifacts**: All files in `.workflow/.lite-plan/{session-id}/`
+- **Session Artifacts**: All files in `{projectRoot}/.workflow/.lite-plan/{session-id}/`
 - **Next Action**: Auto-continue to [Phase 2: Lite Execute](02-lite-execute.md) with --in-memory
 - **TodoWrite**: Mark "Lite Plan - Planning" as completed, start "Execution (Phase 2)"

.codex/skills/workflow-lite-plan-execute/phases/02-lite-execute.md

@@ -40,6 +40,7 @@ Flexible task execution phase supporting three input modes: in-memory plan (from
 
 **Behavior**:
 - Store prompt as `originalUserInput`
+- Execute `git rev-parse --show-toplevel` to determine `projectRoot`
 - Create simple execution plan from prompt
 - ASK_USER: Select execution method (Agent/Codex/Auto)
 - ASK_USER: Select code review tool (Skip/Gemini/Agent/Other)
@@ -67,8 +68,9 @@ Route by mode:
 **Format Detection**:
 
 ```
-1. Read file content
+1. Execute git rev-parse --show-toplevel to determine projectRoot
-2. Attempt JSON parsing
+2. Read file content
+3. Attempt JSON parsing
    ├─ Valid JSON with summary + approach + tasks fields → plan.json format
    │   ├─ Use parsed data as planObject
    │   └─ Set originalUserInput = summary
@@ -245,7 +247,7 @@ Contains: file index, task-relevant context, code reference, execution notes
 Plan: {plan path}
 
 ### Project Guidelines
-@.workflow/project-guidelines.json
+@{projectRoot}/.workflow/project-guidelines.json
 
 Complete each task according to its "Done when" checklist.
 ```
@@ -260,8 +262,8 @@ Complete each task according to its "Done when" checklist.
 1. Spawn code-developer agent with prompt:
    ├─ MANDATORY FIRST STEPS:
    │   ├─ Read: ~/.codex/agents/code-developer.md
-   │   ├─ Read: .workflow/project-tech.json
+   │   ├─ Read: {projectRoot}/.workflow/project-tech.json
-   │   ├─ Read: .workflow/project-guidelines.json
+   │   ├─ Read: {projectRoot}/.workflow/project-guidelines.json
    │   └─ Read: {exploration_log_refined} (execution-relevant context)
    └─ Body: {buildExecutionPrompt(batch)}
 
@@ -366,12 +368,12 @@ ccw cli -p "Clarify the security concerns" --resume {reviewId} --tool gemini --m
 
 **Trigger**: After all executions complete (regardless of code review)
 
-**Skip Condition**: Skip if `.workflow/project-tech.json` does not exist
+**Skip Condition**: Skip if `{projectRoot}/.workflow/project-tech.json` does not exist
 
 **Operations**:
 
 ```
-1. Read .workflow/project-tech.json
+1. Read {projectRoot}/.workflow/project-tech.json
    └─ If not found → silent skip
 
 2. Initialize development_index if missing
@@ -428,6 +430,7 @@ Passed from planning phase via global variable:
 
 ```javascript
 {
+  projectRoot: string,                   // 项目根目录绝对路径 (git rev-parse --show-toplevel || pwd)
   planObject: {
     summary: string,
     approach: string,
@@ -452,7 +455,7 @@ Passed from planning phase via global variable:
   // Session artifacts location (saved by planning phase)
   session: {
     id: string,                        // Session identifier: {taskSlug}-{shortTimestamp}
-    folder: string,                    // Session folder path: .workflow/.lite-plan/{session-id}
+    folder: string,                    // Session folder path: {projectRoot}/.workflow/.lite-plan/{session-id}
     artifacts: {
       explorations: [{angle, path}],   // exploration-{angle}.json paths
       explorations_manifest: string,   // explorations-manifest.json path

.codex/skills/workflow-plan-execute/SKILL.md

@@ -109,8 +109,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ## TASK CONTEXT
 ${taskContext}

.codex/skills/workflow-plan-execute/phases/01-session-discovery.md

@@ -16,8 +16,8 @@ Discover existing sessions or start new workflow session with intelligent sessio
 ### Check and Initialize
 ```bash
 # Check if project state exists (both files required)
-bash(test -f .workflow/project-tech.json && echo "TECH_EXISTS" || echo "TECH_NOT_FOUND")
+bash(test -f ${projectRoot}/.workflow/project-tech.json && echo "TECH_EXISTS" || echo "TECH_NOT_FOUND")
-bash(test -f .workflow/project-guidelines.json && echo "GUIDELINES_EXISTS" || echo "GUIDELINES_NOT_FOUND")
+bash(test -f ${projectRoot}/.workflow/project-guidelines.json && echo "GUIDELINES_EXISTS" || echo "GUIDELINES_NOT_FOUND")
 ```
 
 **If either NOT_FOUND**, delegate to `workflow:init`:
@@ -32,8 +32,8 @@ codex workflow:init
 **Output**:
 - If BOTH_EXIST: `PROJECT_STATE: initialized`
 - If NOT_FOUND: Calls `workflow:init` → creates:
-  - `.workflow/project-tech.json` with full technical analysis
+  - `{projectRoot}/.workflow/project-tech.json` with full technical analysis
-  - `.workflow/project-guidelines.json` with empty scaffold
+  - `{projectRoot}/.workflow/project-guidelines.json` with empty scaffold
 
 **Note**: `workflow:init` uses cli-explore-agent to build comprehensive project understanding (technology stack, architecture, key components). This step runs once per project. Subsequent executions skip initialization.
 
@@ -67,16 +67,16 @@ CONTEXT: Existing user database schema, REST API endpoints
 ### Step 1.3: Validate
 
 - Session ID successfully extracted
-- Session directory `.workflow/active/[sessionId]/` exists
+- Session directory `{projectRoot}/.workflow/active/[sessionId]/` exists
 
-**Note**: Session directory contains `workflow-session.json` (metadata). Do NOT look for `manifest.json` here - it only exists in `.workflow/archives/` for archived sessions.
+**Note**: Session directory contains `workflow-session.json` (metadata). Do NOT look for `manifest.json` here - it only exists in `{projectRoot}/.workflow/archives/` for archived sessions.
 
 ### Step 1.4: Initialize Planning Notes
 
 Create `planning-notes.md` with N+1 context support:
 
 ```javascript
-const planningNotesPath = `.workflow/active/${sessionId}/planning-notes.md`
+const planningNotesPath = `${projectRoot}/.workflow/active/${sessionId}/planning-notes.md`
 const userGoal = structuredDescription.goal
 const userConstraints = structuredDescription.context || "None specified"
 
@@ -142,12 +142,12 @@ workflow:session:start
 
 ### Step 1: List Active Sessions
 ```bash
-bash(ls -1 .workflow/active/ 2>/dev/null | head -5)
+bash(ls -1 ${projectRoot}/.workflow/active/ 2>/dev/null | head -5)
 ```
 
 ### Step 2: Display Session Metadata
 ```bash
-bash(cat .workflow/active/WFS-promptmaster-platform/workflow-session.json)
+bash(cat ${projectRoot}/.workflow/active/WFS-promptmaster-platform/workflow-session.json)
 ```
 
 ### Step 4: User Decision
@@ -164,7 +164,7 @@ workflow:session:start --auto "task description"
 
 ### Step 1: Check Active Sessions Count
 ```bash
-bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)
+bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)
 ```
 
 ### Step 2a: No Active Sessions → Create New
@@ -173,12 +173,12 @@ bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)
 bash(echo "implement OAuth2 auth" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
 
 # Create directory structure
-bash(mkdir -p .workflow/active/WFS-implement-oauth2-auth/.process)
+bash(mkdir -p ${projectRoot}/.workflow/active/WFS-implement-oauth2-auth/.process)
-bash(mkdir -p .workflow/active/WFS-implement-oauth2-auth/.task)
+bash(mkdir -p ${projectRoot}/.workflow/active/WFS-implement-oauth2-auth/.task)
-bash(mkdir -p .workflow/active/WFS-implement-oauth2-auth/.summaries)
+bash(mkdir -p ${projectRoot}/.workflow/active/WFS-implement-oauth2-auth/.summaries)
 
 # Create metadata (include type field, default to "workflow" if not specified)
-bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning","type":"workflow","created_at":"2024-12-04T08:00:00Z"}' > .workflow/active/WFS-implement-oauth2-auth/workflow-session.json)
+bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning","type":"workflow","created_at":"2024-12-04T08:00:00Z"}' > ${projectRoot}/.workflow/active/WFS-implement-oauth2-auth/workflow-session.json)
 ```
 
 **Output**: `SESSION_ID: WFS-implement-oauth2-auth`
@@ -186,10 +186,10 @@ bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2
 ### Step 2b: Single Active Session → Check Relevance
 ```bash
 # Extract session ID
-bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
+bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
 
 # Read project name from metadata
-bash(cat .workflow/active/WFS-promptmaster-platform/workflow-session.json | grep -o '"project":"[^"]*"' | cut -d'"' -f4)
+bash(cat ${projectRoot}/.workflow/active/WFS-promptmaster-platform/workflow-session.json | grep -o '"project":"[^"]*"' | cut -d'"' -f4)
 
 # Check keyword match (manual comparison)
 # If task contains project keywords → Reuse session
@@ -202,7 +202,7 @@ bash(cat .workflow/active/WFS-promptmaster-platform/workflow-session.json | grep
 ### Step 2c: Multiple Active Sessions → Use First
 ```bash
 # Get first active session
-bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
+bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
 
 # Output warning and session ID
 # WARNING: Multiple active sessions detected
@@ -222,20 +222,20 @@ workflow:session:start --new "task description"
 bash(echo "fix login bug" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
 
 # Check if exists, add counter if needed
-bash(ls .workflow/active/WFS-fix-login-bug 2>/dev/null && echo "WFS-fix-login-bug-2" || echo "WFS-fix-login-bug")
+bash(ls ${projectRoot}/.workflow/active/WFS-fix-login-bug 2>/dev/null && echo "WFS-fix-login-bug-2" || echo "WFS-fix-login-bug")
 ```
 
 ### Step 2: Create Session Structure
 ```bash
-bash(mkdir -p .workflow/active/WFS-fix-login-bug/.process)
+bash(mkdir -p ${projectRoot}/.workflow/active/WFS-fix-login-bug/.process)
-bash(mkdir -p .workflow/active/WFS-fix-login-bug/.task)
+bash(mkdir -p ${projectRoot}/.workflow/active/WFS-fix-login-bug/.task)
-bash(mkdir -p .workflow/active/WFS-fix-login-bug/.summaries)
+bash(mkdir -p ${projectRoot}/.workflow/active/WFS-fix-login-bug/.summaries)
 ```
 
 ### Step 3: Create Metadata
 ```bash
 # Include type field from --type parameter (default: "workflow")
-bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning","type":"workflow","created_at":"2024-12-04T08:00:00Z"}' > .workflow/active/WFS-fix-login-bug/workflow-session.json)
+bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning","type":"workflow","created_at":"2024-12-04T08:00:00Z"}' > ${projectRoot}/.workflow/active/WFS-fix-login-bug/workflow-session.json)
 ```
 
 **Output**: `SESSION_ID: WFS-fix-login-bug`
@@ -274,7 +274,7 @@ SESSION_ID: WFS-promptmaster-platform
 ## Output
 
 - **Variable**: `sessionId` (e.g., `WFS-implement-oauth2-auth`)
-- **File**: `.workflow/active/{sessionId}/planning-notes.md`
+- **File**: `{projectRoot}/.workflow/active/{sessionId}/planning-notes.md`
 - **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
 
 ## Next Phase

.codex/skills/workflow-plan-execute/phases/02-context-gathering.md

@@ -18,7 +18,7 @@ Intelligently collect project context using context-search-agent based on task d
 - **Inline Resolution**: Conflicts resolved as sub-step within this phase, not a separate phase
 - **Conditional Trigger**: Conflict resolution only executes when exploration results contain conflict indicators
 - **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode)
-- **Standardized Output**: Generate `.workflow/active/{session}/.process/context-package.json`
+- **Standardized Output**: Generate `{projectRoot}/.workflow/active/{session}/.process/context-package.json`
 - **Explicit Lifecycle**: Manage subagent creation, waiting, and cleanup
 
 ## Execution Process
@@ -69,7 +69,7 @@ Step 5: Output Verification (enhanced)
 **Execute First** - Check if valid package already exists:
 
 ```javascript
-const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
+const contextPackagePath = `${projectRoot}/.workflow/${session_id}/.process/context-package.json`;
 
 if (file_exists(contextPackagePath)) {
   const existing = Read(contextPackagePath);
@@ -122,7 +122,7 @@ function selectAngles(taskDescription, complexity) {
 
 const complexity = analyzeTaskComplexity(task_description);
 const selectedAngles = selectAngles(task_description, complexity);
-const sessionFolder = `.workflow/active/${session_id}/.process`;
+const sessionFolder = `${projectRoot}/.workflow/active/${session_id}/.process`;
 
 // 2.2 Launch Parallel Explore Agents (with conflict detection)
 const explorationAgents = [];
@@ -135,8 +135,8 @@ selectedAngles.forEach((angle, index) => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -294,8 +294,8 @@ const conflictAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-execution-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -334,7 +334,7 @@ TASK:
   - Cross-validate with exploration critical_files
   - Generate clarification questions for boundary definition
 MODE: analysis
-CONTEXT: @**/*.ts @**/*.js @**/*.tsx @**/*.jsx @.workflow/active/${session_id}/**/*
+CONTEXT: @**/*.ts @**/*.js @**/*.tsx @**/*.jsx @${projectRoot}/.workflow/active/${session_id}/**/*
 EXPECTED: Conflict list with severity ratings, including:
   - Validation of exploration conflict_indicators
   - ModuleOverlap conflicts with overlap_analysis
@@ -369,7 +369,7 @@ Return JSON following the schema above. Key requirements:
 ### 5. Planning Notes Record (REQUIRED)
 After analysis complete, append a brief execution record to planning-notes.md:
 
-**File**: .workflow/active/${session_id}/planning-notes.md
+**File**: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
 **Location**: Under "## Conflict Decisions (Phase 2)" section
 **Format**:
 \`\`\`
@@ -584,7 +584,7 @@ const resolutionOutput = {
   failed_modifications: failedModifications
 };
 
-const resolutionPath = `.workflow/active/${sessionId}/.process/conflict-resolution.json`;
+const resolutionPath = `${projectRoot}/.workflow/active/${sessionId}/.process/conflict-resolution.json`;
 Write(resolutionPath, JSON.stringify(resolutionOutput, null, 2));
 
 // Output custom conflict summary (if any)
@@ -614,7 +614,7 @@ close_agent({ id: conflictAgentId });
 
 ```javascript
 // Load user intent from planning-notes.md (from Phase 1)
-const planningNotesPath = `.workflow/active/${session_id}/planning-notes.md`;
+const planningNotesPath = `${projectRoot}/.workflow/active/${session_id}/planning-notes.md`;
 let userIntent = { goal: task_description, key_constraints: "None specified" };
 
 if (file_exists(planningNotesPath)) {
@@ -637,8 +637,8 @@ const contextAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/context-search-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -648,7 +648,7 @@ const contextAgentId = spawn_agent({
 ## Session Information
 - **Session ID**: ${session_id}
 - **Task Description**: ${task_description}
-- **Output Path**: .workflow/${session_id}/.process/context-package.json
+- **Output Path**: ${projectRoot}/.workflow/${session_id}/.process/context-package.json
 
 ## User Intent (from Phase 1 - Planning Notes)
 **GOAL**: ${userIntent.goal}
@@ -674,8 +674,8 @@ Execute complete context-search-agent workflow for implementation planning:
 
 ### Phase 1: Initialization & Pre-Analysis
 1. **Project State Loading**:
-   - Read and parse \`.workflow/project-tech.json\`. Use its \`overview\` section as the foundational \`project_context\`. This is your primary source for architecture, tech stack, and key components.
+   - Read and parse \`${projectRoot}/.workflow/project-tech.json\`. Use its \`overview\` section as the foundational \`project_context\`. This is your primary source for architecture, tech stack, and key components.
-   - Read and parse \`.workflow/project-guidelines.json\`. Load \`conventions\`, \`constraints\`, and \`learnings\` into a \`project_guidelines\` section.
+   - Read and parse \`${projectRoot}/.workflow/project-guidelines.json\`. Load \`conventions\`, \`constraints\`, and \`learnings\` into a \`project_guidelines\` section.
    - If files don't exist, proceed with fresh analysis.
 2. **Detection**: Check for existing context-package (early exit if valid)
 3. **Foundation**: Initialize CodexLens, get project structure, load docs
@@ -761,7 +761,7 @@ Before completion verify:
 ## Planning Notes Record (REQUIRED)
 After completing context-package.json, append a brief execution record to planning-notes.md:
 
-**File**: .workflow/active/${session_id}/planning-notes.md
+**File**: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
 **Location**: Under "## Context Findings (Phase 2)" section
 **Format**:
 \`\`\`
@@ -790,7 +790,7 @@ After agent completes, verify output:
 
 ```javascript
 // Verify file was created
-const outputPath = `.workflow/${session_id}/.process/context-package.json`;
+const outputPath = `${projectRoot}/.workflow/${session_id}/.process/context-package.json`;
 if (!file_exists(outputPath)) {
   throw new Error("Agent failed to generate context-package.json");
 }
@@ -916,7 +916,7 @@ If Edit tool fails mid-application:
 
 ## Output
 
-- **Variable**: `contextPath` (e.g., `.workflow/active/WFS-xxx/.process/context-package.json`)
+- **Variable**: `contextPath` (e.g., `{projectRoot}/.workflow/active/WFS-xxx/.process/context-package.json`)
 - **Variable**: `conflictRisk` (none/low/medium/high/resolved)
 - **File**: Updated `planning-notes.md` with context findings + conflict decisions (if applicable)
 - **File**: Optional `conflict-resolution.json` (when conflicts resolved inline)

.codex/skills/workflow-plan-execute/phases/03-task-generation.md

@@ -164,7 +164,7 @@ const userConfig = {
 
 **Session Path Structure**:
 ```
-.workflow/active/WFS-{session-id}/
+{projectRoot}/.workflow/active/WFS-{session-id}/
 ├── workflow-session.json          # Session metadata
 ├── planning-notes.md              # Consolidated planning notes
 ├── .process/
@@ -243,8 +243,8 @@ const planningAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -256,7 +256,7 @@ IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT im
 CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size)
 
 ## PLANNING NOTES (PHASE 1-2 CONTEXT)
-Load: .workflow/active/${session_id}/planning-notes.md
+Load: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
 
 This document contains:
 - User Intent: Original GOAL and KEY_CONSTRAINTS from Phase 1
@@ -268,14 +268,14 @@ This document contains:
 
 ## SESSION PATHS
 Input:
-  - Session Metadata: .workflow/active/${session_id}/workflow-session.json
+  - Session Metadata: ${projectRoot}/.workflow/active/${session_id}/workflow-session.json
-  - Planning Notes: .workflow/active/${session_id}/planning-notes.md
+  - Planning Notes: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
-  - Context Package: .workflow/active/${session_id}/.process/context-package.json
+  - Context Package: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json
 
 Output:
-  - Task Dir: .workflow/active/${session_id}/.task/
+  - Task Dir: ${projectRoot}/.workflow/active/${session_id}/.task/
-  - IMPL_PLAN: .workflow/active/${session_id}/IMPL_PLAN.md
+  - IMPL_PLAN: ${projectRoot}/.workflow/active/${session_id}/IMPL_PLAN.md
-  - TODO_LIST: .workflow/active/${session_id}/TODO_LIST.md
+  - TODO_LIST: ${projectRoot}/.workflow/active/${session_id}/TODO_LIST.md
 
 ## CONTEXT METADATA
 Session ID: ${session_id}
@@ -390,7 +390,7 @@ Hard Constraints:
 ## PLANNING NOTES RECORD (REQUIRED)
 After completing, update planning-notes.md:
 
-**File**: .workflow/active/${session_id}/planning-notes.md
+**File**: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
 
 1. **Task Generation (Phase 3)**: Task count and key tasks
 2. **N+1 Context**: Key decisions (with rationale) + deferred items
@@ -442,8 +442,8 @@ modules.forEach(module => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -456,7 +456,7 @@ IMPORTANT: Generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md by Phase 3 Co
 CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size)
 
 ## PLANNING NOTES (PHASE 1-2 CONTEXT)
-Load: .workflow/active/${session_id}/planning-notes.md
+Load: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
 
 This document contains consolidated constraints and user intent to guide module-scoped task generation.
 
@@ -469,12 +469,12 @@ This document contains consolidated constraints and user intent to guide module-
 
 ## SESSION PATHS
 Input:
-  - Session Metadata: .workflow/active/${session_id}/workflow-session.json
+  - Session Metadata: ${projectRoot}/.workflow/active/${session_id}/workflow-session.json
-  - Planning Notes: .workflow/active/${session_id}/planning-notes.md
+  - Planning Notes: ${projectRoot}/.workflow/active/${session_id}/planning-notes.md
-  - Context Package: .workflow/active/${session_id}/.process/context-package.json
+  - Context Package: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json
 
 Output:
-  - Task Dir: .workflow/active/${session_id}/.task/
+  - Task Dir: ${projectRoot}/.workflow/active/${session_id}/.task/
 
 ## CONTEXT METADATA
 Session ID: ${session_id}
@@ -645,8 +645,8 @@ const coordinatorAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -657,13 +657,13 @@ IMPORTANT: This is INTEGRATION ONLY - consolidate existing task JSONs, NOT creat
 
 ## SESSION PATHS
 Input:
-  - Session Metadata: .workflow/active/${session_id}/workflow-session.json
+  - Session Metadata: ${projectRoot}/.workflow/active/${session_id}/workflow-session.json
-  - Context Package: .workflow/active/${session_id}/.process/context-package.json
+  - Context Package: ${projectRoot}/.workflow/active/${session_id}/.process/context-package.json
-  - Task JSONs: .workflow/active/${session_id}/.task/IMPL-*.json (from Phase 2B)
+  - Task JSONs: ${projectRoot}/.workflow/active/${session_id}/.task/IMPL-*.json (from Phase 2B)
 Output:
-  - Updated Task JSONs: .workflow/active/${session_id}/.task/IMPL-*.json (resolved dependencies)
+  - Updated Task JSONs: ${projectRoot}/.workflow/active/${session_id}/.task/IMPL-*.json (resolved dependencies)
-  - IMPL_PLAN: .workflow/active/${session_id}/IMPL_PLAN.md
+  - IMPL_PLAN: ${projectRoot}/.workflow/active/${session_id}/IMPL_PLAN.md
-  - TODO_LIST: .workflow/active/${session_id}/TODO_LIST.md
+  - TODO_LIST: ${projectRoot}/.workflow/active/${session_id}/TODO_LIST.md
 
 ## CONTEXT METADATA
 Session ID: ${session_id}
@@ -739,9 +739,9 @@ function resolveCrossModuleDependency(placeholder, allTasks) {
 ## Output
 
 - **Files**:
-  - `.workflow/active/{sessionId}/IMPL_PLAN.md`
+  - `{projectRoot}/.workflow/active/{sessionId}/IMPL_PLAN.md`
-  - `.workflow/active/{sessionId}/.task/IMPL-*.json`
+  - `{projectRoot}/.workflow/active/{sessionId}/.task/IMPL-*.json`
-  - `.workflow/active/{sessionId}/TODO_LIST.md`
+  - `{projectRoot}/.workflow/active/{sessionId}/TODO_LIST.md`
 - **Updated**: `planning-notes.md` with task generation record and N+1 context
 
 ## Next Step

.codex/skills/workflow-plan-execute/phases/04-execution.md

@@ -62,8 +62,8 @@ Before generating TodoWrite, update session status from "planning" to "active":
 ```bash
 # Update session status (idempotent - safe to run if already active)
 jq '.status = "active" | .execution_started_at = (.execution_started_at // now | todate)' \
-  .workflow/active/${sessionId}/workflow-session.json > tmp.json && \
+  ${projectRoot}/.workflow/active/${sessionId}/workflow-session.json > tmp.json && \
-  mv tmp.json .workflow/active/${sessionId}/workflow-session.json
+  mv tmp.json ${projectRoot}/.workflow/active/${sessionId}/workflow-session.json
 ```
 This ensures the dashboard shows the session as "ACTIVE" during execution.
 
@@ -127,7 +127,7 @@ If IMPL_PLAN.md lacks execution strategy, use intelligent fallback:
 ```
 while (TODO_LIST.md has pending tasks) {
   next_task_id = getTodoWriteInProgressTask()
-  task_json = Read(.workflow/active/{session}/.task/{next_task_id}.json)  // Lazy load
+  task_json = Read(${projectRoot}/.workflow/active/{session}/.task/{next_task_id}.json)  // Lazy load
   executeTaskWithAgent(task_json)  // spawn_agent → wait → close_agent
   updateTodoListMarkCompleted(next_task_id)
   advanceTodoWriteToNextTask()
@@ -159,8 +159,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/${meta.agent}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -207,8 +207,8 @@ parallelTasks.forEach(task => {
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/${task.meta.agent}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 

.codex/skills/workflow-tdd-plan/SKILL.md

@@ -80,8 +80,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ## TASK CONTEXT
 ${taskContext}
@@ -302,7 +302,7 @@ Read and execute: `workflow-plan-execute/phases/02-context-gathering.md` with `-
 
 **Parse Output**:
 - Extract: context-package.json path (store as `contextPath`)
-- Typical pattern: `.workflow/active/[sessionId]/.process/context-package.json`
+- Typical pattern: `{projectRoot}/.workflow/active/[sessionId]/.process/context-package.json`
 
 **Validation**:
 - Context package path extracted
@@ -326,7 +326,7 @@ Read and execute: `phases/01-test-context-gather.md` with `--session [sessionId]
 - Related components and integration points
 - Test framework detection
 
-**Parse**: Extract testContextPath (`.workflow/active/[sessionId]/.process/test-context-package.json`)
+**Parse**: Extract testContextPath (`{projectRoot}/.workflow/active/[sessionId]/.process/test-context-package.json`)
 
 **TodoWrite Update (Phase 3 - tasks attached)**:
 ```json
@@ -458,7 +458,7 @@ Read and execute: `phases/02-task-generate-tdd.md` with `--session [sessionId]`
 - Generic task names: `Warning: Vague task names suggest unclear TDD cycles`
 - Missing focus_paths: `Warning: Task lacks clear file scope for implementation`
 
-**Action**: Log warnings to `.workflow/active/[sessionId]/.process/tdd-warnings.log` (non-blocking)
+**Action**: Log warnings to `{projectRoot}/.workflow/active/[sessionId]/.process/tdd-warnings.log` (non-blocking)
 
 **TodoWrite Update (Phase 5 - tasks attached)**:
 ```json
@@ -527,15 +527,15 @@ Warning TDD Red Flag: [issue description]
 
 ```bash
 # Verify session artifacts exist
-ls -la .workflow/active/[sessionId]/{IMPL_PLAN.md,TODO_LIST.md}
+ls -la ${projectRoot}/.workflow/active/[sessionId]/{IMPL_PLAN.md,TODO_LIST.md}
-ls -la .workflow/active/[sessionId]/.task/IMPL-*.json
+ls -la ${projectRoot}/.workflow/active/[sessionId]/.task/IMPL-*.json
 
 # Count generated artifacts
-echo "IMPL tasks: $(ls .workflow/active/[sessionId]/.task/IMPL-*.json 2>/dev/null | wc -l)"
+echo "IMPL tasks: $(ls ${projectRoot}/.workflow/active/[sessionId]/.task/IMPL-*.json 2>/dev/null | wc -l)"
 
 # Sample task structure verification (first task)
 jq '{id, tdd: .meta.tdd_workflow, cli_id: .meta.cli_execution_id, phases: [.flow_control.implementation_approach[].tdd_phase]}' \
-  "$(ls .workflow/active/[sessionId]/.task/IMPL-*.json | head -1)"
+  "$(ls ${projectRoot}/.workflow/active/[sessionId]/.task/IMPL-*.json | head -1)"
 ```
 
 **Evidence Required Before Summary**:
@@ -568,11 +568,11 @@ Structure:
 [...]
 
 Plans generated:
-- Unified Implementation Plan: .workflow/active/[sessionId]/IMPL_PLAN.md
+- Unified Implementation Plan: {projectRoot}/.workflow/active/[sessionId]/IMPL_PLAN.md
   (includes TDD Implementation Tasks section with workflow_type: "tdd")
-- Task List: .workflow/active/[sessionId]/TODO_LIST.md
+- Task List: {projectRoot}/.workflow/active/[sessionId]/TODO_LIST.md
   (with internal TDD phase indicators and CLI execution strategies)
-- Task JSONs: .workflow/active/[sessionId]/.task/IMPL-*.json
+- Task JSONs: {projectRoot}/.workflow/active/[sessionId]/.task/IMPL-*.json
   (with cli_execution_id and execution strategies for resume support)
 
 TDD Configuration:

.codex/skills/workflow-tdd-plan/phases/01-test-context-gather.md

@@ -10,7 +10,7 @@ Orchestrator command that invokes `test-context-search-agent` to gather comprehe
 - **Detection-First**: Check for existing test-context-package before executing
 - **Coverage-First**: Analyze existing test coverage before planning new tests
 - **Source Context Loading**: Import implementation summaries from source session
-- **Standardized Output**: Generate `.workflow/active/{test_session_id}/.process/test-context-package.json`
+- **Standardized Output**: Generate `{projectRoot}/.workflow/active/{test_session_id}/.process/test-context-package.json`
 - **Explicit Lifecycle**: Always close_agent after wait completes to free resources
 
 ## Execution Process
@@ -50,7 +50,7 @@ Step 3: Output Verification
 **Execute First** - Check if valid package already exists:
 
 ```javascript
-const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
+const testContextPath = `${projectRoot}/.workflow/${test_session_id}/.process/test-context-package.json`;
 
 if (file_exists(testContextPath)) {
   const existing = Read(testContextPath);
@@ -80,8 +80,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/test-context-search-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -90,7 +90,7 @@ const agentId = spawn_agent({
 
 ## Session Information
 - **Test Session ID**: ${test_session_id}
-- **Output Path**: .workflow/${test_session_id}/.process/test-context-package.json
+- **Output Path**: ${projectRoot}/.workflow/${test_session_id}/.process/test-context-package.json
 
 ## Mission
 Execute complete test-context-search-agent workflow for test generation planning:
@@ -161,7 +161,7 @@ After agent completes, verify output:
 
 ```javascript
 // Verify file was created
-const outputPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
+const outputPath = `${projectRoot}/.workflow/${test_session_id}/.process/test-context-package.json`;
 if (!file_exists(outputPath)) {
   throw new Error("Agent failed to generate test-context-package.json");
 }
@@ -193,7 +193,7 @@ Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-pac
 
 ## Success Criteria
 
-- Valid test-context-package.json generated in `.workflow/active/{test_session_id}/.process/`
+- Valid test-context-package.json generated in `{projectRoot}/.workflow/active/{test_session_id}/.process/`
 - Source session context loaded successfully
 - Test coverage gaps identified (>90% accuracy)
 - Test framework detected and documented
@@ -234,7 +234,7 @@ Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-pac
 ## Post-Phase Update
 
 After Phase 1 (Test Context Gather) completes:
-- **Output Created**: `test-context-package.json` in `.workflow/active/{session}/.process/`
+- **Output Created**: `test-context-package.json` in `{projectRoot}/.workflow/active/{session}/.process/`
 - **Data Available**: Test coverage stats, framework info, missing tests list
 - **Next Action**: Continue to Phase 4 (Conflict Resolution, if conflict_risk >= medium) or Phase 5 (TDD Task Generation)
 - **TodoWrite**: Collapse Phase 3 sub-tasks to "Phase 3: Test Coverage Analysis: completed"

.codex/skills/workflow-tdd-plan/phases/02-task-generate-tdd.md

@@ -165,7 +165,7 @@ const userConfig = {
 
 **Session Path Structure** (Provided by Command to Agent):
 ```
-.workflow/active/WFS-{session-id}/
+${projectRoot}/.workflow/active/WFS-{session-id}/
 ├── workflow-session.json          # Session metadata
 ├── .process/
 │   ├── context-package.json       # Context package with artifact catalog
@@ -181,9 +181,9 @@ const userConfig = {
 
 **Command Preparation**:
 1. **Assemble Session Paths** for agent prompt:
-   - `session_metadata_path`: `.workflow/active/{session-id}/workflow-session.json`
+   - `session_metadata_path`: `${projectRoot}/.workflow/active/{session-id}/workflow-session.json`
-   - `context_package_path`: `.workflow/active/{session-id}/.process/context-package.json`
+   - `context_package_path`: `${projectRoot}/.workflow/active/{session-id}/.process/context-package.json`
-   - `test_context_package_path`: `.workflow/active/{session-id}/.process/test-context-package.json`
+   - `test_context_package_path`: `${projectRoot}/.workflow/active/{session-id}/.process/test-context-package.json`
    - Output directory paths
 
 2. **Provide Metadata** (simple values):
@@ -250,21 +250,21 @@ const userConfig = {
 1. **Load Session Context** (if not in memory)
    ```javascript
    if (!memory.has("workflow-session.json")) {
-     Read(.workflow/active/{session-id}/workflow-session.json)
+     Read(${projectRoot}/.workflow/active/{session-id}/workflow-session.json)
    }
    ```
 
 2. **Load Context Package** (if not in memory)
    ```javascript
    if (!memory.has("context-package.json")) {
-     Read(.workflow/active/{session-id}/.process/context-package.json)
+     Read(${projectRoot}/.workflow/active/{session-id}/.process/context-package.json)
    }
    ```
 
 3. **Load Test Context Package** (if not in memory)
    ```javascript
    if (!memory.has("test-context-package.json")) {
-     Read(.workflow/active/{session-id}/.process/test-context-package.json)
+     Read(${projectRoot}/.workflow/active/{session-id}/.process/test-context-package.json)
    }
    ```
 
@@ -319,8 +319,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -336,14 +336,14 @@ CRITICAL: Follow the progressive loading strategy (load analysis.md files increm
 
 ## SESSION PATHS
 Input:
-  - Session Metadata: .workflow/active/{session-id}/workflow-session.json
+  - Session Metadata: ${projectRoot}/.workflow/active/{session-id}/workflow-session.json
-  - Context Package: .workflow/active/{session-id}/.process/context-package.json
+  - Context Package: ${projectRoot}/.workflow/active/{session-id}/.process/context-package.json
-  - Test Context: .workflow/active/{session-id}/.process/test-context-package.json
+  - Test Context: ${projectRoot}/.workflow/active/{session-id}/.process/test-context-package.json
 
 Output:
-  - Task Dir: .workflow/active/{session-id}/.task/
+  - Task Dir: ${projectRoot}/.workflow/active/{session-id}/.task/
-  - IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
+  - IMPL_PLAN: ${projectRoot}/.workflow/active/{session-id}/IMPL_PLAN.md
-  - TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
+  - TODO_LIST: ${projectRoot}/.workflow/active/{session-id}/TODO_LIST.md
 
 ## CONTEXT METADATA
 Session ID: {session-id}
@@ -416,7 +416,7 @@ IMPORTANT: Do NOT add command field to implementation_approach steps. Execution
 #### Required Outputs Summary
 
 ##### 1. TDD Task JSON Files (.task/IMPL-*.json)
-- **Location**: \`.workflow/active/{session-id}/.task/\`
+- **Location**: \`${projectRoot}/.workflow/active/{session-id}/.task/\`
 - **Schema**: 6-field structure with TDD-specific metadata
   - \`id, title, status, context_package_path, meta, context, flow_control\`
   - \`meta.tdd_workflow\`: true (REQUIRED)
@@ -434,7 +434,7 @@ IMPORTANT: Do NOT add command field to implementation_approach steps. Execution
 - **Details**: See action-planning-agent.md § TDD Task JSON Generation
 
 ##### 2. IMPL_PLAN.md (TDD Variant)
-- **Location**: \`.workflow/active/{session-id}/IMPL_PLAN.md\`
+- **Location**: \`${projectRoot}/.workflow/active/{session-id}/IMPL_PLAN.md\`
 - **Template**: \`~/.ccw/workflows/cli-templates/prompts/workflow/impl-plan-template.txt\`
 - **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown
 - **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles
@@ -442,7 +442,7 @@ IMPORTANT: Do NOT add command field to implementation_approach steps. Execution
 - **Details**: See action-planning-agent.md § TDD Implementation Plan Creation
 
 ##### 3. TODO_LIST.md
-- **Location**: \`.workflow/active/{session-id}/TODO_LIST.md\`
+- **Location**: \`${projectRoot}/.workflow/active/{session-id}/TODO_LIST.md\`
 - **Format**: Hierarchical task list with internal TDD phase indicators (Red → Green → Refactor)
 - **Status**: ▸ (container), [ ] (pending), [x] (completed)
 - **Links**: Task JSON references and summaries
@@ -569,12 +569,12 @@ close_agent({ id: agentId });
 // Command assembles these simple values and paths for agent
 const commandProvides = {
   // Session paths
-  session_metadata_path: ".workflow/active/WFS-{id}/workflow-session.json",
+  session_metadata_path: "${projectRoot}/.workflow/active/WFS-{id}/workflow-session.json",
-  context_package_path: ".workflow/active/WFS-{id}/.process/context-package.json",
+  context_package_path: "${projectRoot}/.workflow/active/WFS-{id}/.process/context-package.json",
-  test_context_package_path: ".workflow/active/WFS-{id}/.process/test-context-package.json",
+  test_context_package_path: "${projectRoot}/.workflow/active/WFS-{id}/.process/test-context-package.json",
-  output_task_dir: ".workflow/active/WFS-{id}/.task/",
+  output_task_dir: "${projectRoot}/.workflow/active/WFS-{id}/.task/",
-  output_impl_plan: ".workflow/active/WFS-{id}/IMPL_PLAN.md",
+  output_impl_plan: "${projectRoot}/.workflow/active/WFS-{id}/IMPL_PLAN.md",
-  output_todo_list: ".workflow/active/WFS-{id}/TODO_LIST.md",
+  output_todo_list: "${projectRoot}/.workflow/active/WFS-{id}/TODO_LIST.md",
 
   // Simple metadata
   session_id: "WFS-{id}",
@@ -651,7 +651,7 @@ This section provides quick reference for TDD task JSON structure. For complete
 
 ## Output Files Structure
 ```
-.workflow/active/{session-id}/
+${projectRoot}/.workflow/active/{session-id}/
 ├── IMPL_PLAN.md                     # Unified plan with TDD Implementation Tasks section
 ├── TODO_LIST.md                     # Progress tracking with internal TDD phase indicators
 ├── .task/

.codex/skills/workflow-tdd-plan/phases/03-tdd-verify.md

@@ -4,7 +4,7 @@
 
 Verify TDD workflow execution quality by validating Red-Green-Refactor cycle compliance, test coverage completeness, and task chain structure integrity. This phase orchestrates multiple analysis steps and generates a comprehensive compliance report with quality gate recommendation.
 
-**Output**: A structured Markdown report saved to `.workflow/active/WFS-{session}/TDD_COMPLIANCE_REPORT.md` containing:
+**Output**: A structured Markdown report saved to `{projectRoot}/.workflow/active/WFS-{session}/TDD_COMPLIANCE_REPORT.md` containing:
 - Executive summary with compliance score and quality gate recommendation
 - Task chain validation (TEST → IMPL → REFACTOR structure)
 - Test coverage metrics (line, branch, function)
@@ -71,18 +71,18 @@ IF --session parameter provided:
     session_id = provided session
 ELSE:
     # Auto-detect active session
-    active_sessions = bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
+    active_sessions = bash(find ${projectRoot}/.workflow/active/ -name "WFS-*" -type d 2>/dev/null)
     IF active_sessions is empty:
         ERROR: "No active workflow session found. Use --session <session-id>"
         EXIT
     ELSE IF active_sessions has multiple entries:
         # Use most recently modified session
-        session_id = bash(ls -td .workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename)
+        session_id = bash(ls -td ${projectRoot}/.workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename)
     ELSE:
         session_id = basename(active_sessions[0])
 
 # Derive paths
-session_dir = .workflow/active/WFS-{session_id}
+session_dir = ${projectRoot}/.workflow/active/WFS-{session_id}
 task_dir = session_dir/.task
 summaries_dir = session_dir/.summaries
 process_dir = session_dir/.process
@@ -292,7 +292,7 @@ echo "Next: Review full report for detailed findings"
 
 ### Chain Validation Algorithm
 ```
-1. Load all task JSONs from .workflow/active/{sessionId}/.task/
+1. Load all task JSONs from ${projectRoot}/.workflow/active/{sessionId}/.task/
 2. Extract task IDs and group by feature number
 3. For each feature:
    - Check TEST-N.M exists
@@ -323,7 +323,7 @@ echo "Next: Review full report for detailed findings"
 
 ## Output Files
 ```
-.workflow/active/WFS-{session-id}/
+${projectRoot}/.workflow/active/WFS-{session-id}/
 ├── TDD_COMPLIANCE_REPORT.md     # Comprehensive compliance report
 └── .process/
     ├── test-results.json         # From phases/04-tdd-coverage-analysis.md

.codex/skills/workflow-tdd-plan/phases/04-tdd-coverage-analysis.md

@@ -46,7 +46,7 @@ Phase 5: Generate Analysis Report
 
 ### Phase 1: Extract Test Tasks
 ```bash
-find .workflow/active/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \;
+find ${projectRoot}/.workflow/active/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \;
 ```
 
 **Output**: List of test directories/files from all TEST tasks
@@ -54,20 +54,20 @@ find .workflow/active/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.cont
 ### Phase 2: Run Test Suite
 ```bash
 # Node.js/JavaScript
-npm test -- --coverage --json > .workflow/active/{session_id}/.process/test-results.json
+npm test -- --coverage --json > ${projectRoot}/.workflow/active/{session_id}/.process/test-results.json
 
 # Python
-pytest --cov --json-report > .workflow/active/{session_id}/.process/test-results.json
+pytest --cov --json-report > ${projectRoot}/.workflow/active/{session_id}/.process/test-results.json
 
 # Other frameworks (detect from project)
-[test_command] --coverage --json-output .workflow/active/{session_id}/.process/test-results.json
+[test_command] --coverage --json-output ${projectRoot}/.workflow/active/{session_id}/.process/test-results.json
 ```
 
 **Output**: test-results.json with coverage data
 
 ### Phase 3: Parse Coverage Data
 ```bash
-jq '.coverage' .workflow/active/{session_id}/.process/test-results.json > .workflow/active/{session_id}/.process/coverage-report.json
+jq '.coverage' ${projectRoot}/.workflow/active/{session_id}/.process/test-results.json > ${projectRoot}/.workflow/active/{session_id}/.process/coverage-report.json
 ```
 
 **Extract**:
@@ -83,7 +83,7 @@ For each TDD chain (TEST-N.M -> IMPL-N.M -> REFACTOR-N.M):
 **1. Red Phase Verification**
 ```bash
 # Check TEST task summary
-cat .workflow/active/{session_id}/.summaries/TEST-N.M-summary.md
+cat ${projectRoot}/.workflow/active/{session_id}/.summaries/TEST-N.M-summary.md
 ```
 
 Verify:
@@ -94,7 +94,7 @@ Verify:
 **2. Green Phase Verification**
 ```bash
 # Check IMPL task summary
-cat .workflow/active/{session_id}/.summaries/IMPL-N.M-summary.md
+cat ${projectRoot}/.workflow/active/{session_id}/.summaries/IMPL-N.M-summary.md
 ```
 
 Verify:
@@ -105,7 +105,7 @@ Verify:
 **3. Refactor Phase Verification**
 ```bash
 # Check REFACTOR task summary
-cat .workflow/active/{session_id}/.summaries/REFACTOR-N.M-summary.md
+cat ${projectRoot}/.workflow/active/{session_id}/.summaries/REFACTOR-N.M-summary.md
 ```
 
 Verify:
@@ -115,7 +115,7 @@ Verify:
 
 ### Phase 5: Generate Analysis Report
 
-Create `.workflow/active/{session_id}/.process/tdd-cycle-report.md`:
+Create `${projectRoot}/.workflow/active/{session_id}/.process/tdd-cycle-report.md`:
 
 ```markdown
 # TDD Cycle Analysis - {Session ID}
@@ -171,7 +171,7 @@ Create `.workflow/active/{session_id}/.process/tdd-cycle-report.md`:
 
 ## Output Files
 ```
-.workflow/active/{session-id}/
+${projectRoot}/.workflow/active/{session-id}/
 └── .process/
     ├── test-results.json         # Raw test execution results
     ├── coverage-report.json      # Parsed coverage data

.codex/skills/workflow-test-fix-cycle/SKILL.md

@@ -88,8 +88,8 @@ const agentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ## TASK CONTEXT
 ${taskContext}
@@ -263,7 +263,7 @@ Phase 2: Test-Cycle Execution (phases/02-test-cycle-execute.md)
 ### Directory Structure
 
 ```
-.workflow/active/WFS-test-[session]/
+{projectRoot}/.workflow/active/WFS-test-[session]/
 ├── workflow-session.json              # Session metadata
 ├── IMPL_PLAN.md                       # Test generation and execution strategy
 ├── TODO_LIST.md                       # Task checklist

.codex/skills/workflow-test-fix-cycle/phases/01-test-fix-gen.md

@@ -34,7 +34,7 @@
 if (input.startsWith("WFS-")) {
   MODE = "session"
   // Load source session to preserve original task description
-  Read(".workflow/active/[sourceSessionId]/workflow-session.json")
+  Read("${projectRoot}/.workflow/active/[sourceSessionId]/workflow-session.json")
 } else {
   MODE = "prompt"
 }
@@ -56,7 +56,7 @@ if (input.startsWith("WFS-")) {
 - Extract: `SESSION_ID: WFS-test-[slug]` (store as `testSessionId`)
 
 **Validation**:
-- Session Mode: Source session `.workflow/active/[sourceSessionId]/` exists with completed IMPL tasks
+- Session Mode: Source session `{projectRoot}/.workflow/active/[sourceSessionId]/` exists with completed IMPL tasks
 - Both Modes: New test session directory created with metadata
 
 **Progress Tracking**: Mark sub-phase 1.1 completed, sub-phase 1.2 in_progress
@@ -75,8 +75,8 @@ const contextAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/test-context-search-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -84,8 +84,8 @@ const contextAgentId = spawn_agent({
 Gather test context for session [testSessionId]
 
 ## Session Paths
-- Session Dir: .workflow/active/[testSessionId]/
+- Session Dir: ${projectRoot}/.workflow/active/[testSessionId]/
-- Output: .workflow/active/[testSessionId]/.process/test-context-package.json
+- Output: ${projectRoot}/.workflow/active/[testSessionId]/.process/test-context-package.json
 
 ## Expected Deliverables
 - test-context-package.json with coverage analysis and test framework detection
@@ -102,8 +102,8 @@ const contextAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/context-search-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -111,8 +111,8 @@ const contextAgentId = spawn_agent({
 Gather project context for session [testSessionId]: [task_description]
 
 ## Session Paths
-- Session Dir: .workflow/active/[testSessionId]/
+- Session Dir: ${projectRoot}/.workflow/active/[testSessionId]/
-- Output: .workflow/active/[testSessionId]/.process/context-package.json
+- Output: ${projectRoot}/.workflow/active/[testSessionId]/.process/context-package.json
 
 ## Expected Deliverables
 - context-package.json with codebase analysis
@@ -127,7 +127,7 @@ close_agent({ id: contextAgentId });
 
 **Parse Output**:
 - Extract: context package path (store as `contextPath`)
-- Pattern: `.workflow/active/[testSessionId]/.process/[test-]context-package.json`
+- Pattern: `${projectRoot}/.workflow/active/[testSessionId]/.process/[test-]context-package.json`
 
 **Validation**:
 - Context package file exists and is valid JSON
@@ -176,8 +176,8 @@ const analysisAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-execution-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -196,7 +196,7 @@ Analyze test requirements for session [testSessionId] using Gemini CLI
 - Generate TEST_ANALYSIS_RESULTS.md
 
 ## Output Path
-.workflow/active/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
+${projectRoot}/.workflow/active/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
 
 ## Expected Deliverables
 - TEST_ANALYSIS_RESULTS.md with L0-L3 requirements and AI issue scan
@@ -218,7 +218,7 @@ close_agent({ id: analysisAgentId });
 - Scan for AI code issues
 - Generate `TEST_ANALYSIS_RESULTS.md`
 
-**Output**: `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md`
+**Output**: `${projectRoot}/.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md`
 
 **Validation** - TEST_ANALYSIS_RESULTS.md must include:
 - Project Type Detection (with confidence)
@@ -245,8 +245,8 @@ const taskGenAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/action-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: ${projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: ${projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -255,7 +255,7 @@ Generate test-specific IMPL_PLAN.md and task JSONs for session [testSessionId]
 
 ## Context
 - Session ID: [testSessionId]
-- TEST_ANALYSIS_RESULTS.md: .workflow/active/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
+- TEST_ANALYSIS_RESULTS.md: ${projectRoot}/.workflow/active/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
 
 ## Expected Output (minimum 4 tasks)
 - IMPL-001.json: Test understanding & generation (@code-developer)
@@ -266,9 +266,9 @@ Generate test-specific IMPL_PLAN.md and task JSONs for session [testSessionId]
 - TODO_LIST.md: Task checklist
 
 ## Output Paths
-- Tasks: .workflow/active/[testSessionId]/.task/
+- Tasks: ${projectRoot}/.workflow/active/[testSessionId]/.task/
-- Plan: .workflow/active/[testSessionId]/IMPL_PLAN.md
+- Plan: ${projectRoot}/.workflow/active/[testSessionId]/IMPL_PLAN.md
-- Todo: .workflow/active/[testSessionId]/TODO_LIST.md
+- Todo: ${projectRoot}/.workflow/active/[testSessionId]/TODO_LIST.md
 `
 });
 
@@ -290,12 +290,12 @@ close_agent({ id: taskGenAgentId });
 | IMPL-002 | test-fix | @test-fix-agent | Test execution & fix cycle |
 
 **Validation**:
-- `.workflow/active/[testSessionId]/.task/IMPL-001.json` exists
+- `${projectRoot}/.workflow/active/[testSessionId]/.task/IMPL-001.json` exists
-- `.workflow/active/[testSessionId]/.task/IMPL-001.3-validation.json` exists
+- `${projectRoot}/.workflow/active/[testSessionId]/.task/IMPL-001.3-validation.json` exists
-- `.workflow/active/[testSessionId]/.task/IMPL-001.5-review.json` exists
+- `${projectRoot}/.workflow/active/[testSessionId]/.task/IMPL-001.5-review.json` exists
-- `.workflow/active/[testSessionId]/.task/IMPL-002.json` exists
+- `${projectRoot}/.workflow/active/[testSessionId]/.task/IMPL-002.json` exists
-- `.workflow/active/[testSessionId]/IMPL_PLAN.md` exists
+- `${projectRoot}/.workflow/active/[testSessionId]/IMPL_PLAN.md` exists
-- `.workflow/active/[testSessionId]/TODO_LIST.md` exists
+- `${projectRoot}/.workflow/active/[testSessionId]/TODO_LIST.md` exists
 
 **Progress Tracking Update (agent task attached)**:
 ```json
@@ -335,9 +335,9 @@ Quality Thresholds:
 - Max Fix Iterations: 5
 
 Artifacts:
-- Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
+- Test plan: ${projectRoot}/.workflow/[testSessionId]/IMPL_PLAN.md
-- Task list: .workflow/[testSessionId]/TODO_LIST.md
+- Task list: ${projectRoot}/.workflow/[testSessionId]/TODO_LIST.md
-- Analysis: .workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
+- Analysis: ${projectRoot}/.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
 
 → Transitioning to Phase 2: Test-Cycle Execution
 ```

.codex/skills/workflow-test-fix-cycle/phases/02-test-cycle-execute.md

@@ -90,8 +90,8 @@ const analysisAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/cli-planning-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -157,8 +157,8 @@ const fixAgentId = spawn_agent({
 
 ### MANDATORY FIRST STEPS (Agent Execute)
 1. **Read role definition**: ~/.codex/agents/test-fix-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
+2. Read: {projectRoot}/.workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
+3. Read: {projectRoot}/.workflow/project-guidelines.json
 
 ---
 
@@ -276,7 +276,7 @@ const taskTypeSuccessCriteria = {
 ## Session File Structure
 
 ```
-.workflow/active/WFS-test-{session}/
+{projectRoot}/.workflow/active/WFS-test-{session}/
 ├── workflow-session.json           # Session metadata
 ├── IMPL_PLAN.md, TODO_LIST.md
 ├── .task/