catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-10 02:24:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor(workflow): migrate to sessions/ subdirectory structure

Browse Source 
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>
This commit is contained in:
catlog22
2025-11-18 11:34:52 +08:00
parent 2aacc34c24
commit d9fcdad949
4 changed files with 54 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
.claude/commands/workflow/execute.md
View File

@@ -55,7 +55,7 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
**Applies to**: Normal mode only (skipped in resume mode) **Applies to**: Normal mode only (skipped in resume mode)
**Process**: **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 2. **Select Session**: If multiple found, prompt user selection
3. **Load Session Metadata**: Read `workflow-session.json` ONLY (minimal context) 3. **Load Session Metadata**: Read `workflow-session.json` ONLY (minimal context)
4. **DO NOT read task JSONs yet** - defer until execution phase 4. **DO NOT read task JSONs yet** - defer until execution phase
@@ -322,11 +322,11 @@ TodoWrite({
} }
}, },
"session": { "session": {
"workflow_dir": ".workflow/WFS-session/", "workflow_dir": ".workflow/sessions/WFS-session/",
"context_package_path": ".workflow/WFS-session/.process/context-package.json", "context_package_path": ".workflow/sessions/WFS-session/.process/context-package.json",
"todo_list_path": ".workflow/WFS-session/TODO_LIST.md", "todo_list_path": ".workflow/sessions/WFS-session/TODO_LIST.md",
"summaries_dir": ".workflow/WFS-session/.summaries/", "summaries_dir": ".workflow/sessions/WFS-session/.summaries/",
"task_json_path": ".workflow/WFS-session/.task/IMPL-1.1.json" "task_json_path": ".workflow/sessions/WFS-session/.task/IMPL-1.1.json"
}, },
"dependencies": [ /* Task summaries from depends_on */ ], "dependencies": [ /* Task summaries from depends_on */ ],
"inherited": { /* Parent task context */ } "inherited": { /* Parent task context */ }
@@ -452,7 +452,7 @@ Task(subagent_type="{meta.agent}",
"step": "load_synthesis_specification", "step": "load_synthesis_specification",
"action": "Load synthesis specification from context-package.json", "action": "Load synthesis specification from context-package.json",
"commands": [ "commands": [
"Read(.workflow/WFS-[session]/.process/context-package.json)", "Read(.workflow/sessions/WFS-[session]/.process/context-package.json)",
"Extract(brainstorm_artifacts.synthesis_output.path)", "Extract(brainstorm_artifacts.synthesis_output.path)",
"Read(extracted path)" "Read(extracted path)"
], ],
@@ -514,7 +514,7 @@ meta.agent missing → Infer from meta.type:
## Workflow File Structure Reference ## Workflow File Structure Reference
``` ```
.workflow/WFS-[topic-slug]/ .workflow/sessions/WFS-[topic-slug]/
├── workflow-session.json # Session state and metadata ├── workflow-session.json # Session state and metadata
├── IMPL_PLAN.md # Planning document and requirements ├── IMPL_PLAN.md # Planning document and requirements
├── TODO_LIST.md # Progress tracking (auto-updated) ├── 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 | | Error Type | Cause | Recovery Strategy | Max Attempts |
|-----------|-------|------------------|--------------| |-----------|-------|------------------|--------------|
| **Discovery Errors** | | **Discovery Errors** |
| No active session | No `.active-*` markers found | Create or resume session: `/workflow:plan "project"` | N/A | | No active session | No sessions in `.workflow/sessions/` | Create or resume session: `/workflow:plan "project"` | N/A |
| Multiple sessions | Multiple `.active-*` markers | Prompt user selection | 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 | | Corrupted session | Invalid JSON files | Recreate session structure or validate files | N/A |
| **Execution Errors** | | **Execution Errors** |
| Agent failure | Agent crash/timeout | Retry with simplified context | 2 | | Agent failure | Agent crash/timeout | Retry with simplified context | 2 |
@@ -557,26 +557,23 @@ meta.agent missing → Infer from meta.type:
**Session Recovery**: **Session Recovery**:
```bash ```bash
# Check session integrity # Check session integrity
find .workflow -name ".active-*" | while read marker; do find .workflow/sessions/ -name "WFS-*" -type d | while read session_dir; do
session=$(basename "$marker" | sed 's/^\.active-//') session=$(basename "$session_dir")
[ ! -d ".workflow/$session" ] && rm "$marker" [ ! -f "$session_dir/workflow-session.json" ] && \
echo '{"session_id":"'$session'","status":"active"}' > "$session_dir/workflow-session.json"
done done
# Recreate corrupted session files
[ ! -f ".workflow/$session/workflow-session.json" ] && \
echo '{"session_id":"'$session'","status":"active"}' > ".workflow/$session/workflow-session.json"
``` ```
**Task Recovery**: **Task Recovery**:
```bash ```bash
# Validate task JSON integrity # 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" jq empty "$task_file" 2>/dev/null || echo "Corrupted: $task_file"
done done
# Fix missing dependencies # 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 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 done
``` ```

29
.claude/commands/workflow/session/complete.md
View File

@@ -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 #### Step 1.1: Find Active Session and Get Name
```bash ```bash
# Find active marker # Find active session directory
bash(find .workflow/ -name ".active-*" -type f | head -1) bash(find .workflow/sessions/ -name "WFS-*" -type d | head -1)
# Extract session name from marker path # Extract session name from directory path
bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//') bash(basename .workflow/sessions/WFS-session-name)
``` ```
**Output**: Session name `WFS-session-name` **Output**: Session name `WFS-session-name`
#### Step 1.2: Move Session to Archive #### Step 1.2: Move Session to Archive
```bash ```bash
# Create archive directory if needed # Create archive directory if needed
bash(mkdir -p .workflow/.archives/) bash(mkdir -p .workflow/archives/)
# Move session to archive location # 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) ### Phase 2: Agent-Orchestrated Completion (All Data Processing)
@@ -60,8 +60,7 @@ Task(
Complete workflow session archival. Session already moved to archive location. Complete workflow session archival. Session already moved to archive location.
## Context ## Context
- Session: .workflow/.archives/WFS-session-name/ - Session: .workflow/archives/WFS-session-name/
- Active marker: .workflow/.active-WFS-session-name
## Tasks ## Tasks
@@ -77,15 +76,12 @@ Complete workflow session archival. Session already moved to archive location.
- Calculate: duration_hours, success_rate, tags (3-5 keywords) - Calculate: duration_hours, success_rate, tags (3-5 keywords)
- Construct complete JSON with session_id, description, archived_at, archive_path, metrics, tags, lessons - 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** 6. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}
7. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}
## Error Handling ## Error Handling
- On failure: return {"status": "error", "task": "...", "message": "..."} - 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 - Generate lessons learned analysis
- Build complete archive metadata - Build complete archive metadata
- Update manifest - Update manifest
- Remove active marker
- Return success/error result - Return success/error result
### Phase 3: Update Project Feature Registry ### Phase 3: Update Project Feature Registry
@@ -134,7 +129,7 @@ WARNING: No project.json found. Run /workflow:session:start to initialize.
```bash ```bash
# Read archived IMPL_PLAN.md # 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): **Data Processing** (No agent needed):
@@ -192,7 +187,7 @@ const newFeature = {
}, },
traceability: { traceability: {
session_id: sessionId, 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 commit_hash: getLatestCommitHash() || "" // Optional: git rev-parse HEAD
}, },
docs: [], // Placeholder for future doc links docs: [], // Placeholder for future doc links

48
.claude/commands/workflow/session/start.md
View File

@@ -49,19 +49,14 @@ SlashCommand({command: "/workflow:init"});
/workflow:session:start /workflow:session:start
``` ```
### Step 1: Check Active Sessions ### Step 1: List Active Sessions
```bash ```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
bash(ls -1 .workflow/WFS-* 2>/dev/null | head -5) bash(cat .workflow/sessions/WFS-promptmaster-platform/workflow-session.json)
```
### Step 3: Display Session Metadata
```bash
bash(cat .workflow/WFS-promptmaster-platform/workflow-session.json)
``` ```
### Step 4: User Decision ### 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 ### Step 1: Check Active Sessions Count
```bash ```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 ### 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) bash(echo "implement OAuth2 auth" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
# Create directory structure # Create directory structure
bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.process) bash(mkdir -p .workflow/sessions/WFS-implement-oauth2-auth/.process)
bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.task) bash(mkdir -p .workflow/sessions/WFS-implement-oauth2-auth/.task)
bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.summaries) bash(mkdir -p .workflow/sessions/WFS-implement-oauth2-auth/.summaries)
# Create metadata # Create metadata
bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning"}' > .workflow/WFS-implement-oauth2-auth/workflow-session.json) bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning"}' > .workflow/sessions/WFS-implement-oauth2-auth/workflow-session.json)
# Mark as active
bash(touch .workflow/.active-WFS-implement-oauth2-auth)
``` ```
**Output**: `SESSION_ID: WFS-implement-oauth2-auth` **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 ### Step 2b: Single Active Session → Check Relevance
```bash ```bash
# Extract session ID # 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 # 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) # Check keyword match (manual comparison)
# If task contains project keywords → Reuse session # 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 ### Step 2c: Multiple Active Sessions → Use First
```bash ```bash
# Get first active session # 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 # Output warning and session ID
# WARNING: Multiple active sessions detected # 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) 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 # 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 ### Step 2: Create Session Structure
```bash ```bash
bash(mkdir -p .workflow/WFS-fix-login-bug/.process) bash(mkdir -p .workflow/sessions/WFS-fix-login-bug/.process)
bash(mkdir -p .workflow/WFS-fix-login-bug/.task) bash(mkdir -p .workflow/sessions/WFS-fix-login-bug/.task)
bash(mkdir -p .workflow/WFS-fix-login-bug/.summaries) bash(mkdir -p .workflow/sessions/WFS-fix-login-bug/.summaries)
``` ```
### Step 3: Create Metadata ### Step 3: Create Metadata
```bash ```bash
bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning"}' > .workflow/WFS-fix-login-bug/workflow-session.json) bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning"}' > .workflow/sessions/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)
``` ```
**Output**: `SESSION_ID: WFS-fix-login-bug` **Output**: `SESSION_ID: WFS-fix-login-bug`

16
.claude/commands/workflow/status.md
View File

@@ -108,7 +108,7 @@ ${sortedFeatures.map(f => `
### Quick Access ### Quick Access
- View session details: /workflow:status - 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}/ - Documentation: .workflow/docs/${projectData.project_name}/
### Query Commands ### Query Commands
@@ -139,7 +139,7 @@ Complete your first workflow session to add features:
```bash ```bash
# List 5 most recent archived sessions # 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**: **Output**:
@@ -156,28 +156,28 @@ Use /workflow:session:complete to archive current session.
### Step 1: Find Active Session ### Step 1: Find Active Session
```bash ```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 ### Step 2: Load Session Data
```bash ```bash
cat .workflow/WFS-session/workflow-session.json cat .workflow/sessions/WFS-session/workflow-session.json
``` ```
### Step 3: Scan Task Files ### Step 3: Scan Task Files
```bash ```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 ### Step 4: Generate Task Status
```bash ```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 ### Step 5: Count Task Progress
```bash ```bash
find .workflow/WFS-session/.task/ -name "*.json" -type f | wc -l find .workflow/sessions/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/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
``` ```
### Step 6: Display Overview ### Step 6: Display Overview