catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-28 20:01:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor(workflow): remove all .active marker file references and sync documentation

Browse Source 
Core Changes (10 files):
- commands: cli/execute.md, memory/docs.md, workflow/review.md, workflow/brainstorm/*.md
- agents: cli-execution-agent.md
- workflows: task-core.md, workflow-architecture.md

Transformations:
- Removed all .active-* marker file operations (touch/rm/find)
- Updated session discovery to directory-based (.workflow/sessions/)
- Updated directory structure examples to show sessions/ subdirectory
- Replaced marker-based state with location-based state

Reference Documentation (57 files):
- Auto-synced via analyze_commands.py script
- Includes all core file changes
- Updated command indexes (all-commands.json, by-category.json, etc.)

Migration complete: 100% .active marker references removed
Session state now determined by directory location only
This commit is contained in:
catlog22
2025-11-19 20:24:14 +08:00
parent bc5ddb3670
commit 487b359266
71 changed files with 3742 additions and 4069 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude/skills/command-guide/reference/commands/workflow/action-plan-verify.md
View File

@@ -32,7 +32,7 @@ Identify inconsistencies, duplications, ambiguities, and underspecified items be
IF --session parameter provided:
session_id = provided session
ELSE:
CHECK: .workflow/.active-* marker files
CHECK: find .workflow/sessions/ -name "WFS-*" -type d
IF active_session EXISTS:
session_id = get_active_session()
ELSE:
@@ -40,7 +40,7 @@ ELSE:
EXIT
# Derive absolute paths
session_dir = .workflow/WFS-{session}
session_dir = .workflow/sessions/WFS-{session}
brainstorm_dir = session_dir/.brainstorming
task_dir = session_dir/.task
@@ -333,7 +333,7 @@ Output a Markdown report (no file writes) with the following structure:
#### TodoWrite-Based Remediation Workflow
**Report Location**: `.workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md`
**Report Location**: `.workflow/sessions/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md`
**Recommended Workflow**:
1. **Create TodoWrite Task List**: Extract all findings from report
@@ -361,7 +361,7 @@ Priority Order:
**Save Analysis Report**:
```bash
report_path = ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
report_path = ".workflow/sessions/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
Write(report_path, full_report_content)
```
@@ -404,12 +404,12 @@ TodoWrite([
**File Modification Workflow**:
```bash
# For task JSON modifications:
1. Read(.workflow/WFS-{session}/.task/IMPL-X.Y.json)
1. Read(.workflow/sessions/WFS-{session}/.task/IMPL-X.Y.json)
2. Edit() to apply fixes
3. Mark todo as completed
# For IMPL_PLAN modifications:
1. Read(.workflow/WFS-{session}/IMPL_PLAN.md)
1. Read(.workflow/sessions/WFS-{session}/IMPL_PLAN.md)
2. Edit() to apply strategic changes
3. Mark todo as completed
```

12
.claude/skills/command-guide/reference/commands/workflow/brainstorm/api-designer.md
View File

@@ -46,10 +46,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
CHECK: find .workflow/sessions/ -name "WFS-*" -type d
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
brainstorm_dir = .workflow/sessions/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
@@ -162,7 +162,7 @@ IF update_mode = "incremental":
### Output Files
```
.workflow/WFS-[topic]/.brainstorming/
.workflow/sessions/WFS-[topic]/.brainstorming/
├── guidance-specification.md # Input: Framework (if exists)
└── api-designer/
└── analysis.md # ★ OUTPUT: Framework-based analysis
@@ -181,7 +181,7 @@ IF update_mode = "incremental":
Session detection and selection:
```bash
# Check for active sessions
active_sessions=$(find .workflow -name ".active-*" 2>/dev/null)
active_sessions=$(find .workflow/sessions/ -name "WFS-*" -type d 2>/dev/null)
if [ multiple_sessions ]; then
prompt_user_to_select_session()
else
@@ -280,7 +280,7 @@ TodoWrite tracking for two-step process:
### Output Location
```
.workflow/WFS-{topic-slug}/.brainstorming/api-designer/
.workflow/sessions/WFS-{topic-slug}/.brainstorming/api-designer/
├── analysis.md # Primary API design analysis
├── api-specification.md # Detailed endpoint specifications (OpenAPI/Swagger)
├── data-contracts.md # Request/response schemas and validation rules
@@ -531,7 +531,7 @@ Upon completion, update `workflow-session.json`:
"api_designer": {
"status": "completed",
"completed_at": "timestamp",
"output_directory": ".workflow/WFS-{topic}/.brainstorming/api-designer/",
"output_directory": ".workflow/sessions/WFS-{topic}/.brainstorming/api-designer/",
"key_insights": ["endpoint_design", "versioning_strategy", "data_contracts"]
}
}

15
.claude/skills/command-guide/reference/commands/workflow/brainstorm/artifacts.md
View File

@@ -10,7 +10,7 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
Six-phase workflow: **Automatic project context collection** → Extract topic challenges → Select roles → Generate task-specific questions → Detect conflicts → Generate confirmed guidance (declarative statements only).
**Input**: `"GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]`
**Output**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (CONFIRMED/SELECTED format)
**Output**: `.workflow/sessions/WFS-{topic}/.brainstorming/guidance-specification.md` (CONFIRMED/SELECTED format)
**Core Principle**: Questions dynamically generated from project context + topic keywords/challenges, NOT from generic templates
**Parameters**:
@@ -32,7 +32,7 @@ Six-phase workflow: **Automatic project context collection** → Extract topic c
**Standalone Mode**:
```json
[
{"content": "Initialize session (.workflow/.active-* check, parse --count parameter)", "status": "pending", "activeForm": "Initializing"},
{"content": "Initialize session (.workflow/sessions/ session check, parse --count parameter)", "status": "pending", "activeForm": "Initializing"},
{"content": "Phase 0: Automatic project context collection (call context-gather)", "status": "pending", "activeForm": "Phase 0 context collection"},
{"content": "Phase 1: Extract challenges, output 2-4 task-specific questions, wait for user input", "status": "pending", "activeForm": "Phase 1 topic analysis"},
{"content": "Phase 2: Recommend count+2 roles, output role selection, wait for user input", "status": "pending", "activeForm": "Phase 2 role selection"},
@@ -133,7 +133,7 @@ b) {role-name} ({中文名})
## Execution Phases
### Session Management
- Check `.workflow/.active-*` markers first
- Check `.workflow/sessions/` for existing sessions
- Multiple sessions → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]`
- Parse `--count N` parameter from user input (default: 3 if not specified)
- Store decisions in `workflow-session.json` including count parameter
@@ -145,7 +145,7 @@ b) {role-name} ({中文名})
**Detection Mechanism** (execute first):
```javascript
// Check if context-package already exists
const contextPackagePath = `.workflow/WFS-{session-id}/.process/context-package.json`;
const contextPackagePath = `.workflow/sessions/WFS-{session-id}/.process/context-package.json`;
if (file_exists(contextPackagePath)) {
// Validate package
@@ -229,7 +229,7 @@ Report completion with statistics.
**Steps**:
1. **Load Phase 0 context** (if available):
- Read `.workflow/WFS-{session-id}/.process/context-package.json`
- Read `.workflow/sessions/WFS-{session-id}/.process/context-package.json`
- Extract: tech_stack, existing modules, conflict_risk, relevant files
2. **Deep topic analysis** (context-aware):
@@ -449,7 +449,7 @@ FOR each selected role:
## Output Document Template
**File**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md`
**File**: `.workflow/sessions/WFS-{topic}/.brainstorming/guidance-specification.md`
```markdown
# [Project] - Confirmed Guidance Specification
@@ -596,8 +596,7 @@ ELSE:
## File Structure
```
.workflow/WFS-[topic]/
├── .active-brainstorming
.workflow/sessions/WFS-[topic]/
├── workflow-session.json # Session metadata ONLY
└── .brainstorming/
└── guidance-specification.md # Full guidance content

37
.claude/skills/command-guide/reference/commands/workflow/brainstorm/auto-parallel.md
View File

@@ -85,7 +85,7 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
**Validation**:
- guidance-specification.md created with confirmed decisions
- workflow-session.json contains selected_roles[] (metadata only, no content duplication)
- Session directory `.workflow/WFS-{topic}/.brainstorming/` exists
- Session directory `.workflow/sessions/WFS-{topic}/.brainstorming/` exists
**TodoWrite Update (Phase 1 SlashCommand invoked - tasks attached)**:
```json
@@ -132,13 +132,13 @@ Execute {role-name} analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: {role-name}
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/{role}/
OUTPUT_LOCATION: .workflow/sessions/WFS-{session}/.brainstorming/{role}/
TOPIC: {user-provided-topic}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Command: Read(.workflow/sessions/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -148,7 +148,7 @@ TOPIC: {user-provided-topic}
3. **load_session_metadata**
- Action: Load session metadata and original user intent
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Command: Read(.workflow/sessions/WFS-{session}/workflow-session.json)
- Output: session_context (contains original user prompt as PRIMARY reference)
4. **load_style_skill** (ONLY for ui-designer role when style_skill_package exists)
@@ -194,7 +194,7 @@ TOPIC: {user-provided-topic}
- guidance-specification.md path
**Validation**:
- Each role creates `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (primary file)
- Each role creates `.workflow/sessions/WFS-{topic}/.brainstorming/{role}/analysis.md` (primary file)
- If content is large (>800 lines), may split to `analysis-1.md`, `analysis-2.md` (max 3 files total)
- **File naming pattern**: ALL files MUST start with `analysis` prefix (use `analysis*.md` for globbing)
- **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files
@@ -245,7 +245,7 @@ TOPIC: {user-provided-topic}
**Input**: `sessionId` from Phase 1
**Validation**:
- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
- `.workflow/sessions/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
- Synthesis references all role analyses
**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
@@ -280,7 +280,7 @@ TOPIC: {user-provided-topic}
```
Brainstorming complete for session: {sessionId}
Roles analyzed: {count}
Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
Synthesis: .workflow/sessions/WFS-{topic}/.brainstorming/synthesis-specification.md
✅ Next Steps:
1. /workflow:concept-clarify --session {sessionId} # Optional refinement
@@ -392,31 +392,31 @@ CONTEXT_VARS:
## Session Management
**⚡ FIRST ACTION**: Check for `.workflow/.active-*` markers before Phase 1
**⚡ FIRST ACTION**: Check `.workflow/sessions/` for existing sessions before Phase 1
**Multiple Sessions Support**:
- Different Claude instances can have different active brainstorming sessions
- If multiple active sessions found, prompt user to select
- If single active session found, use it
- If no active session exists, create `WFS-[topic-slug]`
- Different Claude instances can have different brainstorming sessions
- If multiple sessions found, prompt user to select
- If single session found, use it
- If no session exists, create `WFS-[topic-slug]`
**Session Continuity**:
- MUST use selected active session for all phases
- MUST use selected session for all phases
- Each role's context stored in session directory
- Session isolation: Each session maintains independent state
## Output Structure
**Phase 1 Output**:
- `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package)
- `.workflow/sessions/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
- `.workflow/sessions/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package)
**Phase 2 Output**:
- `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
- `.workflow/sessions/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
- `.superdesign/design_iterations/` (ui-designer artifacts, if --style-skill provided)
**Phase 3 Output**:
- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
- `.workflow/sessions/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
**⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
**⚠️ Style References**: When --style-skill provided, workflow-session.json stores style_skill_package name, ui-designer loads from `.claude/skills/style-{package-name}/`
@@ -446,8 +446,7 @@ CONTEXT_VARS:
**File Structure**:
```
.workflow/WFS-[topic]/
├── .active-brainstorming
.workflow/sessions/WFS-[topic]/
├── workflow-session.json # Session metadata ONLY
└── .brainstorming/
├── guidance-specification.md # Framework (Phase 1)

14
.claude/skills/command-guide/reference/commands/workflow/brainstorm/data-architect.md
View File

@@ -47,10 +47,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
CHECK: find .workflow/sessions/ -name "WFS-*" -type d
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
brainstorm_dir = .workflow/sessions/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
@@ -87,13 +87,13 @@ Execute data-architect analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: data-architect
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/data-architect/
OUTPUT_LOCATION: .workflow/sessions/WFS-{session}/.brainstorming/data-architect/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Command: Read(.workflow/sessions/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -103,7 +103,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Command: Read(.workflow/sessions/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
@@ -163,7 +163,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/data-architect/
.workflow/sessions/WFS-{session}/.brainstorming/data-architect/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
@@ -208,7 +208,7 @@ TodoWrite({
"data_architect": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/data-architect/analysis.md",
"output_location": ".workflow/sessions/WFS-{session}/.brainstorming/data-architect/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}

14
.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-manager.md
View File

@@ -27,10 +27,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
CHECK: find .workflow/sessions/ -name "WFS-*" -type d
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
brainstorm_dir = .workflow/sessions/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
@@ -67,13 +67,13 @@ Execute product-manager analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: product-manager
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/product-manager/
OUTPUT_LOCATION: .workflow/sessions/WFS-{session}/.brainstorming/product-manager/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Command: Read(.workflow/sessions/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -83,7 +83,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Command: Read(.workflow/sessions/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
@@ -143,7 +143,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/product-manager/
.workflow/sessions/WFS-{session}/.brainstorming/product-manager/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
@@ -188,7 +188,7 @@ TodoWrite({
"product_manager": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/product-manager/analysis.md",
"output_location": ".workflow/sessions/WFS-{session}/.brainstorming/product-manager/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}

14
.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-owner.md
View File

@@ -27,10 +27,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
CHECK: find .workflow/sessions/ -name "WFS-*" -type d
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
brainstorm_dir = .workflow/sessions/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
@@ -67,13 +67,13 @@ Execute product-owner analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: product-owner
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/product-owner/
OUTPUT_LOCATION: .workflow/sessions/WFS-{session}/.brainstorming/product-owner/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Command: Read(.workflow/sessions/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -83,7 +83,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Command: Read(.workflow/sessions/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
@@ -143,7 +143,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/product-owner/
.workflow/sessions/WFS-{session}/.brainstorming/product-owner/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
@@ -188,7 +188,7 @@ TodoWrite({
"product_owner": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/product-owner/analysis.md",
"output_location": ".workflow/sessions/WFS-{session}/.brainstorming/product-owner/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}

14
.claude/skills/command-guide/reference/commands/workflow/brainstorm/scrum-master.md
View File

@@ -27,10 +27,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
CHECK: find .workflow/sessions/ -name "WFS-*" -type d
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
brainstorm_dir = .workflow/sessions/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
@@ -67,13 +67,13 @@ Execute scrum-master analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: scrum-master
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/scrum-master/
OUTPUT_LOCATION: .workflow/sessions/WFS-{session}/.brainstorming/scrum-master/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Command: Read(.workflow/sessions/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -83,7 +83,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Command: Read(.workflow/sessions/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
@@ -143,7 +143,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/scrum-master/
.workflow/sessions/WFS-{session}/.brainstorming/scrum-master/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
@@ -188,7 +188,7 @@ TodoWrite({
"scrum_master": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/scrum-master/analysis.md",
"output_location": ".workflow/sessions/WFS-{session}/.brainstorming/scrum-master/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}

14
.claude/skills/command-guide/reference/commands/workflow/brainstorm/subject-matter-expert.md
View File

@@ -27,10 +27,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
CHECK: find .workflow/sessions/ -name "WFS-*" -type d
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
brainstorm_dir = .workflow/sessions/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
@@ -67,13 +67,13 @@ Execute subject-matter-expert analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: subject-matter-expert
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/subject-matter-expert/
OUTPUT_LOCATION: .workflow/sessions/WFS-{session}/.brainstorming/subject-matter-expert/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Command: Read(.workflow/sessions/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -83,7 +83,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Command: Read(.workflow/sessions/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
@@ -143,7 +143,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/subject-matter-expert/
.workflow/sessions/WFS-{session}/.brainstorming/subject-matter-expert/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
@@ -188,7 +188,7 @@ TodoWrite({
"subject_matter_expert": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md",
"output_location": ".workflow/sessions/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}

8
.claude/skills/command-guide/reference/commands/workflow/brainstorm/synthesis.md
View File

@@ -48,7 +48,7 @@ Three-phase workflow to eliminate ambiguities and enhance conceptual depth in ro
### Phase 1: Discovery & Validation
1. **Detect Session**: Use `--session` parameter or `.workflow/.active-*` marker
1. **Detect Session**: Use `--session` parameter or find `.workflow/sessions/WFS-*` directories
2. **Validate Files**:
- `guidance-specification.md` (optional, warn if missing)
- `*/analysis*.md` (required, error if empty)
@@ -59,7 +59,7 @@ Three-phase workflow to eliminate ambiguities and enhance conceptual depth in ro
**Main flow prepares file paths for Agent**:
1. **Discover Analysis Files**:
- Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md)
- Glob(.workflow/sessions/WFS-{session}/.brainstorming/*/analysis*.md)
- Supports: analysis.md, analysis-1.md, analysis-2.md, analysis-3.md
- Validate: At least one file exists (error if empty)
@@ -69,7 +69,7 @@ Three-phase workflow to eliminate ambiguities and enhance conceptual depth in ro
3. **Pass to Agent** (Phase 3):
- `session_id`
- `brainstorm_dir`: .workflow/WFS-{session}/.brainstorming/
- `brainstorm_dir`: .workflow/sessions/WFS-{session}/.brainstorming/
- `role_analysis_paths`: ["product-manager/analysis.md", "system-architect/analysis-1.md", ...]
- `participating_roles`: ["product-manager", "system-architect", ...]
@@ -361,7 +361,7 @@ Updated {role2}/analysis.md with Clarifications section + enhanced content
## Output
**Location**: `.workflow/WFS-{session}/.brainstorming/[role]/analysis*.md` (in-place updates)
**Location**: `.workflow/sessions/WFS-{session}/.brainstorming/[role]/analysis*.md` (in-place updates)
**Updated Structure**:
```markdown

14
.claude/skills/command-guide/reference/commands/workflow/brainstorm/system-architect.md
View File

@@ -46,10 +46,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
CHECK: find .workflow/sessions/ -name "WFS-*" -type d
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
brainstorm_dir = .workflow/sessions/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
@@ -162,7 +162,7 @@ IF update_mode = "incremental":
### Output Files
```
.workflow/WFS-[topic]/.brainstorming/
.workflow/sessions/WFS-[topic]/.brainstorming/
├── guidance-specification.md # Input: Framework (if exists)
└── system-architect/
└── analysis.md # ★ OUTPUT: Framework-based analysis
@@ -186,8 +186,8 @@ IF update_mode = "incremental":
### ⚠️ Session Management - FIRST STEP
Session detection and selection:
```bash
# Check for active sessions
active_sessions=$(find .workflow -name ".active-*" 2>/dev/null)
# Check for existing sessions
existing_sessions=$(find .workflow/sessions/ -name "WFS-*" -type d 2>/dev/null)
if [ multiple_sessions ]; then
prompt_user_to_select_session()
else
@@ -279,7 +279,7 @@ TodoWrite tracking for two-step process:
### Output Location
```
.workflow/WFS-{topic-slug}/.brainstorming/system-architect/
.workflow/sessions/WFS-{topic-slug}/.brainstorming/system-architect/
├── analysis.md # Primary architecture analysis
├── architecture-design.md # Detailed system design and diagrams
├── technology-stack.md # Technology stack recommendations and justifications
@@ -340,7 +340,7 @@ Upon completion, update `workflow-session.json`:
"system_architect": {
"status": "completed",
"completed_at": "timestamp",
"output_directory": ".workflow/WFS-{topic}/.brainstorming/system-architect/",
"output_directory": ".workflow/sessions/WFS-{topic}/.brainstorming/system-architect/",
"key_insights": ["scalability_bottleneck", "architecture_pattern", "technology_recommendation"]
}
}

14
.claude/skills/command-guide/reference/commands/workflow/brainstorm/ui-designer.md
View File

@@ -48,10 +48,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
CHECK: find .workflow/sessions/ -name "WFS-*" -type d
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
brainstorm_dir = .workflow/sessions/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
@@ -88,13 +88,13 @@ Execute ui-designer analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: ui-designer
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/ui-designer/
OUTPUT_LOCATION: .workflow/sessions/WFS-{session}/.brainstorming/ui-designer/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Command: Read(.workflow/sessions/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -104,7 +104,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Command: Read(.workflow/sessions/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
@@ -164,7 +164,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/ui-designer/
.workflow/sessions/WFS-{session}/.brainstorming/ui-designer/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
@@ -209,7 +209,7 @@ TodoWrite({
"ui_designer": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md",
"output_location": ".workflow/sessions/WFS-{session}/.brainstorming/ui-designer/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}

14
.claude/skills/command-guide/reference/commands/workflow/brainstorm/ux-expert.md
View File

@@ -48,10 +48,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
### Phase 1: Session & Framework Detection
```bash
# Check active session and framework
CHECK: .workflow/.active-* marker files
CHECK: find .workflow/sessions/ -name "WFS-*" -type d
IF active_session EXISTS:
session_id = get_active_session()
brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
brainstorm_dir = .workflow/sessions/WFS-{session}/.brainstorming/
CHECK: brainstorm_dir/guidance-specification.md
IF EXISTS:
@@ -88,13 +88,13 @@ Execute ux-expert analysis for existing topic framework
## Context Loading
ASSIGNED_ROLE: ux-expert
OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/ux-expert/
OUTPUT_LOCATION: .workflow/sessions/WFS-{session}/.brainstorming/ux-expert/
ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
## Flow Control Steps
1. **load_topic_framework**
- Action: Load structured topic discussion framework
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
- Command: Read(.workflow/sessions/WFS-{session}/.brainstorming/guidance-specification.md)
- Output: topic_framework_content
2. **load_role_template**
@@ -104,7 +104,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
3. **load_session_metadata**
- Action: Load session metadata and existing context
- Command: Read(.workflow/WFS-{session}/workflow-session.json)
- Command: Read(.workflow/sessions/WFS-{session}/workflow-session.json)
- Output: session_context
## Analysis Requirements
@@ -164,7 +164,7 @@ TodoWrite({
### Framework-Based Analysis
```
.workflow/WFS-{session}/.brainstorming/ux-expert/
.workflow/sessions/WFS-{session}/.brainstorming/ux-expert/
└── analysis.md # Structured analysis addressing guidance-specification.md discussion points
```
@@ -209,7 +209,7 @@ TodoWrite({
"ux_expert": {
"status": "completed",
"framework_addressed": true,
"output_location": ".workflow/WFS-{session}/.brainstorming/ux-expert/analysis.md",
"output_location": ".workflow/sessions/WFS-{session}/.brainstorming/ux-expert/analysis.md",
"framework_reference": "@../guidance-specification.md"
}
}

533
.claude/skills/command-guide/reference/commands/workflow/execute.md
View File

@@ -7,7 +7,7 @@ argument-hint: "[--resume-session=\"session-id\"]"
# Workflow Execute Command
## Overview
Orchestrates autonomous workflow execution through systematic task discovery, agent coordination, and progress tracking. **Executes entire workflow without user interruption**, providing complete context to agents and ensuring proper flow control execution with comprehensive TodoWrite tracking.
Orchestrates autonomous workflow execution through systematic task discovery, agent coordination, and progress tracking. **Executes entire workflow without user interruption** (except initial session selection if multiple active sessions exist), providing complete context to agents and ensuring proper flow control execution with comprehensive TodoWrite tracking.
**Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session.
@@ -22,83 +22,72 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
| **Memory** | All tasks | 1-2 tasks | **90% less** |
| **Scalability** | 10-20 tasks | 100+ tasks | **5-10x** |
**Loading Strategy**:
- **TODO_LIST.md**: Read in Phase 2 (task metadata, status, dependencies)
- **IMPL_PLAN.md**: Read existence in Phase 2, parse execution strategy when needed
- **Task JSONs**: Complete lazy loading (read only during execution)
## Core Rules
**Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.**
**Execute all discovered pending tasks sequentially until workflow completion or blocking dependency.**
**Execute all discovered pending tasks until workflow completion or blocking dependency.**
**Auto-complete session when all tasks finished: Call `/workflow:session:complete` upon workflow completion.**
## Core Responsibilities
- **Session Discovery**: Identify and select active workflow sessions
- **Task Dependency Resolution**: Analyze task relationships and execution order
- **Execution Strategy Parsing**: Extract execution model from IMPL_PLAN.md
- **TodoWrite Progress Tracking**: Maintain real-time execution status throughout entire workflow
- **Agent Orchestration**: Coordinate specialized agents with complete context
- **Flow Control Execution**: Execute pre-analysis steps and context accumulation
- **Status Synchronization**: Update task JSON files and workflow state
- **Autonomous Completion**: Continue execution until all tasks complete or reach blocking state
- **Session Auto-Complete**: Call `/workflow:session:complete` when all workflow tasks finished
## Execution Philosophy
- **IMPL_PLAN-driven**: Follow execution strategy from IMPL_PLAN.md Section 4
- **Discovery-first**: Auto-discover existing plans and tasks
- **Status-aware**: Execute only ready tasks with resolved dependencies
- **Context-rich**: Provide complete task JSON and accumulated context to agents
- **Progress tracking**: **Continuous TodoWrite updates throughout entire workflow execution**
- **Flow control**: Sequential step execution with variable passing
- **Autonomous completion**: **Execute all tasks without user interruption until workflow complete**
## Flow Control Execution
**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
### Orchestrator Responsibility
- Pass complete task JSON to agent (including `flow_control` block)
- Provide session paths for artifact access
- Monitor agent completion
### Agent Responsibility
- Parse `flow_control.pre_analysis` array from JSON
- Execute steps sequentially with variable substitution
- Accumulate context from artifacts and dependencies
- Follow error handling per `step.on_error`
- Complete implementation using accumulated context
**Orchestrator does NOT execute flow control steps - Agent interprets and executes them from JSON.**
- **Progress tracking**: Continuous TodoWrite updates throughout entire workflow execution
- **Autonomous completion**: Execute all tasks without user interruption until workflow complete
## Execution Lifecycle
### Resume Mode Detection
**Special Flag Processing**: When `--resume-session="session-id"` is provided:
1. **Skip Discovery Phase**: Use provided session ID directly
2. **Load Specified Session**: Read session state from `.workflow/{session-id}/`
3. **Direct TodoWrite Generation**: Skip to Phase 3 (Planning) immediately
4. **Accelerated Execution**: Enter agent coordination without validation delays
### Phase 1: Discovery
**Applies to**: Normal mode only (skipped in resume mode)
### Phase 1: Discovery (Normal Mode Only)
1. **Check Active Sessions**: Find `.workflow/.active-*` markers
**Process**:
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
**Note**: In resume mode, this phase is completely skipped.
**Resume Mode**: This phase is completely skipped when `--resume-session="session-id"` flag is provided.
### Phase 2: Planning Document Analysis
**Applies to**: Normal mode only (skipped in resume mode)
### Phase 2: Planning Document Analysis (Normal Mode Only)
**Optimized to avoid reading all task JSONs upfront**
1. **Read IMPL_PLAN.md**: Understand overall strategy, task breakdown summary, dependencies
**Process**:
1. **Read IMPL_PLAN.md**: Check existence, understand overall strategy
2. **Read TODO_LIST.md**: Get current task statuses and execution progress
3. **Extract Task Metadata**: Parse task IDs, titles, and dependency relationships from TODO_LIST.md
4. **Build Execution Queue**: Determine ready tasks based on TODO_LIST.md status and dependencies
**Key Optimization**: Use IMPL_PLAN.md and TODO_LIST.md as primary sources instead of reading all task JSONs
**Key Optimization**: Use IMPL_PLAN.md (existence check only) and TODO_LIST.md as primary sources instead of reading all task JSONs
**Note**: In resume mode, this phase is also skipped as session analysis was already completed by `/workflow:status`.
**Resume Mode**: This phase is skipped when `--resume-session` flag is provided (session already known).
### Phase 3: TodoWrite Generation (Resume Mode Entry Point)
**This is where resume mode directly enters after skipping Phases 1 & 2**
### Phase 3: TodoWrite Generation
**Applies to**: Both normal and resume modes (resume mode entry point)
**Process**:
1. **Create TodoWrite List**: Generate task list from TODO_LIST.md (not from task JSONs)
- Parse TODO_LIST.md to extract all tasks with current statuses
- Identify first pending task with met dependencies
- Generate comprehensive TodoWrite covering entire workflow
2. **Mark Initial Status**: Set first ready task as `in_progress` in TodoWrite
2. **Mark Initial Status**: Set first ready task(s) as `in_progress` in TodoWrite
- **Sequential execution**: Mark ONE task as `in_progress`
- **Parallel batch**: Mark ALL tasks in current batch as `in_progress`
3. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id)
4. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
@@ -108,18 +97,22 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
- Generate TodoWrite from TODO_LIST.md state
- Proceed immediately to agent execution (Phase 4)
### Phase 4: Execution (Lazy Task Loading)
**Key Optimization**: Read task JSON **only when needed** for execution
### Phase 4: Execution Strategy Selection & Task Execution
**Applies to**: Both normal and resume modes
1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID
2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY
3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control)
4. **Pass Task with Flow Control**: Include complete task JSON with `pre_analysis` steps for agent execution
5. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
6. **Monitor Progress**: Track agent execution and handle errors without user interruption
7. **Collect Results**: Gather implementation results and outputs
8. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
9. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat from step 1
**Step 4A: Parse Execution Strategy from IMPL_PLAN.md**
Read IMPL_PLAN.md Section 4 to extract:
- **Execution Model**: Sequential | Parallel | Phased | TDD Cycles
- **Parallelization Opportunities**: Which tasks can run in parallel
- **Serialization Requirements**: Which tasks must run sequentially
- **Critical Path**: Priority execution order
If IMPL_PLAN.md lacks execution strategy, use intelligent fallback (analyze task structure).
**Step 4B: Execute Tasks with Lazy Loading**
**Key Optimization**: Read task JSON **only when needed** for execution
**Execution Loop Pattern**:
```
@@ -132,6 +125,16 @@ while (TODO_LIST.md has pending tasks) {
}
```
**Execution Process per Task**:
1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID
2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY
3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control)
4. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
5. **Monitor Progress**: Track agent execution and handle errors without user interruption
6. **Collect Results**: Gather implementation results and outputs
7. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
8. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat
**Benefits**:
- Reduces initial context loading by ~90%
- Only reads task JSON when actually executing
@@ -139,6 +142,9 @@ while (TODO_LIST.md has pending tasks) {
- Faster startup time for workflow execution
### Phase 5: Completion
**Applies to**: Both normal and resume modes
**Process**:
1. **Update Task Status**: Mark completed tasks in JSON files
2. **Generate Summary**: Create task summary in `.summaries/`
3. **Update TodoWrite**: Mark current task complete, advance to next
@@ -146,34 +152,52 @@ while (TODO_LIST.md has pending tasks) {
5. **Check Workflow Complete**: Verify all tasks are completed
6. **Auto-Complete Session**: Call `/workflow:session:complete` when all tasks finished
## Task Discovery & Queue Building
## Execution Strategy (IMPL_PLAN-Driven)
### Session Discovery Process (Normal Mode - Optimized)
```
├── Check for .active-* markers in .workflow/
├── If multiple active sessions found → Prompt user to select
├── Locate selected session's workflow folder
├── Load session metadata: workflow-session.json (minimal context)
├── Read IMPL_PLAN.md (strategy overview and task summary)
├── Read TODO_LIST.md (current task statuses and dependencies)
├── Parse TODO_LIST.md to extract task metadata (NO JSON loading)
├── Build execution queue from TODO_LIST.md
└── Generate TodoWrite from TODO_LIST.md state
```
### Strategy Priority
**Key Change**: Task JSONs are NOT loaded during discovery - they are loaded lazily during execution
**IMPL_PLAN-Driven Execution (Recommended)**:
1. **Read IMPL_PLAN.md execution strategy** (Section 4: Implementation Strategy)
2. **Follow explicit guidance**:
- Execution Model (Sequential/Parallel/Phased/TDD)
- Parallelization Opportunities (which tasks can run in parallel)
- Serialization Requirements (which tasks must run sequentially)
- Critical Path (priority execution order)
3. **Use TODO_LIST.md for status tracking** only
4. **IMPL_PLAN decides "HOW"**, execute.md implements it
### Resume Mode Process (--resume-session flag - Optimized)
```
├── Use provided session-id directly (skip discovery)
├── Validate .workflow/{session-id}/ directory exists
├── Read TODO_LIST.md for current progress
├── Parse TODO_LIST.md to extract task IDs and statuses
├── Generate TodoWrite from TODO_LIST.md (prioritize in-progress/pending tasks)
└── Enter Phase 4 (Execution) with lazy task JSON loading
```
**Intelligent Fallback (When IMPL_PLAN lacks execution details)**:
1. **Analyze task structure**:
- Check `meta.execution_group` in task JSONs
- Analyze `depends_on` relationships
- Understand task complexity and risk
2. **Apply smart defaults**:
- No dependencies + same execution_group → Parallel
- Has dependencies → Sequential (wait for deps)
- Critical/high-risk tasks → Sequential
3. **Conservative approach**: When uncertain, prefer sequential execution
**Key Change**: Completely skip IMPL_PLAN.md and task JSON loading - use TODO_LIST.md only
### Execution Models
#### 1. Sequential Execution
**When**: IMPL_PLAN specifies "Sequential" OR no clear parallelization guidance
**Pattern**: Execute tasks one by one in TODO_LIST order
**TodoWrite**: ONE task marked as `in_progress` at a time
#### 2. Parallel Execution
**When**: IMPL_PLAN specifies "Parallel" with clear parallelization opportunities
**Pattern**: Execute independent task groups concurrently
**TodoWrite**: MULTIPLE tasks (in same batch) marked as `in_progress` simultaneously
#### 3. Phased Execution
**When**: IMPL_PLAN specifies "Phased" with phase breakdown
**Pattern**: Execute tasks in phases, respect phase boundaries
**TodoWrite**: Within each phase, follow Sequential or Parallel rules
#### 4. Intelligent Fallback
**When**: IMPL_PLAN lacks execution strategy details
**Pattern**: Analyze task structure and apply smart defaults
**TodoWrite**: Follow Sequential or Parallel rules based on analysis
### Task Status Logic
```
@@ -182,155 +206,36 @@ completed → skip
blocked → skip until dependencies clear
```
## Batch Execution with Dependency Graph
### Parallel Execution Algorithm
**Core principle**: Execute independent tasks concurrently in batches based on dependency graph.
#### Algorithm Steps (Optimized with Lazy Loading)
```javascript
function executeBatchWorkflow(sessionId) {
// 1. Build dependency graph from TODO_LIST.md (NOT task JSONs)
const graph = buildDependencyGraphFromTodoList(`.workflow/${sessionId}/TODO_LIST.md`);
// 2. Process batches until graph is empty
while (!graph.isEmpty()) {
// 3. Identify current batch (tasks with in-degree = 0)
const batch = graph.getNodesWithInDegreeZero();
// 4. Load task JSONs ONLY for current batch (lazy loading)
const batchTaskJsons = batch.map(taskId =>
Read(`.workflow/${sessionId}/.task/${taskId}.json`)
);
// 5. Check for parallel execution opportunities
const parallelGroups = groupByExecutionGroup(batchTaskJsons);
// 6. Execute batch concurrently
await Promise.all(
parallelGroups.map(group => executeBatch(group))
);
// 7. Update graph: remove completed tasks and their edges
graph.removeNodes(batch);
// 8. Update TODO_LIST.md and TodoWrite to reflect completed batch
updateTodoListAfterBatch(batch);
updateTodoWriteAfterBatch(batch);
}
// 9. All tasks complete - auto-complete session
SlashCommand("/workflow:session:complete");
}
function buildDependencyGraphFromTodoList(todoListPath) {
const todoContent = Read(todoListPath);
const tasks = parseTodoListTasks(todoContent);
const graph = new DirectedGraph();
tasks.forEach(task => {
graph.addNode(task.id, { id: task.id, title: task.title, status: task.status });
task.dependencies?.forEach(depId => graph.addEdge(depId, task.id));
});
return graph;
}
function parseTodoListTasks(todoContent) {
// Parse: - [ ] **IMPL-001**: Task title → [📋](./.task/IMPL-001.json)
const taskPattern = /- \[([ x])\] \*\*([A-Z]+-\d+(?:\.\d+)?)\*\*: (.+?) →/g;
const tasks = [];
let match;
while ((match = taskPattern.exec(todoContent)) !== null) {
tasks.push({
status: match[1] === 'x' ? 'completed' : 'pending',
id: match[2],
title: match[3]
});
}
return tasks;
}
function groupByExecutionGroup(tasks) {
const groups = {};
tasks.forEach(task => {
const groupId = task.meta.execution_group || task.id;
if (!groups[groupId]) groups[groupId] = [];
groups[groupId].push(task);
});
return Object.values(groups);
}
async function executeBatch(tasks) {
// Execute all tasks in batch concurrently
return Promise.all(
tasks.map(task => executeTask(task))
);
}
```
#### Execution Group Rules
1. **Same `execution_group` ID** → Execute in parallel (independent, different contexts)
2. **No `execution_group` (null)** → Execute sequentially (has dependencies)
3. **Different `execution_group` IDs** → Execute in parallel (independent batches)
4. **Same `context_signature`** → Should have been merged (warning if not)
#### Parallel Execution Example
```
Batch 1 (no dependencies):
- IMPL-1.1 (execution_group: "parallel-auth-api") → Agent 1
- IMPL-1.2 (execution_group: "parallel-ui-comp") → Agent 2
- IMPL-1.3 (execution_group: "parallel-db-schema") → Agent 3
Wait for Batch 1 completion...
Batch 2 (depends on Batch 1):
- IMPL-2.1 (execution_group: null, depends_on: [IMPL-1.1, IMPL-1.2]) → Agent 1
Wait for Batch 2 completion...
Batch 3 (independent of Batch 2):
- IMPL-3.1 (execution_group: "parallel-tests-1") → Agent 1
- IMPL-3.2 (execution_group: "parallel-tests-2") → Agent 2
```
## TodoWrite Coordination
**Comprehensive workflow tracking** with immediate status updates throughout entire execution without user interruption:
#### TodoWrite Workflow Rules
1. **Initial Creation**: Generate TodoWrite from discovered pending tasks for entire workflow
- **Normal Mode**: Create from discovery results
- **Resume Mode**: Create from existing session state and current progress
2. **Parallel Task Support**:
- **Single-task execution**: Mark ONLY ONE task as `in_progress` at a time
- **Batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously
- **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks
3. **Immediate Updates**: Update status after each task/batch completion without user interruption
4. **Status Synchronization**: Sync with JSON task files after updates
5. **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
### TodoWrite Rules (Unified)
#### Resume Mode TodoWrite Generation
**Special behavior when `--resume-session` flag is present**:
- Load existing session progress from `.workflow/{session-id}/TODO_LIST.md`
- Identify currently in-progress or next pending task
- Generate TodoWrite starting from interruption point
- Preserve completed task history in TodoWrite display
- Focus on remaining pending tasks for execution
**Rule 1: Initial Creation**
- **Normal Mode**: Generate TodoWrite from discovered pending tasks for entire workflow
- **Resume Mode**: Generate from existing session state and current progress
#### TodoWrite Tool Usage
**Use Claude Code's built-in TodoWrite tool** to track workflow progress in real-time:
**Rule 2: In-Progress Task Count (Execution-Model-Dependent)**
- **Sequential execution**: Mark ONLY ONE task as `in_progress` at a time
- **Parallel batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously
- **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks
**Rule 3: Status Updates**
- **Immediate Updates**: Update status after each task/batch completion without user interruption
- **Status Synchronization**: Sync with JSON task files after updates
- **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
**Rule 4: Workflow Completion Check**
- When all tasks marked `completed`, auto-call `/workflow:session:complete`
### TodoWrite Tool Usage
**Example 1: Sequential Execution**
```javascript
// Example 1: Sequential execution (traditional)
TodoWrite({
todos: [
{
content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
status: "in_progress", // Single task in progress
status: "in_progress", // ONE task in progress
activeForm: "Executing IMPL-1.1: Design auth schema"
},
{
@@ -340,8 +245,10 @@ TodoWrite({
}
]
});
```
// Example 2: Batch execution (parallel tasks with execution_group)
**Example 2: Parallel Batch Execution**
```javascript
TodoWrite({
todos: [
{
@@ -366,44 +273,9 @@ TodoWrite({
}
]
});
// Example 3: After batch completion
TodoWrite({
todos: [
{
content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
status: "completed", // Batch completed
activeForm: "Executing IMPL-1.1: Build Auth API"
},
{
content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
status: "completed", // Batch completed
activeForm: "Executing IMPL-1.2: Build User UI"
},
{
content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
status: "completed", // Batch completed
activeForm: "Executing IMPL-1.3: Setup Database"
},
{
content: "Execute IMPL-2.1: Integration Tests [test-fix-agent]",
status: "in_progress", // Next batch started
activeForm: "Executing IMPL-2.1: Integration Tests"
}
]
});
```
**TodoWrite Integration Rules**:
- **Continuous Workflow Tracking**: Use TodoWrite tool throughout entire workflow execution
- **Real-time Updates**: Immediate progress tracking without user interruption
- **Single Active Task**: Only ONE task marked as `in_progress` at any time
- **Immediate Completion**: Mark tasks `completed` immediately after finishing
- **Status Sync**: Sync TodoWrite status with JSON task files after each update
- **Full Execution**: Continue TodoWrite tracking until all workflow tasks complete
- **Workflow Completion Check**: When all tasks marked `completed`, auto-call `/workflow:session:complete`
#### TODO_LIST.md Update Timing
### TODO_LIST.md Update Timing
**Single source of truth for task status** - enables lazy loading by providing task metadata without reading JSONs
- **Before Agent Launch**: Mark task as `in_progress`
@@ -411,18 +283,17 @@ TodoWrite({
- **On Error**: Keep as `in_progress`, add error note
- **Workflow Complete**: Call `/workflow:session:complete`
### 3. Agent Context Management
**Comprehensive context preparation** for autonomous agent execution:
## Agent Context Management
#### Context Sources (Priority Order)
### Context Sources (Priority Order)
1. **Complete Task JSON**: Full task definition including all fields and artifacts
2. **Artifacts Context**: Brainstorming outputs and role analysess from task.context.artifacts
2. **Artifacts Context**: Brainstorming outputs and role analyses from task.context.artifacts
3. **Flow Control Context**: Accumulated outputs from pre_analysis steps (including artifact loading)
4. **Dependency Summaries**: Previous task completion summaries
5. **Session Context**: Workflow paths and session metadata
6. **Inherited Context**: Parent task context and shared variables
#### Context Assembly Process
### Context Assembly Process
```
1. Load Task JSON → Base context (including artifacts array)
2. Load Artifacts → Synthesis specifications and brainstorming outputs
@@ -432,7 +303,7 @@ TodoWrite({
6. Combine All → Complete agent context with artifact integration
```
#### Agent Context Package Structure
### Agent Context Package Structure
```json
{
"task": { /* Complete task JSON with artifacts array */ },
@@ -451,18 +322,18 @@ 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 */ }
}
```
#### Context Validation Rules
### Context Validation Rules
- **Task JSON Complete**: All 5 fields present and valid, including artifacts array in context
- **Artifacts Available**: All artifacts loaded from context-package.json
- **Flow Control Ready**: All pre_analysis steps completed including artifact loading steps
@@ -470,10 +341,26 @@ TodoWrite({
- **Session Paths Valid**: All workflow paths exist and accessible (verified via context-package.json)
- **Agent Assignment**: Valid agent type specified in meta.agent
### 4. Agent Execution Pattern
**Structured agent invocation** with complete context and clear instructions:
## Agent Execution Pattern
#### Agent Prompt Template
### Flow Control Execution
**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
**Orchestrator Responsibility**:
- Pass complete task JSON to agent (including `flow_control` block)
- Provide session paths for artifact access
- Monitor agent completion
**Agent Responsibility**:
- Parse `flow_control.pre_analysis` array from JSON
- Execute steps sequentially with variable substitution
- Accumulate context from artifacts and dependencies
- Follow error handling per `step.on_error`
- Complete implementation using accumulated context
**Orchestrator does NOT execute flow control steps - Agent interprets and executes them from JSON.**
### Agent Prompt Template
```bash
Task(subagent_type="{meta.agent}",
prompt="**EXECUTE TASK FROM JSON**
@@ -512,7 +399,7 @@ Task(subagent_type="{meta.agent}",
description="Execute task: {task.id}")
```
#### Agent JSON Loading Specification
### Agent JSON Loading Specification
**MANDATORY AGENT PROTOCOL**: All agents must follow this exact loading sequence:
1. **JSON Loading**: First action must be `cat {session.task_json_path}`
@@ -565,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)"
],
@@ -606,7 +493,7 @@ Task(subagent_type="{meta.agent}",
}
```
#### Execution Flow
### Execution Flow
1. **Load Task JSON**: Agent reads and validates complete JSON structure
2. **Execute Flow Control**: Agent runs pre_analysis steps if present
3. **Prepare Implementation**: Agent uses implementation_approach from JSON
@@ -614,7 +501,7 @@ Task(subagent_type="{meta.agent}",
5. **Update Status**: Agent marks JSON status as completed
6. **Generate Summary**: Agent creates completion summary
#### Agent Assignment Rules
### Agent Assignment Rules
```
meta.agent specified → Use specified agent
meta.agent missing → Infer from meta.type:
@@ -625,15 +512,9 @@ meta.agent missing → Infer from meta.type:
- "docs" → @doc-generator
```
#### Error Handling During Execution
- **Agent Failure**: Retry once with adjusted context
- **Flow Control Error**: Skip optional steps, fail on critical
- **Context Missing**: Reload from JSON files and retry
- **Timeout**: Mark as blocked, continue with next task
## 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)
@@ -644,78 +525,26 @@ meta.agent missing → Infer from meta.type:
│ ├── IMPL-1-summary.md # Task completion details
│ └── IMPL-1.1-summary.md # Subtask completion details
└── .process/ # Planning artifacts
├── context-package.json # Smart context package
└── ANALYSIS_RESULTS.md # Planning analysis results
```
## Error Handling & Recovery
### Discovery Phase Errors
| Error | Cause | Resolution | Command |
|-------|-------|------------|---------|
| No active session | No `.active-*` markers found | Create or resume session | `/workflow:plan "project"` |
| Multiple sessions | Multiple `.active-*` markers | Select specific session | Manual choice prompt |
| Corrupted session | Invalid JSON files | Recreate session structure | `/workflow:session:status --validate` |
| Missing task files | Broken task references | Regenerate tasks | `/task:create` or repair |
### Common Errors & Recovery
### Execution Phase Errors
| Error | Cause | Recovery Strategy | Max Attempts |
|-------|-------|------------------|--------------|
| Error Type | Cause | Recovery Strategy | Max Attempts |
|-----------|-------|------------------|--------------|
| **Discovery Errors** |
| 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 |
| Flow control error | Command failure | Skip optional, fail critical | 1 per step |
| Context loading error | Missing dependencies | Reload from JSON, use defaults | 3 |
| JSON file corruption | File system issues | Restore from backup/recreate | 1 |
### Recovery Procedures
#### Session Recovery
```bash
# Check session integrity
find .workflow -name ".active-*" | while read marker; do
session=$(basename "$marker" | sed 's/^\.active-//')
if [ ! -d ".workflow/$session" ]; then
echo "Removing orphaned marker: $marker"
rm "$marker"
fi
done
# Recreate corrupted session files
if [ ! -f ".workflow/$session/workflow-session.json" ]; then
echo '{"session_id":"'$session'","status":"active"}' > ".workflow/$session/workflow-session.json"
fi
```
#### Task Recovery
```bash
# Validate task JSON integrity
for task_file in .workflow/$session/.task/*.json; do
if ! jq empty "$task_file" 2>/dev/null; then
echo "Corrupted task file: $task_file"
# Backup and regenerate or restore from backup
fi
done
# Fix missing dependencies
missing_deps=$(jq -r '.context.depends_on[]?' .workflow/$session/.task/*.json | sort -u)
for dep in $missing_deps; do
if [ ! -f ".workflow/$session/.task/$dep.json" ]; then
echo "Missing dependency: $dep - creating placeholder"
fi
done
```
#### Context Recovery
```bash
# Reload context from available sources
if [ -f ".workflow/$session/.process/ANALYSIS_RESULTS.md" ]; then
echo "Reloading planning context..."
fi
# Restore from documentation if available
if [ -d ".workflow/docs/" ]; then
echo "Using documentation context as fallback..."
fi
```
### Error Prevention
- **Pre-flight Checks**: Validate session integrity before execution
- **Backup Strategy**: Create task snapshots before major operations
@@ -723,16 +552,28 @@ fi
- **Dependency Validation**: Check all depends_on references exist
- **Context Verification**: Ensure all required context is available
## Usage Examples
### Recovery Procedures
### Basic Usage
**Session Recovery**:
```bash
/workflow:execute # Execute all pending tasks autonomously
/workflow:session:status # Check progress
/task:execute IMPL-1.2 # Execute specific task
# Check session integrity
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
```
### Integration
- **Planning**: `/workflow:plan` → `/workflow:execute` → `/workflow:review`
- **Recovery**: `/workflow:status --validate` → `/workflow:execute`
**Task Recovery**:
```bash
# Validate task JSON integrity
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/sessions/$session/.task/*.json | sort -u)
for dep in $missing_deps; do
[ ! -f ".workflow/sessions/$session/.task/$dep.json" ] && echo "Missing dependency: $dep"
done
```

399
.claude/skills/command-guide/reference/commands/workflow/init.md Normal file
View File

@@ -0,0 +1,399 @@
---
name: init
description: Initialize project-level state with intelligent project analysis using cli-explore-agent
argument-hint: "[--regenerate]"
examples:
- /workflow:init
- /workflow:init --regenerate
---
# Workflow Init Command (/workflow:init)
## Overview
Initializes `.workflow/project.json` with comprehensive project understanding by leveraging **cli-explore-agent** for intelligent analysis.
**Key Features**:
- **Intelligent Project Analysis**: Uses cli-explore-agent's Deep Scan mode
- **Technology Stack Detection**: Identifies languages, frameworks, build tools
- **Architecture Overview**: Discovers patterns, layers, key components
- **One-time Initialization**: Skips if project.json exists (unless --regenerate)
## Usage
```bash
/workflow:init # Initialize project state (skip if exists)
/workflow:init --regenerate # Force regeneration of project.json
```
## Implementation Flow
### Step 1: Check Existing State
```bash
# Check if project.json already exists
bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
```
**If EXISTS and no --regenerate flag**:
```
Project already initialized at .workflow/project.json
Use /workflow:init --regenerate to rebuild project analysis
Use /workflow:status --project to view current state
```
**If NOT_FOUND or --regenerate flag**: Proceed to initialization
### Step 2: Project Discovery
```bash
# Get project name and root
bash(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
# Create .workflow directory
bash(mkdir -p .workflow)
```
### Step 3: Intelligent Project Analysis
**Invoke cli-explore-agent** with Deep Scan mode for comprehensive understanding:
```javascript
Task(
subagent_type="cli-explore-agent",
description="Deep project analysis",
prompt=`
Analyze project structure and technology stack for workflow initialization.
## Analysis Objective
Perform Deep Scan analysis to build comprehensive project understanding for .workflow/project.json initialization.
## Required Analysis
### 1. Technology Stack Detection
- **Primary Languages**: Identify all programming languages with file counts
- **Frameworks**: Detect web frameworks (React, Vue, Express, Django, etc.)
- **Build Tools**: Identify build systems (npm, cargo, maven, gradle, etc.)
- **Test Frameworks**: Find testing tools (jest, pytest, go test, etc.)
### 2. Project Architecture
- **Architecture Style**: Identify patterns (MVC, microservices, monorepo, etc.)
- **Layer Structure**: Discover architectural layers (presentation, business, data)
- **Design Patterns**: Find common patterns (singleton, factory, repository, etc.)
- **Key Components**: List 5-10 core modules/components with brief descriptions
### 3. Project Metrics
- **Total Files**: Count source code files
- **Lines of Code**: Estimate total LOC
- **Module Count**: Number of top-level modules/packages
- **Complexity**: Overall complexity rating (low/medium/high)
### 4. Entry Points
- **Main Entry**: Identify primary application entry point(s)
- **CLI Commands**: Discover available commands/scripts
- **API Endpoints**: Find HTTP/REST/GraphQL endpoints (if applicable)
## Execution Mode
Use **Deep Scan** with Dual-Source Strategy:
- Phase 1: Bash structural scan (fast pattern discovery)
- Phase 2: Gemini semantic analysis (design intent, patterns)
- Phase 3: Synthesis (merge findings with attribution)
## Analysis Scope
- Root directory: ${projectRoot}
- Exclude: node_modules, dist, build, .git, vendor, __pycache__
- Focus: Source code directories (src, lib, pkg, app, etc.)
## Output Format
Return JSON structure for programmatic processing:
\`\`\`json
{
"technology_stack": {
"languages": [
{"name": "TypeScript", "file_count": 150, "primary": true},
{"name": "Python", "file_count": 30, "primary": false}
],
"frameworks": ["React", "Express", "TypeORM"],
"build_tools": ["npm", "webpack"],
"test_frameworks": ["Jest", "Supertest"]
},
"architecture": {
"style": "Layered MVC with Repository Pattern",
"layers": ["presentation", "business-logic", "data-access"],
"patterns": ["MVC", "Repository Pattern", "Dependency Injection"],
"key_components": [
{
"name": "Authentication Module",
"path": "src/auth",
"description": "JWT-based authentication with OAuth2 support",
"importance": "high"
},
{
"name": "User Management",
"path": "src/users",
"description": "User CRUD operations and profile management",
"importance": "high"
}
]
},
"metrics": {
"total_files": 180,
"lines_of_code": 15000,
"module_count": 12,
"complexity": "medium"
},
"entry_points": {
"main": "src/index.ts",
"cli_commands": ["npm start", "npm test", "npm run build"],
"api_endpoints": ["/api/auth", "/api/users", "/api/posts"]
},
"analysis_metadata": {
"timestamp": "2025-01-18T10:30:00Z",
"mode": "deep-scan",
"source": "cli-explore-agent"
}
}
\`\`\`
## Quality Requirements
- ✅ All technology stack items verified (no guessing)
- ✅ Key components include file paths for navigation
- ✅ Architecture style based on actual code patterns, not assumptions
- ✅ Metrics calculated from actual file counts/lines
- ✅ Entry points verified as executable
`
)
```
**Agent Output**: JSON structure with comprehensive project analysis
### Step 4: Build project.json from Analysis
**Data Processing**:
```javascript
// Parse agent analysis output
const analysis = JSON.parse(agentOutput);
// Build complete project.json structure
const projectMeta = {
// Basic metadata
project_name: projectName,
initialized_at: new Date().toISOString(),
// Project overview (from cli-explore-agent)
overview: {
description: generateDescription(analysis), // e.g., "TypeScript web application with React frontend"
technology_stack: analysis.technology_stack,
architecture: {
style: analysis.architecture.style,
layers: analysis.architecture.layers,
patterns: analysis.architecture.patterns
},
key_components: analysis.architecture.key_components,
entry_points: analysis.entry_points,
metrics: analysis.metrics
},
// Feature registry (initially empty, populated by complete)
features: [],
// Statistics
statistics: {
total_features: 0,
total_sessions: 0,
last_updated: new Date().toISOString()
},
// Analysis metadata
_metadata: {
initialized_by: "cli-explore-agent",
analysis_timestamp: analysis.analysis_metadata.timestamp,
analysis_mode: analysis.analysis_metadata.mode
}
};
// Helper: Generate project description
function generateDescription(analysis) {
const primaryLang = analysis.technology_stack.languages.find(l => l.primary);
const frameworks = analysis.technology_stack.frameworks.slice(0, 2).join(', ');
return `${primaryLang.name} project using ${frameworks}`;
}
// Write to .workflow/project.json
Write('.workflow/project.json', JSON.stringify(projectMeta, null, 2));
```
### Step 5: Output Summary
```
✓ Project initialized successfully
## Project Overview
Name: ${projectName}
Description: ${overview.description}
### Technology Stack
Languages: ${languages.map(l => l.name).join(', ')}
Frameworks: ${frameworks.join(', ')}
### Architecture
Style: ${architecture.style}
Components: ${key_components.length} core modules identified
### Project Metrics
Files: ${metrics.total_files}
LOC: ${metrics.lines_of_code}
Complexity: ${metrics.complexity}
## Next Steps
1. Start a workflow: /workflow:plan "feature description"
2. View project state: /workflow:status --project
3. View details: cat .workflow/project.json
---
Project state saved to: .workflow/project.json
```
## Extended project.json Schema
### Complete Structure
```json
{
"project_name": "claude_dms3",
"initialized_at": "2025-01-18T10:00:00Z",
"overview": {
"description": "TypeScript workflow automation system with AI agent orchestration",
"technology_stack": {
"languages": [
{"name": "TypeScript", "file_count": 150, "primary": true},
{"name": "Bash", "file_count": 30, "primary": false}
],
"frameworks": ["Node.js"],
"build_tools": ["npm"],
"test_frameworks": ["Jest"]
},
"architecture": {
"style": "Agent-based workflow orchestration with modular command system",
"layers": ["command-layer", "agent-orchestration", "cli-integration"],
"patterns": ["Command Pattern", "Agent Pattern", "Template Method"]
},
"key_components": [
{
"name": "Workflow Planning",
"path": ".claude/commands/workflow",
"description": "Multi-phase planning workflow with brainstorming and task generation",
"importance": "high"
},
{
"name": "Agent System",
"path": ".claude/agents",
"description": "Specialized agents for code development, testing, documentation",
"importance": "high"
},
{
"name": "CLI Tool Integration",
"path": ".claude/scripts",
"description": "Gemini, Qwen, Codex wrapper scripts for AI-powered analysis",
"importance": "medium"
}
],
"entry_points": {
"main": ".claude/commands/workflow/plan.md",
"cli_commands": ["/workflow:plan", "/workflow:execute", "/memory:docs"],
"api_endpoints": []
},
"metrics": {
"total_files": 180,
"lines_of_code": 15000,
"module_count": 12,
"complexity": "medium"
}
},
"features": [],
"statistics": {
"total_features": 0,
"total_sessions": 0,
"last_updated": "2025-01-18T10:00:00Z"
},
"_metadata": {
"initialized_by": "cli-explore-agent",
"analysis_timestamp": "2025-01-18T10:00:00Z",
"analysis_mode": "deep-scan"
}
}
```
## Regeneration Behavior
When using `--regenerate` flag:
1. **Backup existing file**:
```bash
bash(cp .workflow/project.json .workflow/project.json.backup)
```
2. **Preserve features array**:
```javascript
const existingMeta = JSON.parse(Read('.workflow/project.json'));
const preservedFeatures = existingMeta.features || [];
const preservedStats = existingMeta.statistics || {};
```
3. **Re-run cli-explore-agent analysis**
4. **Merge preserved data with new analysis**:
```javascript
const newProjectMeta = {
...analysisResults,
features: preservedFeatures, // Keep existing features
statistics: preservedStats // Keep statistics
};
```
5. **Output**:
```
✓ Project analysis regenerated
Backup saved: .workflow/project.json.backup
Updated:
- Technology stack analysis
- Architecture overview
- Key components discovery
Preserved:
- ${preservedFeatures.length} existing features
- Session statistics
```
## Error Handling
### Agent Failure
```
If cli-explore-agent fails:
1. Fall back to basic initialization
2. Use get_modules_by_depth.sh for structure
3. Create minimal project.json with placeholder overview
4. Log warning: "Project initialized with basic analysis. Run /workflow:init --regenerate for full analysis"
```
### Missing Tools
```
If Gemini CLI unavailable:
1. Agent uses Qwen fallback
2. If both fail, use bash-only analysis
3. Mark in _metadata: "analysis_mode": "bash-fallback"
```
### Invalid Project Root
```
If not in git repo and empty directory:
1. Warn user: "Empty project detected"
2. Create minimal project.json
3. Suggest: "Add code files and run /workflow:init --regenerate"
```

568
.claude/skills/command-guide/reference/commands/workflow/lite-execute.md Normal file
View File

@@ -0,0 +1,568 @@
---
name: lite-execute
description: Execute tasks based on in-memory plan, prompt description, or file content
argument-hint: "[--in-memory] [\"task description\"|file-path]"
allowed-tools: TodoWrite(*), Task(*), Bash(*)
---
# Workflow Lite-Execute Command (/workflow:lite-execute)
## Overview
Flexible task execution command supporting three input modes: in-memory plan (from lite-plan), direct prompt description, or file content. Handles execution orchestration, progress tracking, and optional code review.
**Core capabilities:**
- Multi-mode input (in-memory plan, prompt description, or file path)
- Execution orchestration (Agent or Codex) with full context
- Live progress tracking via TodoWrite at execution call level
- Optional code review with selected tool (Gemini, Agent, or custom)
- Context continuity across multiple executions
- Intelligent format detection (Enhanced Task JSON vs plain text)
## Usage
### Command Syntax
```bash
/workflow:lite-execute [FLAGS] <INPUT>
# Flags
--in-memory Use plan from memory (called by lite-plan)
# Arguments
<input> Task description string, or path to file (required)
```
## Input Modes
### Mode 1: In-Memory Plan
**Trigger**: Called by lite-plan after Phase 4 approval with `--in-memory` flag
**Input Source**: `executionContext` global variable set by lite-plan
**Content**: Complete execution context (see Data Structures section)
**Behavior**:
- Skip execution method selection (already set by lite-plan)
- Directly proceed to execution with full context
- All planning artifacts available (exploration, clarifications, plan)
### Mode 2: Prompt Description
**Trigger**: User calls with task description string
**Input**: Simple task description (e.g., "Add unit tests for auth module")
**Behavior**:
- Store prompt as `originalUserInput`
- Create simple execution plan from prompt
- AskUserQuestion: Select execution method (Agent/Codex/Auto)
- AskUserQuestion: Select code review tool (Skip/Gemini/Agent/Other)
- Proceed to execution with `originalUserInput` included
**User Interaction**:
```javascript
AskUserQuestion({
questions: [
{
question: "Select execution method:",
header: "Execution",
multiSelect: false,
options: [
{ label: "Agent", description: "@code-developer agent" },
{ label: "Codex", description: "codex CLI tool" },
{ label: "Auto", description: "Auto-select based on complexity" }
]
},
{
question: "Enable code review after execution?",
header: "Code Review",
multiSelect: false,
options: [
{ label: "Skip", description: "No review" },
{ label: "Gemini Review", description: "Gemini CLI tool" },
{ label: "Agent Review", description: "Current agent review" }
]
}
]
})
```
### Mode 3: File Content
**Trigger**: User calls with file path
**Input**: Path to file containing task description or Enhanced Task JSON
**Step 1: Read and Detect Format**
```javascript
fileContent = Read(filePath)
// Attempt JSON parsing
try {
jsonData = JSON.parse(fileContent)
// Check if Enhanced Task JSON from lite-plan
if (jsonData.meta?.workflow === "lite-plan") {
// Extract plan data
planObject = {
summary: jsonData.context.plan.summary,
approach: jsonData.context.plan.approach,
tasks: jsonData.context.plan.tasks,
estimated_time: jsonData.meta.estimated_time,
recommended_execution: jsonData.meta.recommended_execution,
complexity: jsonData.meta.complexity
}
explorationContext = jsonData.context.exploration || null
clarificationContext = jsonData.context.clarifications || null
originalUserInput = jsonData.title
isEnhancedTaskJson = true
} else {
// Valid JSON but not Enhanced Task JSON - treat as plain text
originalUserInput = fileContent
isEnhancedTaskJson = false
}
} catch {
// Not valid JSON - treat as plain text prompt
originalUserInput = fileContent
isEnhancedTaskJson = false
}
```
**Step 2: Create Execution Plan**
If `isEnhancedTaskJson === true`:
- Use extracted `planObject` directly
- Skip planning, use lite-plan's existing plan
- User still selects execution method and code review
If `isEnhancedTaskJson === false`:
- Treat file content as prompt (same behavior as Mode 2)
- Create simple execution plan from content
**Step 3: User Interaction**
- AskUserQuestion: Select execution method (Agent/Codex/Auto)
- AskUserQuestion: Select code review tool
- Proceed to execution with full context
## Execution Process
### Workflow Overview
```
Input Processing → Mode Detection
|
v
[Mode 1] --in-memory: Load executionContext → Skip selection
[Mode 2] Prompt: Create plan → User selects method + review
[Mode 3] File: Detect format → Extract plan OR treat as prompt → User selects
|
v
Execution & Progress Tracking
├─ Step 1: Initialize execution tracking
├─ Step 2: Create TodoWrite execution list
├─ Step 3: Launch execution (Agent or Codex)
├─ Step 4: Track execution progress
└─ Step 5: Code review (optional)
|
v
Execution Complete
```
## Detailed Execution Steps
### Step 1: Initialize Execution Tracking
**Operations**:
- Initialize result tracking for multi-execution scenarios
- Set up `previousExecutionResults` array for context continuity
```javascript
// Initialize result tracking
previousExecutionResults = []
```
### Step 2: Create TodoWrite Execution List
**Operations**:
- Create execution tracking from task list
- Typically single execution call for all tasks
- Split into multiple calls if task list very large (>10 tasks)
**Execution Call Creation**:
```javascript
function createExecutionCalls(tasks) {
const taskTitles = tasks.map(t => t.title || t)
// Single call for ≤10 tasks (most common)
if (tasks.length <= 10) {
return [{
method: executionMethod === "Codex" ? "Codex" : "Agent",
taskSummary: taskTitles.length <= 3
? taskTitles.join(', ')
: `${taskTitles.slice(0, 2).join(', ')}, and ${taskTitles.length - 2} more`,
tasks: tasks
}]
}
// Split into multiple calls for >10 tasks
const callSize = 5
const calls = []
for (let i = 0; i < tasks.length; i += callSize) {
const batchTasks = tasks.slice(i, i + callSize)
const batchTitles = batchTasks.map(t => t.title || t)
calls.push({
method: executionMethod === "Codex" ? "Codex" : "Agent",
taskSummary: `Tasks ${i + 1}-${Math.min(i + callSize, tasks.length)}: ${batchTitles[0]}...`,
tasks: batchTasks
})
}
return calls
}
// Create execution calls with IDs
executionCalls = createExecutionCalls(planObject.tasks).map((call, index) => ({
...call,
id: `[${call.method}-${index+1}]`
}))
// Create TodoWrite list
TodoWrite({
todos: executionCalls.map(call => ({
content: `${call.id} (${call.taskSummary})`,
status: "pending",
activeForm: `Executing ${call.id} (${call.taskSummary})`
}))
})
```
**Example Execution Lists**:
```
Single call (typical):
[ ] [Agent-1] (Create AuthService, Add JWT utilities, Implement middleware)
Few tasks:
[ ] [Codex-1] (Create AuthService, Add JWT utilities, and 3 more)
Large task sets (>10):
[ ] [Agent-1] (Tasks 1-5: Create AuthService, Add JWT utilities, ...)
[ ] [Agent-2] (Tasks 6-10: Create tests, Update docs, ...)
```
### Step 3: Launch Execution
**IMPORTANT**: CLI execution MUST run in foreground (no background execution)
**Execution Loop**:
```javascript
for (currentIndex = 0; currentIndex < executionCalls.length; currentIndex++) {
const currentCall = executionCalls[currentIndex]
// Update TodoWrite: mark current call in_progress
// Launch execution with previousExecutionResults context
// After completion: collect result, add to previousExecutionResults
// Update TodoWrite: mark current call completed
}
```
**Option A: Agent Execution**
When to use:
- `executionMethod = "Agent"`
- `executionMethod = "Auto" AND complexity = "Low"`
Agent call format:
```javascript
function formatTaskForAgent(task, index) {
return `
### Task ${index + 1}: ${task.title}
**File**: ${task.file}
**Action**: ${task.action}
**Description**: ${task.description}
**Implementation Steps**:
${task.implementation.map((step, i) => `${i + 1}. ${step}`).join('\n')}
**Reference**:
- Pattern: ${task.reference.pattern}
- Example Files: ${task.reference.files.join(', ')}
- Guidance: ${task.reference.examples}
**Acceptance Criteria**:
${task.acceptance.map((criterion, i) => `${i + 1}. ${criterion}`).join('\n')}
`
}
Task(
subagent_type="code-developer",
description="Implement planned tasks",
prompt=`
${originalUserInput ? `## Original User Request\n${originalUserInput}\n\n` : ''}
## Implementation Plan
**Summary**: ${planObject.summary}
**Approach**: ${planObject.approach}
## Task Breakdown (${planObject.tasks.length} tasks)
${planObject.tasks.map((task, i) => formatTaskForAgent(task, i)).join('\n')}
${previousExecutionResults.length > 0 ? `\n## Previous Execution Results\n${previousExecutionResults.map(result => `
[${result.executionId}] ${result.status}
Tasks: ${result.tasksSummary}
Completion: ${result.completionSummary}
Outputs: ${result.keyOutputs || 'See git diff'}
${result.notes ? `Notes: ${result.notes}` : ''}
`).join('\n---\n')}` : ''}
## Code Context
${explorationContext || "No exploration performed"}
${clarificationContext ? `\n## Clarifications\n${JSON.stringify(clarificationContext, null, 2)}` : ''}
## Instructions
- Reference original request to ensure alignment
- Review previous results to understand completed work
- Build on previous work, avoid duplication
- Test functionality as you implement
- Complete all assigned tasks
`
)
```
**Result Collection**: After completion, collect result following `executionResult` structure (see Data Structures section)
**Option B: CLI Execution (Codex)**
When to use:
- `executionMethod = "Codex"`
- `executionMethod = "Auto" AND complexity = "Medium" or "High"`
Command format:
```bash
function formatTaskForCodex(task, index) {
return `
${index + 1}. ${task.title} (${task.file})
Action: ${task.action}
What: ${task.description}
How:
${task.implementation.map((step, i) => ` ${i + 1}. ${step}`).join('\n')}
Reference: ${task.reference.pattern} (see ${task.reference.files.join(', ')})
Guidance: ${task.reference.examples}
Verify:
${task.acceptance.map((criterion, i) => ` - ${criterion}`).join('\n')}
`
}
codex --full-auto exec "
${originalUserInput ? `## Original User Request\n${originalUserInput}\n\n` : ''}
## Implementation Plan
TASK: ${planObject.summary}
APPROACH: ${planObject.approach}
### Task Breakdown (${planObject.tasks.length} tasks)
${planObject.tasks.map((task, i) => formatTaskForCodex(task, i)).join('\n')}
${previousExecutionResults.length > 0 ? `\n### Previous Execution Results\n${previousExecutionResults.map(result => `
[${result.executionId}] ${result.status}
Tasks: ${result.tasksSummary}
Status: ${result.completionSummary}
Outputs: ${result.keyOutputs || 'See git diff'}
${result.notes ? `Notes: ${result.notes}` : ''}
`).join('\n---\n')}
IMPORTANT: Review previous results. Build on completed work. Avoid duplication.
` : ''}
### Code Context from Exploration
${explorationContext ? `
Project Structure: ${explorationContext.project_structure || 'Standard structure'}
Relevant Files: ${explorationContext.relevant_files?.join(', ') || 'TBD'}
Current Patterns: ${explorationContext.patterns || 'Follow existing conventions'}
Integration Points: ${explorationContext.dependencies || 'None specified'}
Constraints: ${explorationContext.constraints || 'None'}
` : 'No prior exploration - analyze codebase as needed'}
${clarificationContext ? `\n### User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''}
## Execution Instructions
- Reference original request to ensure alignment
- Review previous results for context continuity
- Build on previous work, don't duplicate completed tasks
- Complete all assigned tasks in single execution
- Test functionality as you implement
Complexity: ${planObject.complexity}
" --skip-git-repo-check -s danger-full-access
```
**Execution with tracking**:
```javascript
// Launch CLI in foreground (NOT background)
bash_result = Bash(
command=cli_command,
timeout=600000 // 10 minutes
)
// Update TodoWrite when execution completes
```
**Result Collection**: After completion, analyze output and collect result following `executionResult` structure
### Step 4: Track Execution Progress
**Real-time TodoWrite Updates** at execution call level:
```javascript
// When call starts
TodoWrite({
todos: [
{ content: "[Agent-1] (Implement auth + Create JWT utils)", status: "in_progress", activeForm: "..." },
{ content: "[Agent-2] (Add middleware + Update routes)", status: "pending", activeForm: "..." }
]
})
// When call completes
TodoWrite({
todos: [
{ content: "[Agent-1] (Implement auth + Create JWT utils)", status: "completed", activeForm: "..." },
{ content: "[Agent-2] (Add middleware + Update routes)", status: "in_progress", activeForm: "..." }
]
})
```
**User Visibility**:
- User sees execution call progress (not individual task progress)
- Current execution highlighted as "in_progress"
- Completed executions marked with checkmark
- Each execution shows task summary for context
### Step 5: Code Review (Optional)
**Skip Condition**: Only run if `codeReviewTool ≠ "Skip"`
**Operations**:
- Agent Review: Current agent performs direct review
- Gemini Review: Execute gemini CLI with review prompt
- Custom tool: Execute specified CLI tool (qwen, codex, etc.)
**Command Formats**:
```bash
# Agent Review: Direct agent review (no CLI)
# Uses analysis prompt and TodoWrite tools directly
# Gemini Review:
gemini -p "
PURPOSE: Code review for implemented changes
TASK: • Analyze quality • Identify issues • Suggest improvements
MODE: analysis
CONTEXT: @**/* | Memory: Review lite-execute changes
EXPECTED: Quality assessment with recommendations
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes | analysis=READ-ONLY
"
# Qwen Review (custom tool via "Other"):
qwen -p "
PURPOSE: Code review for implemented changes
TASK: • Analyze quality • Identify issues • Suggest improvements
MODE: analysis
CONTEXT: @**/* | Memory: Review lite-execute changes
EXPECTED: Quality assessment with recommendations
RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on recent changes | analysis=READ-ONLY
"
# Codex Review (custom tool via "Other"):
codex --full-auto exec "Review recent code changes for quality, potential issues, and improvements" --skip-git-repo-check -s danger-full-access
```
## Best Practices
### Execution Intelligence
1. **Context Continuity**: Each execution call receives previous results
- Prevents duplication across multiple executions
- Maintains coherent implementation flow
- Builds on completed work
2. **Execution Call Tracking**: Progress at call level, not task level
- Each call handles all or subset of tasks
- Clear visibility of current execution
- Simple progress updates
3. **Flexible Execution**: Multiple input modes supported
- In-memory: Seamless lite-plan integration
- Prompt: Quick standalone execution
- File: Intelligent format detection
- Enhanced Task JSON (lite-plan export): Full plan extraction
- Plain text: Uses as prompt
### Task Management
1. **Live Progress Updates**: Real-time TodoWrite tracking
- Execution calls created before execution starts
- Updated as executions progress
- Clear completion status
2. **Simple Execution**: Straightforward task handling
- All tasks in single call (typical)
- Split only for very large task sets (>10)
- Agent/Codex determines optimal execution order
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| Missing executionContext | --in-memory without context | Error: "No execution context found. Only available when called by lite-plan." |
| File not found | File path doesn't exist | Error: "File not found: {path}. Check file path." |
| Empty file | File exists but no content | Error: "File is empty: {path}. Provide task description." |
| Invalid Enhanced Task JSON | JSON missing required fields | Warning: "Missing required fields. Treating as plain text." |
| Malformed JSON | JSON parsing fails | Treat as plain text (expected for non-JSON files) |
| Execution failure | Agent/Codex crashes | Display error, save partial progress, suggest retry |
| Codex unavailable | Codex not installed | Show installation instructions, offer Agent execution |
## Data Structures
### executionContext (Input - Mode 1)
Passed from lite-plan via global variable:
```javascript
{
planObject: {
summary: string,
approach: string,
tasks: [...],
estimated_time: string,
recommended_execution: string,
complexity: string
},
explorationContext: {...} | null,
clarificationContext: {...} | null,
executionMethod: "Agent" | "Codex" | "Auto",
codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
originalUserInput: string
}
```
### executionResult (Output)
Collected after each execution call completes:
```javascript
{
executionId: string, // e.g., "[Agent-1]", "[Codex-1]"
status: "completed" | "partial" | "failed",
tasksSummary: string, // Brief description of tasks handled
completionSummary: string, // What was completed
keyOutputs: string, // Files created/modified, key changes
notes: string // Important context for next execution
}
```
Appended to `previousExecutionResults` array for context continuity in multi-execution scenarios.

1211
.claude/skills/command-guide/reference/commands/workflow/lite-plan.md
View File

File diff suppressed because it is too large Load Diff

53
.claude/skills/command-guide/reference/commands/workflow/plan.md
View File

@@ -236,35 +236,31 @@ SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]
- `.workflow/[sessionId]/.task/IMPL-*.json` exists (at least one)
- `.workflow/[sessionId]/TODO_LIST.md` exists
<!-- TodoWrite: When task-generate-agent invoked, INSERT 3 task-generate-agent tasks -->
<!-- TodoWrite: When task-generate-agent invoked, ATTACH 1 agent task -->
**TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached)**:
**TodoWrite Update (Phase 4 SlashCommand invoked - agent task attached)**:
```json
[
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
{"content": "Phase 4.1: Discovery - analyze requirements (task-generate-agent)", "status": "in_progress", "activeForm": "Analyzing requirements"},
{"content": "Phase 4.2: Planning - design tasks (task-generate-agent)", "status": "pending", "activeForm": "Designing tasks"},
{"content": "Phase 4.3: Output - generate JSONs (task-generate-agent)", "status": "pending", "activeForm": "Generating task JSONs"}
{"content": "Execute task-generate-agent", "status": "in_progress", "activeForm": "Executing task-generate-agent"}
]
```
**Note**: SlashCommand invocation **attaches** task-generate-agent's 3 tasks. Orchestrator **executes** these tasks.
**Note**: Single agent task attached. Agent autonomously completes discovery, planning, and output generation internally.
**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
<!-- TodoWrite: After agent completes, mark task as completed -->
<!-- TodoWrite: After Phase 4 tasks complete, REMOVE Phase 4.1-4.3, restore to orchestrator view -->
**TodoWrite Update (Phase 4 completed - tasks collapsed)**:
**TodoWrite Update (Phase 4 completed)**:
```json
[
{"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
{"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
{"content": "Execute task generation", "status": "completed", "activeForm": "Executing task generation"}
{"content": "Execute task-generate-agent", "status": "completed", "activeForm": "Executing task-generate-agent"}
]
```
**Note**: Phase 4 tasks completed and collapsed to summary.
**Note**: Agent task completed. No collapse needed (single task).
**Return to User**:
```
@@ -288,31 +284,35 @@ Quality Gate: Consider running /workflow:action-plan-verify to catch issues earl
1. **Task Attachment** (when SlashCommand invoked):
- Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
- Example: `/workflow:tools:context-gather` attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
- **Phase 2, 3**: Multiple sub-tasks attached (e.g., Phase 2.1, 2.2, 2.3)
- **Phase 4**: Single agent task attached (e.g., "Execute task-generate-agent")
- First attached task marked as `in_progress`, others as `pending`
- Orchestrator **executes** these attached tasks sequentially
2. **Task Collapse** (after sub-tasks complete):
- Remove detailed sub-tasks from TodoWrite
- **Applies to Phase 2, 3**: Remove detailed sub-tasks from TodoWrite
- **Collapse** to high-level phase summary
- Example: Phase 2.1-2.3 collapse to "Execute context gathering: completed"
- **Phase 4**: No collapse needed (single task, just mark completed)
- Maintains clean orchestrator-level view
3. **Continuous Execution**:
- After collapse, automatically proceed to next pending phase
- After completion, automatically proceed to next pending phase
- No user intervention required between phases
- TodoWrite dynamically reflects current execution state
**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary for Phase 2/3, or marked completed for Phase 4) → Next phase begins → Repeat until all phases complete.
### Benefits
- ✓ Real-time visibility into sub-task execution
- ✓ Clear mental model: SlashCommand = attach → execute → collapse
- ✓ Clear mental model: SlashCommand = attach → execute → collapse (Phase 2/3) or complete (Phase 4)
- ✓ Clean summary after completion
- ✓ Easy to track workflow progress
**Note**: See individual Phase descriptions (Phase 2, 3, 4) for detailed TodoWrite Update examples with full JSON structures.
**Note**: See individual Phase descriptions for detailed TodoWrite Update examples:
- **Phase 2, 3**: Multiple sub-tasks with attach/collapse pattern
- **Phase 4**: Single agent task (no collapse needed)
## Input Processing
@@ -425,20 +425,21 @@ Conditional Branch: Check conflict_risk
└─ ELSE: Skip Phase 3, proceed to Phase 4
↓
Phase 4: Task Generation (SlashCommand invoked)
→ ATTACH 3 tasks: ← ATTACHED
- Phase 4.1: Discovery - analyze requirements
- Phase 4.2: Planning - design tasks
- Phase 4.3: Output - generate JSONs
→ Execute Phase 4.1-4.3
→ COLLAPSE tasks ← COLLAPSED
→ ATTACH 1 agent task: ← ATTACHED
- Execute task-generate-agent
→ Agent autonomously completes internally:
(discovery → planning → output)
→ Outputs: IMPL_PLAN.md, IMPL-*.json, TODO_LIST.md
↓
Return summary to user
```
**Key Points**:
- **← ATTACHED**: Sub-tasks attached to TodoWrite when SlashCommand invoked
- **← COLLAPSED**: Sub-tasks collapsed to summary after completion
- **← ATTACHED**: Tasks attached to TodoWrite when SlashCommand invoked
- Phase 2, 3: Multiple sub-tasks
- Phase 4: Single agent task
- **← COLLAPSED**: Sub-tasks collapsed to summary after completion (Phase 2, 3 only)
- **Phase 4**: Single agent task, no collapse (just mark completed)
- **Conditional Branch**: Phase 3 only executes if conflict_risk ≥ medium
- **Continuous Flow**: No user intervention between phases

105
.claude/skills/command-guide/reference/commands/workflow/resume.md
View File

@@ -1,105 +0,0 @@
---
name: resume
description: Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection
argument-hint: "session-id for workflow session to resume"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
# Sequential Workflow Resume Command
## Usage
```bash
/workflow:resume "<session-id>"
```
## Purpose
**Sequential command coordination for workflow resumption** by first analyzing current session status, then continuing execution with special resume context. This command orchestrates intelligent session resumption through two-step process.
## Command Coordination Workflow
### Phase 1: Status Analysis
1. **Call status command**: Execute `/workflow:status` to analyze current session state
2. **Verify session information**: Check session ID, progress, and current task status
3. **Identify resume point**: Determine where workflow was interrupted
### Phase 2: Resume Execution
1. **Call execute with resume flag**: Execute `/workflow:execute --resume-session="{session-id}"`
2. **Pass session context**: Provide analyzed session information to execute command
3. **Direct agent execution**: Skip discovery phase, directly enter TodoWrite and agent execution
## Implementation Protocol
### Sequential Command Execution
```bash
# Phase 1: Analyze current session status
SlashCommand(command="/workflow:status")
# Phase 2: Resume execution with special flag
SlashCommand(command="/workflow:execute --resume-session=\"{session-id}\"")
```
### Progress Tracking
```javascript
TodoWrite({
todos: [
{
content: "Analyze current session status and progress",
status: "in_progress",
activeForm: "Analyzing session status"
},
{
content: "Resume workflow execution with session context",
status: "pending",
activeForm: "Resuming workflow execution"
}
]
});
```
## Resume Information Flow
### Status Analysis Results
The `/workflow:status` command provides:
- **Session ID**: Current active session identifier
- **Current Progress**: Completed, in-progress, and pending tasks
- **Interruption Point**: Last executed task and next pending task
- **Session State**: Overall workflow status
### Execute Command Context
The special `--resume-session` flag tells `/workflow:execute`:
- **Skip Discovery**: Don't search for sessions, use provided session ID
- **Direct Execution**: Go straight to TodoWrite generation and agent launching
- **Context Restoration**: Use existing session state and summaries
- **Resume Point**: Continue from identified interruption point
## Error Handling
### Session Validation Failures
- **Session not found**: Report missing session, suggest available sessions
- **Session inactive**: Recommend activating session first
- **Status command fails**: Retry once, then report analysis failure
### Execute Resumption Failures
- **No pending tasks**: Report workflow completion status
- **Execute command fails**: Report resumption failure, suggest manual intervention
## Success Criteria
1. **Status analysis complete**: Session state properly analyzed and reported
2. **Execute command launched**: Resume execution started with proper context
3. **Agent coordination**: TodoWrite and agent execution initiated successfully
4. **Context preservation**: Session state and progress properly maintained
## Related Commands
**Prerequisite Commands**:
- `/workflow:plan` or `/workflow:execute` - Workflow must be in progress or paused
**Called by This Command** (2 phases):
- `/workflow:status` - Phase 1: Analyze current session status and identify resume point
- `/workflow:execute` - Phase 2: Resume execution with `--resume-session` flag
**Follow-up Commands**:
- None - Workflow continues automatically via `/workflow:execute`
---
*Sequential command coordination for workflow session resumption*

24
.claude/skills/command-guide/reference/commands/workflow/review.md
View File

@@ -39,17 +39,17 @@ argument-hint: "[--type=security|architecture|action-items|quality] [optional: s
if [ -n "$SESSION_ARG" ]; then
sessionId="$SESSION_ARG"
else
sessionId=$(find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//')
sessionId=$(find .workflow/sessions/ -name "WFS-*" -type d | head -1 | xargs basename)
fi
# Step 2: Validation
if [ ! -d ".workflow/${sessionId}" ]; then
if [ ! -d ".workflow/sessions/${sessionId}" ]; then
echo "Session ${sessionId} not found"
exit 1
fi
# Check for completed tasks
if [ ! -d ".workflow/${sessionId}/.summaries" ] || [ -z "$(find .workflow/${sessionId}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
if [ ! -d ".workflow/sessions/${sessionId}/.summaries" ] || [ -z "$(find .workflow/sessions/${sessionId}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
echo "No completed implementation found. Complete implementation first"
exit 1
fi
@@ -80,13 +80,13 @@ After bash validation, the model takes control to:
1. **Load Context**: Read completed task summaries and changed files
```bash
# Load implementation summaries
cat .workflow/${sessionId}/.summaries/IMPL-*.md
cat .workflow/sessions/${sessionId}/.summaries/IMPL-*.md
# Load test results (if available)
cat .workflow/${sessionId}/.summaries/TEST-FIX-*.md 2>/dev/null
cat .workflow/sessions/${sessionId}/.summaries/TEST-FIX-*.md 2>/dev/null
# Get changed files
git log --since="$(cat .workflow/${sessionId}/workflow-session.json | jq -r .created_at)" --name-only --pretty=format: | sort -u
git log --since="$(cat .workflow/sessions/${sessionId}/workflow-session.json | jq -r .created_at)" --name-only --pretty=format: | sort -u
```
2. **Perform Specialized Review**: Based on `review_type`
@@ -99,7 +99,7 @@ After bash validation, the model takes control to:
```
- Use Gemini for security analysis:
```bash
cd .workflow/${sessionId} && gemini -p "
cd .workflow/sessions/${sessionId} && gemini -p "
PURPOSE: Security audit of completed implementation
TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues
CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
@@ -111,7 +111,7 @@ After bash validation, the model takes control to:
**Architecture Review** (`--type=architecture`):
- Use Qwen for architecture analysis:
```bash
cd .workflow/${sessionId} && qwen -p "
cd .workflow/sessions/${sessionId} && qwen -p "
PURPOSE: Architecture compliance review
TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions
CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
@@ -123,7 +123,7 @@ After bash validation, the model takes control to:
**Quality Review** (`--type=quality`):
- Use Gemini for code quality:
```bash
cd .workflow/${sessionId} && gemini -p "
cd .workflow/sessions/${sessionId} && gemini -p "
PURPOSE: Code quality and best practices review
TASK: Assess code readability, maintainability, adherence to best practices
CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
@@ -136,14 +136,14 @@ After bash validation, the model takes control to:
- Verify all requirements and acceptance criteria met:
```bash
# Load task requirements and acceptance criteria
find .workflow/${sessionId}/.task -name "IMPL-*.json" -exec jq -r '
find .workflow/sessions/${sessionId}/.task -name "IMPL-*.json" -exec jq -r '
"Task: " + .id + "\n" +
"Requirements: " + (.context.requirements | join(", ")) + "\n" +
"Acceptance: " + (.context.acceptance | join(", "))
' {} \;
# Check implementation summaries against requirements
cd .workflow/${sessionId} && gemini -p "
cd .workflow/sessions/${sessionId} && gemini -p "
PURPOSE: Verify all requirements and acceptance criteria are met
TASK: Cross-check implementation summaries against original requirements
CONTEXT: @.task/IMPL-*.json,.summaries/IMPL-*.md,../.. @../../CLAUDE.md
@@ -195,7 +195,7 @@ After bash validation, the model takes control to:
4. **Output Files**:
```bash
# Save review report
Write(.workflow/${sessionId}/REVIEW-${review_type}.md)
Write(.workflow/sessions/${sessionId}/REVIEW-${review_type}.md)
# Update session metadata
# (optional) Update workflow-session.json with review status

471
.claude/skills/command-guide/reference/commands/workflow/session/complete.md
View File

@@ -19,129 +19,472 @@ Mark the currently active workflow session as complete, analyze it for lessons l
## Implementation Flow
### Phase 1: Prepare for Archival (Minimal Manual Operations)
### Phase 1: Pre-Archival Preparation (Transactional Setup)
**Purpose**: Find active session, move to archive location, pass control to agent. Minimal operations.
**Purpose**: Find active session, create archiving marker to prevent concurrent operations. Session remains in active location for agent processing.
#### 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
#### Step 1.2: Check for Existing Archiving Marker (Resume Detection)
```bash
# Create archive directory if needed
bash(mkdir -p .workflow/.archives/)
# Move session to archive location
bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
# Check if session is already being archived
bash(test -f .workflow/sessions/WFS-session-name/.archiving && echo "RESUMING" || echo "NEW")
```
**Result**: Session now at `.workflow/.archives/WFS-session-name/`
### Phase 2: Agent-Orchestrated Completion (All Data Processing)
**If RESUMING**:
- Previous archival attempt was interrupted
- Skip to Phase 2 to resume agent analysis
**Purpose**: Agent analyzes archived session, generates metadata, updates manifest, and removes active marker.
**If NEW**:
- Continue to Step 1.3
#### Step 1.3: Create Archiving Marker
```bash
# Mark session as "archiving in progress"
bash(touch .workflow/sessions/WFS-session-name/.archiving)
```
**Purpose**:
- Prevents concurrent operations on this session
- Enables recovery if archival fails
- Session remains in `.workflow/sessions/` for agent analysis
**Result**: Session still at `.workflow/sessions/WFS-session-name/` with `.archiving` marker
### Phase 2: Agent Analysis (In-Place Processing)
**Purpose**: Agent analyzes session WHILE STILL IN ACTIVE LOCATION. Generates metadata but does NOT move files or update manifest.
#### Agent Invocation
Invoke `universal-executor` agent to complete the archival process.
Invoke `universal-executor` agent to analyze session and prepare archive metadata.
**Agent Task**:
```
Task(
subagent_type="universal-executor",
description="Complete session archival",
description="Analyze session for archival",
prompt=`
Complete workflow session archival. Session already moved to archive location.
Analyze workflow session for archival preparation. Session is STILL in active location.
## Context
- Session: .workflow/.archives/WFS-session-name/
- Active marker: .workflow/.active-WFS-session-name
- Session: .workflow/sessions/WFS-session-name/
- Status: Marked as archiving (.archiving marker present)
- Location: Active sessions directory (NOT archived yet)
## Tasks
1. **Extract session data** from workflow-session.json (session_id, description/topic, started_at/timestamp, completed_at, status)
1. **Extract session data** from workflow-session.json
- session_id, description/topic, started_at, completed_at, status
- If status != "completed", update it with timestamp
2. **Count files**: tasks (.task/*.json) and summaries (.summaries/*.md)
3. **Generate lessons**: Use gemini with ~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt (fallback: analyze files directly)
3. **Generate lessons**: Use gemini with ~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt
- Return: {successes, challenges, watch_patterns}
4. **Build archive entry**:
- 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, metrics, tags, lessons
- Include archive_path: ".workflow/archives/WFS-session-name" (future location)
5. **Update manifest**: Initialize .workflow/.archives/manifest.json if needed, append entry
5. **Extract feature metadata** (for Phase 4):
- Parse IMPL_PLAN.md for title (first # heading)
- Extract description (first paragraph, max 200 chars)
- Generate feature tags (3-5 keywords from content)
6. **Remove active marker**
6. **Return result**: Complete metadata package for atomic commit
{
"status": "success",
"session_id": "WFS-session-name",
"archive_entry": {
"session_id": "...",
"description": "...",
"archived_at": "...",
"archive_path": ".workflow/archives/WFS-session-name",
"metrics": {...},
"tags": [...],
"lessons": {...}
},
"feature_metadata": {
"title": "...",
"description": "...",
"tags": [...]
}
}
7. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}
## Important Constraints
- DO NOT move or delete any files
- DO NOT update manifest.json yet
- Session remains in .workflow/sessions/ during analysis
- Return complete metadata package for orchestrator to commit atomically
## Error Handling
- On failure: return {"status": "error", "task": "...", "message": "..."}
- Do NOT remove marker if failed
- Do NOT modify any files on error
`
)
```
**Expected Output**:
- Agent returns JSON result confirming successful archival
- Display completion summary to user based on agent response
- Agent returns complete metadata package
- Session remains in `.workflow/sessions/` with `.archiving` marker
- No files moved or manifests updated yet
### Phase 3: Atomic Commit (Transactional File Operations)
**Purpose**: Atomically commit all changes. Only execute if Phase 2 succeeds.
#### Step 3.1: Create Archive Directory
```bash
bash(mkdir -p .workflow/archives/)
```
#### Step 3.2: Move Session to Archive
```bash
bash(mv .workflow/sessions/WFS-session-name .workflow/archives/WFS-session-name)
```
**Result**: Session now at `.workflow/archives/WFS-session-name/`
#### Step 3.3: Update Manifest
```bash
# Read current manifest (or create empty array if not exists)
bash(test -f .workflow/archives/manifest.json && cat .workflow/archives/manifest.json || echo "[]")
```
**JSON Update Logic**:
```javascript
// Read agent result from Phase 2
const agentResult = JSON.parse(agentOutput);
const archiveEntry = agentResult.archive_entry;
// Read existing manifest
let manifest = [];
try {
const manifestContent = Read('.workflow/archives/manifest.json');
manifest = JSON.parse(manifestContent);
} catch {
manifest = []; // Initialize if not exists
}
// Append new entry
manifest.push(archiveEntry);
// Write back
Write('.workflow/archives/manifest.json', JSON.stringify(manifest, null, 2));
```
#### Step 3.4: Remove Archiving Marker
```bash
bash(rm .workflow/archives/WFS-session-name/.archiving)
```
**Result**: Clean archived session without temporary markers
**Output Confirmation**:
```
✓ Session "${sessionId}" archived successfully
Location: .workflow/archives/WFS-session-name/
Lessons: ${archiveEntry.lessons.successes.length} successes, ${archiveEntry.lessons.challenges.length} challenges
Manifest: Updated with ${manifest.length} total sessions
```
### Phase 4: Update Project Feature Registry
**Purpose**: Record completed session as a project feature in `.workflow/project.json`.
**Execution**: Uses feature metadata from Phase 2 agent result to update project registry.
#### Step 4.1: Check Project State Exists
```bash
bash(test -f .workflow/project.json && echo "EXISTS" || echo "SKIP")
```
**If SKIP**: Output warning and skip Phase 4
```
WARNING: No project.json found. Run /workflow:session:start to initialize.
```
#### Step 4.2: Extract Feature Information from Agent Result
**Data Processing** (Uses Phase 2 agent output):
```javascript
// Extract feature metadata from agent result
const agentResult = JSON.parse(agentOutput);
const featureMeta = agentResult.feature_metadata;
// Data already prepared by agent:
const title = featureMeta.title;
const description = featureMeta.description;
const tags = featureMeta.tags;
// Create feature ID (lowercase slug)
const featureId = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 50);
```
#### Step 4.3: Update project.json
```bash
# Read current project state
bash(cat .workflow/project.json)
```
**JSON Update Logic**:
```javascript
// Read existing project.json (created by /workflow:init)
// Note: overview field is managed by /workflow:init, not modified here
const projectMeta = JSON.parse(Read('.workflow/project.json'));
const currentTimestamp = new Date().toISOString();
const currentDate = currentTimestamp.split('T')[0]; // YYYY-MM-DD
// Extract tags from IMPL_PLAN.md (simple keyword extraction)
const tags = extractTags(planContent); // e.g., ["auth", "security"]
// Build feature object with complete metadata
const newFeature = {
id: featureId,
title: title,
description: description,
status: "completed",
tags: tags,
timeline: {
created_at: currentTimestamp,
implemented_at: currentDate,
updated_at: currentTimestamp
},
traceability: {
session_id: sessionId,
archive_path: archivePath, // e.g., ".workflow/archives/WFS-auth-system"
commit_hash: getLatestCommitHash() || "" // Optional: git rev-parse HEAD
},
docs: [], // Placeholder for future doc links
relations: [] // Placeholder for feature dependencies
};
// Add new feature to array
projectMeta.features.push(newFeature);
// Update statistics
projectMeta.statistics.total_features = projectMeta.features.length;
projectMeta.statistics.total_sessions += 1;
projectMeta.statistics.last_updated = currentTimestamp;
// Write back
Write('.workflow/project.json', JSON.stringify(projectMeta, null, 2));
```
**Helper Functions**:
```javascript
// Extract tags from IMPL_PLAN.md content
function extractTags(planContent) {
const tags = [];
// Look for common keywords
const keywords = {
'auth': /authentication|login|oauth|jwt/i,
'security': /security|encrypt|hash|token/i,
'api': /api|endpoint|rest|graphql/i,
'ui': /component|page|interface|frontend/i,
'database': /database|schema|migration|sql/i,
'test': /test|testing|spec|coverage/i
};
for (const [tag, pattern] of Object.entries(keywords)) {
if (pattern.test(planContent)) {
tags.push(tag);
}
}
return tags.slice(0, 5); // Max 5 tags
}
// Get latest git commit hash (optional)
function getLatestCommitHash() {
try {
const result = Bash({
command: "git rev-parse --short HEAD 2>/dev/null",
description: "Get latest commit hash"
});
return result.trim();
} catch {
return "";
}
}
```
#### Step 4.4: Output Confirmation
```
✓ Feature "${title}" added to project registry
ID: ${featureId}
Session: ${sessionId}
Location: .workflow/project.json
```
**Error Handling**:
- If project.json malformed: Output error, skip update
- If feature_metadata missing from agent result: Skip Phase 4
- If extraction fails: Use minimal defaults
**Phase 4 Total Commands**: 1 bash read + JSON manipulation
## Error Recovery
### If Agent Fails (Phase 2)
**Symptoms**:
- Agent returns `{"status": "error", ...}`
- Agent crashes or times out
- Analysis incomplete
**Recovery Steps**:
```bash
# Session still in .workflow/sessions/WFS-session-name
# Remove archiving marker
bash(rm .workflow/sessions/WFS-session-name/.archiving)
```
**User Notification**:
```
ERROR: Session archival failed during analysis phase
Reason: [error message from agent]
Session remains active in: .workflow/sessions/WFS-session-name
Recovery:
1. Fix any issues identified in error message
2. Retry: /workflow:session:complete
Session state: SAFE (no changes committed)
```
### If Move Fails (Phase 3)
**Symptoms**:
- `mv` command fails
- Permission denied
- Disk full
**Recovery Steps**:
```bash
# Archiving marker still present
# Session still in .workflow/sessions/ (move failed)
# No manifest updated yet
```
**User Notification**:
```
ERROR: Session archival failed during move operation
Reason: [mv error message]
Session remains in: .workflow/sessions/WFS-session-name
Recovery:
1. Fix filesystem issues (permissions, disk space)
2. Retry: /workflow:session:complete
- System will detect .archiving marker
- Will resume from Phase 2 (agent analysis)
Session state: SAFE (analysis complete, ready to retry move)
```
### If Manifest Update Fails (Phase 3)
**Symptoms**:
- JSON parsing error
- Write permission denied
- Session moved but manifest not updated
**Recovery Steps**:
```bash
# Session moved to .workflow/archives/WFS-session-name
# Manifest NOT updated
# Archiving marker still present in archived location
```
**User Notification**:
```
ERROR: Session archived but manifest update failed
Reason: [error message]
Session location: .workflow/archives/WFS-session-name
Recovery:
1. Fix manifest.json issues (syntax, permissions)
2. Manual manifest update:
- Add archive entry from agent output
- Remove .archiving marker: rm .workflow/archives/WFS-session-name/.archiving
Session state: PARTIALLY COMPLETE (session archived, manifest needs update)
```
## Workflow Execution Strategy
### Two-Phase Approach (Optimized)
### Transactional Four-Phase Approach
**Phase 1: Minimal Manual Setup** (2 simple operations)
**Phase 1: Pre-Archival Preparation** (Marker creation)
- Find active session and extract name
- Move session to archive location
- **No data extraction** - agent handles all data processing
- **No counting** - agent does this from archive location
- **Total**: 2 bash commands (find + move)
- Check for existing `.archiving` marker (resume detection)
- Create `.archiving` marker if new
- **No data processing** - just state tracking
- **Total**: 2-3 bash commands (find + marker check/create)
**Phase 2: Agent-Driven Completion** (1 agent invocation)
- Extract all session data from archived location
**Phase 2: Agent Analysis** (Read-only data processing)
- Extract all session data from active location
- Count tasks and summaries
- Generate lessons learned analysis
- Build complete archive metadata
- Update manifest
- Remove active marker
- Return success/error result
- Extract feature metadata from IMPL_PLAN.md
- Build complete archive + feature metadata package
- **No file modifications** - pure analysis
- **Total**: 1 agent invocation
## Quick Commands
**Phase 3: Atomic Commit** (Transactional file operations)
- Create archive directory
- Move session to archive location
- Update manifest.json with archive entry
- Remove `.archiving` marker
- **All-or-nothing**: Either all succeed or session remains in safe state
- **Total**: 4 bash commands + JSON manipulation
```bash
# Phase 1: Find and move
bash(find .workflow/ -name ".active-*" -type f | head -1)
bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
bash(mkdir -p .workflow/.archives/)
bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
**Phase 4: Project Registry Update** (Optional feature tracking)
- Check project.json exists
- Use feature metadata from Phase 2 agent result
- Build feature object with complete traceability
- Update project statistics
- **Independent**: Can fail without affecting archival
- **Total**: 1 bash read + JSON manipulation
# Phase 2: Agent completes archival
Task(subagent_type="universal-executor", description="Complete session archival", prompt=`...`)
```
### Transactional Guarantees
## Archive Query Commands
**State Consistency**:
- Session NEVER in inconsistent state
- `.archiving` marker enables safe resume
- Agent failure leaves session in recoverable state
- Move/manifest operations grouped in Phase 3
After archival, you can query the manifest:
**Failure Isolation**:
- Phase 1 failure: No changes made
- Phase 2 failure: Session still active, can retry
- Phase 3 failure: Clear error state, manual recovery documented
- Phase 4 failure: Does not affect archival success
```bash
# List all archived sessions
jq '.archives[].session_id' .workflow/.archives/manifest.json
**Resume Capability**:
- Detect interrupted archival via `.archiving` marker
- Resume from Phase 2 (skip marker creation)
- Idempotent operations (safe to retry)
# Find sessions by keyword
jq '.archives[] | select(.description | test("auth"; "i"))' .workflow/.archives/manifest.json
### Benefits Over Previous Design
# Get specific session details
jq '.archives[] | select(.session_id == "WFS-user-auth")' .workflow/.archives/manifest.json
# List all watch patterns across sessions
jq '.archives[].lessons.watch_patterns[]' .workflow/.archives/manifest.json
```
**Old Design Weakness**:
- Move first → agent second
- Agent failure → session moved but metadata incomplete
- Inconsistent state requires manual cleanup
**New Design Strengths**:
- Agent first → move second
- Agent failure → session still active, safe to retry
- Transactional commit → all-or-nothing file operations
- Marker-based state → resume capability

23
.claude/skills/command-guide/reference/commands/workflow/session/list.md
View File

@@ -19,35 +19,35 @@ Display all workflow sessions with their current status, progress, and metadata.
### Step 1: Find All Sessions
```bash
ls .workflow/WFS-* 2>/dev/null
ls .workflow/sessions/WFS-* 2>/dev/null
```
### Step 2: Check Active Session
```bash
ls .workflow/.active-* 2>/dev/null | head -1
find .workflow/sessions/ -name "WFS-*" -type d 2>/dev/null | head -1
```
### Step 3: Read Session Metadata
```bash
jq -r '.session_id, .status, .project' .workflow/WFS-session/workflow-session.json
jq -r '.session_id, .status, .project' .workflow/sessions/WFS-session/workflow-session.json
```
### Step 4: Count Task Progress
```bash
find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | 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 2>/dev/null | wc -l
find .workflow/sessions/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
```
### Step 5: Get Creation Time
```bash
jq -r '.created_at // "unknown"' .workflow/WFS-session/workflow-session.json
jq -r '.created_at // "unknown"' .workflow/sessions/WFS-session/workflow-session.json
```
## Simple Bash Commands
### Basic Operations
- **List sessions**: `find .workflow/ -maxdepth 1 -type d -name "WFS-*"`
- **Find active**: `find .workflow/ -name ".active-*" -type f`
- **List sessions**: `find .workflow/sessions/ -name "WFS-*" -type d`
- **Find active**: `find .workflow/sessions/ -name "WFS-*" -type d`
- **Read session data**: `jq -r '.session_id, .status' session.json`
- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
@@ -89,11 +89,8 @@ Total: 3 sessions (1 active, 1 paused, 1 completed)
### Quick Commands
```bash
# Count all sessions
ls .workflow/WFS-* | wc -l
# Show only active
ls .workflow/.active-* | basename | sed 's/^\.active-//'
ls .workflow/sessions/WFS-* | wc -l
# Show recent sessions
ls -t .workflow/WFS-*/workflow-session.json | head -3
ls -t .workflow/sessions/WFS-*/workflow-session.json | head -3
```

24
.claude/skills/command-guide/reference/commands/workflow/session/resume.md
View File

@@ -17,45 +17,39 @@ Resume the most recently paused workflow session, restoring all context and stat
### Step 1: Find Paused Sessions
```bash
ls .workflow/WFS-* 2>/dev/null
ls .workflow/sessions/WFS-* 2>/dev/null
```
### Step 2: Check Session Status
```bash
jq -r '.status' .workflow/WFS-session/workflow-session.json
jq -r '.status' .workflow/sessions/WFS-session/workflow-session.json
```
### Step 3: Find Most Recent Paused
```bash
ls -t .workflow/WFS-*/workflow-session.json | head -1
ls -t .workflow/sessions/WFS-*/workflow-session.json | head -1
```
### Step 4: Update Session Status
```bash
jq '.status = "active"' .workflow/WFS-session/workflow-session.json > temp.json
mv temp.json .workflow/WFS-session/workflow-session.json
jq '.status = "active"' .workflow/sessions/WFS-session/workflow-session.json > temp.json
mv temp.json .workflow/sessions/WFS-session/workflow-session.json
```
### Step 5: Add Resume Timestamp
```bash
jq '.resumed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
mv temp.json .workflow/WFS-session/workflow-session.json
```
### Step 6: Create Active Marker
```bash
touch .workflow/.active-WFS-session-name
jq '.resumed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/sessions/WFS-session/workflow-session.json > temp.json
mv temp.json .workflow/sessions/WFS-session/workflow-session.json
```
## Simple Bash Commands
### Basic Operations
- **List sessions**: `ls .workflow/WFS-*`
- **List sessions**: `ls .workflow/sessions/WFS-*`
- **Check status**: `jq -r '.status' session.json`
- **Find recent**: `ls -t .workflow/*/workflow-session.json | head -1`
- **Find recent**: `ls -t .workflow/sessions/*/workflow-session.json | head -1`
- **Update status**: `jq '.status = "active"' session.json > temp.json`
- **Add timestamp**: `jq '.resumed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
- **Create marker**: `touch .workflow/.active-session`
### Resume Result
```

112
.claude/skills/command-guide/reference/commands/workflow/session/start.md
View File

@@ -13,6 +13,35 @@ examples:
## Overview
Manages workflow sessions with three operation modes: discovery (manual), auto (intelligent), and force-new.
**Dual Responsibility**:
1. **Project-level initialization** (first-time only): Creates `.workflow/project.json` for feature registry
2. **Session-level initialization** (always): Creates session directory structure
## Step 0: Initialize Project State (First-time Only)
**Executed before all modes** - Ensures project-level state file exists by calling `/workflow:init`.
### Check and Initialize
```bash
# Check if project state exists
bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
```
**If NOT_FOUND**, delegate to `/workflow:init`:
```javascript
// Call workflow:init for intelligent project analysis
SlashCommand({command: "/workflow:init"});
// Wait for init completion
// project.json will be created with comprehensive project overview
```
**Output**:
- If EXISTS: `PROJECT_STATE: initialized`
- If NOT_FOUND: Calls `/workflow:init` → creates `.workflow/project.json` with full project analysis
**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.
## Mode 1: Discovery Mode (Default)
### Usage
@@ -20,19 +49,14 @@ Manages workflow sessions with three operation modes: discovery (manual), auto (
/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
@@ -49,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
@@ -58,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`
@@ -74,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
@@ -90,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
@@ -110,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`
@@ -173,41 +188,6 @@ SlashCommand(command="/workflow:session:start")
SlashCommand(command="/workflow:session:start --new \"experimental feature\"")
```
## Simple Bash Commands
### Basic Operations
```bash
# Check active sessions
bash(ls .workflow/.active-*)
# List all sessions
bash(ls .workflow/WFS-*)
# Read session metadata
bash(cat .workflow/WFS-[session-id]/workflow-session.json)
# Create session directories
bash(mkdir -p .workflow/WFS-[session-id]/.process)
bash(mkdir -p .workflow/WFS-[session-id]/.task)
bash(mkdir -p .workflow/WFS-[session-id]/.summaries)
# Mark session as active
bash(touch .workflow/.active-WFS-[session-id])
# Clean active markers
bash(rm .workflow/.active-*)
```
### Generate Session Slug
```bash
bash(echo "Task Description" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
```
### Create Metadata JSON
```bash
bash(echo '{"session_id":"WFS-test","project":"test project","status":"planning"}' > .workflow/WFS-test/workflow-session.json)
```
## Session ID Format
- Pattern: `WFS-[lowercase-slug]`
- Characters: `a-z`, `0-9`, `-` only

216
.claude/skills/command-guide/reference/commands/workflow/status.md
View File

@@ -1,47 +1,183 @@
---
name: workflow:status
description: Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view
argument-hint: "[optional: task-id]"
description: Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view
argument-hint: "[optional: --project|task-id|--validate]"
---
# Workflow Status Command (/workflow:status)
## Overview
Generates on-demand views from JSON task data. No synchronization needed - all views are calculated from the current state of JSON files.
Generates on-demand views from project and session data. Supports two modes:
1. **Project Overview** (`--project`): Shows completed features and project statistics
2. **Workflow Tasks** (default): Shows current session task progress
No synchronization needed - all views are calculated from current JSON state.
## Usage
```bash
/workflow:status # Show current workflow overview
/workflow:status # Show current workflow session overview
/workflow:status --project # Show project-level feature registry
/workflow:status impl-1 # Show specific task details
/workflow:status --validate # Validate workflow integrity
```
## Implementation Flow
### Mode Selection
**Check for --project flag**:
- If `--project` flag present → Execute **Project Overview Mode**
- Otherwise → Execute **Workflow Session Mode** (default)
## Project Overview Mode
### Step 1: Check Project State
```bash
bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
```
**If NOT_FOUND**:
```
No project state found.
Run /workflow:session:start to initialize project.
```
### Step 2: Read Project Data
```bash
bash(cat .workflow/project.json)
```
### Step 3: Parse and Display
**Data Processing**:
```javascript
const projectData = JSON.parse(Read('.workflow/project.json'));
const features = projectData.features || [];
const stats = projectData.statistics || {};
const overview = projectData.overview || null;
// Sort features by implementation date (newest first)
const sortedFeatures = features.sort((a, b) =>
new Date(b.implemented_at) - new Date(a.implemented_at)
);
```
**Output Format** (with extended overview):
```
## Project: ${projectData.project_name}
Initialized: ${projectData.initialized_at}
${overview ? `
### Overview
${overview.description}
**Technology Stack**:
${overview.technology_stack.languages.map(l => `- ${l.name}${l.primary ? ' (primary)' : ''}: ${l.file_count} files`).join('\n')}
Frameworks: ${overview.technology_stack.frameworks.join(', ')}
**Architecture**:
Style: ${overview.architecture.style}
Patterns: ${overview.architecture.patterns.join(', ')}
**Key Components** (${overview.key_components.length}):
${overview.key_components.map(c => `- ${c.name} (${c.path})\n ${c.description}`).join('\n')}
**Metrics**:
- Files: ${overview.metrics.total_files}
- Lines of Code: ${overview.metrics.lines_of_code}
- Complexity: ${overview.metrics.complexity}
---
` : ''}
### Completed Features (${stats.total_features})
${sortedFeatures.map(f => `
- ${f.title} (${f.timeline?.implemented_at || f.implemented_at})
${f.description}
Tags: ${f.tags?.join(', ') || 'none'}
Session: ${f.traceability?.session_id || f.session_id}
Archive: ${f.traceability?.archive_path || 'unknown'}
${f.traceability?.commit_hash ? `Commit: ${f.traceability.commit_hash}` : ''}
`).join('\n')}
### Project Statistics
- Total Features: ${stats.total_features}
- Total Sessions: ${stats.total_sessions}
- Last Updated: ${stats.last_updated}
### Quick Access
- View session details: /workflow:status
- Archive query: jq '.archives[] | select(.session_id == "SESSION_ID")' .workflow/archives/manifest.json
- Documentation: .workflow/docs/${projectData.project_name}/
### Query Commands
# Find by tag
cat .workflow/project.json | jq '.features[] | select(.tags[] == "auth")'
# View archive
cat ${feature.traceability.archive_path}/IMPL_PLAN.md
# List all tags
cat .workflow/project.json | jq -r '.features[].tags[]' | sort -u
```
**Empty State**:
```
## Project: ${projectData.project_name}
Initialized: ${projectData.initialized_at}
No features completed yet.
Complete your first workflow session to add features:
1. /workflow:plan "feature description"
2. /workflow:execute
3. /workflow:session:complete
```
### Step 4: Show Recent Sessions (Optional)
```bash
# List 5 most recent archived sessions
bash(ls -1t .workflow/archives/WFS-* 2>/dev/null | head -5 | xargs -I {} basename {})
```
**Output**:
```
### Recent Sessions
- WFS-auth-system (archived)
- WFS-payment-flow (archived)
- WFS-user-dashboard (archived)
Use /workflow:session:complete to archive current session.
```
## Workflow Session Mode (Default)
### 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
@@ -56,64 +192,4 @@ find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
## Completed Tasks
- [COMPLETED] impl-0: Setup completed
```
## Simple Bash Commands
### Basic Operations
- **Find active session**: `find .workflow/ -name ".active-*" -type f`
- **Read session info**: `cat .workflow/session/workflow-session.json`
- **List tasks**: `find .workflow/session/.task/ -name "*.json" -type f`
- **Check task status**: `cat task.json | jq -r '.status'`
- **Count completed**: `find .summaries/ -name "*.md" -type f | wc -l`
### Task Status Check
- **pending**: Not started yet
- **active**: Currently in progress
- **completed**: Finished with summary
- **blocked**: Waiting for dependencies
### Validation Commands
```bash
# Check session exists
test -f .workflow/.active-* && echo "Session active"
# Validate task files
for f in .workflow/session/.task/*.json; do jq empty "$f" && echo "Valid: $f"; done
# Check summaries match
find .task/ -name "*.json" -type f | wc -l
find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l
```
## Simple Output Format
### Default Overview
```
Session: WFS-user-auth
Status: ACTIVE
Progress: 5/12 tasks
Current: impl-3 (Building API endpoints)
Next: impl-4 (Adding authentication)
Completed: impl-1, impl-2
```
### Task Details
```
Task: impl-1
Title: Build authentication module
Status: completed
Agent: code-developer
Created: 2025-09-15
Completed: 2025-09-15
Summary: .summaries/impl-1-summary.md
```
### Validation Results
```
Session file valid
8 task files found
3 summaries found
5 tasks pending completion
```

2
.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md
View File

@@ -496,7 +496,7 @@ Supports action-planning-agent for more autonomous TDD planning with:
**Session Structure**:
```
.workflow/WFS-xxx/
.workflow/sessions/WFS-xxx/
├── IMPL_PLAN.md (unified plan with TDD Implementation Tasks section)
├── TODO_LIST.md (with internal TDD phase indicators)
├── .process/

34
.claude/skills/command-guide/reference/commands/workflow/tdd-verify.md
View File

@@ -28,7 +28,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
sessionId = argument
# Else auto-detect active session
find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//'
find .workflow/sessions/ -name "WFS-*" -type d | head -1 | sed 's/.*\///'
```
**Extract**: sessionId
@@ -44,18 +44,18 @@ find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//'
```bash
# Load all task JSONs
find .workflow/{sessionId}/.task/ -name '*.json'
find .workflow/sessions/{sessionId}/.task/ -name '*.json'
# Extract task IDs
find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.id' {} \;
find .workflow/sessions/{sessionId}/.task/ -name '*.json' -exec jq -r '.id' {} \;
# Check dependencies
find .workflow/{sessionId}/.task/ -name 'IMPL-*.json' -exec jq -r '.context.depends_on[]?' {} \;
find .workflow/{sessionId}/.task/ -name 'REFACTOR-*.json' -exec jq -r '.context.depends_on[]?' {} \;
find .workflow/sessions/{sessionId}/.task/ -name 'IMPL-*.json' -exec jq -r '.context.depends_on[]?' {} \;
find .workflow/sessions/{sessionId}/.task/ -name 'REFACTOR-*.json' -exec jq -r '.context.depends_on[]?' {} \;
# Check meta fields
find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.tdd_phase' {} \;
find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
find .workflow/sessions/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.tdd_phase' {} \;
find .workflow/sessions/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
```
**Validation**:
@@ -82,9 +82,9 @@ find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
- Compliance score
**Validation**:
- `.workflow/{sessionId}/.process/test-results.json` exists
- `.workflow/{sessionId}/.process/coverage-report.json` exists
- `.workflow/{sessionId}/.process/tdd-cycle-report.md` exists
- `.workflow/sessions/{sessionId}/.process/test-results.json` exists
- `.workflow/sessions/{sessionId}/.process/coverage-report.json` exists
- `.workflow/sessions/{sessionId}/.process/tdd-cycle-report.md` exists
**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
@@ -97,7 +97,7 @@ find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
cd project-root && gemini -p "
PURPOSE: Generate TDD compliance report
TASK: Analyze TDD workflow execution and generate quality report
CONTEXT: @{.workflow/{sessionId}/.task/*.json,.workflow/{sessionId}/.summaries/*,.workflow/{sessionId}/.process/tdd-cycle-report.md}
CONTEXT: @{.workflow/sessions/{sessionId}/.task/*.json,.workflow/sessions/{sessionId}/.summaries/*,.workflow/sessions/{sessionId}/.process/tdd-cycle-report.md}
EXPECTED:
- TDD compliance score (0-100)
- Chain completeness verification
@@ -106,7 +106,7 @@ EXPECTED:
- Red-Green-Refactor cycle validation
- Best practices adherence assessment
RULES: Focus on TDD best practices and workflow adherence. Be specific about violations and improvements.
" > .workflow/{sessionId}/TDD_COMPLIANCE_REPORT.md
" > .workflow/sessions/{sessionId}/TDD_COMPLIANCE_REPORT.md
```
**Output**: TDD_COMPLIANCE_REPORT.md
@@ -134,7 +134,7 @@ Function Coverage: {percentage}%
## Compliance Score: {score}/100
Detailed report: .workflow/{sessionId}/TDD_COMPLIANCE_REPORT.md
Detailed report: .workflow/sessions/{sessionId}/TDD_COMPLIANCE_REPORT.md
Recommendations:
- Complete missing REFACTOR-3.1 task
@@ -168,7 +168,7 @@ TodoWrite({todos: [
### Chain Validation Algorithm
```
1. Load all task JSONs from .workflow/{sessionId}/.task/
1. Load all task JSONs from .workflow/sessions/{sessionId}/.task/
2. Extract task IDs and group by feature number
3. For each feature:
- Check TEST-N.M exists
@@ -202,7 +202,7 @@ Final Score: Max(0, Base Score - Deductions)
## Output Files
```
.workflow/{session-id}/
.workflow/sessions/{session-id}/
├── TDD_COMPLIANCE_REPORT.md # Comprehensive compliance report ⭐
└── .process/
├── test-results.json # From tdd-coverage-analysis
@@ -215,8 +215,8 @@ Final Score: Max(0, Base Score - Deductions)
### Session Discovery Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| No active session | No .active-* file | Provide session-id explicitly |
| Multiple active sessions | Multiple .active-* files | Provide session-id explicitly |
| No active session | No WFS-* directories | Provide session-id explicitly |
| Multiple active sessions | Multiple WFS-* directories | Provide session-id explicitly |
| Session not found | Invalid session-id | Check available sessions |
### Validation Errors

4
.claude/skills/command-guide/reference/commands/workflow/test-cycle-execute.md
View File

@@ -543,7 +543,7 @@ This package is passed to agents via the Task tool's prompt context.
"coverage_target": 80
},
"session": {
"workflow_dir": ".workflow/WFS-test-{session}/",
"workflow_dir": ".workflow/sessions/WFS-test-{session}/",
"iteration_state_file": ".process/iteration-state.json",
"test_results_file": ".process/test-results.json",
"fix_history_file": ".process/fix-history.json"
@@ -555,7 +555,7 @@ This package is passed to agents via the Task tool's prompt context.
### Test-Fix Session Files
```
.workflow/WFS-test-{session}/
.workflow/sessions/WFS-test-{session}/
├── workflow-session.json # Session metadata with workflow_type
├── IMPL_PLAN.md # Test plan
├── TODO_LIST.md # Progress tracking

4
.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md
View File

@@ -513,7 +513,7 @@ If quality gate fails:
### Output Files Structure
Created in `.workflow/WFS-test-[session]/`:
Created in `.workflow/sessions/WFS-test-[session]/`:
```
WFS-test-[session]/
@@ -579,7 +579,7 @@ Test-Fix-Gen Workflow Orchestrator (Dual-Mode Support)
└─ Command ends, control returns to user
Artifacts Created:
├── .workflow/WFS-test-[session]/
├── .workflow/sessions/WFS-test-[session]/
│ ├── workflow-session.json
│ ├── IMPL_PLAN.md
│ ├── TODO_LIST.md

4
.claude/skills/command-guide/reference/commands/workflow/test-gen.md
View File

@@ -397,7 +397,7 @@ Test-Gen Workflow Orchestrator
└─ Command ends, control returns to user
Artifacts Created:
├── .workflow/WFS-test-[session]/
├── .workflow/sessions/WFS-test-[session]/
│ ├── workflow-session.json
│ ├── IMPL_PLAN.md
│ ├── TODO_LIST.md
@@ -444,7 +444,7 @@ See `/workflow:tools:test-task-generate` for complete task JSON schemas.
## Output Files
Created in `.workflow/WFS-test-[session]/`:
Created in `.workflow/sessions/WFS-test-[session]/`:
- `workflow-session.json` - Session metadata
- `.process/test-context-package.json` - Coverage analysis
- `.process/TEST_ANALYSIS_RESULTS.md` - Test requirements

4
.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md
View File

@@ -3,8 +3,8 @@ name: conflict-resolution
description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen
argument-hint: "--session WFS-session-id --context path/to/context-package.json"
examples:
- /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
- /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
- /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/sessions/WFS-auth/.process/context-package.json
- /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/sessions/WFS-payment/.process/context-package.json
---
# Conflict Resolution Command

51
.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md
View File

@@ -71,9 +71,10 @@ You are executing as context-search-agent (.claude/agents/context-search-agent.m
Execute complete context-search-agent workflow for implementation planning:
### Phase 1: Initialization & Pre-Analysis
1. **Detection**: Check for existing context-package (early exit if valid)
2. **Foundation**: Initialize code-index, get project structure, load docs
3. **Analysis**: Extract keywords, determine scope, classify complexity
1. **Project State Loading**: Read and parse `.workflow/project.json`. Use its `overview` section as the foundational `project_context`. This is your primary source for architecture, tech stack, and key components. If file doesn't exist, proceed with fresh analysis.
2. **Detection**: Check for existing context-package (early exit if valid)
3. **Foundation**: Initialize code-index, get project structure, load docs
4. **Analysis**: Extract keywords, determine scope, classify complexity based on task description and project state
### Phase 2: Multi-Source Context Discovery
Execute all 4 discovery tracks:
@@ -84,16 +85,17 @@ Execute all 4 discovery tracks:
### Phase 3: Synthesis, Assessment & Packaging
1. Apply relevance scoring and build dependency graph
2. Synthesize 4-source data (archive > docs > code > web)
3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
4. Perform conflict detection with risk assessment
5. **Inject historical conflicts** from archive analysis into conflict_detection
6. Generate and validate context-package.json
2. **Synthesize 4-source data**: Merge findings from all sources (archive > docs > code > web). **Prioritize the context from `project.json`** for architecture and tech stack unless code analysis reveals it's outdated.
3. **Populate `project_context`**: Directly use the `overview` from `project.json` to fill the `project_context` section of the output `context-package.json`. Include technology_stack, architecture, key_components, and entry_points.
4. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
5. Perform conflict detection with risk assessment
6. **Inject historical conflicts** from archive analysis into conflict_detection
7. Generate and validate context-package.json
## Output Requirements
Complete context-package.json with:
- **metadata**: task_description, keywords, complexity, tech_stack, session_id
- **project_context**: architecture_patterns, coding_conventions, tech_stack
- **project_context**: architecture_patterns, coding_conventions, tech_stack (sourced from `project.json` overview)
- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
- **dependencies**: {internal[], external[]} with dependency graph
- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
@@ -139,7 +141,7 @@ Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json`
**Key Sections**:
- **metadata**: Session info, keywords, complexity, tech stack
- **project_context**: Architecture patterns, conventions, tech stack
- **project_context**: Architecture patterns, conventions, tech stack (populated from `project.json` overview)
- **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
- **dependencies**: Internal and external dependency graphs
- **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
@@ -154,7 +156,7 @@ The context-search-agent MUST perform historical archive analysis as Track 1 in
**Step 1: Check for Archive Manifest**
```bash
# Check if archive manifest exists
if [[ -f .workflow/.archives/manifest.json ]]; then
if [[ -f .workflow/archives/manifest.json ]]; then
# Manifest available for querying
fi
```
@@ -233,7 +235,7 @@ if (historicalConflicts.length > 0 && currentRisk === "low") {
### Archive Query Algorithm
```markdown
1. IF .workflow/.archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
1. IF .workflow/archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
2. IF manifest exists:
a. Load manifest.json
b. Extract keywords from task_description (nouns, verbs, technical terms)
@@ -250,33 +252,10 @@ if (historicalConflicts.length > 0 && currentRisk === "low") {
3. Continue to Track 2 (reference documentation)
```
## Usage Examples
### Basic Usage
```bash
/workflow:tools:context-gather --session WFS-auth-feature "Implement JWT authentication with refresh tokens"
```
## Success Criteria
- ✅ Valid context-package.json generated in `.workflow/{session}/.process/`
- ✅ Contains >80% relevant files based on task keywords
- ✅ Execution completes within 2 minutes
- ✅ All required schema fields present and valid
- ✅ Conflict risk accurately assessed
- ✅ Agent reports completion with statistics
## Error Handling
| Error | Cause | Resolution |
|-------|-------|------------|
| Package validation failed | Invalid session_id in existing package | Re-run agent to regenerate |
| Agent execution timeout | Large codebase or slow MCP | Increase timeout, check code-index status |
| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
| File count exceeds limit | Too many relevant files | Agent should auto-prioritize top 50 by relevance |
## Notes
- **Detection-first**: Always check for existing package before invoking agent
- **Project.json integration**: Agent reads `.workflow/project.json` as primary source for project context, avoiding redundant analysis
- **Agent autonomy**: Agent handles all discovery logic per `.claude/agents/context-search-agent.md`
- **No redundancy**: This command is a thin orchestrator, all logic in agent
- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call

6
.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md
View File

@@ -231,13 +231,13 @@ const agentContext = {
// Use memory if available, else load
session_metadata: memory.has("workflow-session.json")
? memory.get("workflow-session.json")
: Read(.workflow/WFS-[id]/workflow-session.json),
: Read(.workflow/sessions/WFS-[id]/workflow-session.json),
context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
context_package_path: ".workflow/sessions/WFS-[id]/.process/context-package.json",
context_package: memory.has("context-package.json")
? memory.get("context-package.json")
: Read(".workflow/WFS-[id]/.process/context-package.json"),
: Read(".workflow/sessions/WFS-[id]/.process/context-package.json"),
// Extract brainstorm artifacts from context package
brainstorm_artifacts: extractBrainstormArtifacts(context_package),

10
.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md
View File

@@ -338,19 +338,19 @@ const agentContext = {
// Use memory if available, else load
session_metadata: memory.has("workflow-session.json")
? memory.get("workflow-session.json")
: Read(.workflow/WFS-[id]/workflow-session.json),
: Read(.workflow/sessions/WFS-[id]/workflow-session.json),
context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
context_package_path: ".workflow/sessions/WFS-[id]/.process/context-package.json",
context_package: memory.has("context-package.json")
? memory.get("context-package.json")
: Read(".workflow/WFS-[id]/.process/context-package.json"),
: Read(".workflow/sessions/WFS-[id]/.process/context-package.json"),
test_context_package_path: ".workflow/WFS-[id]/.process/test-context-package.json",
test_context_package_path: ".workflow/sessions/WFS-[id]/.process/test-context-package.json",
test_context_package: memory.has("test-context-package.json")
? memory.get("test-context-package.json")
: Read(".workflow/WFS-[id]/.process/test-context-package.json"),
: Read(".workflow/sessions/WFS-[id]/.process/test-context-package.json"),
// Extract brainstorm artifacts from context package
brainstorm_artifacts: extractBrainstormArtifacts(context_package),

6
.claude/skills/command-guide/reference/commands/workflow/tools/task-generate.md
View File

@@ -224,7 +224,7 @@ Each task JSON embeds all necessary context, artifacts, and execution steps usin
- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks)
- `title`: Descriptive task name
- `status`: Task state (`pending|active|completed|blocked|container`)
- `context_package_path`: Path to context package (`.workflow/WFS-[session]/.process/context-package.json`)
- `context_package_path`: Path to context package (`.workflow/sessions/WFS-[session]/.process/context-package.json`)
- `meta`: Task metadata
- `context`: Task-specific context and requirements
- `flow_control`: Execution steps and workflow
@@ -269,7 +269,7 @@ Each task JSON embeds all necessary context, artifacts, and execution steps usin
"id": "IMPL-1",
"title": "Implement feature X with Y components",
"status": "pending",
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
"context_package_path": ".workflow/sessions/WFS-session/.process/context-package.json",
"meta": {
"type": "feature",
"agent": "@code-developer",
@@ -291,7 +291,7 @@ Each task JSON embeds all necessary context, artifacts, and execution steps usin
"depends_on": [],
"artifacts": [
{
"path": ".workflow/WFS-session/.brainstorming/system-architect/analysis.md",
"path": ".workflow/sessions/WFS-session/.brainstorming/system-architect/analysis.md",
"priority": "highest",
"usage": "Architecture decisions and API specifications"
}

2
.claude/skills/command-guide/reference/commands/workflow/tools/tdd-coverage-analysis.md
View File

@@ -272,6 +272,6 @@ Function Coverage: 91%
Overall Compliance: 93/100
Detailed report: .workflow/WFS-auth/.process/tdd-cycle-report.md
Detailed report: .workflow/sessions/WFS-auth/.process/tdd-cycle-report.md
```

2
.claude/skills/command-guide/reference/commands/workflow/tools/test-concept-enhanced.md
View File

@@ -3,7 +3,7 @@ name: test-concept-enhanced
description: Analyze test requirements and generate test generation strategy using Gemini with test-context package
argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json"
examples:
- /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/WFS-test-auth/.process/test-context-package.json
- /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/sessions/WFS-test-auth/.process/test-context-package.json
---
# Test Concept Enhanced Command

12
.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md
View File

@@ -273,19 +273,19 @@ const agentContext = {
// Use memory if available, else load
session_metadata: memory.has("workflow-session.json")
? memory.get("workflow-session.json")
: Read(.workflow/WFS-test-[id]/workflow-session.json),
: Read(.workflow/sessions/WFS-test-[id]/workflow-session.json),
test_analysis_results_path: ".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md",
test_analysis_results_path: ".workflow/sessions/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md",
test_analysis_results: memory.has("TEST_ANALYSIS_RESULTS.md")
? memory.get("TEST_ANALYSIS_RESULTS.md")
: Read(".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md"),
: Read(".workflow/sessions/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md"),
test_context_package_path: ".workflow/WFS-test-[id]/.process/test-context-package.json",
test_context_package_path: ".workflow/sessions/WFS-test-[id]/.process/test-context-package.json",
test_context_package: memory.has("test-context-package.json")
? memory.get("test-context-package.json")
: Read(".workflow/WFS-test-[id]/.process/test-context-package.json"),
: Read(".workflow/sessions/WFS-test-[id]/.process/test-context-package.json"),
// Load source session summaries if exists
source_session_id: session_metadata.source_session_id || null,
@@ -312,7 +312,7 @@ This section provides quick reference for test task JSON structure. For complete
## Output Files Structure
```
.workflow/WFS-test-[session]/
.workflow/sessions/WFS-test-[session]/
├── workflow-session.json # Test session metadata
├── IMPL_PLAN.md # Test validation plan
├── TODO_LIST.md # Progress tracking

2
.claude/skills/command-guide/reference/commands/workflow/ui-design/animation-extract.md
View File

@@ -67,7 +67,7 @@ if [ -n "$DESIGN_ID" ]; then
relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
elif [ -n "$SESSION_ID" ]; then
# Latest in session
relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
relative_path=$(find .workflow/sessions/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
else
# Latest globally
relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)

380
.claude/skills/command-guide/reference/commands/workflow/ui-design/capture.md
View File

@@ -1,380 +0,0 @@
---
name: capture
description: Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping
argument-hint: --url-map "target:url,..." [--design-id <id>] [--session <id>]
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__*
---
# Batch Screenshot Capture (/workflow:ui-design:capture)
## Overview
Batch screenshot tool with MCP-first strategy and multi-tier fallback. Processes multiple URLs in parallel.
**Strategy**: MCP → Playwright → Chrome → Manual
**Output**: Flat structure `screenshots/{target}.png`
## Phase 1: Initialize & Parse
### Step 1: Determine Base Path & Generate Design ID
```bash
# Priority: --design-id > session (latest) > standalone (create new)
if [ -n "$DESIGN_ID" ]; then
# Use provided design ID
relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
if [ -z "$relative_path" ]; then
echo "ERROR: Design run not found: $DESIGN_ID"
echo "HINT: Run '/workflow:ui-design:list' to see available design runs"
exit 1
fi
elif [ -n "$SESSION_ID" ]; then
# Find latest in session or create new
relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
if [ -z "$relative_path" ]; then
design_id="design-run-$(date +%Y%m%d)-$RANDOM"
relative_path=".workflow/WFS-$SESSION_ID/${design_id}"
fi
else
# Create new standalone design run
design_id="design-run-$(date +%Y%m%d)-$RANDOM"
relative_path=".workflow/${design_id}"
fi
# Create directory and convert to absolute path
bash(mkdir -p "$relative_path"/screenshots)
base_path=$(cd "$relative_path" && pwd)
# Extract and display design_id
design_id=$(basename "$base_path")
echo "✓ Design ID: $design_id"
echo "✓ Base path: $base_path"
```
### Step 2: Parse URL Map
```javascript
// Input: "home:https://linear.app, pricing:https://linear.app/pricing"
url_entries = []
FOR pair IN split(params["--url-map"], ","):
parts = pair.split(":", 1)
IF len(parts) != 2:
ERROR: "Invalid format: {pair}. Expected: 'target:url'"
EXIT 1
target = parts[0].strip().lower().replace(" ", "-")
url = parts[1].strip()
// Validate target name
IF NOT regex_match(target, r"^[a-z0-9][a-z0-9_-]*$"):
ERROR: "Invalid target: {target}"
EXIT 1
// Add https:// if missing
IF NOT url.startswith("http"):
url = f"https://{url}"
url_entries.append({target, url})
```
**Output**: `base_path`, `url_entries[]`
### Step 3: Initialize Todos
```javascript
TodoWrite({todos: [
{content: "Parse url-map", status: "completed", activeForm: "Parsing"},
{content: "Detect MCP tools", status: "in_progress", activeForm: "Detecting"},
{content: "Capture screenshots", status: "pending", activeForm: "Capturing"},
{content: "Verify results", status: "pending", activeForm: "Verifying"}
]})
```
## Phase 2: Detect Screenshot Tools
### Step 1: Check MCP Availability
```javascript
// List available MCP servers
all_resources = ListMcpResourcesTool()
available_servers = unique([r.server for r in all_resources])
// Check Chrome DevTools MCP
chrome_devtools = "chrome-devtools" IN available_servers
chrome_screenshot = check_tool_exists("mcp__chrome-devtools__take_screenshot")
// Check Playwright MCP
playwright_mcp = "playwright" IN available_servers
playwright_screenshot = check_tool_exists("mcp__playwright__screenshot")
// Determine primary tool
IF chrome_devtools AND chrome_screenshot:
tool = "chrome-devtools"
ELSE IF playwright_mcp AND playwright_screenshot:
tool = "playwright"
ELSE:
tool = null
```
**Output**: `tool` (chrome-devtools | playwright | null)
### Step 2: Check Local Fallback
```bash
# Only if MCP unavailable
bash(which playwright 2>/dev/null || echo "")
bash(which google-chrome || which chrome || which chromium 2>/dev/null || echo "")
```
**Output**: `local_tools[]`
## Phase 3: Capture Screenshots
### Screenshot Format Options
**PNG Format** (default, lossless):
- **Pros**: Lossless quality, best for detailed UI screenshots
- **Cons**: Larger file sizes (typically 200-500 KB per screenshot)
- **Parameters**: `format: "png"` (no quality parameter)
- **Use case**: High-fidelity UI replication, design system extraction
**WebP Format** (optional, lossy/lossless):
- **Pros**: Smaller file sizes with good quality (50-70% smaller than PNG)
- **Cons**: Requires quality parameter, slight quality loss at high compression
- **Parameters**: `format: "webp", quality: 90` (80-100 recommended)
- **Use case**: Batch captures, network-constrained environments
**JPEG Format** (optional, lossy):
- **Pros**: Smallest file sizes
- **Cons**: Lossy compression, not recommended for UI screenshots
- **Parameters**: `format: "jpeg", quality: 90`
- **Use case**: Photo-heavy pages, not recommended for UI design
### Step 1: MCP Capture (If Available)
```javascript
IF tool == "chrome-devtools":
// Get or create page
pages = mcp__chrome-devtools__list_pages()
IF pages.length == 0:
mcp__chrome-devtools__new_page({url: url_entries[0].url})
page_idx = 0
ELSE:
page_idx = 0
mcp__chrome-devtools__select_page({pageIdx: page_idx})
// Capture each URL
FOR entry IN url_entries:
mcp__chrome-devtools__navigate_page({url: entry.url, timeout: 30000})
bash(sleep 2)
// PNG format doesn't support quality parameter
// Use PNG for lossless quality (larger files)
mcp__chrome-devtools__take_screenshot({
fullPage: true,
format: "png",
filePath: f"{base_path}/screenshots/{entry.target}.png"
})
// Alternative: Use WebP with quality for smaller files
// mcp__chrome-devtools__take_screenshot({
// fullPage: true,
// format: "webp",
// quality: 90,
// filePath: f"{base_path}/screenshots/{entry.target}.webp"
// })
ELSE IF tool == "playwright":
FOR entry IN url_entries:
mcp__playwright__screenshot({
url: entry.url,
output_path: f"{base_path}/screenshots/{entry.target}.png",
full_page: true,
timeout: 30000
})
```
### Step 2: Local Fallback (If MCP Failed)
```bash
# Try Playwright CLI
bash(playwright screenshot "$url" "$output_file" --full-page --timeout 30000)
# Try Chrome headless
bash($chrome --headless --screenshot="$output_file" --window-size=1920,1080 "$url")
```
### Step 3: Manual Mode (If All Failed)
```
⚠️ Manual Screenshot Required
Failed URLs:
home: https://linear.app
Save to: .workflow/design-run-20250110/screenshots/home.png
Steps:
1. Visit URL in browser
2. Take full-page screenshot
3. Save to path above
4. Type 'ready' to continue
Options: ready | skip | abort
```
## Phase 4: Verification
### Step 1: Scan Captured Files
```bash
bash(ls -1 $base_path/screenshots/*.{png,jpg,jpeg,webp} 2>/dev/null)
bash(du -h $base_path/screenshots/*.png 2>/dev/null)
```
### Step 2: Generate Metadata
```javascript
captured_files = Glob(f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}")
captured_targets = [basename_no_ext(f) for f in captured_files]
metadata = {
"timestamp": current_timestamp(),
"total_requested": len(url_entries),
"total_captured": len(captured_targets),
"screenshots": []
}
FOR entry IN url_entries:
is_captured = entry.target IN captured_targets
metadata.screenshots.append({
"target": entry.target,
"url": entry.url,
"captured": is_captured,
"path": f"{base_path}/screenshots/{entry.target}.png" IF is_captured ELSE null,
"size_kb": file_size_kb IF is_captured ELSE null
})
Write(f"{base_path}/screenshots/capture-metadata.json", JSON.stringify(metadata))
```
**Output**: `capture-metadata.json`
## Completion
### Todo Update
```javascript
TodoWrite({todos: [
{content: "Parse url-map", status: "completed", activeForm: "Parsing"},
{content: "Detect MCP tools", status: "completed", activeForm: "Detecting"},
{content: "Capture screenshots", status: "completed", activeForm: "Capturing"},
{content: "Verify results", status: "completed", activeForm: "Verifying"}
]})
```
### Output Message
```
✅ Batch screenshot capture complete!
Summary:
- Requested: {total_requested}
- Captured: {total_captured}
- Success rate: {success_rate}%
- Method: {tool || "Local fallback"}
Output:
{base_path}/screenshots/
├── home.png (245.3 KB)
├── pricing.png (198.7 KB)
└── capture-metadata.json
Next: /workflow:ui-design:extract --images "screenshots/*.png"
```
## Simple Bash Commands
### Path Operations
```bash
# Find design directory
bash(find .workflow -type d -name "design-run-*" | head -1)
# Create screenshot directory
bash(mkdir -p $BASE_PATH/screenshots)
```
### Tool Detection
```bash
# Check MCP
all_resources = ListMcpResourcesTool()
# Check local tools
bash(which playwright 2>/dev/null)
bash(which google-chrome 2>/dev/null)
```
### Verification
```bash
# List captures
bash(ls -1 $base_path/screenshots/*.png 2>/dev/null)
# File sizes
bash(du -h $base_path/screenshots/*.png)
```
## Output Structure
```
{base_path}/
└── screenshots/
├── home.png
├── pricing.png
├── about.png
└── capture-metadata.json
```
## Error Handling
### Common Errors
```
ERROR: Invalid url-map format
→ Use: "target:url, target2:url2"
ERROR: png screenshots do not support 'quality'
→ PNG format is lossless, no quality parameter needed
→ Remove quality parameter OR switch to webp/jpeg format
ERROR: MCP unavailable
→ Using local fallback
ERROR: All tools failed
→ Manual mode activated
```
### Format-Specific Errors
```
❌ Wrong: format: "png", quality: 90
✅ Right: format: "png"
✅ Or use: format: "webp", quality: 90
✅ Or use: format: "jpeg", quality: 90
```
### Recovery
- **Partial success**: Keep successful captures
- **Retry**: Re-run with failed targets only
- **Manual**: Follow interactive guidance
## Quality Checklist
- [ ] All requested URLs processed
- [ ] File sizes > 1KB (valid images)
- [ ] Metadata JSON generated
- [ ] No missing targets (or documented)
## Key Features
- **MCP-first**: Prioritize managed tools
- **Multi-tier fallback**: 4 layers (MCP → Local → Manual)
- **Batch processing**: Parallel capture
- **Error tolerance**: Partial failures handled
- **Structured output**: Flat, predictable
## Integration
**Input**: `--url-map` (multiple target:url pairs)
**Output**: `screenshots/*.png` + `capture-metadata.json`
**Called by**: `/workflow:ui-design:imitate-auto`, `/workflow:ui-design:explore-auto`
**Next**: `/workflow:ui-design:extract` or `/workflow:ui-design:explore-layers`

42
.claude/skills/command-guide/reference/commands/workflow/ui-design/update.md → .claude/skills/command-guide/reference/commands/workflow/ui-design/design-sync.md
View File

@@ -1,11 +1,11 @@
---
name: update
description: Update brainstorming artifacts with finalized design system references from selected prototypes
name: design-sync
description: Synchronize finalized design system references to brainstorming artifacts, preparing them for /workflow:plan consumption
argument-hint: --session <session_id> [--selected-prototypes "<list>"]
allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
---
# Design Update Command
# Design Sync Command
## Overview
@@ -25,10 +25,10 @@ Synchronize finalized design system references to brainstorming artifacts, prepa
```bash
# Validate session
CHECK: .workflow/.active-* marker files; VALIDATE: session_id matches active session
CHECK: find .workflow/sessions/ -name "WFS-*" -type d; VALIDATE: session_id matches active session
# Verify design artifacts in latest design run
latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-run-*")
latest_design = find_latest_path_matching(".workflow/sessions/WFS-{session}/design-run-*")
# Detect design system structure
IF exists({latest_design}/style-extraction/style-1/design-tokens.json):
@@ -51,7 +51,7 @@ REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
```bash
# Check if role analysis documents contains current design run reference
synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/role analysis documents"
synthesis_spec_path = ".workflow/sessions/WFS-{session}/.brainstorming/role analysis documents"
current_design_run = basename(latest_design) # e.g., "design-run-20250109-143022"
IF exists(synthesis_spec_path):
@@ -68,8 +68,8 @@ IF exists(synthesis_spec_path):
```bash
# Load target brainstorming artifacts (files to be updated)
Read(.workflow/WFS-{session}/.brainstorming/role analysis documents)
IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
Read(.workflow/sessions/WFS-{session}/.brainstorming/role analysis documents)
IF exists(.workflow/sessions/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
# Optional: Read prototype notes for descriptions (minimal context)
FOR each selected_prototype IN selected_list:
@@ -113,7 +113,7 @@ Update `.brainstorming/role analysis documents` with design system references.
**Implementation**:
```bash
# Option 1: Edit existing section
Edit(file_path=".workflow/WFS-{session}/.brainstorming/role analysis documents",
Edit(file_path=".workflow/sessions/WFS-{session}/.brainstorming/role analysis documents",
old_string="## UI/UX Guidelines\n[existing content]",
new_string="## UI/UX Guidelines\n\n[new design reference content]")
@@ -128,15 +128,15 @@ IF section not found:
```bash
# Always update ui-designer
ui_designer_files = Glob(".workflow/WFS-{session}/.brainstorming/ui-designer/analysis*.md")
ui_designer_files = Glob(".workflow/sessions/WFS-{session}/.brainstorming/ui-designer/analysis*.md")
# Conditionally update other roles
has_animations = exists({latest_design}/animation-extraction/animation-tokens.json)
has_layouts = exists({latest_design}/layout-extraction/layout-templates.json)
IF has_animations: ux_expert_files = Glob(".workflow/WFS-{session}/.brainstorming/ux-expert/analysis*.md")
IF has_layouts: architect_files = Glob(".workflow/WFS-{session}/.brainstorming/system-architect/analysis*.md")
IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/product-manager/analysis*.md")
IF has_animations: ux_expert_files = Glob(".workflow/sessions/WFS-{session}/.brainstorming/ux-expert/analysis*.md")
IF has_layouts: architect_files = Glob(".workflow/sessions/WFS-{session}/.brainstorming/system-architect/analysis*.md")
IF selected_list: pm_files = Glob(".workflow/sessions/WFS-{session}/.brainstorming/product-manager/analysis*.md")
```
**Content Templates**:
@@ -223,7 +223,7 @@ For complete token definitions and usage examples, see:
**Implementation**:
```bash
Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/design-system-reference.md",
Write(file_path=".workflow/sessions/WFS-{session}/.brainstorming/ui-designer/design-system-reference.md",
content="[generated content with @ references]")
```
@@ -259,7 +259,7 @@ Next: /workflow:plan [--agent] "<task description>"
**Updated Files**:
```
.workflow/WFS-{session}/.brainstorming/
.workflow/sessions/WFS-{session}/.brainstorming/
├── role analysis documents # Updated with UI/UX Guidelines section
├── ui-designer/
│ ├── analysis*.md # Updated with design system references
@@ -349,15 +349,3 @@ After update, verify:
- **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
## Why Main Claude Execution?
This command is executed directly by main Claude (not delegated to an Agent) because:
1. **Simple Reference Generation**: Only generating file paths, not complex synthesis
2. **Context Preservation**: Main Claude has full session and conversation context
3. **Minimal Transformation**: Primarily updating references, not analyzing content
4. **Path Resolution**: Requires precise relative path calculation
5. **Edit Operations**: Better error recovery for Edit conflicts
6. **Synthesis Pattern**: Follows same direct-execution pattern as other reference updates
This ensures reliable, lightweight integration without Agent handoff overhead.

2
.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md
View File

@@ -265,7 +265,7 @@ STORE: device_type, device_source
### Phase 4: Run Initialization & Directory Setup
```bash
design_id = "design-run-$(date +%Y%m%d)-$RANDOM"
relative_base_path = --session ? ".workflow/WFS-{session}/${design_id}" : ".workflow/${design_id}"
relative_base_path = --session ? ".workflow/sessions/WFS-{session}/${design_id}" : ".workflow/${design_id}"
# Create directory and convert to absolute path
Bash(mkdir -p "${relative_base_path}/style-extraction")

611
.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-layers.md
View File

@@ -1,611 +0,0 @@
---
name: explore-layers
description: Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer
argument-hint: --url <url> --depth <1-5> [--design-id <id>] [--session <id>]
allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__*
---
# Interactive Layer Exploration (/workflow:ui-design:explore-layers)
## Overview
Single-URL depth-controlled interactive capture. Progressively explores UI layers from pages to Shadow DOM.
**Depth Levels**:
- `1` = Page (full-page screenshot)
- `2` = Elements (key components)
- `3` = Interactions (modals, dropdowns)
- `4` = Embedded (iframes, widgets)
- `5` = Shadow DOM (web components)
**Requirements**: Chrome DevTools MCP
## Phase 1: Setup & Validation
### Step 1: Parse Parameters
```javascript
url = params["--url"]
depth = int(params["--depth"])
// Validate URL
IF NOT url.startswith("http"):
url = f"https://{url}"
// Validate depth
IF depth NOT IN [1, 2, 3, 4, 5]:
ERROR: "Invalid depth: {depth}. Use 1-5"
EXIT 1
```
### Step 2: Determine Base Path
```bash
# Priority: --design-id > --session > create new
if [ -n "$DESIGN_ID" ]; then
# Exact match by design ID
relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
if [ -z "$relative_path" ]; then
echo "ERROR: Design run not found: $DESIGN_ID"
echo "HINT: Run '/workflow:ui-design:list' to see available design runs"
exit 1
fi
elif [ -n "$SESSION_ID" ]; then
# Find latest in session or create new
relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
if [ -z "$relative_path" ]; then
design_id="design-run-$(date +%Y%m%d)-$RANDOM"
relative_path=".workflow/WFS-$SESSION_ID/${design_id}"
fi
else
# Create new standalone design run
design_id="design-run-$(date +%Y%m%d)-$RANDOM"
relative_path=".workflow/${design_id}"
fi
# Create directory structure and convert to absolute path
bash(mkdir -p "$relative_path")
base_path=$(cd "$relative_path" && pwd)
# Extract and display design_id
design_id=$(basename "$base_path")
echo "✓ Design ID: $design_id"
echo "✓ Base path: $base_path"
# Create depth directories
bash(for i in $(seq 1 $depth); do mkdir -p "$base_path"/screenshots/depth-$i; done)
```
**Output**: `url`, `depth`, `base_path`
### Step 3: Validate MCP Availability
```javascript
all_resources = ListMcpResourcesTool()
chrome_devtools = "chrome-devtools" IN [r.server for r in all_resources]
IF NOT chrome_devtools:
ERROR: "explore-layers requires Chrome DevTools MCP"
ERROR: "Install: npm i -g @modelcontextprotocol/server-chrome-devtools"
EXIT 1
```
### Step 4: Initialize Todos
```javascript
todos = [
{content: "Setup and validation", status: "completed", activeForm: "Setting up"}
]
FOR level IN range(1, depth + 1):
todos.append({
content: f"Depth {level}: {DEPTH_NAMES[level]}",
status: "pending",
activeForm: f"Capturing depth {level}"
})
todos.append({content: "Generate layer map", status: "pending", activeForm: "Mapping"})
TodoWrite({todos})
```
## Phase 2: Navigate & Load Page
### Step 1: Get or Create Browser Page
```javascript
pages = mcp__chrome-devtools__list_pages()
IF pages.length == 0:
mcp__chrome-devtools__new_page({url: url, timeout: 30000})
page_idx = 0
ELSE:
page_idx = 0
mcp__chrome-devtools__select_page({pageIdx: page_idx})
mcp__chrome-devtools__navigate_page({url: url, timeout: 30000})
bash(sleep 3) // Wait for page load
```
**Output**: `page_idx`
## Phase 3: Depth 1 - Page Level
### Step 1: Capture Full Page
```javascript
TodoWrite(mark_in_progress: "Depth 1: Page")
output_file = f"{base_path}/screenshots/depth-1/full-page.png"
mcp__chrome-devtools__take_screenshot({
fullPage: true,
format: "png",
quality: 90,
filePath: output_file
})
layer_map = {
"url": url,
"depth": depth,
"layers": {
"depth-1": {
"type": "page",
"captures": [{
"name": "full-page",
"path": output_file,
"size_kb": file_size_kb(output_file)
}]
}
}
}
TodoWrite(mark_completed: "Depth 1: Page")
```
**Output**: `depth-1/full-page.png`
## Phase 4: Depth 2 - Element Level (If depth >= 2)
### Step 1: Analyze Page Structure
```javascript
IF depth < 2: SKIP
TodoWrite(mark_in_progress: "Depth 2: Elements")
snapshot = mcp__chrome-devtools__take_snapshot()
// Filter key elements
key_types = ["nav", "header", "footer", "aside", "button", "form", "article"]
key_elements = [
el for el in snapshot.interactiveElements
if el.type IN key_types OR el.role IN ["navigation", "banner", "main"]
][:10] // Limit to top 10
```
### Step 2: Capture Element Screenshots
```javascript
depth_2_captures = []
FOR idx, element IN enumerate(key_elements):
element_name = sanitize(element.text[:20] or element.type) or f"element-{idx}"
output_file = f"{base_path}/screenshots/depth-2/{element_name}.png"
TRY:
mcp__chrome-devtools__take_screenshot({
uid: element.uid,
format: "png",
quality: 85,
filePath: output_file
})
depth_2_captures.append({
"name": element_name,
"type": element.type,
"path": output_file,
"size_kb": file_size_kb(output_file)
})
CATCH error:
REPORT: f"Skip {element_name}: {error}"
layer_map.layers["depth-2"] = {
"type": "elements",
"captures": depth_2_captures
}
TodoWrite(mark_completed: "Depth 2: Elements")
```
**Output**: `depth-2/{element}.png` × N
## Phase 5: Depth 3 - Interaction Level (If depth >= 3)
### Step 1: Analyze Interactive Triggers
```javascript
IF depth < 3: SKIP
TodoWrite(mark_in_progress: "Depth 3: Interactions")
// Detect structure
structure = mcp__chrome-devtools__evaluate_script({
function: `() => ({
modals: document.querySelectorAll('[role="dialog"], .modal').length,
dropdowns: document.querySelectorAll('[role="menu"], .dropdown').length,
tooltips: document.querySelectorAll('[role="tooltip"], [title]').length
})`
})
// Identify triggers
triggers = []
FOR element IN snapshot.interactiveElements:
IF element.attributes CONTAINS ("data-toggle", "aria-haspopup"):
triggers.append({
uid: element.uid,
type: "modal" IF "modal" IN element.classes ELSE "dropdown",
trigger: "click",
text: element.text
})
ELSE IF element.attributes CONTAINS ("title", "data-tooltip"):
triggers.append({
uid: element.uid,
type: "tooltip",
trigger: "hover",
text: element.text
})
triggers = triggers[:10] // Limit
```
### Step 2: Trigger Interactions & Capture
```javascript
depth_3_captures = []
FOR idx, trigger IN enumerate(triggers):
layer_name = f"{trigger.type}-{sanitize(trigger.text[:15]) or idx}"
output_file = f"{base_path}/screenshots/depth-3/{layer_name}.png"
TRY:
// Trigger interaction
IF trigger.trigger == "click":
mcp__chrome-devtools__click({uid: trigger.uid})
ELSE:
mcp__chrome-devtools__hover({uid: trigger.uid})
bash(sleep 1)
// Capture
mcp__chrome-devtools__take_screenshot({
fullPage: false, // Viewport only
format: "png",
quality: 90,
filePath: output_file
})
depth_3_captures.append({
"name": layer_name,
"type": trigger.type,
"trigger_method": trigger.trigger,
"path": output_file,
"size_kb": file_size_kb(output_file)
})
// Dismiss (ESC key)
mcp__chrome-devtools__evaluate_script({
function: `() => {
document.dispatchEvent(new KeyboardEvent('keydown', {key: 'Escape'}));
}`
})
bash(sleep 0.5)
CATCH error:
REPORT: f"Skip {layer_name}: {error}"
layer_map.layers["depth-3"] = {
"type": "interactions",
"triggers": structure,
"captures": depth_3_captures
}
TodoWrite(mark_completed: "Depth 3: Interactions")
```
**Output**: `depth-3/{interaction}.png` × N
## Phase 6: Depth 4 - Embedded Level (If depth >= 4)
### Step 1: Detect Iframes
```javascript
IF depth < 4: SKIP
TodoWrite(mark_in_progress: "Depth 4: Embedded")
iframes = mcp__chrome-devtools__evaluate_script({
function: `() => {
return Array.from(document.querySelectorAll('iframe')).map(iframe => ({
src: iframe.src,
id: iframe.id || 'iframe',
title: iframe.title || 'untitled'
})).filter(i => i.src && i.src.startsWith('http'));
}`
})
```
### Step 2: Capture Iframe Content
```javascript
depth_4_captures = []
FOR idx, iframe IN enumerate(iframes):
iframe_name = f"iframe-{sanitize(iframe.title or iframe.id)}-{idx}"
output_file = f"{base_path}/screenshots/depth-4/{iframe_name}.png"
TRY:
// Navigate to iframe URL in new tab
mcp__chrome-devtools__new_page({url: iframe.src, timeout: 30000})
bash(sleep 2)
mcp__chrome-devtools__take_screenshot({
fullPage: true,
format: "png",
quality: 90,
filePath: output_file
})
depth_4_captures.append({
"name": iframe_name,
"url": iframe.src,
"path": output_file,
"size_kb": file_size_kb(output_file)
})
// Close iframe tab
current_pages = mcp__chrome-devtools__list_pages()
mcp__chrome-devtools__close_page({pageIdx: current_pages.length - 1})
CATCH error:
REPORT: f"Skip {iframe_name}: {error}"
layer_map.layers["depth-4"] = {
"type": "embedded",
"captures": depth_4_captures
}
TodoWrite(mark_completed: "Depth 4: Embedded")
```
**Output**: `depth-4/iframe-*.png` × N
## Phase 7: Depth 5 - Shadow DOM (If depth = 5)
### Step 1: Detect Shadow Roots
```javascript
IF depth < 5: SKIP
TodoWrite(mark_in_progress: "Depth 5: Shadow DOM")
shadow_elements = mcp__chrome-devtools__evaluate_script({
function: `() => {
const elements = Array.from(document.querySelectorAll('*'));
return elements
.filter(el => el.shadowRoot)
.map((el, idx) => ({
tag: el.tagName.toLowerCase(),
id: el.id || \`shadow-\${idx}\`,
innerHTML: el.shadowRoot.innerHTML.substring(0, 100)
}));
}`
})
```
### Step 2: Capture Shadow DOM Components
```javascript
depth_5_captures = []
FOR idx, shadow IN enumerate(shadow_elements):
shadow_name = f"shadow-{sanitize(shadow.id)}"
output_file = f"{base_path}/screenshots/depth-5/{shadow_name}.png"
TRY:
// Inject highlight script
mcp__chrome-devtools__evaluate_script({
function: `() => {
const el = document.querySelector('${shadow.tag}${shadow.id ? "#" + shadow.id : ""}');
if (el) {
el.scrollIntoView({behavior: 'smooth', block: 'center'});
el.style.outline = '3px solid red';
}
}`
})
bash(sleep 0.5)
// Full-page screenshot (component highlighted)
mcp__chrome-devtools__take_screenshot({
fullPage: false,
format: "png",
quality: 90,
filePath: output_file
})
depth_5_captures.append({
"name": shadow_name,
"tag": shadow.tag,
"path": output_file,
"size_kb": file_size_kb(output_file)
})
CATCH error:
REPORT: f"Skip {shadow_name}: {error}"
layer_map.layers["depth-5"] = {
"type": "shadow-dom",
"captures": depth_5_captures
}
TodoWrite(mark_completed: "Depth 5: Shadow DOM")
```
**Output**: `depth-5/shadow-*.png` × N
## Phase 8: Generate Layer Map
### Step 1: Compile Metadata
```javascript
TodoWrite(mark_in_progress: "Generate layer map")
// Calculate totals
total_captures = sum(len(layer.captures) for layer in layer_map.layers.values())
total_size_kb = sum(
sum(c.size_kb for c in layer.captures)
for layer in layer_map.layers.values()
)
layer_map["summary"] = {
"timestamp": current_timestamp(),
"total_depth": depth,
"total_captures": total_captures,
"total_size_kb": total_size_kb
}
Write(f"{base_path}/screenshots/layer-map.json", JSON.stringify(layer_map, indent=2))
TodoWrite(mark_completed: "Generate layer map")
```
**Output**: `layer-map.json`
## Completion
### Todo Update
```javascript
all_todos_completed = true
TodoWrite({todos: all_completed_todos})
```
### Output Message
```
✅ Interactive layer exploration complete!
Configuration:
- URL: {url}
- Max depth: {depth}
- Layers explored: {len(layer_map.layers)}
Capture Summary:
Depth 1 (Page): {depth_1_count} screenshot(s)
Depth 2 (Elements): {depth_2_count} screenshot(s)
Depth 3 (Interactions): {depth_3_count} screenshot(s)
Depth 4 (Embedded): {depth_4_count} screenshot(s)
Depth 5 (Shadow DOM): {depth_5_count} screenshot(s)
Total: {total_captures} captures ({total_size_kb:.1f} KB)
Output Structure:
{base_path}/screenshots/
├── depth-1/
│ └── full-page.png
├── depth-2/
│ ├── navbar.png
│ └── footer.png
├── depth-3/
│ ├── modal-login.png
│ └── dropdown-menu.png
├── depth-4/
│ └── iframe-analytics.png
├── depth-5/
│ └── shadow-button.png
└── layer-map.json
Next: /workflow:ui-design:extract --images "screenshots/**/*.png"
```
## Simple Bash Commands
### Directory Setup
```bash
# Create depth directories
bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done)
```
### Validation
```bash
# Check MCP
all_resources = ListMcpResourcesTool()
# Count captures per depth
bash(ls $base_path/screenshots/depth-{1..5}/*.png 2>/dev/null | wc -l)
```
### File Operations
```bash
# List all captures
bash(find $base_path/screenshots -name "*.png" -type f)
# Total size
bash(du -sh $base_path/screenshots)
```
## Output Structure
```
{base_path}/screenshots/
├── depth-1/
│ └── full-page.png
├── depth-2/
│ ├── {element}.png
│ └── ...
├── depth-3/
│ ├── {interaction}.png
│ └── ...
├── depth-4/
│ ├── iframe-*.png
│ └── ...
├── depth-5/
│ ├── shadow-*.png
│ └── ...
└── layer-map.json
```
## Depth Level Details
| Depth | Name | Captures | Time | Use Case |
|-------|------|----------|------|----------|
| 1 | Page | Full page | 30s | Quick preview |
| 2 | Elements | Key components | 1-2min | Component library |
| 3 | Interactions | Modals, dropdowns | 2-4min | UI flows |
| 4 | Embedded | Iframes | 3-6min | Complete context |
| 5 | Shadow DOM | Web components | 4-8min | Full coverage |
## Error Handling
### Common Errors
```
ERROR: Chrome DevTools MCP required
→ Install: npm i -g @modelcontextprotocol/server-chrome-devtools
ERROR: Invalid depth
→ Use: 1-5
ERROR: Interaction trigger failed
→ Some modals may be skipped, check layer-map.json
```
### Recovery
- **Partial success**: Lower depth captures preserved
- **Trigger failures**: Interaction layer may be incomplete
- **Iframe restrictions**: Cross-origin iframes skipped
## Quality Checklist
- [ ] All depths up to specified level captured
- [ ] layer-map.json generated with metadata
- [ ] File sizes valid (> 500 bytes)
- [ ] Interaction triggers executed
- [ ] Shadow DOM elements highlighted
## Key Features
- **Depth-controlled**: Progressive capture 1-5 levels
- **Interactive triggers**: Click/hover for hidden layers
- **Iframe support**: Embedded content captured
- **Shadow DOM**: Web component internals
- **Structured output**: Organized by depth
## Integration
**Input**: Single URL + depth level (1-5)
**Output**: Hierarchical screenshots + layer-map.json
**Complements**: `/workflow:ui-design:capture` (multi-URL batch)
**Next**: `/workflow:ui-design:extract` for design analysis

2
.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md
View File

@@ -31,7 +31,7 @@ if [ -n "$DESIGN_ID" ]; then
relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
elif [ -n "$SESSION_ID" ]; then
# Latest in session
relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
relative_path=$(find .workflow/sessions/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
else
# Latest globally
relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)

4
.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md
View File

@@ -67,7 +67,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
**Optional Parameters**:
- `--session <id>`: Workflow session ID
- Integrate into existing session (`.workflow/WFS-{session}/`)
- Integrate into existing session (`.workflow/sessions/WFS-{session}/`)
- Enable automatic design system integration (Phase 4)
- If not provided: standalone mode (`.workflow/`)
@@ -184,7 +184,7 @@ design_id = "design-run-$(date +%Y%m%d)-$RANDOM"
IF --session:
session_id = {provided_session}
relative_base_path = ".workflow/WFS-{session_id}/{design_id}"
relative_base_path = ".workflow/sessions/WFS-{session_id}/{design_id}"
session_mode = "integrated"
ELSE:
session_id = null

2
.claude/skills/command-guide/reference/commands/workflow/ui-design/import-from-code.md
View File

@@ -61,7 +61,7 @@ if [ -n "$DESIGN_ID" ]; then
fi
elif [ -n "$SESSION_ID" ]; then
# Latest in session
relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
relative_path=$(find .workflow/sessions/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
if [ -z "$relative_path" ]; then
echo "ERROR: No design run found in session: $SESSION_ID"
echo "HINT: Create a design run first or provide --design-id"

2
.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md
View File

@@ -84,7 +84,7 @@ if [ -n "$DESIGN_ID" ]; then
relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
elif [ -n "$SESSION_ID" ]; then
# Latest in session
relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
relative_path=$(find .workflow/sessions/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
else
# Latest globally
relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)

174
.claude/skills/command-guide/reference/commands/workflow/ui-design/list.md
View File

@@ -1,174 +0,0 @@
---
name: list
description: List all available design runs with metadata (session, created time, prototype count)
argument-hint: [--session <id>]
allowed-tools: Bash(*), Read(*)
---
# List Design Runs (/workflow:ui-design:list)
## Overview
List all available UI design runs across sessions or within a specific session. Displays design IDs with metadata for easy reference.
**Output**: Formatted list with design-id, session, created time, and prototype count
## Implementation
### Step 1: Determine Search Scope
```bash
# Priority: --session > all sessions
search_path=$(if [ -n "$SESSION_ID" ]; then
echo ".workflow/WFS-$SESSION_ID"
else
echo ".workflow"
fi)
```
### Step 2: Find and Display Design Runs
```bash
echo "Available design runs:"
echo ""
# Find all design-run directories
found_count=0
while IFS= read -r line; do
timestamp=$(echo "$line" | cut -d' ' -f1)
path=$(echo "$line" | cut -d' ' -f2-)
# Extract design_id from path
design_id=$(basename "$path")
# Extract session from path
session_id=$(echo "$path" | grep -oP 'WFS-\K[^/]+' || echo "standalone")
# Format created date
created_at=$(date -d "@${timestamp%.*}" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "unknown")
# Count prototypes
prototype_count=$(find "$path/prototypes" -name "*.html" 2>/dev/null | wc -l)
# Display formatted output
echo " - $design_id"
echo " Session: $session_id"
echo " Created: $created_at"
echo " Prototypes: $prototype_count"
echo ""
found_count=$((found_count + 1))
done < <(find "$search_path" -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr)
# Summary
if [ $found_count -eq 0 ]; then
echo " No design runs found."
echo ""
if [ -n "$SESSION_ID" ]; then
echo "💡 HINT: Try running '/workflow:ui-design:explore-auto' to create a design run"
else
echo "💡 HINT: Try running '/workflow:ui-design:explore-auto --session <id>' to create a design run"
fi
else
echo "Total: $found_count design run(s)"
echo ""
echo "💡 USE: /workflow:ui-design:generate --design-id \"<id>\""
echo " OR: /workflow:ui-design:generate --session \"<session>\""
fi
```
### Step 3: Execute List Command
```bash
Bash(
description: "List all UI design runs with metadata",
command: "
search_path=\"${search_path}\"
SESSION_ID=\"${SESSION_ID:-}\"
echo 'Available design runs:'
echo ''
found_count=0
while IFS= read -r line; do
timestamp=\$(echo \"\$line\" | cut -d' ' -f1)
path=\$(echo \"\$line\" | cut -d' ' -f2-)
design_id=\$(basename \"\$path\")
session_id=\$(echo \"\$path\" | grep -oP 'WFS-\\K[^/]+' || echo 'standalone')
created_at=\$(date -d \"@\${timestamp%.*}\" '+%Y-%m-%d %H:%M' 2>/dev/null || echo 'unknown')
prototype_count=\$(find \"\$path/prototypes\" -name '*.html' 2>/dev/null | wc -l)
echo \" - \$design_id\"
echo \" Session: \$session_id\"
echo \" Created: \$created_at\"
echo \" Prototypes: \$prototype_count\"
echo ''
found_count=\$((found_count + 1))
done < <(find \"\$search_path\" -name 'design-run-*' -type d -printf '%T@ %p\\n' 2>/dev/null | sort -nr)
if [ \$found_count -eq 0 ]; then
echo ' No design runs found.'
echo ''
if [ -n \"\$SESSION_ID\" ]; then
echo '💡 HINT: Try running \\'/workflow:ui-design:explore-auto\\' to create a design run'
else
echo '💡 HINT: Try running \\'/workflow:ui-design:explore-auto --session <id>\\' to create a design run'
fi
else
echo \"Total: \$found_count design run(s)\"
echo ''
echo '💡 USE: /workflow:ui-design:generate --design-id \"<id>\"'
echo ' OR: /workflow:ui-design:generate --session \"<session>\"'
fi
"
)
```
## Example Output
### With Session Filter
```
$ /workflow:ui-design:list --session ui-redesign
Available design runs:
- design-run-20250109-143052
Session: ui-redesign
Created: 2025-01-09 14:30
Prototypes: 12
- design-run-20250109-101534
Session: ui-redesign
Created: 2025-01-09 10:15
Prototypes: 6
Total: 2 design run(s)
💡 USE: /workflow:ui-design:generate --design-id "<id>"
OR: /workflow:ui-design:generate --session "<session>"
```
### All Sessions
```
$ /workflow:ui-design:list
Available design runs:
- design-run-20250109-143052
Session: ui-redesign
Created: 2025-01-09 14:30
Prototypes: 12
- design-run-20250108-092314
Session: landing-page
Created: 2025-01-08 09:23
Prototypes: 3
- design-run-20250107-155623
Session: standalone
Created: 2025-01-07 15:56
Prototypes: 8
Total: 3 design run(s)
💡 USE: /workflow:ui-design:generate --design-id "<id>"
OR: /workflow:ui-design:generate --session "<session>"
```

2
.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md
View File

@@ -62,7 +62,7 @@ if [ -n "$DESIGN_ID" ]; then
relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
elif [ -n "$SESSION_ID" ]; then
# Latest in session
relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
relative_path=$(find .workflow/sessions/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
else
# Latest globally
relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)