refactor(workflow): migrate to sessions/ subdirectory structure

Refactor workflow directory structure to improve clarity and robustness by introducing dedicated sessions/ subdirectory for active sessions. ## Directory Structure Changes ### Before (Old Structure) ``` .workflow/ ├── .active-WFS-session-1 # Marker files (fragile) ├── WFS-session-1/ # Active sessions mixed with config ├── WFS-session-2/ ├── project.json └── .archives/ # Archived sessions ``` ### After (New Structure) ``` .workflow/ ├── project.json # Project metadata ├── sessions/ # [NEW] All active sessions │ └── WFS-session-1/ └── archives/ # Archived sessions (removed dot prefix) ``` ## Key Improvements 1. **Physical Isolation**: Active sessions now in dedicated sessions/ subdirectory 2. **No Marker Files**: Removed fragile .active-* marker file mechanism 3. **Directory-Based State**: Session state determined by directory location - In sessions/ = active - In archives/ = archived 4. **Simpler Discovery**: `ls .workflow/sessions/` instead of `find .workflow/ -name ".active-*"` 5. **Cleaner Root**: .workflow/ root now only contains project.json, sessions/, archives/ ## Path Transformations | Old Pattern | New Pattern | |-------------|-------------| | `find .workflow/ -name ".active-*"` | `find .workflow/sessions/ -name "WFS-*" -type d` | | `.workflow/WFS-[slug]/` | `.workflow/sessions/WFS-[slug]/` | | `.workflow/.archives/` | `.workflow/archives/` | | `touch .workflow/.active-*` | *Removed* | | `rm .workflow/.active-*` | *Removed* | ## Modified Commands ### session/start.md - Update session creation path to .workflow/sessions/WFS-*/ - Remove .active-* marker file creation - Update session discovery to use directory listing - Updated all 3 modes: Discovery, Auto, Force New ### session/complete.md - Update session move from sessions/ to archives/ - Remove .active-* marker file deletion - Update manifest path to archives/manifest.json - Update agent prompts with new paths ### status.md - Update session discovery to find .workflow/sessions/ - Update all session file path references - Update archive query examples ### execute.md - Update session discovery logic - Update all task file paths to include sessions/ prefix - Update context package paths - Update error handling documentation ## Benefits - **Robustness**: Eliminates marker file state inconsistency risk - **Clarity**: Clear separation between active and archived sessions - **Simplicity**: Session discovery is straightforward directory listing - **Alignment**: Closer to OpenSpec's three-layer structure (specs/changes/archive) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-05 01:50:27 +08:00 · 2025-11-18 11:34:52 +08:00
parent 2aacc34c24
commit d9fcdad949
4 changed files with 54 additions and 76 deletions
--- a/.claude/commands/workflow/execute.md
+++ b/.claude/commands/workflow/execute.md
@@ -55,7 +55,7 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 **Applies to**: Normal mode only (skipped in resume mode)

 **Process**:
-1. **Check Active Sessions**: Find `.workflow/.active-*` markers
+1. **Check Active Sessions**: Find sessions in `.workflow/sessions/` directory
 2. **Select Session**: If multiple found, prompt user selection
 3. **Load Session Metadata**: Read `workflow-session.json` ONLY (minimal context)
 4. **DO NOT read task JSONs yet** - defer until execution phase
@@ -322,11 +322,11 @@ TodoWrite({
    }
  },
  "session": {
-    "workflow_dir": ".workflow/WFS-session/",
-    "context_package_path": ".workflow/WFS-session/.process/context-package.json",
-    "todo_list_path": ".workflow/WFS-session/TODO_LIST.md",
-    "summaries_dir": ".workflow/WFS-session/.summaries/",
-    "task_json_path": ".workflow/WFS-session/.task/IMPL-1.1.json"
+    "workflow_dir": ".workflow/sessions/WFS-session/",
+    "context_package_path": ".workflow/sessions/WFS-session/.process/context-package.json",
+    "todo_list_path": ".workflow/sessions/WFS-session/TODO_LIST.md",
+    "summaries_dir": ".workflow/sessions/WFS-session/.summaries/",
+    "task_json_path": ".workflow/sessions/WFS-session/.task/IMPL-1.1.json"
  },
  "dependencies": [ /* Task summaries from depends_on */ ],
  "inherited": { /* Parent task context */ }
@@ -452,7 +452,7 @@ Task(subagent_type="{meta.agent}",
        "step": "load_synthesis_specification",
        "action": "Load synthesis specification from context-package.json",
        "commands": [
-          "Read(.workflow/WFS-[session]/.process/context-package.json)",
+          "Read(.workflow/sessions/WFS-[session]/.process/context-package.json)",
          "Extract(brainstorm_artifacts.synthesis_output.path)",
          "Read(extracted path)"
        ],
@@ -514,7 +514,7 @@ meta.agent missing → Infer from meta.type:

 ## Workflow File Structure Reference
 ```
-.workflow/WFS-[topic-slug]/
+.workflow/sessions/WFS-[topic-slug]/
 ├── workflow-session.json     # Session state and metadata
 ├── IMPL_PLAN.md             # Planning document and requirements
 ├── TODO_LIST.md             # Progress tracking (auto-updated)
@@ -536,8 +536,8 @@ meta.agent missing → Infer from meta.type:
 | Error Type | Cause | Recovery Strategy | Max Attempts |
 |-----------|-------|------------------|--------------|
 | **Discovery Errors** |
-| No active session | No `.active-*` markers found | Create or resume session: `/workflow:plan "project"` | N/A |
-| Multiple sessions | Multiple `.active-*` markers | Prompt user selection | N/A |
+| No active session | No sessions in `.workflow/sessions/` | Create or resume session: `/workflow:plan "project"` | N/A |
+| Multiple sessions | Multiple sessions in `.workflow/sessions/` | 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 | 2 |
@@ -557,26 +557,23 @@ meta.agent missing → Infer from meta.type:
 **Session Recovery**:
 ```bash
 # Check session integrity
-find .workflow -name ".active-*" | while read marker; do
-  session=$(basename "$marker" | sed 's/^\.active-//')
-  [ ! -d ".workflow/$session" ] && rm "$marker"
+find .workflow/sessions/ -name "WFS-*" -type d | while read session_dir; do
+  session=$(basename "$session_dir")
+  [ ! -f "$session_dir/workflow-session.json" ] && \
+    echo '{"session_id":"'$session'","status":"active"}' > "$session_dir/workflow-session.json"
 done
-
-# Recreate corrupted session files
-[ ! -f ".workflow/$session/workflow-session.json" ] && \
-  echo '{"session_id":"'$session'","status":"active"}' > ".workflow/$session/workflow-session.json"
 ```

 **Task Recovery**:
 ```bash
 # Validate task JSON integrity
-for task_file in .workflow/$session/.task/*.json; do
+for task_file in .workflow/sessions/$session/.task/*.json; do
  jq empty "$task_file" 2>/dev/null || echo "Corrupted: $task_file"
 done

 # Fix missing dependencies
-missing_deps=$(jq -r '.context.depends_on[]?' .workflow/$session/.task/*.json | sort -u)
+missing_deps=$(jq -r '.context.depends_on[]?' .workflow/sessions/$session/.task/*.json | sort -u)
 for dep in $missing_deps; do
-  [ ! -f ".workflow/$session/.task/$dep.json" ] && echo "Missing dependency: $dep"
+  [ ! -f ".workflow/sessions/$session/.task/$dep.json" ] && echo "Missing dependency: $dep"
 done
 ```
--- a/.claude/commands/workflow/session/complete.md
+++ b/.claude/commands/workflow/session/complete.md
@@ -25,23 +25,23 @@ Mark the currently active workflow session as complete, analyze it for lessons l

 #### Step 1.1: Find Active Session and Get Name
 ```bash
-# Find active marker
-bash(find .workflow/ -name ".active-*" -type f | head -1)
+# Find active session directory
+bash(find .workflow/sessions/ -name "WFS-*" -type d | head -1)

-# Extract session name from marker path
-bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
+# Extract session name from directory path
+bash(basename .workflow/sessions/WFS-session-name)
 ```
 **Output**: Session name `WFS-session-name`

 #### Step 1.2: Move Session to Archive
 ```bash
 # Create archive directory if needed
-bash(mkdir -p .workflow/.archives/)
+bash(mkdir -p .workflow/archives/)

 # Move session to archive location
-bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
+bash(mv .workflow/sessions/WFS-session-name .workflow/archives/WFS-session-name)
 ```
-**Result**: Session now at `.workflow/.archives/WFS-session-name/`
+**Result**: Session now at `.workflow/archives/WFS-session-name/`

 ### Phase 2: Agent-Orchestrated Completion (All Data Processing)

@@ -60,8 +60,7 @@ Task(
 Complete workflow session archival. Session already moved to archive location.

 ## Context
- Session: .workflow/.archives/WFS-session-name/
- Active marker: .workflow/.active-WFS-session-name
+- Session: .workflow/archives/WFS-session-name/

 ## Tasks

@@ -77,15 +76,12 @@ Complete workflow session archival. Session already moved to archive location.
   - Calculate: duration_hours, success_rate, tags (3-5 keywords)
   - Construct complete JSON with session_id, description, archived_at, archive_path, metrics, tags, lessons

-5. **Update manifest**: Initialize .workflow/.archives/manifest.json if needed, append entry
+5. **Update manifest**: Initialize .workflow/archives/manifest.json if needed, append entry

-6. **Remove active marker**
-
-7. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}
+6. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}

 ## Error Handling
 - On failure: return {"status": "error", "task": "...", "message": "..."}
- Do NOT remove marker if failed
  `
 )
 ```
@@ -111,7 +107,6 @@ Complete workflow session archival. Session already moved to archive location.
 - Generate lessons learned analysis
 - Build complete archive metadata
 - Update manifest
- Remove active marker
 - Return success/error result

 ### Phase 3: Update Project Feature Registry
@@ -134,7 +129,7 @@ WARNING: No project.json found. Run /workflow:session:start to initialize.

 ```bash
 # Read archived IMPL_PLAN.md
-bash(cat .workflow/.archives/WFS-session-name/IMPL_PLAN.md | head -20)
+bash(cat .workflow/archives/WFS-session-name/IMPL_PLAN.md | head -20)
 ```

 **Data Processing** (No agent needed):
@@ -192,7 +187,7 @@ const newFeature = {
  },
  traceability: {
    session_id: sessionId,
-    archive_path: archivePath, // e.g., ".workflow/.archives/WFS-auth-system"
+    archive_path: archivePath, // e.g., ".workflow/archives/WFS-auth-system"
    commit_hash: getLatestCommitHash() || "" // Optional: git rev-parse HEAD
  },
  docs: [],      // Placeholder for future doc links
--- a/.claude/commands/workflow/session/start.md
+++ b/.claude/commands/workflow/session/start.md
@@ -49,19 +49,14 @@ SlashCommand({command: "/workflow:init"});
 /workflow:session:start
 ```

-### Step 1: Check Active Sessions
+### Step 1: List Active Sessions
 ```bash
-bash(ls .workflow/.active-* 2>/dev/null)
+bash(ls -1 .workflow/sessions/ 2>/dev/null | head -5)
 ```

-### Step 2: List All Sessions
+### Step 2: Display Session Metadata
 ```bash
-bash(ls -1 .workflow/WFS-* 2>/dev/null | head -5)
-```
-
-### Step 3: Display Session Metadata
-```bash
-bash(cat .workflow/WFS-promptmaster-platform/workflow-session.json)
+bash(cat .workflow/sessions/WFS-promptmaster-platform/workflow-session.json)
 ```

 ### Step 4: User Decision
@@ -78,7 +73,7 @@ Present session information and wait for user to select or create session.

 ### Step 1: Check Active Sessions Count
 ```bash
-bash(ls .workflow/.active-* 2>/dev/null | wc -l)
+bash(find .workflow/sessions/ -name "WFS-*" -type d 2>/dev/null | wc -l)
 ```

 ### Step 2a: No Active Sessions → Create New
@@ -87,15 +82,12 @@ bash(ls .workflow/.active-* 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/WFS-implement-oauth2-auth/.process)
-bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.task)
-bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.summaries)
+bash(mkdir -p .workflow/sessions/WFS-implement-oauth2-auth/.process)
+bash(mkdir -p .workflow/sessions/WFS-implement-oauth2-auth/.task)
+bash(mkdir -p .workflow/sessions/WFS-implement-oauth2-auth/.summaries)

 # Create metadata
-bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning"}' > .workflow/WFS-implement-oauth2-auth/workflow-session.json)
-
-# Mark as active
-bash(touch .workflow/.active-WFS-implement-oauth2-auth)
+bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning"}' > .workflow/sessions/WFS-implement-oauth2-auth/workflow-session.json)
 ```

 **Output**: `SESSION_ID: WFS-implement-oauth2-auth`
@@ -103,10 +95,10 @@ bash(touch .workflow/.active-WFS-implement-oauth2-auth)
 ### Step 2b: Single Active Session → Check Relevance
 ```bash
 # Extract session ID
-bash(ls .workflow/.active-* 2>/dev/null | head -1 | xargs basename | sed 's/^\.active-//')
+bash(find .workflow/sessions/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)

 # Read project name from metadata
-bash(cat .workflow/WFS-promptmaster-platform/workflow-session.json | grep -o '"project":"[^"]*"' | cut -d'"' -f4)
+bash(cat .workflow/sessions/WFS-promptmaster-platform/workflow-session.json | grep -o '"project":"[^"]*"' | cut -d'"' -f4)

 # Check keyword match (manual comparison)
 # If task contains project keywords → Reuse session
@@ -119,7 +111,7 @@ bash(cat .workflow/WFS-promptmaster-platform/workflow-session.json | grep -o '"p
 ### Step 2c: Multiple Active Sessions → Use First
 ```bash
 # Get first active session
-bash(ls .workflow/.active-* 2>/dev/null | head -1 | xargs basename | sed 's/^\.active-//')
+bash(find .workflow/sessions/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)

 # Output warning and session ID
 # WARNING: Multiple active sessions detected
@@ -139,25 +131,19 @@ bash(ls .workflow/.active-* 2>/dev/null | head -1 | xargs basename | sed 's/^\.a
 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/WFS-fix-login-bug 2>/dev/null && echo "WFS-fix-login-bug-2" || echo "WFS-fix-login-bug")
+bash(ls .workflow/sessions/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/WFS-fix-login-bug/.process)
-bash(mkdir -p .workflow/WFS-fix-login-bug/.task)
-bash(mkdir -p .workflow/WFS-fix-login-bug/.summaries)
+bash(mkdir -p .workflow/sessions/WFS-fix-login-bug/.process)
+bash(mkdir -p .workflow/sessions/WFS-fix-login-bug/.task)
+bash(mkdir -p .workflow/sessions/WFS-fix-login-bug/.summaries)
 ```

 ### Step 3: Create Metadata
 ```bash
-bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning"}' > .workflow/WFS-fix-login-bug/workflow-session.json)
-```
-
-### Step 4: Mark Active and Clean Old Markers
-```bash
-bash(rm .workflow/.active-* 2>/dev/null)
-bash(touch .workflow/.active-WFS-fix-login-bug)
+bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning"}' > .workflow/sessions/WFS-fix-login-bug/workflow-session.json)
 ```

 **Output**: `SESSION_ID: WFS-fix-login-bug`
--- a/.claude/commands/workflow/status.md
+++ b/.claude/commands/workflow/status.md
@@ -108,7 +108,7 @@ ${sortedFeatures.map(f => `

 ### Quick Access
 - View session details: /workflow:status
- Archive query: jq '.archives[] | select(.session_id == "SESSION_ID")' .workflow/.archives/manifest.json
+- Archive query: jq '.archives[] | select(.session_id == "SESSION_ID")' .workflow/archives/manifest.json
 - Documentation: .workflow/docs/${projectData.project_name}/

 ### Query Commands
@@ -139,7 +139,7 @@ Complete your first workflow session to add features:

 ```bash
 # List 5 most recent archived sessions
-bash(ls -1t .workflow/.archives/WFS-* 2>/dev/null | head -5 | xargs -I {} basename {})
+bash(ls -1t .workflow/archives/WFS-* 2>/dev/null | head -5 | xargs -I {} basename {})
 ```

 **Output**:
@@ -156,28 +156,28 @@ Use /workflow:session:complete to archive current session.

 ### Step 1: Find Active Session
 ```bash
-find .workflow/ -name ".active-*" -type f 2>/dev/null | head -1
+find .workflow/sessions/ -name "WFS-*" -type d 2>/dev/null | head -1
 ```

 ### Step 2: Load Session Data
 ```bash
-cat .workflow/WFS-session/workflow-session.json
+cat .workflow/sessions/WFS-session/workflow-session.json
 ```

 ### Step 3: Scan Task Files
 ```bash
-find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null
+find .workflow/sessions/WFS-session/.task/ -name "*.json" -type f 2>/dev/null
 ```

 ### Step 4: Generate Task Status
 ```bash
-cat .workflow/WFS-session/.task/impl-1.json | jq -r '.status'
+cat .workflow/sessions/WFS-session/.task/impl-1.json | jq -r '.status'
 ```

 ### Step 5: Count Task Progress
 ```bash
-find .workflow/WFS-session/.task/ -name "*.json" -type f | wc -l
-find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
+find .workflow/sessions/WFS-session/.task/ -name "*.json" -type f | wc -l
+find .workflow/sessions/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 ```

 ### Step 6: Display Overview