diff --git a/.claude/agents/cli-execution-agent.md b/.claude/agents/cli-execution-agent.md index 71c4a697..bcf7f7ea 100644 --- a/.claude/agents/cli-execution-agent.md +++ b/.claude/agents/cli-execution-agent.md @@ -190,11 +190,11 @@ cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories **Session Detection**: ```bash -find .workflow/ -name '.active-*' -type f +find .workflow/sessions/ -name 'WFS-*' -type d ``` **Output Paths**: -- **With session**: `.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md` +- **With session**: `.workflow/sessions/WFS-{id}/.chat/{agent}-{timestamp}.md` - **No session**: `.workflow/.scratchpad/{agent}-{description}-{timestamp}.md` **Log Structure**: diff --git a/.claude/commands/cli/execute.md b/.claude/commands/cli/execute.md index bb79b2b3..38f59a99 100644 --- a/.claude/commands/cli/execute.md +++ b/.claude/commands/cli/execute.md @@ -76,8 +76,8 @@ Use `resume --last` when current task extends/relates to previous execution. See ## Workflow Integration -**Session Management**: Auto-detects `.workflow/.active-*` marker -- Active session: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md` +**Session Management**: Auto-detects active session from `.workflow/sessions/` directory +- Active session: Save to `.workflow/sessions/WFS-[id]/.chat/execute-[timestamp].md` - No session: Create new session or save to scratchpad **Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary diff --git a/.claude/commands/memory/docs.md b/.claude/commands/memory/docs.md index fb2b3008..ddc2ccc5 100644 --- a/.claude/commands/memory/docs.md +++ b/.claude/commands/memory/docs.md @@ -63,10 +63,10 @@ Lightweight planner that analyzes project structure, decomposes documentation wo bash(pwd && basename "$(pwd)" && git rev-parse --show-toplevel 2>/dev/null || pwd && date +%Y%m%d-%H%M%S) # Create session directories (replace timestamp) -bash(mkdir -p .workflow/WFS-docs-{timestamp}/.{task,process,summaries} && touch .workflow/.active-WFS-docs-{timestamp}) +bash(mkdir -p .workflow/sessions/WFS-docs-{timestamp}/.{task,process,summaries}) # Create workflow-session.json (replace values) -bash(echo '{"session_id":"WFS-docs-{timestamp}","project":"{project} documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","mode":"full","tool":"gemini","cli_execute":false}' | jq '.' > .workflow/WFS-docs-{timestamp}/workflow-session.json) +bash(echo '{"session_id":"WFS-docs-{timestamp}","project":"{project} documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","mode":"full","tool":"gemini","cli_execute":false}' | jq '.' > .workflow/sessions/WFS-docs-{timestamp}/workflow-session.json) ``` ### Phase 2: Analyze Structure @@ -458,8 +458,7 @@ api_id=$((group_count + 3)) **Unified Structure** (single JSON replaces multiple text files): ``` -.workflow/ -├── .active-WFS-docs-{timestamp} +.workflow/sessions/ └── WFS-docs-{timestamp}/ ├── workflow-session.json # Session metadata ├── IMPL_PLAN.md diff --git a/.claude/commands/workflow/brainstorm/artifacts.md b/.claude/commands/workflow/brainstorm/artifacts.md index 50408f10..7bd06e9d 100644 --- a/.claude/commands/workflow/brainstorm/artifacts.md +++ b/.claude/commands/workflow/brainstorm/artifacts.md @@ -133,7 +133,7 @@ b) {role-name} ({中文名}) ## Execution Phases ### Session Management -- Check `.workflow/sessions/` for active sessions 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 @@ -597,7 +597,6 @@ ELSE: ``` .workflow/sessions/WFS-[topic]/ -├── .active-brainstorming ├── workflow-session.json # Session metadata ONLY └── .brainstorming/ └── guidance-specification.md # Full guidance content diff --git a/.claude/commands/workflow/brainstorm/auto-parallel.md b/.claude/commands/workflow/brainstorm/auto-parallel.md index 20d932fd..7b7a3575 100644 --- a/.claude/commands/workflow/brainstorm/auto-parallel.md +++ b/.claude/commands/workflow/brainstorm/auto-parallel.md @@ -392,16 +392,16 @@ CONTEXT_VARS: ## Session Management -**⚡ FIRST ACTION**: Check `.workflow/sessions/` for active sessions 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 @@ -447,7 +447,6 @@ CONTEXT_VARS: **File Structure**: ``` .workflow/sessions/WFS-[topic]/ -├── .active-brainstorming ├── workflow-session.json # Session metadata ONLY └── .brainstorming/ ├── guidance-specification.md # Framework (Phase 1) diff --git a/.claude/commands/workflow/brainstorm/system-architect.md b/.claude/commands/workflow/brainstorm/system-architect.md index f08e0494..55c1f414 100644 --- a/.claude/commands/workflow/brainstorm/system-architect.md +++ b/.claude/commands/workflow/brainstorm/system-architect.md @@ -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 diff --git a/.claude/commands/workflow/review.md b/.claude/commands/workflow/review.md index aa1e456b..1950d6db 100644 --- a/.claude/commands/workflow/review.md +++ b/.claude/commands/workflow/review.md @@ -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 diff --git a/.claude/skills/command-guide/index/all-commands.json b/.claude/skills/command-guide/index/all-commands.json index 3044c868..7b5de206 100644 --- a/.claude/skills/command-guide/index/all-commands.json +++ b/.claude/skills/command-guide/index/all-commands.json @@ -101,7 +101,7 @@ { "name": "enhance-prompt", "command": "/enhance-prompt", - "description": "Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection", + "description": "Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection", "arguments": "user input to enhance", "category": "general", "subcategory": null, @@ -428,11 +428,33 @@ "difficulty": "Intermediate", "file_path": "workflow/execute.md" }, + { + "name": "init", + "command": "/workflow:init", + "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent", + "arguments": "[--regenerate]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "file_path": "workflow/init.md" + }, + { + "name": "lite-execute", + "command": "/workflow:lite-execute", + "description": "Execute tasks based on in-memory plan, prompt description, or file content", + "arguments": "[--in-memory] [\\\"task description\\\"|file-path]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "implementation", + "difficulty": "Intermediate", + "file_path": "workflow/lite-execute.md" + }, { "name": "lite-plan", "command": "/workflow:lite-plan", - "description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation", - "arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md", + "description": "Lightweight interactive planning workflow with in-memory planning, code exploration, and execution dispatch to lite-execute after user confirmation", + "arguments": "[-e|--explore] \\\"task description\\\"|file.md", "category": "workflow", "subcategory": null, "usage_scenario": "planning", @@ -450,17 +472,6 @@ "difficulty": "Intermediate", "file_path": "workflow/plan.md" }, - { - "name": "resume", - "command": "/workflow:resume", - "description": "Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection", - "arguments": "session-id for workflow session to resume", - "category": "workflow", - "subcategory": null, - "usage_scenario": "session-management", - "difficulty": "Intermediate", - "file_path": "workflow/resume.md" - }, { "name": "review", "command": "/workflow:review", @@ -519,8 +530,8 @@ { "name": "workflow:status", "command": "/workflow:status", - "description": "Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view", - "arguments": "[optional: task-id]", + "description": "Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view", + "arguments": "[optional: --project|task-id|--validate]", "category": "workflow", "subcategory": null, "usage_scenario": "session-management", @@ -692,17 +703,6 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/animation-extract.md" }, - { - "name": "capture", - "command": "/workflow:ui-design:capture", - "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping", - "arguments": "--url-map \"target:url,...\" [--design-id ] [--session ]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Intermediate", - "file_path": "workflow/ui-design/capture.md" - }, { "name": "workflow:ui-design:codify-style", "command": "/workflow:ui-design:codify-style", @@ -714,6 +714,17 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/codify-style.md" }, + { + "name": "design-sync", + "command": "/workflow:ui-design:design-sync", + "description": "Synchronize finalized design system references to brainstorming artifacts, preparing them for /workflow:plan consumption", + "arguments": "--session [--selected-prototypes \"\"]", + "category": "workflow", + "subcategory": "ui-design", + "usage_scenario": "planning", + "difficulty": "Intermediate", + "file_path": "workflow/ui-design/design-sync.md" + }, { "name": "explore-auto", "command": "/workflow:ui-design:explore-auto", @@ -725,17 +736,6 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/explore-auto.md" }, - { - "name": "explore-layers", - "command": "/workflow:ui-design:explore-layers", - "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer", - "arguments": "--url --depth <1-5> [--design-id ] [--session ]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Intermediate", - "file_path": "workflow/ui-design/explore-layers.md" - }, { "name": "generate", "command": "/workflow:ui-design:generate", @@ -780,17 +780,6 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/layout-extract.md" }, - { - "name": "list", - "command": "/workflow:ui-design:list", - "description": "List all available design runs with metadata (session, created time, prototype count)", - "arguments": "[--session ]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Beginner", - "file_path": "workflow/ui-design/list.md" - }, { "name": "workflow:ui-design:reference-page-generator", "command": "/workflow:ui-design:reference-page-generator", @@ -812,16 +801,5 @@ "usage_scenario": "general", "difficulty": "Intermediate", "file_path": "workflow/ui-design/style-extract.md" - }, - { - "name": "update", - "command": "/workflow:ui-design:update", - "description": "Update brainstorming artifacts with finalized design system references from selected prototypes", - "arguments": "--session [--selected-prototypes \"\"]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Intermediate", - "file_path": "workflow/ui-design/update.md" } ] \ No newline at end of file diff --git a/.claude/skills/command-guide/index/by-category.json b/.claude/skills/command-guide/index/by-category.json index 65f67207..9773883d 100644 --- a/.claude/skills/command-guide/index/by-category.json +++ b/.claude/skills/command-guide/index/by-category.json @@ -109,7 +109,7 @@ { "name": "enhance-prompt", "command": "/enhance-prompt", - "description": "Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection", + "description": "Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection", "arguments": "user input to enhance", "category": "general", "subcategory": null, @@ -316,11 +316,33 @@ "difficulty": "Intermediate", "file_path": "workflow/execute.md" }, + { + "name": "init", + "command": "/workflow:init", + "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent", + "arguments": "[--regenerate]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "file_path": "workflow/init.md" + }, + { + "name": "lite-execute", + "command": "/workflow:lite-execute", + "description": "Execute tasks based on in-memory plan, prompt description, or file content", + "arguments": "[--in-memory] [\\\"task description\\\"|file-path]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "implementation", + "difficulty": "Intermediate", + "file_path": "workflow/lite-execute.md" + }, { "name": "lite-plan", "command": "/workflow:lite-plan", - "description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation", - "arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md", + "description": "Lightweight interactive planning workflow with in-memory planning, code exploration, and execution dispatch to lite-execute after user confirmation", + "arguments": "[-e|--explore] \\\"task description\\\"|file.md", "category": "workflow", "subcategory": null, "usage_scenario": "planning", @@ -338,17 +360,6 @@ "difficulty": "Intermediate", "file_path": "workflow/plan.md" }, - { - "name": "resume", - "command": "/workflow:resume", - "description": "Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection", - "arguments": "session-id for workflow session to resume", - "category": "workflow", - "subcategory": null, - "usage_scenario": "session-management", - "difficulty": "Intermediate", - "file_path": "workflow/resume.md" - }, { "name": "review", "command": "/workflow:review", @@ -363,8 +374,8 @@ { "name": "workflow:status", "command": "/workflow:status", - "description": "Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view", - "arguments": "[optional: task-id]", + "description": "Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view", + "arguments": "[optional: --project|task-id|--validate]", "category": "workflow", "subcategory": null, "usage_scenario": "session-management", @@ -720,17 +731,6 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/animation-extract.md" }, - { - "name": "capture", - "command": "/workflow:ui-design:capture", - "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping", - "arguments": "--url-map \"target:url,...\" [--design-id ] [--session ]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Intermediate", - "file_path": "workflow/ui-design/capture.md" - }, { "name": "workflow:ui-design:codify-style", "command": "/workflow:ui-design:codify-style", @@ -742,6 +742,17 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/codify-style.md" }, + { + "name": "design-sync", + "command": "/workflow:ui-design:design-sync", + "description": "Synchronize finalized design system references to brainstorming artifacts, preparing them for /workflow:plan consumption", + "arguments": "--session [--selected-prototypes \"\"]", + "category": "workflow", + "subcategory": "ui-design", + "usage_scenario": "planning", + "difficulty": "Intermediate", + "file_path": "workflow/ui-design/design-sync.md" + }, { "name": "explore-auto", "command": "/workflow:ui-design:explore-auto", @@ -753,17 +764,6 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/explore-auto.md" }, - { - "name": "explore-layers", - "command": "/workflow:ui-design:explore-layers", - "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer", - "arguments": "--url --depth <1-5> [--design-id ] [--session ]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Intermediate", - "file_path": "workflow/ui-design/explore-layers.md" - }, { "name": "generate", "command": "/workflow:ui-design:generate", @@ -808,17 +808,6 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/layout-extract.md" }, - { - "name": "list", - "command": "/workflow:ui-design:list", - "description": "List all available design runs with metadata (session, created time, prototype count)", - "arguments": "[--session ]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Beginner", - "file_path": "workflow/ui-design/list.md" - }, { "name": "workflow:ui-design:reference-page-generator", "command": "/workflow:ui-design:reference-page-generator", @@ -840,17 +829,6 @@ "usage_scenario": "general", "difficulty": "Intermediate", "file_path": "workflow/ui-design/style-extract.md" - }, - { - "name": "update", - "command": "/workflow:ui-design:update", - "description": "Update brainstorming artifacts with finalized design system references from selected prototypes", - "arguments": "--session [--selected-prototypes \"\"]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Intermediate", - "file_path": "workflow/ui-design/update.md" } ] } diff --git a/.claude/skills/command-guide/index/by-use-case.json b/.claude/skills/command-guide/index/by-use-case.json index ee457f9c..34b9816a 100644 --- a/.claude/skills/command-guide/index/by-use-case.json +++ b/.claude/skills/command-guide/index/by-use-case.json @@ -71,7 +71,7 @@ { "name": "enhance-prompt", "command": "/enhance-prompt", - "description": "Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection", + "description": "Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection", "arguments": "user input to enhance", "category": "general", "subcategory": null, @@ -244,6 +244,17 @@ "difficulty": "Intermediate", "file_path": "workflow/brainstorm/ux-expert.md" }, + { + "name": "init", + "command": "/workflow:init", + "description": "Initialize project-level state with intelligent project analysis using cli-explore-agent", + "arguments": "[--regenerate]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "general", + "difficulty": "Intermediate", + "file_path": "workflow/init.md" + }, { "name": "list", "command": "/workflow:session:list", @@ -299,17 +310,6 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/animation-extract.md" }, - { - "name": "capture", - "command": "/workflow:ui-design:capture", - "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping", - "arguments": "--url-map \"target:url,...\" [--design-id ] [--session ]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Intermediate", - "file_path": "workflow/ui-design/capture.md" - }, { "name": "explore-auto", "command": "/workflow:ui-design:explore-auto", @@ -321,17 +321,6 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/explore-auto.md" }, - { - "name": "explore-layers", - "command": "/workflow:ui-design:explore-layers", - "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer", - "arguments": "--url --depth <1-5> [--design-id ] [--session ]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Intermediate", - "file_path": "workflow/ui-design/explore-layers.md" - }, { "name": "imitate-auto", "command": "/workflow:ui-design:imitate-auto", @@ -354,17 +343,6 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/layout-extract.md" }, - { - "name": "list", - "command": "/workflow:ui-design:list", - "description": "List all available design runs with metadata (session, created time, prototype count)", - "arguments": "[--session ]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Beginner", - "file_path": "workflow/ui-design/list.md" - }, { "name": "style-extract", "command": "/workflow:ui-design:style-extract", @@ -375,17 +353,6 @@ "usage_scenario": "general", "difficulty": "Intermediate", "file_path": "workflow/ui-design/style-extract.md" - }, - { - "name": "update", - "command": "/workflow:ui-design:update", - "description": "Update brainstorming artifacts with finalized design system references from selected prototypes", - "arguments": "--session [--selected-prototypes \"\"]", - "category": "workflow", - "subcategory": "ui-design", - "usage_scenario": "general", - "difficulty": "Intermediate", - "file_path": "workflow/ui-design/update.md" } ], "implementation": [ @@ -444,6 +411,17 @@ "difficulty": "Intermediate", "file_path": "workflow/execute.md" }, + { + "name": "lite-execute", + "command": "/workflow:lite-execute", + "description": "Execute tasks based on in-memory plan, prompt description, or file content", + "arguments": "[--in-memory] [\\\"task description\\\"|file-path]", + "category": "workflow", + "subcategory": null, + "usage_scenario": "implementation", + "difficulty": "Intermediate", + "file_path": "workflow/lite-execute.md" + }, { "name": "test-cycle-execute", "command": "/workflow:test-cycle-execute", @@ -592,8 +570,8 @@ { "name": "lite-plan", "command": "/workflow:lite-plan", - "description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation", - "arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md", + "description": "Lightweight interactive planning workflow with in-memory planning, code exploration, and execution dispatch to lite-execute after user confirmation", + "arguments": "[-e|--explore] \\\"task description\\\"|file.md", "category": "workflow", "subcategory": null, "usage_scenario": "planning", @@ -633,6 +611,17 @@ "difficulty": "Intermediate", "file_path": "workflow/ui-design/codify-style.md" }, + { + "name": "design-sync", + "command": "/workflow:ui-design:design-sync", + "description": "Synchronize finalized design system references to brainstorming artifacts, preparing them for /workflow:plan consumption", + "arguments": "--session [--selected-prototypes \"\"]", + "category": "workflow", + "subcategory": "ui-design", + "usage_scenario": "planning", + "difficulty": "Intermediate", + "file_path": "workflow/ui-design/design-sync.md" + }, { "name": "workflow:ui-design:import-from-code", "command": "/workflow:ui-design:import-from-code", @@ -725,17 +714,6 @@ } ], "session-management": [ - { - "name": "resume", - "command": "/workflow:resume", - "description": "Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection", - "arguments": "session-id for workflow session to resume", - "category": "workflow", - "subcategory": null, - "usage_scenario": "session-management", - "difficulty": "Intermediate", - "file_path": "workflow/resume.md" - }, { "name": "complete", "command": "/workflow:session:complete", @@ -761,8 +739,8 @@ { "name": "workflow:status", "command": "/workflow:status", - "description": "Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view", - "arguments": "[optional: task-id]", + "description": "Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view", + "arguments": "[optional: --project|task-id|--validate]", "category": "workflow", "subcategory": null, "usage_scenario": "session-management", diff --git a/.claude/skills/command-guide/index/essential-commands.json b/.claude/skills/command-guide/index/essential-commands.json index e1fe7b39..4196e574 100644 --- a/.claude/skills/command-guide/index/essential-commands.json +++ b/.claude/skills/command-guide/index/essential-commands.json @@ -24,8 +24,8 @@ { "name": "workflow:status", "command": "/workflow:status", - "description": "Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view", - "arguments": "[optional: task-id]", + "description": "Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view", + "arguments": "[optional: --project|task-id|--validate]", "category": "workflow", "subcategory": null, "usage_scenario": "session-management", @@ -109,17 +109,6 @@ "difficulty": "Intermediate", "file_path": "workflow/action-plan-verify.md" }, - { - "name": "resume", - "command": "/workflow:resume", - "description": "Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection", - "arguments": "session-id for workflow session to resume", - "category": "workflow", - "subcategory": null, - "usage_scenario": "session-management", - "difficulty": "Intermediate", - "file_path": "workflow/resume.md" - }, { "name": "review", "command": "/workflow:review", @@ -145,7 +134,7 @@ { "name": "enhance-prompt", "command": "/enhance-prompt", - "description": "Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection", + "description": "Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection", "arguments": "user input to enhance", "category": "general", "subcategory": null, diff --git a/.claude/skills/command-guide/reference/agents/cli-execution-agent.md b/.claude/skills/command-guide/reference/agents/cli-execution-agent.md index 71c4a697..bcf7f7ea 100644 --- a/.claude/skills/command-guide/reference/agents/cli-execution-agent.md +++ b/.claude/skills/command-guide/reference/agents/cli-execution-agent.md @@ -190,11 +190,11 @@ cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories **Session Detection**: ```bash -find .workflow/ -name '.active-*' -type f +find .workflow/sessions/ -name 'WFS-*' -type d ``` **Output Paths**: -- **With session**: `.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md` +- **With session**: `.workflow/sessions/WFS-{id}/.chat/{agent}-{timestamp}.md` - **No session**: `.workflow/.scratchpad/{agent}-{description}-{timestamp}.md` **Log Structure**: diff --git a/.claude/skills/command-guide/reference/agents/cli-explore-agent.md b/.claude/skills/command-guide/reference/agents/cli-explore-agent.md index 13b565ef..d174905b 100644 --- a/.claude/skills/command-guide/reference/agents/cli-explore-agent.md +++ b/.claude/skills/command-guide/reference/agents/cli-explore-agent.md @@ -22,7 +22,7 @@ description: | - Progressive disclosure: Quick overview → detailed analysis → dependency deep-dive - Context-aware filtering based on task requirements -color: blue +color: yellow --- You are a specialized **CLI Exploration Agent** that executes read-only code analysis tasks autonomously to discover module structures, map dependencies, and understand architectural patterns. @@ -513,37 +513,19 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code- - Use Gemini semantic analysis as tiebreaker - Document uncertainty in report with attribution -## Integration with Other Agents +## Available Tools & Services -### As Service Provider (Called by Others) - -**Planning Agents** (`action-planning-agent`, `conceptual-planning-agent`): -- **Use Case**: Pre-planning reconnaissance to understand existing code -- **Input**: Task description + focus areas -- **Output**: Structural overview + dependency analysis -- **Flow**: Planning agent → CLI explore agent (quick-scan) → Context for planning - -**Execution Agents** (`code-developer`, `cli-execution-agent`): -- **Use Case**: Refactoring impact analysis before code modifications -- **Input**: Target files/functions to modify -- **Output**: Dependency map + risk assessment -- **Flow**: Execution agent → CLI explore agent (dependency-map) → Safe modification strategy - -**UI Design Agent** (`ui-design-agent`): -- **Use Case**: Discover existing UI components and design tokens -- **Input**: Component directory + file patterns -- **Output**: Component inventory + styling patterns -- **Flow**: UI agent delegates structure analysis to CLI explore agent - -### As Consumer (Calls Others) +This agent can leverage the following tools to enhance analysis: **Context Search Agent** (`context-search-agent`): - **Use Case**: Get project-wide context before analysis -- **Flow**: CLI explore agent → Context search agent → Enhanced analysis with full context +- **When to use**: Need comprehensive project understanding beyond file structure +- **Integration**: Call context-search-agent first, then use results to guide exploration -**MCP Tools**: +**MCP Tools** (Code Index): - **Use Case**: Enhanced file discovery and search capabilities -- **Flow**: CLI explore agent → Code Index MCP → Faster pattern discovery +- **When to use**: Large codebases requiring fast pattern discovery +- **Integration**: Prefer Code Index MCP when available, fallback to rg/bash tools ## Key Reminders @@ -636,52 +618,3 @@ rg "^import .*;" --type java -n # Find test files find . -name "*Test.java" -o -name "*Tests.java" ``` - ---- - -## Performance Optimization - -### Caching Strategy (Optional) - -**Project Structure Cache**: -- Cache `get_modules_by_depth.sh` output for 1 hour -- Invalidate on file system changes (watch .git/index) - -**Pattern Match Cache**: -- Cache rg results for common patterns (class/function definitions) -- Invalidate on file modifications - -**Gemini Analysis Cache**: -- Cache semantic analysis results for unchanged files -- Key: file_path + content_hash -- TTL: 24 hours - -### Parallel Execution - -**Quick-Scan Mode**: -- Run rg searches in parallel (classes, functions, imports) -- Merge results after completion - -**Deep-Scan Mode**: -- Execute Bash scan (Phase 1) and Gemini setup concurrently -- Wait for Phase 1 completion before Phase 2 (Gemini needs context) - -**Dependency-Map Mode**: -- Discover imports and exports in parallel -- Build graph after all discoveries complete - -### Resource Limits - -**File Count Limits**: -- Quick-scan: Unlimited (filtered by relevance) -- Deep-scan: Max 100 files for Gemini analysis -- Dependency-map: Max 500 modules for graph construction - -**Timeout Limits**: -- Quick-scan: 30 seconds (bash-only, fast) -- Deep-scan: 5 minutes (includes Gemini CLI) -- Dependency-map: 10 minutes (graph construction + analysis) - -**Memory Limits**: -- Limit rg output to 10MB (use --max-count) -- Stream large outputs instead of loading into memory diff --git a/.claude/skills/command-guide/reference/agents/cli-lite-planning-agent.md b/.claude/skills/command-guide/reference/agents/cli-lite-planning-agent.md new file mode 100644 index 00000000..5f060b50 --- /dev/null +++ b/.claude/skills/command-guide/reference/agents/cli-lite-planning-agent.md @@ -0,0 +1,724 @@ +--- +name: cli-lite-planning-agent +description: | + Specialized agent for executing CLI planning tools (Gemini/Qwen) to generate detailed implementation plans with actionable task breakdowns. Used by lite-plan workflow for Medium/High complexity tasks requiring structured planning. + + Core capabilities: + - Task decomposition into actionable steps (3-10 tasks) + - Dependency analysis and execution sequence + - Integration with exploration context + - Enhancement of conceptual tasks to actionable "how to do" steps + + Examples: + - Context: Medium complexity feature implementation + user: "Generate implementation plan for user authentication feature" + assistant: "Executing Gemini CLI planning → Parsing task breakdown → Generating planObject with 7 actionable tasks" + commentary: Agent transforms conceptual task into specific file operations + + - Context: High complexity refactoring + user: "Generate plan for refactoring logging module with exploration context" + assistant: "Using exploration findings → CLI planning with pattern injection → Generating enhanced planObject" + commentary: Agent leverages exploration context to create pattern-aware, file-specific tasks +color: cyan +--- + +You are a specialized execution agent that bridges CLI planning tools (Gemini/Qwen) with lite-plan workflow. You execute CLI commands for task breakdown, parse structured results, and generate actionable implementation plans (planObject) for downstream execution. + +## Execution Process + +### Input Processing + +**What you receive (Context Package)**: +```javascript +{ + "task_description": "User's original task description", + "explorationContext": { + "project_structure": "Overall architecture description", + "relevant_files": ["file1.ts", "file2.ts", "..."], + "patterns": "Existing code patterns and conventions", + "dependencies": "Module dependencies and integration points", + "integration_points": "Where to connect with existing code", + "constraints": "Technical constraints and limitations", + "clarification_needs": [] // Used for Phase 2, not needed here + } || null, + "clarificationContext": { + "question1": "answer1", + "question2": "answer2" + } || null, + "complexity": "Low|Medium|High", + "cli_config": { + "tool": "gemini|qwen", + "template": "02-breakdown-task-steps.txt", + "timeout": 3600000, // 60 minutes for planning + "fallback": "qwen" + } +} +``` + +**Context Enrichment Strategy**: +```javascript +// Merge task description with exploration findings +const enrichedContext = { + task_description: task_description, + relevant_files: explorationContext?.relevant_files || [], + patterns: explorationContext?.patterns || "No patterns identified", + dependencies: explorationContext?.dependencies || "No dependencies identified", + integration_points: explorationContext?.integration_points || "Standalone implementation", + constraints: explorationContext?.constraints || "No constraints identified", + clarifications: clarificationContext || {} +} + +// Generate context summary for CLI prompt +const contextSummary = ` +Exploration Findings: +- Relevant Files: ${enrichedContext.relevant_files.join(', ')} +- Patterns: ${enrichedContext.patterns} +- Dependencies: ${enrichedContext.dependencies} +- Integration: ${enrichedContext.integration_points} +- Constraints: ${enrichedContext.constraints} + +User Clarifications: +${Object.entries(enrichedContext.clarifications).map(([q, a]) => `- ${q}: ${a}`).join('\n')} +` +``` + +### Execution Flow (Three-Phase) + +``` +Phase 1: Context Preparation & CLI Execution +1. Validate context package and extract task context +2. Merge task description with exploration and clarification context +3. Construct CLI command with planning template +4. Execute Gemini/Qwen CLI tool with timeout (60 minutes) +5. Handle errors and fallback to alternative tool if needed +6. Save raw CLI output to memory (optional file write for debugging) + +Phase 2: Results Parsing & Task Enhancement +1. Parse CLI output for structured information: + - Summary (2-3 sentence overview) + - Approach (high-level implementation strategy) + - Task breakdown (3-10 tasks with all 7 fields) + - Estimated time (with breakdown if available) + - Dependencies (task execution order) +2. Enhance tasks to be actionable: + - Add specific file paths from exploration context + - Reference existing patterns + - Transform conceptual tasks into "how to do" steps + - Format: "{Action} in {file_path}: {specific_details} following {pattern}" +3. Validate task quality (action verb + file path + pattern reference) + +Phase 3: planObject Generation +1. Build planObject structure from parsed and enhanced results +2. Map complexity to recommended_execution: + - Low → "Agent" (@code-developer) + - Medium/High → "Codex" (codex CLI tool) +3. Return planObject (in-memory, no file writes) +4. Return success status to orchestrator (lite-plan) +``` + +## Core Functions + +### 1. CLI Planning Execution + +**Template-Based Command Construction**: +```bash +cd {project_root} && {cli_tool} -p " +PURPOSE: Generate detailed implementation plan for {complexity} complexity task with structured actionable task breakdown +TASK: +• Analyze task requirements: {task_description} +• Break down into 3-10 structured task objects with complete implementation guidance +• For each task, provide: + - Title and target file + - Action type (Create|Update|Implement|Refactor|Add|Delete) + - Description (what to implement) + - Implementation steps (how to do it, 3-7 specific steps) + - Reference (which patterns/files to follow, with specific examples) + - Acceptance criteria (verification checklist) +• Identify dependencies and execution sequence +• Provide realistic time estimates with breakdown +MODE: analysis +CONTEXT: @**/* | Memory: {exploration_context_summary} +EXPECTED: Structured plan with the following format: + +## Implementation Summary +[2-3 sentence overview] + +## High-Level Approach +[Strategy with pattern references] + +## Task Breakdown + +### Task 1: [Title] +**File**: [file/path.ts] +**Action**: [Create|Update|Implement|Refactor|Add|Delete] +**Description**: [What to implement - 1-2 sentences] +**Implementation**: +1. [Specific step 1 - how to do it] +2. [Specific step 2 - concrete action] +3. [Specific step 3 - implementation detail] +4. [Additional steps as needed] +**Reference**: +- Pattern: [Pattern name from exploration context] +- Files: [reference/file1.ts], [reference/file2.ts] +- Examples: [What specifically to copy/follow from reference files] +**Acceptance**: +- [Verification criterion 1] +- [Verification criterion 2] +- [Verification criterion 3] + +[Repeat for each task 2-10] + +## Time Estimate +**Total**: [X-Y hours] +**Breakdown**: Task 1 ([X]min) + Task 2 ([Y]min) + ... + +## Dependencies +- Task 2 depends on Task 1 (requires authentication service) +- Tasks 3-5 can run in parallel +- Task 6 requires all previous tasks + +RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/02-breakdown-task-steps.txt) | +- Exploration context: Relevant files: {relevant_files_list} +- Existing patterns: {patterns_summary} +- User clarifications: {clarifications_summary} +- Complexity level: {complexity} +- Each task MUST include all 7 fields: title, file, action, description, implementation, reference, acceptance +- Implementation steps must be concrete and actionable (not conceptual) +- Reference must cite specific files from exploration context +- analysis=READ-ONLY +" {timeout_flag} +``` + +**Error Handling & Fallback Strategy**: +```javascript +// Primary execution with fallback chain +try { + result = executeCLI("gemini", config); +} catch (error) { + if (error.code === 429 || error.code === 404) { + console.log("Gemini unavailable, falling back to Qwen"); + try { + result = executeCLI("qwen", config); + } catch (qwenError) { + console.error("Both Gemini and Qwen failed"); + // Return degraded mode with basic plan + return { + status: "degraded", + message: "CLI planning failed, using fallback strategy", + planObject: generateBasicPlan(task_description, explorationContext) + }; + } + } else { + throw error; + } +} + +// Fallback plan generation when all CLI tools fail +function generateBasicPlan(taskDesc, exploration) { + const relevantFiles = exploration?.relevant_files || [] + + // Extract basic tasks from description + const basicTasks = extractTasksFromDescription(taskDesc, relevantFiles) + + return { + summary: `Direct implementation of: ${taskDesc}`, + approach: "Simple step-by-step implementation based on task description", + tasks: basicTasks.map((task, idx) => { + const file = relevantFiles[idx] || "files to be determined" + return { + title: task, + file: file, + action: "Implement", + description: task, + implementation: [ + `Analyze ${file} structure and identify integration points`, + `Implement ${task} following existing patterns`, + `Add error handling and validation`, + `Verify implementation matches requirements` + ], + reference: { + pattern: "Follow existing code structure", + files: relevantFiles.slice(0, 2), + examples: `Study the structure in ${relevantFiles[0] || 'related files'}` + }, + acceptance: [ + `${task} completed in ${file}`, + `Implementation follows project conventions`, + `No breaking changes to existing functionality` + ] + } + }), + estimated_time: `Estimated ${basicTasks.length * 30} minutes (${basicTasks.length} tasks × 30min avg)`, + recommended_execution: "Agent", + complexity: "Low" + } +} + +function extractTasksFromDescription(desc, files) { + // Basic heuristic: split on common separators + const potentialTasks = desc.split(/[,;]|\band\b/) + .map(s => s.trim()) + .filter(s => s.length > 10) + + if (potentialTasks.length >= 3) { + return potentialTasks.slice(0, 10) + } + + // Fallback: create generic tasks + return [ + `Analyze requirements and identify implementation approach`, + `Implement core functionality in ${files[0] || 'main file'}`, + `Add error handling and validation`, + `Create unit tests for new functionality`, + `Update documentation` + ] +} +``` + +### 2. Output Parsing & Enhancement + +**Structured Task Parsing**: +```javascript +// Parse CLI output for structured tasks +function extractStructuredTasks(cliOutput) { + const tasks = [] + const taskPattern = /### Task \d+: (.+?)\n\*\*File\*\*: (.+?)\n\*\*Action\*\*: (.+?)\n\*\*Description\*\*: (.+?)\n\*\*Implementation\*\*:\n((?:\d+\. .+?\n)+)\*\*Reference\*\*:\n((?:- .+?\n)+)\*\*Acceptance\*\*:\n((?:- .+?\n)+)/g + + let match + while ((match = taskPattern.exec(cliOutput)) !== null) { + // Parse implementation steps + const implementation = match[5].trim() + .split('\n') + .map(s => s.replace(/^\d+\. /, '')) + .filter(s => s.length > 0) + + // Parse reference fields + const referenceText = match[6].trim() + const patternMatch = /- Pattern: (.+)/m.exec(referenceText) + const filesMatch = /- Files: (.+)/m.exec(referenceText) + const examplesMatch = /- Examples: (.+)/m.exec(referenceText) + + const reference = { + pattern: patternMatch ? patternMatch[1].trim() : "No pattern specified", + files: filesMatch ? filesMatch[1].split(',').map(f => f.trim()) : [], + examples: examplesMatch ? examplesMatch[1].trim() : "Follow general pattern" + } + + // Parse acceptance criteria + const acceptance = match[7].trim() + .split('\n') + .map(s => s.replace(/^- /, '')) + .filter(s => s.length > 0) + + tasks.push({ + title: match[1].trim(), + file: match[2].trim(), + action: match[3].trim(), + description: match[4].trim(), + implementation: implementation, + reference: reference, + acceptance: acceptance + }) + } + + return tasks +} + +const parsedResults = { + summary: extractSection("Implementation Summary"), + approach: extractSection("High-Level Approach"), + raw_tasks: extractStructuredTasks(cliOutput), + time_estimate: extractSection("Time Estimate"), + dependencies: extractSection("Dependencies") +} +``` + +**Validation & Enhancement**: +```javascript +// Validate and enhance tasks if CLI output is incomplete +function validateAndEnhanceTasks(rawTasks, explorationContext) { + return rawTasks.map(taskObj => { + // Validate required fields + const validated = { + title: taskObj.title || "Unnamed task", + file: taskObj.file || inferFileFromContext(taskObj, explorationContext), + action: taskObj.action || inferAction(taskObj.title), + description: taskObj.description || taskObj.title, + implementation: taskObj.implementation?.length > 0 + ? taskObj.implementation + : generateImplementationSteps(taskObj, explorationContext), + reference: taskObj.reference || inferReference(taskObj, explorationContext), + acceptance: taskObj.acceptance?.length > 0 + ? taskObj.acceptance + : generateAcceptanceCriteria(taskObj) + } + + return validated + }) +} + +// Helper functions for inference +function inferFileFromContext(taskObj, explorationContext) { + const relevantFiles = explorationContext?.relevant_files || [] + const titleLower = taskObj.title.toLowerCase() + const matchedFile = relevantFiles.find(f => + titleLower.includes(f.split('/').pop().split('.')[0].toLowerCase()) + ) + return matchedFile || "file-to-be-determined.ts" +} + +function inferAction(title) { + if (/create|add new|implement/i.test(title)) return "Create" + if (/update|modify|change/i.test(title)) return "Update" + if (/refactor/i.test(title)) return "Refactor" + if (/delete|remove/i.test(title)) return "Delete" + return "Implement" +} + +function generateImplementationSteps(taskObj, explorationContext) { + const patterns = explorationContext?.patterns || "" + return [ + `Analyze ${taskObj.file} structure and identify integration points`, + `Implement ${taskObj.title} following ${patterns || 'existing patterns'}`, + `Add error handling and validation`, + `Update related components if needed`, + `Verify implementation matches requirements` + ] +} + +function inferReference(taskObj, explorationContext) { + const patterns = explorationContext?.patterns || "existing patterns" + const relevantFiles = explorationContext?.relevant_files || [] + + return { + pattern: patterns.split('.')[0] || "Follow existing code structure", + files: relevantFiles.slice(0, 2), + examples: `Study the structure and methods in ${relevantFiles[0] || 'related files'}` + } +} + +function generateAcceptanceCriteria(taskObj) { + return [ + `${taskObj.title} completed in ${taskObj.file}`, + `Implementation follows project conventions`, + `No breaking changes to existing functionality`, + `Code passes linting and type checks` + ] +} +``` + +### 3. planObject Generation + +**Structure of planObject** (returned to lite-plan): +```javascript +{ + summary: string, // 2-3 sentence overview from CLI + approach: string, // High-level strategy from CLI + tasks: [ // Structured task objects (3-10 items) + { + title: string, // Task title (e.g., "Create AuthService") + file: string, // Target file path + action: string, // Action type: Create|Update|Implement|Refactor|Add|Delete + description: string, // What to implement (1-2 sentences) + implementation: string[], // Step-by-step how to do it (3-7 steps) + reference: { // What to reference + pattern: string, // Pattern name (e.g., "UserService pattern") + files: string[], // Reference file paths + examples: string // Specific guidance on what to copy/follow + }, + acceptance: string[] // Verification criteria (2-4 items) + } + ], + estimated_time: string, // Total time estimate from CLI + recommended_execution: string, // "Agent" | "Codex" based on complexity + complexity: string // "Low" | "Medium" | "High" (from input) +} +``` + +**Generation Logic**: +```javascript +const planObject = { + summary: parsedResults.summary || `Implementation plan for: ${task_description.slice(0, 100)}`, + + approach: parsedResults.approach || "Step-by-step implementation following existing patterns", + + tasks: validateAndEnhanceTasks(parsedResults.raw_tasks, explorationContext), + + estimated_time: parsedResults.time_estimate || estimateTimeFromTaskCount(parsedResults.raw_tasks.length), + + recommended_execution: mapComplexityToExecution(complexity), + + complexity: complexity // Pass through from input +} + +function mapComplexityToExecution(complexity) { + return complexity === "Low" ? "Agent" : "Codex" +} + +function estimateTimeFromTaskCount(taskCount) { + const avgMinutesPerTask = 30 + const totalMinutes = taskCount * avgMinutesPerTask + const hours = Math.floor(totalMinutes / 60) + const minutes = totalMinutes % 60 + + if (hours === 0) { + return `${minutes} minutes (${taskCount} tasks × ${avgMinutesPerTask}min avg)` + } + return `${hours}h ${minutes}m (${taskCount} tasks × ${avgMinutesPerTask}min avg)` +} +``` + +## Quality Standards + +### CLI Execution Standards +- **Timeout Management**: Use dynamic timeout (3600000ms = 60min for planning) +- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail) +- **Error Context**: Include full error details in failure reports +- **Output Preservation**: Optionally save raw CLI output for debugging + +### Task Object Standards + +**Completeness** - Each task must have all 7 required fields: +- **title**: Clear, concise task name +- **file**: Exact file path (from exploration.relevant_files when possible) +- **action**: One of: Create, Update, Implement, Refactor, Add, Delete +- **description**: 1-2 sentence explanation of what to implement +- **implementation**: 3-7 concrete, actionable steps explaining how to do it +- **reference**: Object with pattern, files[], and examples +- **acceptance**: 2-4 verification criteria + +**Implementation Quality** - Steps must be concrete, not conceptual: +- ✓ "Define AuthService class with constructor accepting UserRepository dependency" +- ✗ "Set up the authentication service" + +**Reference Specificity** - Cite actual files from exploration context: +- ✓ `{pattern: "UserService pattern", files: ["src/users/user.service.ts"], examples: "Follow constructor injection and async method patterns"}` +- ✗ `{pattern: "service pattern", files: [], examples: "follow patterns"}` + +**Acceptance Measurability** - Criteria must be verifiable: +- ✓ "AuthService class created with login(), logout(), validateToken() methods" +- ✗ "Service works correctly" + +### Task Validation + +**Validation Function**: +```javascript +function validateTaskObject(task) { + const errors = [] + + // Validate required fields + if (!task.title || task.title.trim().length === 0) { + errors.push("Missing title") + } + if (!task.file || task.file.trim().length === 0) { + errors.push("Missing file path") + } + if (!task.action || !['Create', 'Update', 'Implement', 'Refactor', 'Add', 'Delete'].includes(task.action)) { + errors.push(`Invalid action: ${task.action}`) + } + if (!task.description || task.description.trim().length === 0) { + errors.push("Missing description") + } + if (!task.implementation || task.implementation.length < 3) { + errors.push("Implementation must have at least 3 steps") + } + if (!task.reference || !task.reference.pattern) { + errors.push("Missing pattern reference") + } + if (!task.acceptance || task.acceptance.length < 2) { + errors.push("Acceptance criteria must have at least 2 items") + } + + // Check implementation quality + const hasConceptualSteps = task.implementation?.some(step => + /^(handle|manage|deal with|set up|work on)/i.test(step) + ) + if (hasConceptualSteps) { + errors.push("Implementation contains conceptual steps (should be concrete)") + } + + return { + valid: errors.length === 0, + errors: errors + } +} +``` + +**Good vs Bad Examples**: +```javascript +// ❌ BAD (Incomplete, vague) +{ + title: "Add authentication", + file: "auth.ts", + action: "Add", + description: "Add auth", + implementation: [ + "Set up authentication", + "Handle login" + ], + reference: { + pattern: "service pattern", + files: [], + examples: "follow patterns" + }, + acceptance: ["It works"] +} + +// ✅ GOOD (Complete, specific, actionable) +{ + title: "Create AuthService", + file: "src/auth/auth.service.ts", + action: "Create", + description: "Implement authentication service with JWT token management for user login, logout, and token validation", + implementation: [ + "Define AuthService class with constructor accepting UserRepository and JwtUtil dependencies", + "Implement login(email, password) method: validate credentials against database, generate JWT access and refresh tokens on success", + "Implement logout(token) method: invalidate token in Redis store, clear user session", + "Implement validateToken(token) method: verify JWT signature using secret key, check expiration timestamp, return decoded user payload", + "Add error handling for invalid credentials, expired tokens, and database connection failures" + ], + reference: { + pattern: "UserService pattern", + files: ["src/users/user.service.ts", "src/utils/jwt.util.ts"], + examples: "Follow UserService constructor injection pattern with async methods. Use JwtUtil.generateToken() and JwtUtil.verifyToken() for token operations" + }, + acceptance: [ + "AuthService class created with login(), logout(), validateToken() methods", + "Methods follow UserService async/await pattern with try-catch error handling", + "JWT token generation uses JwtUtil with 1h access token and 7d refresh token expiry", + "All methods return typed responses (success/error objects)" + ] +} +``` + +## Key Reminders + +**ALWAYS:** +- **Validate context package**: Ensure task_description present before CLI execution +- **Handle CLI errors gracefully**: Use fallback chain (Gemini → Qwen → degraded mode) +- **Parse CLI output structurally**: Extract all 7 task fields (title, file, action, description, implementation, reference, acceptance) +- **Validate task objects**: Each task must have all required fields with quality content +- **Generate complete planObject**: All fields populated with structured task objects +- **Return in-memory result**: No file writes unless debugging +- **Preserve exploration context**: Use relevant_files and patterns in task references +- **Ensure implementation concreteness**: Steps must be actionable, not conceptual +- **Cite specific references**: Reference actual files from exploration context + +**NEVER:** +- Execute implementation directly (return plan, let lite-execute handle execution) +- Skip CLI planning (always run CLI even for simple tasks, unless degraded mode) +- Return vague task objects (validate all required fields) +- Use conceptual implementation steps ("set up", "handle", "manage") +- Modify files directly (planning only, no implementation) +- Exceed timeout limits (use configured timeout value) +- Return tasks with empty reference files (cite actual exploration files) +- Skip task validation (all task objects must pass quality checks) + +## Configuration & Examples + +### CLI Tool Configuration + +**Gemini Configuration**: +```javascript +{ + "tool": "gemini", + "model": "gemini-2.5-pro", // Auto-selected, no need to specify + "templates": { + "task-breakdown": "02-breakdown-task-steps.txt", + "architecture-planning": "01-plan-architecture-design.txt", + "component-design": "02-design-component-spec.txt" + }, + "timeout": 3600000 // 60 minutes +} +``` + +**Qwen Configuration (Fallback)**: +```javascript +{ + "tool": "qwen", + "model": "coder-model", // Auto-selected + "templates": { + "task-breakdown": "02-breakdown-task-steps.txt", + "architecture-planning": "01-plan-architecture-design.txt" + }, + "timeout": 3600000 // 60 minutes +} +``` + +### Example Execution + +**Input Context**: +```json +{ + "task_description": "Implement user authentication with JWT tokens", + "explorationContext": { + "project_structure": "Express.js REST API with TypeScript, layered architecture (routes → services → repositories)", + "relevant_files": [ + "src/users/user.service.ts", + "src/users/user.repository.ts", + "src/middleware/cors.middleware.ts", + "src/routes/api.ts" + ], + "patterns": "Service-Repository pattern used throughout. Services in src/{module}/{module}.service.ts, Repositories in src/{module}/{module}.repository.ts. Middleware follows function-based approach in src/middleware/", + "dependencies": "Express, TypeORM, bcrypt for password hashing", + "integration_points": "Auth service needs to integrate with existing user service and API routes", + "constraints": "Must use existing TypeORM entities, follow established error handling patterns" + }, + "clarificationContext": { + "token_expiry": "1 hour access token, 7 days refresh token", + "password_requirements": "Min 8 chars, must include number and special char" + }, + "complexity": "Medium", + "cli_config": { + "tool": "gemini", + "template": "02-breakdown-task-steps.txt", + "timeout": 3600000 + } +} +``` + +**Execution Summary**: +1. **Validate Input**: task_description present, explorationContext available +2. **Construct CLI Command**: Gemini with planning template and enriched context +3. **Execute CLI**: Gemini runs and returns structured plan (timeout: 60min) +4. **Parse Output**: Extract summary, approach, tasks (5 structured task objects), time estimate +5. **Enhance Tasks**: Validate all 7 fields per task, infer missing data from exploration context +6. **Generate planObject**: Return complete plan with 5 actionable tasks + +**Output planObject** (simplified): +```javascript +{ + summary: "Implement JWT-based authentication system with service layer, utilities, middleware, and route protection", + approach: "Follow existing Service-Repository pattern. Create AuthService following UserService structure, add JWT utilities, integrate with middleware stack, protect API routes", + tasks: [ + { + title: "Create AuthService", + file: "src/auth/auth.service.ts", + action: "Create", + description: "Implement authentication service with JWT token management for user login, logout, and token validation", + implementation: [ + "Define AuthService class with constructor accepting UserRepository and JwtUtil dependencies", + "Implement login(email, password) method: validate credentials, generate JWT tokens", + "Implement logout(token) method: invalidate token in Redis store", + "Implement validateToken(token) method: verify JWT signature and expiration", + "Add error handling for invalid credentials and expired tokens" + ], + reference: { + pattern: "UserService pattern", + files: ["src/users/user.service.ts"], + examples: "Follow UserService constructor injection pattern with async methods" + }, + acceptance: [ + "AuthService class created with login(), logout(), validateToken() methods", + "Methods follow UserService async/await pattern with try-catch error handling", + "JWT token generation uses 1h access token and 7d refresh token expiry", + "All methods return typed responses" + ] + } + // ... 4 more tasks (JWT utilities, auth middleware, route protection, tests) + ], + estimated_time: "3-4 hours (1h service + 30m utils + 1h middleware + 30m routes + 1h tests)", + recommended_execution: "Codex", + complexity: "Medium" +} +``` diff --git a/.claude/skills/command-guide/reference/agents/cli-planning-agent.md b/.claude/skills/command-guide/reference/agents/cli-planning-agent.md index cb7e9905..e9d75fad 100644 --- a/.claude/skills/command-guide/reference/agents/cli-planning-agent.md +++ b/.claude/skills/command-guide/reference/agents/cli-planning-agent.md @@ -10,7 +10,7 @@ description: | commentary: Agent encapsulates CLI execution + result parsing + task generation - Context: Coverage gap analysis - user: "Analyze coverage gaps and generate补充test task" + user: "Analyze coverage gaps and generate supplement test task" assistant: "Executing CLI analysis for uncovered code paths → Generating test supplement task" commentary: Agent handles both analysis and task JSON generation autonomously color: purple @@ -18,12 +18,11 @@ color: purple You are a specialized execution agent that bridges CLI analysis tools with task generation. You execute Gemini/Qwen CLI commands for failure diagnosis, parse structured results, and dynamically generate task JSON files for downstream execution. -## Core Responsibilities - -1. **Execute CLI Analysis**: Run Gemini/Qwen with appropriate templates and context -2. **Parse CLI Results**: Extract structured information (fix strategies, root causes, modification points) -3. **Generate Task JSONs**: Create IMPL-fix-N.json or IMPL-supplement-N.json dynamically -4. **Save Analysis Reports**: Store detailed CLI output as iteration-N-analysis.md +**Core capabilities:** +- Execute CLI analysis with appropriate templates and context +- Parse structured results (fix strategies, root causes, modification points) +- Generate task JSONs dynamically (IMPL-fix-N.json, IMPL-supplement-N.json) +- Save detailed analysis reports (iteration-N-analysis.md) ## Execution Process @@ -43,7 +42,7 @@ You are a specialized execution agent that bridges CLI analysis tools with task "file": "tests/test_auth.py", "line": 45, "criticality": "high", - "test_type": "integration" // ← NEW: L0: static, L1: unit, L2: integration, L3: e2e + "test_type": "integration" // L0: static, L1: unit, L2: integration, L3: e2e } ], "error_messages": ["error1", "error2"], @@ -61,7 +60,7 @@ You are a specialized execution agent that bridges CLI analysis tools with task "tool": "gemini|qwen", "model": "gemini-3-pro-preview-11-2025|qwen-coder-model", "template": "01-diagnose-bug-root-cause.txt", - "timeout": 2400000, + "timeout": 2400000, // 40 minutes for analysis "fallback": "qwen" }, "task_config": { @@ -79,16 +78,16 @@ You are a specialized execution agent that bridges CLI analysis tools with task Phase 1: CLI Analysis Execution 1. Validate context package and extract failure context 2. Construct CLI command with appropriate template -3. Execute Gemini/Qwen CLI tool +3. Execute Gemini/Qwen CLI tool with layer-specific guidance 4. Handle errors and fallback to alternative tool if needed 5. Save raw CLI output to .process/iteration-N-cli-output.txt Phase 2: Results Parsing & Strategy Extraction 1. Parse CLI output for structured information: - - Root cause analysis + - Root cause analysis (RCA) - Fix strategy and approach - Modification points (files, functions, line numbers) - - Expected outcome + - Expected outcome and verification steps 2. Extract quantified requirements: - Number of files to modify - Specific functions to fix (with line numbers) @@ -96,7 +95,7 @@ Phase 2: Results Parsing & Strategy Extraction 3. Generate structured analysis report (iteration-N-analysis.md) Phase 3: Task JSON Generation -1. Load task JSON template (defined below) +1. Load task JSON template 2. Populate template with parsed CLI results 3. Add iteration context and previous attempts 4. Write task JSON to .workflow/{session}/.task/IMPL-fix-N.json @@ -105,9 +104,9 @@ Phase 3: Task JSON Generation ## Core Functions -### 1. CLI Command Construction +### 1. CLI Analysis Execution -**Template-Based Approach with Test Layer Awareness**: +**Template-Based Command Construction with Test Layer Awareness**: ```bash cd {project_root} && {cli_tool} -p " PURPOSE: Analyze {test_type} test failures and generate fix strategy for iteration {iteration} @@ -151,8 +150,9 @@ const layerGuidance = { const guidance = layerGuidance[test_type] || "Analyze holistically, avoid quick patches"; ``` -**Error Handling & Fallback**: +**Error Handling & Fallback Strategy**: ```javascript +// Primary execution with fallback chain try { result = executeCLI("gemini", config); } catch (error) { @@ -173,16 +173,18 @@ try { throw error; } } + +// Fallback strategy when all CLI tools fail +function generateBasicFixStrategy(failure_context) { + // Generate basic fix task based on error pattern matching + // Use previous successful fix patterns from fix-history.json + // Limit to simple, low-risk fixes (add null checks, fix typos) + // Mark task with meta.analysis_quality: "degraded" flag + // Orchestrator will treat degraded analysis with caution +} ``` -**Fallback Strategy (When All CLI Tools Fail)**: -- Generate basic fix task based on error patterns matching -- Use previous successful fix patterns from fix-history.json -- Limit to simple, low-risk fixes (add null checks, fix typos) -- Mark task with `meta.analysis_quality: "degraded"` flag -- Orchestrator will treat degraded analysis with caution (may skip iteration) - -### 2. CLI Output Parsing +### 2. Output Parsing & Task Generation **Expected CLI Output Structure** (from bug diagnosis template): ```markdown @@ -220,18 +222,34 @@ try { ```javascript const parsedResults = { root_causes: extractSection("根本原因分析"), - modification_points: extractModificationPoints(), + modification_points: extractModificationPoints(), // Returns: ["file:function:lines", ...] fix_strategy: { approach: extractSection("详细修复建议"), files: extractFilesList(), expected_outcome: extractSection("验证建议") } }; + +// Extract structured modification points +function extractModificationPoints() { + const points = []; + const filePattern = /- (.+?\.(?:ts|js|py)) \(lines (\d+-\d+)\): (.+)/g; + + let match; + while ((match = filePattern.exec(cliOutput)) !== null) { + points.push({ + file: match[1], + lines: match[2], + function: match[3], + formatted: `${match[1]}:${match[3]}:${match[2]}` + }); + } + + return points; +} ``` -### 3. Task JSON Generation (Template Definition) - -**Task JSON Template for IMPL-fix-N** (Simplified): +**Task JSON Generation** (Simplified Template): ```json { "id": "IMPL-fix-{iteration}", @@ -284,9 +302,7 @@ const parsedResults = { { "step": "load_analysis_context", "action": "Load CLI analysis report for full failure context if needed", - "commands": [ - "Read({meta.analysis_report})" - ], + "commands": ["Read({meta.analysis_report})"], "output_to": "full_failure_analysis", "note": "Analysis report contains: failed_tests, error_messages, pass_rate, root causes, previous_attempts" } @@ -334,19 +350,17 @@ const parsedResults = { **Template Variables Replacement**: - `{iteration}`: From context.iteration -- `{test_type}`: Dominant test type from failed_tests (e.g., "integration", "unit") +- `{test_type}`: Dominant test type from failed_tests - `{dominant_test_type}`: Most common test_type in failed_tests array -- `{layer_specific_approach}`: Guidance based on test layer from layerGuidance map +- `{layer_specific_approach}`: Guidance from layerGuidance map - `{fix_summary}`: First 50 chars of fix_strategy.approach - `{failed_tests.length}`: Count of failures - `{modification_points.length}`: Count of modification points -- `{modification_points}`: Array of file:function:lines from parsed CLI output +- `{modification_points}`: Array of file:function:lines - `{timestamp}`: ISO 8601 timestamp -- `{parent_task_id}`: ID of the parent test task (e.g., "IMPL-002") -- `{file1}`, `{file2}`, etc.: Specific file paths from modification_points -- `{specific_change_1}`, etc.: Change descriptions for each modification point +- `{parent_task_id}`: ID of parent test task -### 4. Analysis Report Generation +### 3. Analysis Report Generation **Structure of iteration-N-analysis.md**: ```markdown @@ -373,6 +387,7 @@ pass_rate: {pass_rate}% - **Error**: {test.error} - **File**: {test.file}:{test.line} - **Criticality**: {test.criticality} +- **Test Type**: {test.test_type} {endforeach} ## Root Cause Analysis @@ -403,15 +418,16 @@ See: `.process/iteration-{iteration}-cli-output.txt` ### CLI Execution Standards - **Timeout Management**: Use dynamic timeout (2400000ms = 40min for analysis) -- **Fallback Chain**: Gemini → Qwen (if Gemini fails with 429/404) +- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail) - **Error Context**: Include full error details in failure reports -- **Output Preservation**: Save raw CLI output for debugging +- **Output Preservation**: Save raw CLI output to .process/ for debugging ### Task JSON Standards - **Quantification**: All requirements must include counts and explicit lists - **Specificity**: Modification points must have file:function:line format - **Measurability**: Acceptance criteria must include verification commands - **Traceability**: Link to analysis reports and CLI output files +- **Minimal Redundancy**: Use references (analysis_report) instead of embedding full context ### Analysis Report Standards - **Structured Format**: Use consistent markdown sections @@ -430,19 +446,23 @@ See: `.process/iteration-{iteration}-cli-output.txt` - **Link files properly**: Use relative paths from session root - **Preserve CLI output**: Save raw output to .process/ for debugging - **Generate measurable acceptance criteria**: Include verification commands +- **Apply layer-specific guidance**: Use test_type to customize analysis approach **NEVER:** - Execute tests directly (orchestrator manages test execution) - Skip CLI analysis (always run CLI even for simple failures) - Modify files directly (generate task JSON for @test-fix-agent to execute) -- **Embed redundant data in task JSON** (use analysis_report reference instead) -- **Copy input context verbatim to output** (creates data duplication) +- Embed redundant data in task JSON (use analysis_report reference instead) +- Copy input context verbatim to output (creates data duplication) - Generate vague modification points (always specify file:function:lines) - Exceed timeout limits (use configured timeout value) +- Ignore test layer context (L0/L1/L2/L3 determines diagnosis approach) -## CLI Tool Configuration +## Configuration & Examples -### Gemini Configuration +### CLI Tool Configuration + +**Gemini Configuration**: ```javascript { "tool": "gemini", @@ -452,11 +472,12 @@ See: `.process/iteration-{iteration}-cli-output.txt` "test-failure": "01-diagnose-bug-root-cause.txt", "coverage-gap": "02-analyze-code-patterns.txt", "regression": "01-trace-code-execution.txt" - } + }, + "timeout": 2400000 // 40 minutes } ``` -### Qwen Configuration (Fallback) +**Qwen Configuration (Fallback)**: ```javascript { "tool": "qwen", @@ -464,47 +485,12 @@ See: `.process/iteration-{iteration}-cli-output.txt` "templates": { "test-failure": "01-diagnose-bug-root-cause.txt", "coverage-gap": "02-analyze-code-patterns.txt" - } + }, + "timeout": 2400000 // 40 minutes } ``` -## Integration with test-cycle-execute - -**Orchestrator Call Pattern**: -```javascript -// When pass_rate < 95% -Task( - subagent_type="cli-planning-agent", - description=`Analyze test failures and generate fix task (iteration ${iteration})`, - prompt=` - ## Context Package - ${JSON.stringify(contextPackage, null, 2)} - - ## Your Task - 1. Execute CLI analysis using ${cli_config.tool} - 2. Parse CLI output and extract fix strategy - 3. Generate IMPL-fix-${iteration}.json with structured task definition - 4. Save analysis report to .process/iteration-${iteration}-analysis.md - 5. Report success and task ID back to orchestrator - ` -) -``` - -**Agent Response**: -```javascript -{ - "status": "success", - "task_id": "IMPL-fix-{iteration}", - "task_path": ".workflow/{session}/.task/IMPL-fix-{iteration}.json", - "analysis_report": ".process/iteration-{iteration}-analysis.md", - "cli_output": ".process/iteration-{iteration}-cli-output.txt", - "summary": "{fix_strategy.approach first 100 chars}", - "modification_points_count": {count}, - "estimated_complexity": "low|medium|high" -} -``` - -## Example Execution +### Example Execution **Input Context**: ```json @@ -530,24 +516,45 @@ Task( "cli_config": { "tool": "gemini", "template": "01-diagnose-bug-root-cause.txt" + }, + "task_config": { + "agent": "@test-fix-agent", + "type": "test-fix-iteration", + "max_iterations": 5 } } ``` -**Execution Steps**: -1. Detect test_type: "integration" → Apply integration-specific diagnosis -2. Execute: `gemini -p "PURPOSE: Analyze integration test failure... [layer-specific context]"` - - CLI prompt includes: "Examine component interactions, data flow, interface contracts" - - Guidance: "Analyze full call stack and data flow across components" -3. Parse: Extract RCA, 修复建议, 验证建议 sections -4. Generate: IMPL-fix-1.json (SIMPLIFIED) with: +**Execution Summary**: +1. **Detect test_type**: "integration" → Apply integration-specific diagnosis +2. **Execute CLI**: + ```bash + gemini -p "PURPOSE: Analyze integration test failure... + TASK: Examine component interactions, data flow, interface contracts... + RULES: Analyze full call stack and data flow across components" + ``` +3. **Parse Output**: Extract RCA, 修复建议, 验证建议 sections +4. **Generate Task JSON** (IMPL-fix-1.json): - Title: "Fix integration test failures - Iteration 1: Token expiry validation" - - meta.analysis_report: ".process/iteration-1-analysis.md" (Reference, not embedded data) + - meta.analysis_report: ".process/iteration-1-analysis.md" (reference) - meta.test_layer: "integration" - - Requirements: "Fix 1 integration test failures by applying the provided fix strategy" - - fix_strategy.modification_points: ["src/auth/auth.service.ts:validateToken:45-60", "src/middleware/auth.middleware.ts:checkExpiry:120-135"] + - Requirements: "Fix 1 integration test failures by applying provided fix strategy" + - fix_strategy.modification_points: + - "src/auth/auth.service.ts:validateToken:45-60" + - "src/middleware/auth.middleware.ts:checkExpiry:120-135" - fix_strategy.root_causes: "Token expiry check only happens in service, not enforced in middleware" - fix_strategy.quality_assurance: {avoids_symptom_fix: true, addresses_root_cause: true} - - **NO failure_context object** - full context available via analysis_report reference -5. Save: iteration-1-analysis.md with full CLI output, layer context, failed_tests details, previous_attempts -6. Return: task_id="IMPL-fix-1", test_layer="integration", status="success" +5. **Save Analysis Report**: iteration-1-analysis.md with full CLI output, layer context, failed_tests details +6. **Return**: + ```javascript + { + status: "success", + task_id: "IMPL-fix-1", + task_path: ".workflow/WFS-test-session-001/.task/IMPL-fix-1.json", + analysis_report: ".process/iteration-1-analysis.md", + cli_output: ".process/iteration-1-cli-output.txt", + summary: "Token expiry check only happens in service, not enforced in middleware", + modification_points_count: 2, + estimated_complexity: "medium" + } + ``` diff --git a/.claude/skills/command-guide/reference/agents/context-search-agent.md b/.claude/skills/command-guide/reference/agents/context-search-agent.md index 02cf7444..54369fd7 100644 --- a/.claude/skills/command-guide/reference/agents/context-search-agent.md +++ b/.claude/skills/command-guide/reference/agents/context-search-agent.md @@ -432,25 +432,6 @@ Before completion verify: - [ ] File relevance >80% - [ ] No sensitive data exposed -## Performance Limits - -**File Counts**: -- Max 30 high-priority (score >0.8) -- Max 20 medium-priority (score 0.5-0.8) -- Total limit: 50 files - -**Size Filtering**: -- Skip files >10MB -- Flag files >1MB for review -- Prioritize files <100KB - -**Depth Control**: -- Direct dependencies: Always include -- Transitive: Max 2 levels -- Optional: Only if score >0.7 - -**Tool Priority**: Code-Index > ripgrep > find > grep - ## Output Report ``` diff --git a/.claude/skills/command-guide/reference/commands/cli/execute.md b/.claude/skills/command-guide/reference/commands/cli/execute.md index bb79b2b3..38f59a99 100644 --- a/.claude/skills/command-guide/reference/commands/cli/execute.md +++ b/.claude/skills/command-guide/reference/commands/cli/execute.md @@ -76,8 +76,8 @@ Use `resume --last` when current task extends/relates to previous execution. See ## Workflow Integration -**Session Management**: Auto-detects `.workflow/.active-*` marker -- Active session: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md` +**Session Management**: Auto-detects active session from `.workflow/sessions/` directory +- Active session: Save to `.workflow/sessions/WFS-[id]/.chat/execute-[timestamp].md` - No session: Create new session or save to scratchpad **Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary diff --git a/.claude/skills/command-guide/reference/commands/enhance-prompt.md b/.claude/skills/command-guide/reference/commands/enhance-prompt.md index 0d4c55fb..768563c7 100644 --- a/.claude/skills/command-guide/reference/commands/enhance-prompt.md +++ b/.claude/skills/command-guide/reference/commands/enhance-prompt.md @@ -1,37 +1,22 @@ --- name: enhance-prompt -description: Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection +description: Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection argument-hint: "user input to enhance" --- ## Overview -Systematically enhances user prompts by combining session memory context with codebase patterns, translating ambiguous requests into actionable specifications. +Systematically enhances user prompts by leveraging session memory context and intent analysis, translating ambiguous requests into actionable specifications. ## Core Protocol **Enhancement Pipeline:** -`Intent Translation` → `Context Integration` → `Gemini Analysis (if needed)` → `Structured Output` +`Intent Translation` → `Context Integration` → `Structured Output` **Context Sources:** - Session memory (conversation history, previous analysis) -- Codebase patterns (via Gemini when triggered) - Implicit technical requirements - -## Gemini Trigger Logic - -```pseudo -FUNCTION should_use_gemini(user_prompt): - critical_keywords = ["refactor", "migrate", "redesign", "auth", "payment", "security"] - - RETURN ( - prompt_affects_multiple_modules(user_prompt, threshold=3) OR - any_keyword_in_prompt(critical_keywords, user_prompt) - ) -END -``` - -**Gemini Integration:** ~/.claude/workflows/intelligent-tools-strategy.md +- User intent patterns ## Enhancement Rules @@ -47,22 +32,18 @@ END ### Context Integration Strategy -**Session Memory First:** +**Session Memory:** - Reference recent conversation context - Reuse previously identified patterns - Build on established understanding - -**Codebase Analysis (via Gemini):** -- Only when complexity requires it -- Focus on integration points -- Identify existing patterns +- Infer technical requirements from discussion **Example:** ```bash # User: "add login" # Session Memory: Previous auth discussion, JWT mentioned # Inferred: JWT-based auth, integrate with existing session management -# Gemini (if multi-module): Analyze AuthService patterns, middleware structure +# Action: Implement JWT authentication with session persistence ``` ## Output Structure @@ -76,7 +57,7 @@ ATTENTION: [Critical constraints] ### Output Examples -**Simple (no Gemini):** +**Example 1:** ```bash # Input: "fix login button" INTENT: Debug non-functional login button @@ -85,28 +66,28 @@ ACTION: Check event binding → verify state updates → test auth flow ATTENTION: Preserve existing OAuth integration ``` -**Complex (with Gemini):** +**Example 2:** ```bash # Input: "refactor payment code" INTENT: Restructure payment module for maintainability -CONTEXT: Session memory - PCI compliance requirements - Gemini - PaymentService → StripeAdapter pattern identified -ACTION: Extract reusable validators → isolate payment gateway logic +CONTEXT: Session memory - PCI compliance requirements, Stripe integration patterns +ACTION: Extract reusable validators → isolate payment gateway logic → maintain adapter pattern ATTENTION: Zero behavior change, maintain PCI compliance, full test coverage ``` -## Automatic Triggers +## Enhancement Triggers - Ambiguous language: "fix", "improve", "clean up" -- Multi-module impact (>3 modules) +- Vague requests requiring clarification +- Complex technical requirements - Architecture changes - Critical systems: auth, payment, security -- Complex refactoring +- Multi-step refactoring ## Key Principles -1. **Memory First**: Leverage session context before analysis -2. **Minimal Gemini**: Only when complexity demands it -3. **Context Reuse**: Build on previous understanding -4. **Clear Output**: Structured, actionable specifications +1. **Session Memory First**: Leverage conversation context and established understanding +2. **Context Reuse**: Build on previous discussions and decisions +3. **Clear Output**: Structured, actionable specifications +4. **Intent Clarification**: Transform vague requests into specific technical goals 5. **Avoid Duplication**: Reference existing context, don't repeat \ No newline at end of file diff --git a/.claude/skills/command-guide/reference/commands/memory/docs.md b/.claude/skills/command-guide/reference/commands/memory/docs.md index fb2b3008..ddc2ccc5 100644 --- a/.claude/skills/command-guide/reference/commands/memory/docs.md +++ b/.claude/skills/command-guide/reference/commands/memory/docs.md @@ -63,10 +63,10 @@ Lightweight planner that analyzes project structure, decomposes documentation wo bash(pwd && basename "$(pwd)" && git rev-parse --show-toplevel 2>/dev/null || pwd && date +%Y%m%d-%H%M%S) # Create session directories (replace timestamp) -bash(mkdir -p .workflow/WFS-docs-{timestamp}/.{task,process,summaries} && touch .workflow/.active-WFS-docs-{timestamp}) +bash(mkdir -p .workflow/sessions/WFS-docs-{timestamp}/.{task,process,summaries}) # Create workflow-session.json (replace values) -bash(echo '{"session_id":"WFS-docs-{timestamp}","project":"{project} documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","mode":"full","tool":"gemini","cli_execute":false}' | jq '.' > .workflow/WFS-docs-{timestamp}/workflow-session.json) +bash(echo '{"session_id":"WFS-docs-{timestamp}","project":"{project} documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","mode":"full","tool":"gemini","cli_execute":false}' | jq '.' > .workflow/sessions/WFS-docs-{timestamp}/workflow-session.json) ``` ### Phase 2: Analyze Structure @@ -458,8 +458,7 @@ api_id=$((group_count + 3)) **Unified Structure** (single JSON replaces multiple text files): ``` -.workflow/ -├── .active-WFS-docs-{timestamp} +.workflow/sessions/ └── WFS-docs-{timestamp}/ ├── workflow-session.json # Session metadata ├── IMPL_PLAN.md diff --git a/.claude/skills/command-guide/reference/commands/memory/style-skill-memory.md b/.claude/skills/command-guide/reference/commands/memory/style-skill-memory.md index ed372441..0cae3998 100644 --- a/.claude/skills/command-guide/reference/commands/memory/style-skill-memory.md +++ b/.claude/skills/command-guide/reference/commands/memory/style-skill-memory.md @@ -21,12 +21,14 @@ auto-continue: true **Key Features**: - Extracts primary design references (colors, typography, spacing, etc.) - Provides dynamic adjustment guidelines for design tokens +- Includes prerequisites and tooling requirements (browsers, PostCSS, dark mode) - Progressive loading structure for efficient token usage +- Complete implementation examples with React components - Interactive preview showcase --- -## Usage +## Quick Reference ### Command Syntax @@ -51,20 +53,77 @@ package-name Style reference package name (required) /memory:style-skill-memory ``` +### Key Variables + +**Input Variables**: +- `PACKAGE_NAME`: Style reference package name +- `PACKAGE_DIR`: `.workflow/reference_style/${package_name}` +- `SKILL_DIR`: `.claude/skills/style-${package_name}` +- `REGENERATE`: `true` if --regenerate flag, `false` otherwise + +**Data Sources** (Phase 2): +- `DESIGN_TOKENS_DATA`: Complete design-tokens.json content (from Read) +- `LAYOUT_TEMPLATES_DATA`: Complete layout-templates.json content (from Read) +- `ANIMATION_TOKENS_DATA`: Complete animation-tokens.json content (from Read, if exists) + +**Metadata** (Phase 2): +- `COMPONENT_COUNT`: Total components +- `UNIVERSAL_COUNT`: Universal components count +- `SPECIALIZED_COUNT`: Specialized components count +- `UNIVERSAL_COMPONENTS`: Universal component names (first 5) +- `HAS_ANIMATIONS`: Whether animation-tokens.json exists + +**Analysis Output** (`DESIGN_ANALYSIS` - Phase 2): +- `has_colors`: Colors exist +- `color_semantic`: Has semantic naming (primary/secondary/accent) +- `uses_oklch`: Uses modern color spaces (oklch, lab, etc.) +- `has_dark_mode`: Has separate light/dark mode color tokens +- `spacing_pattern`: Pattern type ("linear", "geometric", "custom") +- `spacing_scale`: Actual scale values (e.g., [4, 8, 16, 32, 64]) +- `has_typography`: Typography system exists +- `typography_hierarchy`: Has size scale for hierarchy +- `uses_calc`: Uses calc() expressions in token values +- `has_radius`: Border radius exists +- `radius_style`: Style characteristic ("sharp" <4px, "moderate" 4-8px, "rounded" >8px) +- `has_shadows`: Shadow system exists +- `shadow_pattern`: Elevation naming pattern +- `has_animations`: Animation tokens exist +- `animation_range`: Duration range (fast to slow) +- `easing_variety`: Types of easing functions + +### Common Errors + +| Error | Cause | Resolution | +|-------|-------|------------| +| Package not found | Invalid package name or doesn't exist | Run `/workflow:ui-design:codify-style` first | +| SKILL already exists | SKILL.md already generated | Use `--regenerate` flag | +| Missing layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style | +| Invalid JSON format | Corrupted package files | Regenerate package with codify-style | + --- ## Execution Process ### Phase 1: Validate Package -**Purpose**: Check if style reference package exists - **TodoWrite** (First Action): ```json [ - {"content": "Validate style reference package", "status": "in_progress", "activeForm": "Validating package"}, - {"content": "Read package data and extract design references", "status": "pending", "activeForm": "Reading package data"}, - {"content": "Generate SKILL.md with progressive loading", "status": "pending", "activeForm": "Generating SKILL.md"} + { + "content": "Validate package exists and check SKILL status", + "activeForm": "Validating package and SKILL status", + "status": "in_progress" + }, + { + "content": "Read package data and analyze design system", + "activeForm": "Reading package data and analyzing design system", + "status": "pending" + }, + { + "content": "Generate SKILL.md with design principles and token values", + "activeForm": "Generating SKILL.md with design principles and token values", + "status": "pending" + } ] ``` @@ -75,8 +134,6 @@ package-name Style reference package name (required) bash(echo "${package_name}" || basename "$(pwd)" | sed 's/^style-//') ``` -Store result as `package_name` - **Step 2: Validate Package Exists** ```bash @@ -113,152 +170,90 @@ if (regenerate_flag && skill_exists) { } ``` -**Summary Variables**: -- `PACKAGE_NAME`: Style reference package name -- `PACKAGE_DIR`: `.workflow/reference_style/${package_name}` -- `SKILL_DIR`: `.claude/skills/style-${package_name}` -- `REGENERATE`: `true` if --regenerate flag, `false` otherwise - -**TodoWrite Update**: -```json -[ - {"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"}, - {"content": "Read package data and extract design references", "status": "in_progress", "activeForm": "Reading package data"} -] -``` +**TodoWrite Update**: Mark "Validate" as completed, "Read package data" as in_progress --- -### Phase 2: Read Package Data & Extract Design References +### Phase 2: Read Package Data & Analyze Design System -**Purpose**: Extract package information and primary design references for SKILL description generation - -**Step 1: Count Components** +**Step 1: Read All JSON Files** ```bash -bash(jq '.layout_templates | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0) -``` +# Read layout templates +Read(file_path=".workflow/reference_style/${package_name}/layout-templates.json") -Store result as `component_count` - -**Step 2: Extract Component Types and Classification** - -```bash -# Extract component names from layout templates -bash(jq -r '.layout_templates | keys[]' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10) - -# Count universal vs specialized components -bash(jq '[.layout_templates[] | select(.component_type == "universal")] | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0) -bash(jq '[.layout_templates[] | select(.component_type == "specialized")] | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0) - -# Extract universal component names only -bash(jq -r '.layout_templates | to_entries | map(select(.value.component_type == "universal")) | .[].key' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10) -``` - -Store as: -- `COMPONENT_TYPES`: List of available component types (all) -- `UNIVERSAL_COUNT`: Number of universal (reusable) components -- `SPECIALIZED_COUNT`: Number of specialized (project-specific) components -- `UNIVERSAL_COMPONENTS`: List of universal component names - -**Step 3: Read Design Tokens** - -```bash +# Read design tokens Read(file_path=".workflow/reference_style/${package_name}/design-tokens.json") + +# Read animation tokens (if exists) +bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "exists" || echo "missing") +Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json") # if exists ``` -**Extract Primary Design References**: - -**Colors** (top 3-5 most important): -```bash -bash(jq -r '.colors | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null | head -5) -``` - -**Typography** (heading and body fonts): -```bash -bash(jq -r '.typography | to_entries | select(.key | contains("family")) | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null) -``` - -**Spacing Scale** (base spacing values): -```bash -bash(jq -r '.spacing | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null) -``` - -**Border Radius** (base radius values): -```bash -bash(jq -r '.border_radius | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null) -``` - -**Shadows** (elevation levels): -```bash -bash(jq -r '.shadows | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null) -``` - -Store extracted references as: -- `PRIMARY_COLORS`: List of primary color tokens -- `TYPOGRAPHY_FONTS`: Font family tokens -- `SPACING_SCALE`: Base spacing values -- `BORDER_RADIUS`: Radius values -- `SHADOWS`: Shadow definitions - -**Step 4: Read Animation Tokens (if available)** +**Step 2: Extract Metadata for Description** ```bash -# Check if animation tokens exist -bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "available" || echo "not_available") +# Count components and classify by type +bash(jq '.layout_templates | length' layout-templates.json) +bash(jq '[.layout_templates[] | select(.component_type == "universal")] | length' layout-templates.json) +bash(jq '[.layout_templates[] | select(.component_type == "specialized")] | length' layout-templates.json) +bash(jq -r '.layout_templates | to_entries[] | select(.value.component_type == "universal") | .key' layout-templates.json | head -5) ``` -If available, extract: -```bash -Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json") +Store results in metadata variables (see [Key Variables](#key-variables)) -# Extract primary animation values -bash(jq -r '.duration | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null) -bash(jq -r '.easing | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null) -``` +**Step 3: Analyze Design System for Dynamic Principles** -Store as: -- `ANIMATION_DURATIONS`: Animation duration tokens -- `EASING_FUNCTIONS`: Easing function tokens - -**Step 5: Count Files** +Analyze design-tokens.json to extract characteristics and patterns: ```bash -bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.html *.css 2>/dev/null | wc -l) +# Color system characteristics +bash(jq '.colors | keys' design-tokens.json) +bash(jq '.colors | to_entries[0:2] | map(.value)' design-tokens.json) +# Check for modern color spaces +bash(jq '.colors | to_entries[] | .value | test("oklch|lab|lch")' design-tokens.json) +# Check for dark mode variants +bash(jq '.colors | keys | map(select(contains("dark") or contains("light")))' design-tokens.json) +# → Store: has_colors, color_semantic, uses_oklch, has_dark_mode + +# Spacing pattern detection +bash(jq '.spacing | to_entries | map(.value) | map(gsub("[^0-9.]"; "") | tonumber)' design-tokens.json) +# Analyze pattern: linear (4-8-12-16) vs geometric (4-8-16-32) vs custom +# → Store: spacing_pattern, spacing_scale + +# Typography characteristics +bash(jq '.typography | keys | map(select(contains("family") or contains("weight")))' design-tokens.json) +bash(jq '.typography | to_entries | map(select(.key | contains("size"))) | .[].value' design-tokens.json) +# Check for calc() usage +bash(jq '. | tostring | test("calc\\(")' design-tokens.json) +# → Store: has_typography, typography_hierarchy, uses_calc + +# Border radius style +bash(jq '.border_radius | to_entries | map(.value)' design-tokens.json) +# Check range: small (sharp <4px) vs moderate (4-8px) vs large (rounded >8px) +# → Store: has_radius, radius_style + +# Shadow characteristics +bash(jq '.shadows | keys' design-tokens.json) +bash(jq '.shadows | to_entries[0].value' design-tokens.json) +# → Store: has_shadows, shadow_pattern + +# Animations (if available) +bash(jq '.duration | to_entries | map(.value)' animation-tokens.json) +bash(jq '.easing | keys' animation-tokens.json) +# → Store: has_animations, animation_range, easing_variety ``` -Store result as `file_count` +Store analysis results in `DESIGN_ANALYSIS` (see [Key Variables](#key-variables)) -**Summary Data Collected**: -- `COMPONENT_COUNT`: Number of components in layout templates -- `UNIVERSAL_COUNT`: Number of universal (reusable) components -- `SPECIALIZED_COUNT`: Number of specialized (project-specific) components -- `COMPONENT_TYPES`: List of component types (first 10) -- `UNIVERSAL_COMPONENTS`: List of universal component names (first 10) -- `FILE_COUNT`: Total files in package -- `HAS_ANIMATIONS`: Whether animation tokens are available -- `PRIMARY_COLORS`: Primary color tokens with values -- `TYPOGRAPHY_FONTS`: Font family tokens -- `SPACING_SCALE`: Base spacing scale -- `BORDER_RADIUS`: Border radius values -- `SHADOWS`: Shadow definitions -- `ANIMATION_DURATIONS`: Animation durations (if available) -- `EASING_FUNCTIONS`: Easing functions (if available) +**Note**: Analysis focuses on characteristics and patterns, not counts. Include technical feature detection (oklch, calc, dark mode) for Prerequisites section. -**TodoWrite Update**: -```json -[ - {"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"}, - {"content": "Generate SKILL.md with progressive loading", "status": "in_progress", "activeForm": "Generating SKILL.md"} -] -``` +**TodoWrite Update**: Mark "Read package data" as completed, "Generate SKILL.md" as in_progress --- ### Phase 3: Generate SKILL.md -**Purpose**: Create SKILL memory index with progressive loading structure and design references - **Step 1: Create SKILL Directory** ```bash @@ -272,336 +267,57 @@ bash(mkdir -p .claude/skills/style-${package_name}) {package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components. ``` -**Key Elements**: -- **Universal Count**: Emphasize available reusable layout templates -- **Project Independence**: Clearly state project-independent nature -- **Specialized Exclusion**: Mention excluded project-specific components -- **Path Reference**: Precise package location -- **Trigger Keywords**: reusable UI components, design tokens, layout patterns, visual consistency -- **Action Coverage**: working with, analyzing, implementing +**Step 3: Load and Process SKILL.md Template** -**Example**: -``` -main-app-style-v1 project-independent design system with 5 universal layout templates and interactive preview (located at .workflow/reference_style/main-app-style-v1). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes 3 project-specific components. -``` - -**Step 3: Write SKILL.md** - -Use Write tool to generate SKILL.md with the following complete content: - -```markdown ---- -name: style-{package_name} -description: {intelligent description from Step 2} ---- - -# {Package Name} Style SKILL Package - -## Documentation: `../../../.workflow/reference_style/{package_name}/` - -## Package Overview - -**Project-independent style reference package** extracted from codebase with reusable design patterns, tokens, and interactive preview. - -**Package Details**: -- Package: {package_name} -- Layout Templates: {component_count} total - - **Universal Components**: {universal_count} (reusable, project-independent) - - **Specialized Components**: {specialized_count} (project-specific, excluded from reference) -- Universal Component Types: {comma-separated list of UNIVERSAL_COMPONENTS} -- Files: {file_count} -- Animation Tokens: {has_animations ? "✓ Available" : "Not available"} - -**⚠️ IMPORTANT - Project Independence**: -This SKILL package represents a **pure style system** independent of any specific project implementation: -- **Universal components** are generic, reusable patterns (buttons, inputs, cards, navigation) -- **Specialized components** are project-specific implementations (excluded from this reference) -- All design tokens and layout patterns are extracted for **reference purposes only** -- Adapt and customize these references based on your project's specific requirements - ---- - -## ⚡ Primary Design References - -**IMPORTANT**: These are **reference values** extracted from the codebase. They should be **dynamically adjusted** based on your specific design needs, not treated as fixed constraints. - -### 🎨 Colors - -{FOR each color in PRIMARY_COLORS: - - **{color.key}**: `{color.value}` -} - -**Usage Guidelines**: -- These colors establish the foundation of the design system -- Adjust saturation, lightness, or hue based on: - - Brand requirements and accessibility needs - - Context (light/dark mode, high-contrast themes) - - User feedback and A/B testing results -- Use color theory principles to maintain harmony when modifying - -### 📝 Typography - -{FOR each font in TYPOGRAPHY_FONTS: - - **{font.key}**: `{font.value}` -} - -**Usage Guidelines**: -- Font families can be substituted based on: - - Brand identity and design language - - Performance requirements (web fonts vs. system fonts) - - Accessibility and readability considerations - - Platform-specific availability -- Maintain hierarchy and scale relationships when changing fonts - -### 📏 Spacing Scale - -{FOR each spacing in SPACING_SCALE: - - **{spacing.key}**: `{spacing.value}` -} - -**Usage Guidelines**: -- Spacing values form a consistent rhythm system -- Adjust scale based on: - - Target device (mobile vs. desktop vs. tablet) - - Content density requirements - - Component-specific needs (compact vs. comfortable layouts) -- Maintain proportional relationships when scaling - -### 🔲 Border Radius - -{FOR each radius in BORDER_RADIUS: - - **{radius.key}**: `{radius.value}` -} - -**Usage Guidelines**: -- Border radius affects visual softness and modernity -- Adjust based on: - - Design aesthetic (sharp vs. rounded vs. pill-shaped) - - Component type (buttons, cards, inputs have different needs) - - Platform conventions (iOS vs. Android vs. Web) - -### 🌫️ Shadows - -{FOR each shadow in SHADOWS: - - **{shadow.key}**: `{shadow.value}` -} - -**Usage Guidelines**: -- Shadows create elevation and depth perception -- Adjust based on: - - Material design depth levels - - Light/dark mode contexts - - Performance considerations (complex shadows impact rendering) - - Visual hierarchy needs - -{IF HAS_ANIMATIONS: -### ⏱️ Animation & Timing - -**Durations**: -{FOR each duration in ANIMATION_DURATIONS: - - **{duration.key}**: `{duration.value}` -} - -**Easing Functions**: -{FOR each easing in EASING_FUNCTIONS: - - **{easing.key}**: `{easing.value}` -} - -**Usage Guidelines**: -- Animation timing affects perceived responsiveness and polish -- Adjust based on: - - User expectations and platform conventions - - Accessibility preferences (reduced motion) - - Animation type (micro-interactions vs. page transitions) - - Performance constraints (mobile vs. desktop) -} - ---- - -## 🎯 Design Adaptation Strategies - -### When to Adjust Design References - -**Brand Alignment**: -- Modify colors to match brand identity and guidelines -- Adjust typography to reflect brand personality -- Tune spacing and radius to align with brand aesthetic - -**Accessibility Requirements**: -- Increase color contrast ratios for WCAG compliance -- Adjust font sizes and spacing for readability -- Modify animation durations for reduced-motion preferences - -**Platform Optimization**: -- Adapt spacing for mobile touch targets (min 44x44px) -- Adjust shadows and radius for platform conventions -- Optimize animation performance for target devices - -**Context-Specific Needs**: -- Dark mode: Adjust colors, shadows, and contrasts -- High-density displays: Fine-tune spacing and sizing -- Responsive design: Scale tokens across breakpoints - -### How to Apply Adjustments - -1. **Identify Need**: Determine which tokens need adjustment based on your specific requirements -2. **Maintain Relationships**: Preserve proportional relationships between related tokens -3. **Test Thoroughly**: Validate changes across components and use cases -4. **Document Changes**: Track modifications and rationale for team alignment -5. **Iterate**: Refine based on user feedback and testing results - ---- - -## Progressive Loading - -### Level 0: Design Tokens (~5K tokens) - -Essential design token system for consistent styling. - -**Files**: -- [Design Tokens](../../../.workflow/reference_style/{package_name}/design-tokens.json) - Colors, typography, spacing, shadows, borders - -**Use when**: Quick token reference, applying consistent styles, color/typography queries - ---- - -### Level 1: Universal Layout Templates (~12K tokens) - -**Project-independent** component layout patterns for reusable UI elements. - -**Files**: -- Level 0 files -- [Layout Templates](../../../.workflow/reference_style/{package_name}/layout-templates.json) - Component structures with HTML/CSS patterns - -**⚠️ Reference Strategy**: -- **Only reference components with `component_type: "universal"`** - these are reusable, project-independent patterns -- **Ignore components with `component_type: "specialized"`** - these are project-specific implementations -- Universal components include: buttons, inputs, forms, cards, navigation, modals, etc. -- Use universal patterns as **reference templates** to adapt for your specific project needs - -**Use when**: Building components, understanding component architecture, implementing layouts - ---- - -### Level 2: Complete System (~20K tokens) - -Full design system with animations and interactive preview. - -**Files**: -- All Level 1 files -- [Animation Tokens](../../../.workflow/reference_style/{package_name}/animation-tokens.json) - Animation durations, easing, transitions _(if available)_ -- [Preview HTML](../../../.workflow/reference_style/{package_name}/preview.html) - Interactive showcase (reference only) -- [Preview CSS](../../../.workflow/reference_style/{package_name}/preview.css) - Showcase styling (reference only) - -**Use when**: Comprehensive analysis, animation development, complete design system understanding - ---- - -## Interactive Preview - -**Location**: `.workflow/reference_style/{package_name}/preview.html` - -**View in Browser**: +**⚠️ CRITICAL - Execute First**: ```bash -cd .workflow/reference_style/{package_name} -python -m http.server 8080 -# Open http://localhost:8080/preview.html +bash(cat ~/.claude/workflows/cli-templates/memory/style-skill-memory/skill-md-template.md) ``` -**Features**: -- Color palette swatches with values -- Typography scale and combinations -- All components with variants and states -- Spacing, radius, shadow visual examples -- Interactive state demonstrations -- Usage code snippets +**Template Processing**: +1. **Replace variables**: Substitute all `{variable}` placeholders with actual values from Phase 2 +2. **Generate dynamic sections**: + - **Prerequisites & Tooling**: Generate based on `DESIGN_ANALYSIS` technical features (oklch, calc, dark mode) + - **Design Principles**: Generate based on `DESIGN_ANALYSIS` characteristics + - **Complete Implementation Example**: Include React component example with token adaptation + - **Design Token Values**: Iterate `DESIGN_TOKENS_DATA`, `ANIMATION_TOKENS_DATA` and display all key-value pairs with DEFAULT annotations +3. **Write to file**: Use Write tool to save to `.claude/skills/style-{package_name}/SKILL.md` ---- +**Variable Replacement Map**: +- `{package_name}` → PACKAGE_NAME +- `{intelligent_description}` → Generated description from Step 2 +- `{component_count}` → COMPONENT_COUNT +- `{universal_count}` → UNIVERSAL_COUNT +- `{specialized_count}` → SPECIALIZED_COUNT +- `{universal_components_list}` → UNIVERSAL_COMPONENTS (comma-separated) +- `{has_animations}` → HAS_ANIMATIONS -## Usage Guidelines +**Dynamic Content Generation**: -### Loading Levels +See template file for complete structure. Key dynamic sections: -**Level 0** (5K): Design tokens only -``` -Load Level 0 for design token reference -``` +1. **Prerequisites & Tooling** (based on DESIGN_ANALYSIS technical features): + - IF uses_oklch → Include PostCSS plugin requirement (`postcss-oklab-function`) + - IF uses_calc → Include preprocessor requirement for calc() expressions + - IF has_dark_mode → Include dark mode implementation mechanism (class or media query) + - ALWAYS include browser support, jq installation, and local server setup -**Level 1** (12K): Tokens + layout templates -``` -Load Level 1 for layout templates and design tokens -``` +2. **Design Principles** (based on DESIGN_ANALYSIS): + - IF has_colors → Include "Color System" principle with semantic pattern + - IF spacing_pattern detected → Include "Spatial Rhythm" with unified scale description (actual token values) + - IF has_typography_hierarchy → Include "Typographic System" with scale examples + - IF has_radius → Include "Shape Language" with style characteristic + - IF has_shadows → Include "Depth & Elevation" with elevation pattern + - IF has_animations → Include "Motion & Timing" with duration range + - ALWAYS include "Accessibility First" principle -**Level 2** (20K): Complete system with animations and preview -``` -Load Level 2 for complete design system with preview reference -``` - -### Common Use Cases - -**Implementing UI Components**: -- Load Level 1 for universal layout templates -- **Only reference components with `component_type: "universal"`** in layout-templates.json -- Apply design tokens from design-tokens.json -- Adapt patterns to your project's specific requirements - -**Ensuring Style Consistency**: -- Load Level 0 for design tokens -- Use design-tokens.json for colors, typography, spacing -- Check preview.html for visual reference (universal components only) - -**Analyzing Component Patterns**: -- Load Level 2 for complete analysis -- Review layout-templates.json for component architecture -- **Filter for `component_type: "universal"` to exclude project-specific implementations** -- Check preview.html for implementation examples - -**Animation Development**: -- Load Level 2 for animation tokens (if available) -- Reference animation-tokens.json for durations and easing -- Apply consistent timing and transitions - -**⚠️ Critical Usage Rule**: -This is a **project-independent style reference system**. When working with layout-templates.json: -- **USE**: Components marked `component_type: "universal"` as reusable reference patterns -- **IGNORE**: Components marked `component_type: "specialized"` (project-specific implementations) -- **ADAPT**: All patterns should be customized for your specific project needs - ---- - -## Package Structure - -``` -.workflow/reference_style/{package_name}/ -├── layout-templates.json # Layout templates from codebase -├── design-tokens.json # Design token system -├── animation-tokens.json # Animation tokens (optional) -├── preview.html # Interactive showcase -└── preview.css # Showcase styling -``` - ---- - -## Regeneration - -To update this SKILL memory after package changes: - -```bash -/memory:style-skill-memory {package_name} --regenerate -``` - ---- - -## Related Commands - -**Generate Package**: -```bash -/workflow:ui-design:codify-style --source ./src --package-name {package_name} -``` - -**Update Package**: -Re-run codify-style with same package name to update extraction. -``` +3. **Design Token Values** (iterate from read data): + - Colors: Iterate `DESIGN_TOKENS_DATA.colors` + - Typography: Iterate `DESIGN_TOKENS_DATA.typography` + - Spacing: Iterate `DESIGN_TOKENS_DATA.spacing` + - Border Radius: Iterate `DESIGN_TOKENS_DATA.border_radius` with calc() explanations + - Shadows: Iterate `DESIGN_TOKENS_DATA.shadows` with DEFAULT token annotations + - Animations (if available): Iterate `ANIMATION_TOKENS_DATA.duration` and `ANIMATION_TOKENS_DATA.easing` **Step 4: Verify SKILL.md Created** @@ -609,115 +325,27 @@ Re-run codify-style with same package name to update extraction. bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" || echo "failed") ``` -**TodoWrite Update**: -```json -[ - {"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"}, - {"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"}, - {"content": "Generate SKILL.md with progressive loading", "status": "completed", "activeForm": "Generating SKILL.md"} -] -``` - -**Final Action**: Report completion summary to user +**TodoWrite Update**: Mark all todos as completed --- -## Completion Message +### Completion Message -Display extracted primary design references to user: +Display a simple completion message with key information: ``` -✅ SKILL memory generated successfully! +✅ SKILL memory generated for style package: {package_name} -Package: {package_name} -SKILL Location: .claude/skills/style-{package_name}/SKILL.md +📁 Location: .claude/skills/style-{package_name}/SKILL.md -📦 Package Details: -- Layout Templates: {component_count} total - - Universal (reusable): {universal_count} - - Specialized (project-specific): {specialized_count} -- Universal Component Types: {show first 5 UNIVERSAL_COMPONENTS, then "+ X more"} -- Files: {file_count} -- Animation Tokens: {has_animations ? "✓ Available" : "Not available"} +📊 Package Summary: + - {component_count} components ({universal_count} universal, {specialized_count} specialized) + - Design tokens: colors, typography, spacing, shadows{animations_note} -🎨 Primary Design References Extracted: -{IF PRIMARY_COLORS exists: -Colors: - {show first 3 PRIMARY_COLORS with key: value} - {if more than 3: + X more colors} -} - -{IF TYPOGRAPHY_FONTS exists: -Typography: - {show all TYPOGRAPHY_FONTS} -} - -{IF SPACING_SCALE exists: -Spacing Scale: - {show first 3 SPACING_SCALE items} - {if more than 3: + X more spacing tokens} -} - -{IF BORDER_RADIUS exists: -Border Radius: - {show all BORDER_RADIUS} -} - -{IF HAS_ANIMATIONS: -Animation: - Durations: {count ANIMATION_DURATIONS} tokens - Easing: {count EASING_FUNCTIONS} functions -} - -⚡ Progressive Loading Levels: -- Level 0: Design Tokens (~5K tokens) -- Level 1: Tokens + Layout Templates (~12K tokens) -- Level 2: Complete System (~20K tokens) - -💡 Usage: -Load design system context when working with: -- UI component implementation -- Layout pattern analysis -- Design token application -- Style consistency validation - -⚠️ IMPORTANT - Project Independence: -This is a **project-independent style reference system**: -- Only use universal components (component_type: "universal") as reference patterns -- Ignore specialized components (component_type: "specialized") - they are project-specific -- The extracted design references are REFERENCE VALUES, not fixed constraints -- Dynamically adjust colors, spacing, typography, and other tokens based on: - - Brand requirements and accessibility needs - - Platform-specific conventions and optimizations - - Context (light/dark mode, responsive breakpoints) - - User feedback and testing results - -See SKILL.md for detailed adjustment guidelines and component filtering instructions. - -🎯 Preview: -Open interactive showcase: - file://{absolute_path}/.workflow/reference_style/{package_name}/preview.html - -📋 Next Steps: -1. Load appropriate level based on your task context -2. Review Primary Design References section for key design tokens -3. Apply design tokens with dynamic adjustments as needed -4. Reference layout-templates.json for component structures -5. Use Design Adaptation Strategies when modifying tokens +💡 Usage: /memory:load-skill-memory style-{package_name} "your task description" ``` ---- - -## Error Handling - -### Common Errors - -| Error | Cause | Resolution | -|-------|-------|------------| -| Package not found | Invalid package name or package doesn't exist | Run codify-style first to create package | -| SKILL already exists | SKILL.md already generated | Use --regenerate to force regeneration | -| Missing layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style | -| Invalid JSON format | Corrupted package files | Regenerate package with codify-style | +Variables: `{package_name}`, `{component_count}`, `{universal_count}`, `{specialized_count}`, `{animations_note}` (", animations" if exists) --- @@ -727,144 +355,42 @@ Open interactive showcase: 1. **Check Before Generate**: Verify package exists before attempting SKILL generation 2. **Respect Existing SKILL**: Don't overwrite unless --regenerate flag provided -3. **Extract Primary References**: Always extract and display key design values (colors, typography, spacing, border radius, shadows, animations) -4. **Include Adjustment Guidance**: Provide clear guidelines on when and how to dynamically adjust design tokens -5. **Progressive Loading**: Always include all 3 levels (0-2) with clear token estimates -6. **Intelligent Description**: Extract component count and key features from metadata +3. **Load Templates via cat**: Use `cat ~/.claude/workflows/cli-templates/memory/style-skill-memory/{template}` to load templates +4. **Variable Substitution**: Replace all `{variable}` placeholders with actual values +5. **Technical Feature Detection**: Analyze tokens for modern features (oklch, calc, dark mode) and generate appropriate Prerequisites section +6. **Dynamic Content Generation**: Generate sections based on DESIGN_ANALYSIS characteristics +7. **Unified Spacing Scale**: Use actual token values as primary scale reference, avoid contradictory pattern descriptions +8. **Direct Iteration**: Iterate data structures (DESIGN_TOKENS_DATA, etc.) for token values +9. **Annotate Special Tokens**: Add comments for DEFAULT tokens and calc() expressions +10. **Embed jq Commands**: Include bash/jq commands in SKILL.md for dynamic loading +11. **Progressive Loading**: Include all 3 levels (0-2) with specific jq commands +12. **Complete Examples**: Include end-to-end implementation examples (React components) +13. **Intelligent Description**: Extract component count and key features from metadata +14. **Emphasize Flexibility**: Strongly warn against rigid copying - values are references for creative adaptation -### SKILL Description Format +### Template Files Location -**Template**: -``` -{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components. -``` - -**Required Elements**: -- Package name -- Universal layout template count (emphasize reusability) -- Project independence statement -- Specialized component exclusion notice -- Location (full path) -- Trigger keywords (reusable UI components, design tokens, layout patterns, visual consistency) -- Action verbs (working with, analyzing, implementing) - -### Primary Design References Extraction - -**Required Data Extraction** (from design-tokens.json): -- Colors: Primary, secondary, accent colors (top 3-5) -- Typography: Font families for headings and body text -- Spacing Scale: Base spacing values (xs, sm, md, lg, xl) -- Border Radius: All radius tokens -- Shadows: Shadow definitions (top 3 elevation levels) - -**Component Classification Extraction** (from layout-templates.json): -- Universal Count: Number of components with `component_type: "universal"` -- Specialized Count: Number of components with `component_type: "specialized"` -- Universal Component Names: List of universal component names (first 10) - -**Optional Data Extraction** (from animation-tokens.json if available): -- Animation Durations: All duration tokens -- Easing Functions: Top 3 easing functions - -**Extraction Format**: -Use `jq` to extract tokens from JSON files. Each token should include key and value. -For component classification, filter by `component_type` field. - -### Dynamic Adjustment Guidelines - -**Include in SKILL.md**: -1. **Usage Guidelines per Category**: Specific guidance for each token category -2. **Adjustment Strategies**: When to adjust design references -3. **Practical Examples**: Context-specific adaptation scenarios -4. **Best Practices**: How to maintain design system coherence while adjusting - -### Progressive Loading Structure - -**Level 0** (~5K tokens): -- design-tokens.json - -**Level 1** (~12K tokens): -- Level 0 files -- layout-templates.json - -**Level 2** (~20K tokens): -- Level 1 files -- animation-tokens.json (if exists) -- preview.html -- preview.css - ---- - -## Benefits - -- **Project Independence**: Clear separation between universal (reusable) and specialized (project-specific) components -- **Component Filtering**: Automatic classification helps identify which patterns are truly reusable -- **Fast Context Loading**: Progressive levels for efficient token usage -- **Primary Design References**: Extracted key design values (colors, typography, spacing, etc.) displayed prominently -- **Dynamic Adjustment Guidance**: Clear instructions on when and how to adjust design tokens -- **Intelligent Triggering**: Keywords optimize SKILL activation -- **Complete Reference**: All package files accessible through SKILL -- **Easy Regeneration**: Simple --regenerate flag for updates -- **Clear Structure**: Organized levels by use case with component type filtering -- **Practical Usage Guidelines**: Context-specific adjustment strategies and component selection criteria - ---- - -## Architecture ``` -style-skill-memory - ├─ Phase 1: Validate - │ ├─ Parse package name from argument or auto-detect - │ ├─ Check package exists in .workflow/reference_style/ - │ └─ Check if SKILL already exists (skip if exists and no --regenerate) - │ - ├─ Phase 2: Read Package Data & Extract Primary References - │ ├─ Count components from layout-templates.json - │ ├─ Extract component types list - │ ├─ Extract primary colors from design-tokens.json (top 3-5) - │ ├─ Extract typography (font families) - │ ├─ Extract spacing scale (base values) - │ ├─ Extract border radius tokens - │ ├─ Extract shadow definitions (top 3) - │ ├─ Extract animation tokens (if available) - │ └─ Count total files in package - │ - └─ Phase 3: Generate SKILL.md - ├─ Create SKILL directory - ├─ Generate intelligent description with keywords - ├─ Write SKILL.md with complete structure: - │ ├─ Package Overview - │ ├─ Primary Design References - │ │ ├─ Colors with usage guidelines - │ │ ├─ Typography with usage guidelines - │ │ ├─ Spacing with usage guidelines - │ │ ├─ Border Radius with usage guidelines - │ │ ├─ Shadows with usage guidelines - │ │ └─ Animation & Timing (if available) - │ ├─ Design Adaptation Strategies - │ │ ├─ When to adjust design references - │ │ └─ How to apply adjustments - │ ├─ Progressive Loading (3 levels) - │ ├─ Interactive Preview - │ ├─ Usage Guidelines - │ ├─ Package Structure - │ ├─ Regeneration - │ └─ Related Commands - ├─ Verify SKILL.md created successfully - └─ Display completion message with extracted design references +Phase 1: Validate + ├─ Parse package_name + ├─ Check PACKAGE_DIR exists + └─ Check SKILL_DIR exists (skip if exists and no --regenerate) -Data Flow: - design-tokens.json → jq extraction → PRIMARY_COLORS, TYPOGRAPHY_FONTS, - SPACING_SCALE, BORDER_RADIUS, SHADOWS - animation-tokens.json → jq extraction → ANIMATION_DURATIONS, EASING_FUNCTIONS - layout-templates.json → jq extraction → COMPONENT_COUNT, UNIVERSAL_COUNT, - SPECIALIZED_COUNT, UNIVERSAL_COMPONENTS - → component_type filtering → Universal vs Specialized classification +Phase 2: Read & Analyze + ├─ Read design-tokens.json → DESIGN_TOKENS_DATA + ├─ Read layout-templates.json → LAYOUT_TEMPLATES_DATA + ├─ Read animation-tokens.json → ANIMATION_TOKENS_DATA (if exists) + ├─ Extract Metadata → COMPONENT_COUNT, UNIVERSAL_COUNT, etc. + └─ Analyze Design System → DESIGN_ANALYSIS (characteristics) - Extracted data → SKILL.md generation → Primary Design References section - → Component Classification section - → Dynamic Adjustment Guidelines - → Project Independence warnings - → Completion message display +Phase 3: Generate + ├─ Create SKILL directory + ├─ Generate intelligent description + ├─ Load SKILL.md template (cat command) + ├─ Replace variables and generate dynamic content + ├─ Write SKILL.md + ├─ Verify creation + ├─ Load completion message template (cat command) + └─ Display completion message ``` diff --git a/.claude/skills/command-guide/reference/commands/workflow/action-plan-verify.md b/.claude/skills/command-guide/reference/commands/workflow/action-plan-verify.md index 64da47b5..c20ee11b 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/action-plan-verify.md +++ b/.claude/skills/command-guide/reference/commands/workflow/action-plan-verify.md @@ -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 ``` diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/api-designer.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/api-designer.md index 51361f6e..251ca8f9 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/api-designer.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/api-designer.md @@ -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"] } } diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/artifacts.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/artifacts.md index f1669356..7bd06e9d 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/artifacts.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/artifacts.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/auto-parallel.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/auto-parallel.md index f731693d..7b7a3575 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/auto-parallel.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/auto-parallel.md @@ -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) diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/data-architect.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/data-architect.md index 902fd95b..97678b99 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/data-architect.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/data-architect.md @@ -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" } } diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-manager.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-manager.md index 21de941b..77145fef 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-manager.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-manager.md @@ -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" } } diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-owner.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-owner.md index f1f5317c..72d5481e 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-owner.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/product-owner.md @@ -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" } } diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/scrum-master.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/scrum-master.md index b909542d..85065e81 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/scrum-master.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/scrum-master.md @@ -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" } } diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/subject-matter-expert.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/subject-matter-expert.md index c111ed7d..c2e52db0 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/subject-matter-expert.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/subject-matter-expert.md @@ -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" } } diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/synthesis.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/synthesis.md index 3625d671..3d0351f4 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/synthesis.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/synthesis.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/system-architect.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/system-architect.md index d11fce89..55c1f414 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/system-architect.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/system-architect.md @@ -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"] } } diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/ui-designer.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/ui-designer.md index e245f83b..963b1228 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/ui-designer.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/ui-designer.md @@ -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" } } diff --git a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/ux-expert.md b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/ux-expert.md index 6b909a0d..b14443d4 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/brainstorm/ux-expert.md +++ b/.claude/skills/command-guide/reference/commands/workflow/brainstorm/ux-expert.md @@ -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" } } diff --git a/.claude/skills/command-guide/reference/commands/workflow/execute.md b/.claude/skills/command-guide/reference/commands/workflow/execute.md index b058b305..0628867b 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/execute.md +++ b/.claude/skills/command-guide/reference/commands/workflow/execute.md @@ -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 +``` diff --git a/.claude/skills/command-guide/reference/commands/workflow/init.md b/.claude/skills/command-guide/reference/commands/workflow/init.md new file mode 100644 index 00000000..56ba7e14 --- /dev/null +++ b/.claude/skills/command-guide/reference/commands/workflow/init.md @@ -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" +``` diff --git a/.claude/skills/command-guide/reference/commands/workflow/lite-execute.md b/.claude/skills/command-guide/reference/commands/workflow/lite-execute.md new file mode 100644 index 00000000..a74dfe56 --- /dev/null +++ b/.claude/skills/command-guide/reference/commands/workflow/lite-execute.md @@ -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] + +# Flags +--in-memory Use plan from memory (called by lite-plan) + +# Arguments + 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. diff --git a/.claude/skills/command-guide/reference/commands/workflow/lite-plan.md b/.claude/skills/command-guide/reference/commands/workflow/lite-plan.md index 6469074f..cc02babd 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/lite-plan.md +++ b/.claude/skills/command-guide/reference/commands/workflow/lite-plan.md @@ -1,53 +1,23 @@ --- name: lite-plan -description: Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation -argument-hint: "[--tool claude|gemini|qwen|codex] [--quick] \"task description\"|file.md" -allowed-tools: TodoWrite(*), Task(*), Bash(*), AskUserQuestion(*) -timeout: 180000 -color: cyan +description: Lightweight interactive planning workflow with in-memory planning, code exploration, and execution dispatch to lite-execute after user confirmation +argument-hint: "[-e|--explore] \"task description\"|file.md" +allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*) --- # Workflow Lite-Plan Command (/workflow:lite-plan) ## Overview -Intelligent lightweight planning and execution command with dynamic workflow adaptation based on task complexity. +Intelligent lightweight planning command with dynamic workflow adaptation based on task complexity. Focuses on planning phases (exploration, clarification, planning, confirmation) and delegates execution to `/workflow:lite-execute`. -**Key Characteristics**: -- Dynamic Workflow: Automatically decides whether to use exploration, clarification, and detailed planning -- Smart Exploration: Calls cli-explore-agent only when task requires codebase context -- Interactive Clarification: Asks user for more information after exploration if needed -- Adaptive Planning: Simple tasks get direct planning, complex tasks use cli-planning-agent -- Two-Dimensional Confirmation: User confirms task + selects execution method in one step -- Direct Execution: Immediately starts execution (agent or CLI) after confirmation -- Live Progress Tracking: Uses TodoWrite to track execution progress in real-time - -## Core Functionality - -- **Intelligent Task Analysis**: Automatically determines if exploration/planning agents are needed -- **Dynamic Exploration**: Calls cli-explore-agent only when task requires codebase understanding -- **Interactive Clarification**: Asks follow-up questions after exploration to gather missing information -- **Adaptive Planning**: - - Simple tasks: Direct planning by current Claude - - Complex tasks: Delegates to cli-planning-agent for detailed breakdown -- **Two-Dimensional Confirmation**: Single user interaction for task approval + execution method selection -- **Direct Execution**: Immediate dispatch to selected execution method (agent or CLI) -- **Live Progress Tracking**: Real-time TodoWrite updates during execution - -## Comparison with Other Commands - -| Feature | lite-plan | /cli:mode:plan | /workflow:plan | -|---------|-----------|----------------|----------------| -| Workflow Adaptation | Dynamic (intelligent) | Fixed | Fixed | -| Code Exploration | Smart (when needed) | No | Always (context-search) | -| Clarification | Yes (interactive) | No | No | -| Planning Strategy | Adaptive (simple/complex) | Fixed template | Agent-based | -| User Interaction | Two-dimensional | No | Minimal | -| Direct Execution | Yes (immediate) | Yes (immediate) | No (requires /workflow:execute) | -| Progress Tracking | Yes (TodoWrite live) | No | Yes (session-based) | -| Execution Time | Fast (1-3 min) | Fast (2-5 min) | Slow (5-10 min) | -| Tool Selection | User choice | --tool flag | Fixed (agent only) | -| File Artifacts | No | No | Yes (IMPL_PLAN.md + JSON) | +**Core capabilities:** +- Intelligent task analysis with automatic exploration detection +- Dynamic code exploration (cli-explore-agent) when codebase understanding needed +- Interactive clarification after exploration to gather missing information +- Adaptive planning strategy (direct Claude vs cli-lite-planning-agent) based on complexity +- Two-step confirmation: plan display → multi-dimensional input collection +- Execution dispatch with complete context handoff to lite-execute ## Usage @@ -56,190 +26,151 @@ Intelligent lightweight planning and execution command with dynamic workflow ada /workflow:lite-plan [FLAGS] # Flags ---tool Preset CLI tool (claude|gemini|qwen|codex); if not provided, user selects during confirmation ---quick Skip code exploration phase (fast mode, completes within 60 seconds) +-e, --explore Force code exploration phase (overrides auto-detection) # Arguments Task description or path to .md file (required) ``` -### Usage Examples -```bash -# Standard planning with full interaction -/workflow:lite-plan "Implement user authentication with JWT tokens" -# -> Shows plan, user confirms, selects tool, immediate execution - -# Quick mode with preset tool -/workflow:lite-plan --quick --tool gemini "Refactor logging module for better performance" -# -> Skips exploration, user confirms plan, executes with Gemini - -# Codex direct execution preset -/workflow:lite-plan --tool codex "Add unit tests for authentication service" -# -> User only confirms plan, executes with Codex immediately - -# Agent mode with Claude -/workflow:lite-plan "Design new API endpoints for payment processing" -# -> User selects Claude agent, immediate execution -``` +### Input Requirements +- **Task description**: String or path to .md file (required) + - Should be specific and concrete + - Can include context about existing code or requirements + - Examples: + - "Implement user authentication with JWT tokens" + - "Refactor logging module for better performance" + - "Add unit tests for authentication service" +- **Flags** (optional): + - `-e` or `--explore`: Force exploration when: + - Task appears simple but requires codebase context + - Auto-detection might miss integration points + - Comprehensive code understanding needed before planning ## Execution Process ### Workflow Overview ``` -User Input ("/workflow:lite-plan \"task\"") - | - v -[Phase 1] Task Analysis & Exploration Decision (10-20 seconds) - -> Analyze task description - -> Decision: Need exploration? (Yes/No/--quick override) - -> If Yes: Launch cli-explore-agent - -> Output: exploration findings (if performed) - | - v -[Phase 2] Clarification (Optional, user interaction) - -> If exploration revealed ambiguities or missing info - -> AskUserQuestion: Gather clarifications - -> Update task context with user responses - -> If no clarification needed: Skip to Phase 3 - | - v -[Phase 3] Complexity Assessment & Planning (20-60 seconds) - -> Assess task complexity (Low/Medium/High) - -> Decision: Planning strategy - - Low: Direct planning (current Claude) - - Medium/High: Delegate to cli-planning-agent - -> Output: Task breakdown with execution approach - | - v -[Phase 4] Task Confirmation & Execution Selection (User interaction) - -> Display task breakdown and approach - -> AskUserQuestion: Two dimensions - 1. Confirm task (Yes/Modify/Cancel) - 2. Execution method (Direct/CLI) - -> If confirmed: Proceed to Phase 5 - -> If modify: Re-run planning with feedback - -> If cancel: Exit - | - v -[Phase 5] Execution & Progress Tracking - -> Create TodoWrite task list from breakdown - -> Launch selected execution (agent or CLI) - -> Track progress with TodoWrite updates - -> Real-time status displayed to user - | - v -Execution Complete +User Input → Task Analysis & Exploration Decision (Phase 1) + ↓ + Clarification (Phase 2, optional) + ↓ + Complexity Assessment & Planning (Phase 3) + ↓ + Task Confirmation & Execution Selection (Phase 4) + ↓ + Dispatch to Execution (Phase 5) + ↓ + Planning Complete (lite-execute continues) ``` -### Task Management Pattern +### Phase Summary -- TodoWrite creates task list before execution starts (Phase 5) -- Tasks marked as in_progress/completed during execution -- Real-time progress updates visible to user -- No intermediate file artifacts generated +**Phase 1: Task Analysis & Exploration Decision** (10-60 seconds) +- Analyze task to determine exploration needs +- Decision logic: `--explore` flag OR requires codebase context +- If needed: Launch cli-explore-agent for code analysis +- Output: `explorationContext` with relevant files, patterns, constraints + +**Phase 2: Clarification** (30-60 seconds, optional) +- Skip if no ambiguities found in Phase 1 +- Use exploration findings to generate targeted questions +- AskUserQuestion based on `clarification_needs` from exploration +- Output: `clarificationContext` with user responses + +**Phase 3: Complexity Assessment & Planning** (20-60 seconds) +- Assess complexity (Low/Medium/High) from multiple factors +- Strategy selection: + - Low: Direct planning by current Claude (fast, 20-30s) + - Medium/High: Delegate to cli-lite-planning-agent (detailed, 40-60s) +- Output: `planObject` with tasks, time estimates, recommendations + +**Phase 4: Task Confirmation & Execution Selection** (user interaction) +- Step 1: Display complete plan as text to user +- Step 2: Collect four inputs via AskUserQuestion: + 1. Confirm plan (Allow/Modify/Cancel + supplements via "Other") + 2. Execution method (Agent/Codex/Auto) + 3. Code review tool (Skip/Gemini/Agent + custom via "Other") + 4. Export JSON (Yes/No for Enhanced Task JSON export) + +**Phase 5: Dispatch to Execution** (<1 second) +- Export Enhanced Task JSON (optional, if user selected "Yes") +- Store `executionContext` in memory with full plan + context +- Call `/workflow:lite-execute --in-memory` +- Execution tracking delegated to lite-execute ## Detailed Phase Execution ### Phase 1: Task Analysis & Exploration Decision -**Operations**: -- Analyze task description to determine if code exploration is needed -- Decision logic: - ```javascript - needsExploration = ( +**Decision Logic**: +```javascript +needsExploration = ( + flags.includes('--explore') || flags.includes('-e') || // Force if flag present + ( task.mentions_specific_files || task.requires_codebase_context || task.needs_architecture_understanding || task.modifies_existing_code - ) && !flags.includes('--quick') - ``` + ) +) +``` **Decision Criteria**: | Task Type | Needs Exploration | Reason | |-----------|-------------------|--------| -| "Implement new feature X" | Maybe | Depends on integration with existing code | -| "Refactor module Y" | Yes | Needs understanding of current implementation | -| "Add tests for Z" | Yes | Needs to understand code structure | -| "Create new standalone utility" | No | Self-contained, no existing code context | +| Any task with `-e`/`--explore` flag | **Yes (forced)** | **Flag overrides auto-detection** | +| "Implement new feature X" | Maybe | Depends on integration needs | +| "Refactor module Y" | Yes | Needs current implementation understanding | +| "Add tests for Z" | Yes | Needs code structure understanding | +| "Create standalone utility" | No | Self-contained, no existing context | | "Update documentation" | No | Doesn't require code exploration | -| "Fix bug in function F" | Yes | Needs to understand implementation | +| "Fix bug in function F" | Yes | Needs implementation understanding | -**If Exploration Needed**: -- Launch cli-explore-agent with task-specific focus -- Agent call format: - ```javascript - Task( - subagent_type="cli-explore-agent", - description="Analyze codebase for task context", - prompt=` - Task: ${task_description} - - Analyze and return the following information in structured format: - 1. Project Structure: Overall architecture and module organization - 2. Relevant Files: List of files that will be affected by this task (with paths) - 3. Current Implementation Patterns: Existing code patterns, conventions, and styles - 4. Dependencies: External dependencies and internal module dependencies - 5. Integration Points: Where this task connects with existing code - 6. Architecture Constraints: Technical limitations or requirements - 7. Clarification Needs: Ambiguities or missing information requiring user input - - Time Limit: 60 seconds - - Output Format: Return a JSON-like structured object with the above fields populated. - Include specific file paths, pattern examples, and clear questions for clarifications. - ` - ) - ``` - -**Expected Return Structure**: +**Exploration Execution** (if needed): ```javascript -explorationContext = { - project_structure: "Description of overall architecture", - relevant_files: ["src/auth/service.ts", "src/middleware/auth.ts", ...], - patterns: "Description of existing patterns (e.g., 'Uses dependency injection pattern', 'React hooks convention')", - dependencies: "List of dependencies and integration points", - integration_points: "Where this connects with existing code", - constraints: "Technical constraints (e.g., 'Must use existing auth library', 'No breaking changes')", - clarification_needs: [ - { - question: "Which authentication method to use?", - context: "Found both JWT and Session patterns", - options: ["JWT tokens", "Session-based", "Hybrid approach"] - }, - // ... more clarification questions - ] -} +Task( + subagent_type="cli-explore-agent", + description="Analyze codebase for task context", + prompt=` + Task: ${task_description} + + Analyze and return structured information: + 1. Project Structure: Architecture and module organization + 2. Relevant Files: Files to be affected (with paths) + 3. Current Patterns: Code patterns, conventions, styles + 4. Dependencies: External/internal module dependencies + 5. Integration Points: Task connections with existing code + 6. Architecture Constraints: Technical limitations/requirements + 7. Clarification Needs: Ambiguities requiring user input + + Time Limit: 60 seconds + Output Format: JSON-like structured object + ` +) ``` -**Output Processing**: -- Store exploration findings in `explorationContext` -- Extract `clarification_needs` array from exploration results -- Set `needsClarification = (clarification_needs.length > 0)` -- Use clarification_needs to generate Phase 2 questions +**Output**: `explorationContext` (see Data Structures section) **Progress Tracking**: -- Mark Phase 1 as completed -- If needsClarification: Mark Phase 2 as in_progress +- Mark Phase 1 completed +- If `clarification_needs.length > 0`: Mark Phase 2 in_progress - Else: Skip to Phase 3 -**Expected Duration**: 10-20 seconds (analysis) + 30-60 seconds (exploration if needed) - --- ### Phase 2: Clarification (Optional) -**Skip Condition**: Only run if Phase 1 set `needsClarification = true` +**Skip Condition**: Only run if `needsClarification = true` from Phase 1 **Operations**: -- Review `explorationContext.clarification_needs` from Phase 1 -- Generate AskUserQuestion based on exploration findings -- Focus on ambiguities that affect implementation approach +- Review `explorationContext.clarification_needs` +- Generate AskUserQuestion from exploration findings +- Focus on ambiguities affecting implementation approach -**AskUserQuestion Call** (simplified reference): +**Question Generation**: ```javascript -// Use clarification_needs from exploration to build questions AskUserQuestion({ questions: explorationContext.clarification_needs.map(need => ({ question: `${need.context}\n\n${need.question}`, @@ -253,27 +184,17 @@ AskUserQuestion({ }) ``` -**Output Processing**: -- Collect user responses and store in `clarificationContext` -- Format: `{ question_id: selected_answer, ... }` -- This context will be passed to Phase 3 planning +**Output**: `clarificationContext` in format `{ question_id: selected_answer }` **Progress Tracking**: -- Mark Phase 2 as completed -- Mark Phase 3 as in_progress - -**Expected Duration**: User-dependent (typically 30-60 seconds) +- Mark Phase 2 completed +- Mark Phase 3 in_progress --- ### Phase 3: Complexity Assessment & Planning -**Operations**: -- Assess task complexity based on multiple factors -- Select appropriate planning strategy -- Generate task breakdown using selected method - -**Complexity Assessment Factors**: +**Complexity Assessment**: ```javascript complexityScore = { file_count: exploration.files_to_modify.length, @@ -295,668 +216,452 @@ else complexity = "High" | Level | Characteristics | Planning Strategy | |-------|----------------|-------------------| | Low | 1-2 files, simple changes, clear requirements | Direct planning (current Claude) | -| Medium | 3-5 files, moderate integration, some ambiguity | Delegate to cli-planning-agent | -| High | 6+ files, complex architecture, high uncertainty | Delegate to cli-planning-agent with detailed analysis | - -**Planning Execution**: +| Medium | 3-5 files, moderate integration, some ambiguity | cli-lite-planning-agent | +| High | 6+ files, complex architecture, high uncertainty | cli-lite-planning-agent with detailed analysis | **Option A: Direct Planning (Low Complexity)** -```javascript -// Current Claude generates plan directly -planObject = { - summary: "Brief overview of what needs to be done", - approach: "Step-by-step implementation strategy", - tasks: [ - "Task 1: Specific action with file references", - "Task 2: Specific action with file references", - // ... 3-5 tasks - ], - complexity: "Low", - estimated_time: "15-30 minutes" -} -``` + +Current Claude generates plan directly: +- Summary: 2-3 sentence overview +- Approach: High-level implementation strategy +- Task Breakdown: 3-5 specific, actionable tasks with file paths +- Estimated Time: Total implementation time +- Recommended Execution: "Agent" **Option B: Agent-Based Planning (Medium/High Complexity)** + +Delegate to cli-lite-planning-agent: ```javascript -// Delegate to cli-planning-agent Task( - subagent_type="cli-planning-agent", + subagent_type="cli-lite-planning-agent", description="Generate detailed implementation plan", prompt=` - Task: ${task_description} + ## Task Description + ${task_description} - Exploration Context: - ${JSON.stringify(explorationContext, null, 2)} + ## Exploration Context + ${JSON.stringify(explorationContext, null, 2) || "No exploration performed"} - User Clarifications: + ## User Clarifications ${JSON.stringify(clarificationContext, null, 2) || "None provided"} - Complexity Level: ${complexity} + ## Complexity Level + ${complexity} - Generate a detailed implementation plan with the following components: + ## Your Task + 1. Execute CLI planning using Gemini (Qwen fallback) + 2. Parse CLI output and extract structured plan + 3. Enhance tasks with file paths and pattern references + 4. Generate planObject with: + - Summary (2-3 sentences) + - Approach (high-level strategy) + - Tasks (3-10 actionable steps) + - Estimated time (with breakdown) + - Recommended execution (Agent for Low, Codex for Medium/High) + 5. Return planObject (no file writes) - 1. Summary: 2-3 sentence overview of the implementation - 2. Approach: High-level implementation strategy - 3. Task Breakdown: 5-10 specific, actionable tasks - - Each task should specify: - * What to do - * Which files to modify/create - * Dependencies on other tasks (if any) - 4. Task Dependencies: Explicit ordering requirements (e.g., "Task 2 depends on Task 1") - 5. Risks: Potential issues and mitigation strategies (for Medium/High complexity) - 6. Estimated Time: Total implementation time estimate - 7. Recommended Execution: "Direct" (agent) or "CLI" (autonomous tool) + ## Quality Requirements + Each task MUST include: + - Action verb (Create/Update/Add/Implement/Refactor) + - Specific file path + - Detailed changes + - Pattern reference from exploration - Output Format: Return a structured object with these fields: - { - summary: string, - approach: string, - tasks: string[], - dependencies: string[] (optional), - risks: string[] (optional), - estimated_time: string, - recommended_execution: "Direct" | "CLI" - } - - Ensure tasks are specific, with file paths and clear acceptance criteria. + Format: "{Action} in {file_path}: {details} following {pattern}" ` ) - -// Agent returns detailed plan -planObject = agent_output.parse() ``` -**Expected Return Structure**: -```javascript -planObject = { - summary: "Implement JWT-based authentication system with middleware integration", - approach: "Create auth service layer, implement JWT utilities, add middleware, update routes", - tasks: [ - "Create authentication service in src/auth/service.ts with login/logout/verify methods", - "Implement JWT token utilities in src/auth/jwt.ts (generate, verify, refresh)", - "Add authentication middleware to src/middleware/auth.ts", - "Update API routes in src/routes/*.ts to use auth middleware", - "Add integration tests for auth flow in tests/auth.test.ts" - ], - dependencies: [ - "Task 3 depends on Task 2 (middleware needs JWT utilities)", - "Task 4 depends on Task 3 (routes need middleware)", - "Task 5 depends on Tasks 1-4 (tests need complete implementation)" - ], - risks: [ - "Token refresh timing may conflict with existing session logic - test thoroughly", - "Breaking change if existing auth is in use - plan migration strategy" - ], - estimated_time: "30-45 minutes", - recommended_execution: "CLI" // Based on clear requirements and straightforward implementation -} -``` - -**Output Structure**: -```javascript -planObject = { - summary: "2-3 sentence overview", - approach: "Implementation strategy", - tasks: [ - "Task 1: ...", - "Task 2: ...", - // ... 3-10 tasks based on complexity - ], - complexity: "Low|Medium|High", - dependencies: ["task1 -> task2", ...], // if Medium/High - risks: ["risk1", "risk2", ...], // if High - estimated_time: "X minutes", - recommended_execution: "Direct|CLI" -} -``` +**Output**: `planObject` (see Data Structures section) **Progress Tracking**: -- Mark Phase 3 as completed -- Mark Phase 4 as in_progress +- Mark Phase 3 completed +- Mark Phase 4 in_progress **Expected Duration**: -- Low complexity: 20-30 seconds (direct) -- Medium/High complexity: 40-60 seconds (agent-based) +- Low: 20-30 seconds (direct) +- Medium/High: 40-60 seconds (agent-based) --- ### Phase 4: Task Confirmation & Execution Selection -**User Interaction Flow**: Two-dimensional confirmation (task + execution method) +**Two-Step Confirmation Process** -**Operations**: -- Display plan summary with full task breakdown -- Collect two-dimensional user input: Task confirmation + Execution method selection -- Support modification flow if user requests changes +**Step 4.1: Display Plan Summary** -**Question 1: Task Confirmation** +Output complete plan as regular text: -Display plan to user and ask for confirmation: -- Show: summary, approach, task breakdown, dependencies, risks, complexity, estimated time -- Options: "Confirm" / "Modify" / "Cancel" -- If Modify: Collect feedback via "Other" option, re-run Phase 3 with modifications -- If Cancel: Exit workflow -- If Confirm: Proceed to Question 2 +``` +## Implementation Plan -**Question 2: Execution Method Selection** (Only if task confirmed) +**Summary**: ${planObject.summary} -Ask user to select execution method: -- Show recommendation from `planObject.recommended_execution` -- Options: - - "Direct - Execute with Agent" (@code-developer) - - "CLI - Gemini" (gemini-2.5-pro) - - "CLI - Codex" (gpt-5) - - "CLI - Qwen" (coder-model) -- Store selection for Phase 5 execution +**Approach**: ${planObject.approach} + +**Task Breakdown** (${planObject.tasks.length} tasks): +${planObject.tasks.map((task, i) => ` +${i+1}. **${task.title}** (${task.file}) + - What: ${task.description} + - How: ${task.implementation.length} steps + - Reference: ${task.reference.pattern} + - Verification: ${task.acceptance.length} criteria +`).join('')} + +**Complexity**: ${planObject.complexity} +**Estimated Time**: ${planObject.estimated_time} +**Recommended Execution**: ${planObject.recommended_execution} +``` + +**Step 4.2: Collect User Confirmation** + +Four questions via single AskUserQuestion call: -**Simplified AskUserQuestion Reference**: ```javascript -// Question 1: Task Confirmation AskUserQuestion({ - questions: [{ - question: `[Display plan with all details]\n\nDo you confirm this plan?`, - header: "Confirm Plan", - options: [ - { label: "Confirm", description: "Proceed to execution" }, - { label: "Modify", description: "Adjust plan" }, - { label: "Cancel", description: "Abort" } - ] - }] -}) + questions: [ + { + question: `**Plan Summary**: ${planObject.summary} -// Question 2: Execution Method (if confirmed) -AskUserQuestion({ - questions: [{ - question: `Select execution method:\n[Show recommendation and tool descriptions]`, - header: "Execution Method", - options: [ - { label: "Direct - Agent", description: "Interactive execution" }, - { label: "CLI - Gemini", description: "gemini-2.5-pro" }, - { label: "CLI - Codex", description: "gpt-5" }, - { label: "CLI - Qwen", description: "coder-model" } - ] - }] +**Tasks**: ${planObject.tasks.length} | **Complexity**: ${planObject.complexity} | **Time**: ${planObject.estimated_time} + +Confirm plan? (Multi-select: can supplement via "Other")`, + header: "Confirm Plan", + multiSelect: true, + options: [ + { label: "Allow", description: "Proceed as-is" }, + { label: "Modify", description: "Adjust before execution" }, + { label: "Cancel", description: "Abort workflow" } + ] + }, + { + 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: ${planObject.complexity === 'Low' ? 'Agent' : 'Codex'}` } + ] + }, + { + question: "Enable code review after execution?\n\n(Custom tools via \"Other\": qwen, codex, etc.)", + header: "Code Review", + multiSelect: false, + options: [ + { label: "Gemini Review", description: "Gemini CLI (gemini-2.5-pro)" }, + { label: "Agent Review", description: "@code-reviewer agent" }, + { label: "Skip", description: "No review" } + ] + }, + { + question: "Export plan to Enhanced Task JSON file?\n\nAllows reuse with lite-execute later.", + header: "Export JSON", + multiSelect: false, + options: [ + { label: "Yes", description: "Export to JSON (recommended for complex tasks)" }, + { label: "No", description: "Keep in-memory only" } + ] + } + ] }) ``` **Decision Flow**: ``` -Task Confirmation: - ├─ Confirm → Execution Method Selection → Phase 5 - ├─ Modify → Collect feedback → Re-run Phase 3 - └─ Cancel → Exit (no execution) +Task Confirmation (Multi-select): + ├─ Allow (+ supplements) → Execution Method Selection + ├─ Modify (+ supplements) → Re-run Phase 3 + └─ Cancel → Exit -Execution Method Selection: - ├─ Direct - Execute with Agent → Launch @code-developer - ├─ CLI - Gemini → Build and execute Gemini command - ├─ CLI - Codex → Build and execute Codex command - └─ CLI - Qwen → Build and execute Qwen command +Execution Method (Single-select): + ├─ Agent → Launch @code-developer + ├─ Codex → Execute with codex CLI + └─ Auto → Low complexity: Agent | Medium/High: Codex + +Code Review (after execution): + ├─ Skip → No review + ├─ Gemini Review → gemini CLI analysis + ├─ Agent Review → Current Claude review + └─ Other → Custom tool (e.g., qwen, codex) + +Export JSON: + ├─ Yes → Export to .workflow/lite-plans/plan-{timestamp}.json + └─ No → In-memory only ``` **Progress Tracking**: -- Mark Phase 4 as completed -- Mark Phase 5 as in_progress - -**Expected Duration**: User-dependent (1-3 minutes typical) +- Mark Phase 4 completed +- Mark Phase 5 in_progress --- -### Phase 5: Execution & Progress Tracking +### Phase 5: Dispatch to Execution -**Operations**: -- Create TodoWrite task list from plan breakdown -- Launch selected execution method (agent or CLI) -- Track execution progress with real-time TodoWrite updates -- Display status to user +**Step 5.1: Export Enhanced Task JSON (Optional)** -**Step 5.1: Create TodoWrite Task List** +Only execute if `userSelection.export_task_json === "Yes"`: -**Before execution starts**, create task list: ```javascript -TodoWrite({ - todos: planObject.tasks.map((task, index) => ({ - content: task, +if (userSelection.export_task_json === "Yes") { + const timestamp = new Date().toISOString().replace(/[:.]/g, '-') + const taskId = `LP-${timestamp}` + const filename = `.workflow/lite-plans/${taskId}.json` + + const enhancedTaskJson = { + id: taskId, + title: original_task_description, status: "pending", - activeForm: task.replace(/^(.*?):/, "$1ing:") // "Implement X" -> "Implementing X" - })) -}) + + meta: { + type: "planning", + created_at: new Date().toISOString(), + complexity: planObject.complexity, + estimated_time: planObject.estimated_time, + recommended_execution: planObject.recommended_execution, + workflow: "lite-plan" + }, + + context: { + requirements: [original_task_description], + plan: { + summary: planObject.summary, + approach: planObject.approach, + tasks: planObject.tasks + }, + exploration: explorationContext || null, + clarifications: clarificationContext || null, + focus_paths: explorationContext?.relevant_files || [], + acceptance: planObject.tasks.flatMap(t => t.acceptance) + } + } + + Write(filename, JSON.stringify(enhancedTaskJson, null, 2)) + console.log(`Enhanced Task JSON exported to: ${filename}`) + console.log(`Reuse with: /workflow:lite-execute ${filename}`) +} ``` -**Example Task List**: -``` -[ ] Implement authentication service in src/auth/service.ts -[ ] Create JWT token utilities in src/auth/jwt.ts -[ ] Add authentication middleware to src/middleware/auth.ts -[ ] Update API routes to use authentication -[ ] Add integration tests for auth flow -``` +**Step 5.2: Store Execution Context** -**Step 5.2: Launch Execution** - -Based on user selection in Phase 4, execute appropriate method: - -#### Option A: Direct Execution with Agent - -**Operations**: -- Launch @code-developer agent with full plan context -- Agent receives exploration findings, clarifications, and task breakdown -- Agent call format: - ```javascript - Task( - subagent_type="code-developer", - description="Implement planned tasks with progress tracking", - prompt=` - Implement the following tasks with TodoWrite progress updates: - - Summary: ${planObject.summary} - - Task Breakdown: - ${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')} - - ${planObject.dependencies ? `\nTask Dependencies:\n${planObject.dependencies.join('\n')}` : ''} - - Implementation Approach: - ${planObject.approach} - - Code Context: - ${explorationContext || "No exploration performed"} - - ${clarificationContext ? `\nClarifications:\n${clarificationContext}` : ''} - - ${planObject.risks ? `\nRisks to Consider:\n${planObject.risks.join('\n')}` : ''} - - IMPORTANT Instructions: - - Update TodoWrite as you complete each task (mark as completed) - - Follow task dependencies if specified - - Implement tasks in sequence unless independent - - Test functionality as you go - - Handle risks proactively - ` - ) - ``` - -**Agent Responsibilities**: -- Mark tasks as in_progress when starting -- Mark tasks as completed when finished -- Update TodoWrite in real-time for user visibility - -#### Option B: CLI Execution (Gemini/Codex/Qwen) - -**Operations**: -- Build CLI command with comprehensive context -- Execute CLI tool with write permissions -- Monitor CLI output and update TodoWrite based on progress indicators -- Parse CLI completion signals to mark tasks as done - -**Command Format (Gemini)** - Full context with exploration and clarifications: -```bash -gemini -p " -PURPOSE: Implement planned tasks with full context from exploration and planning -TASK: -${planObject.tasks.map((t, i) => `• ${t}`).join('\n')} - -MODE: write - -CONTEXT: @**/* | Memory: Implementation plan from lite-plan workflow - -## Exploration Findings -${explorationContext ? ` -Project Structure: -${explorationContext.project_structure || 'Not available'} - -Relevant Files: -${explorationContext.relevant_files?.join('\n') || 'Not specified'} - -Current Implementation Patterns: -${explorationContext.patterns || 'Not analyzed'} - -Dependencies and Integration Points: -${explorationContext.dependencies || 'Not specified'} - -Architecture Constraints: -${explorationContext.constraints || 'None identified'} -` : 'No exploration performed (task did not require codebase context)'} - -## User Clarifications -${clarificationContext ? ` -The following clarifications were provided by the user after exploration: -${Object.entries(clarificationContext).map(([q, a]) => `Q: ${q}\nA: ${a}`).join('\n\n')} -` : 'No clarifications needed'} - -## Implementation Plan Context -Task Summary: ${planObject.summary} - -Implementation Approach: -${planObject.approach} - -${planObject.dependencies ? ` -Task Dependencies (execute in order): -${planObject.dependencies.join('\n')} -` : ''} - -${planObject.risks ? ` -Identified Risks: -${planObject.risks.join('\n')} -` : ''} - -Complexity Level: ${planObject.complexity} -Estimated Time: ${planObject.estimated_time} - -EXPECTED: All tasks implemented following the plan approach, with proper error handling and testing - -RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow implementation approach exactly | Handle identified risks proactively | write=CREATE/MODIFY/DELETE -" -m gemini-2.5-pro --approval-mode yolo -``` - -**Command Format (Codex)** - Session-based with resume support: - -**First Execution (Establish Session)**: -```bash -codex --full-auto exec " -TASK: ${planObject.summary} - -## Task Breakdown -${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')} - -${planObject.dependencies ? `\n## Task Dependencies\n${planObject.dependencies.join('\n')}` : ''} - -## Implementation Approach -${planObject.approach} - -## 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')}` : ''} - -${planObject.risks ? `\n## Risks to Handle\n${planObject.risks.join('\n')}` : ''} - -## Execution Instructions -- Complete all tasks following the breakdown sequence -- Respect task dependencies if specified -- Test functionality as you implement -- Handle identified risks proactively -- Create session for potential resume if needed - -Complexity: ${planObject.complexity} -" -m gpt-5 --skip-git-repo-check -s danger-full-access -``` - -**Subsequent Executions (Resume if needed)**: -```bash -# If first execution fails or is interrupted, can resume: -codex --full-auto exec " -Continue implementation from previous session. - -Remaining tasks: -${remaining_tasks.map((t, i) => `${i+1}. ${t}`).join('\n')} - -Maintain context from previous execution. -" resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access -``` - -**Codex Session Strategy**: -- First execution establishes full context and creates session -- If execution is interrupted or fails, use `resume --last` to continue -- Resume inherits all context from original execution -- Useful for complex tasks that may hit timeouts or require iteration - -**Command Format (Qwen)** - Full context similar to Gemini: -```bash -qwen -p " -PURPOSE: Implement planned tasks with comprehensive context - -TASK: -${planObject.tasks.map((t, i) => `• ${t}`).join('\n')} - -MODE: write - -CONTEXT: @**/* | Memory: Full implementation context from lite-plan - -## Code Exploration Results -${explorationContext ? ` -Analyzed Project Structure: -${explorationContext.project_structure || 'Standard structure'} - -Key Files to Modify: -${explorationContext.relevant_files?.join('\n') || 'To be determined during implementation'} - -Existing Code Patterns: -${explorationContext.patterns || 'Follow codebase conventions'} - -Dependencies: -${explorationContext.dependencies || 'None specified'} - -Constraints: -${explorationContext.constraints || 'None identified'} -` : 'No exploration performed - analyze codebase patterns as you implement'} - -## Clarifications from User -${clarificationContext ? ` -${Object.entries(clarificationContext).map(([question, answer]) => ` -Question: ${question} -Answer: ${answer} -`).join('\n')} -` : 'No additional clarifications provided'} - -## Implementation Strategy -Summary: ${planObject.summary} - -Approach: -${planObject.approach} - -${planObject.dependencies ? ` -Task Order (follow sequence): -${planObject.dependencies.join('\n')} -` : ''} - -${planObject.risks ? ` -Risk Mitigation: -${planObject.risks.join('\n')} -` : ''} - -Task Complexity: ${planObject.complexity} -Time Estimate: ${planObject.estimated_time} - -EXPECTED: Complete implementation with tests and proper error handling - -RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow approach strictly | Test thoroughly | write=CREATE/MODIFY/DELETE -" --approval-mode yolo -``` - -**Execution with Progress Tracking**: ```javascript -// Launch CLI in background -bash_result = Bash( - command=cli_command, - timeout=600000, // 10 minutes - run_in_background=true -) - -// Monitor output and update TodoWrite -// Parse CLI output for task completion indicators -// Update TodoWrite when tasks complete -// Example: When CLI outputs "✓ Task 1 complete" -> Mark task 1 as completed +executionContext = { + planObject: planObject, + explorationContext: explorationContext || null, + clarificationContext: clarificationContext || null, + executionMethod: userSelection.execution_method, + codeReviewTool: userSelection.code_review_tool, + originalUserInput: original_task_description +} ``` -**CLI Progress Monitoring**: -- Parse CLI output for completion keywords ("done", "complete", "✓", etc.) -- Update corresponding TodoWrite tasks based on progress -- Provide real-time visibility to user +**Step 5.3: Call lite-execute** -**Step 5.3: Track Execution Progress** - -**Real-time TodoWrite Updates**: ```javascript -// As execution progresses, update task status: - -// Task started -TodoWrite({ - todos: [ - { content: "Implement auth service", status: "in_progress", activeForm: "Implementing auth service" }, - { content: "Create JWT utilities", status: "pending", activeForm: "Creating JWT utilities" }, - // ... - ] -}) - -// Task completed -TodoWrite({ - todos: [ - { content: "Implement auth service", status: "completed", activeForm: "Implementing auth service" }, - { content: "Create JWT utilities", status: "in_progress", activeForm: "Creating JWT utilities" }, - // ... - ] -}) +SlashCommand(command="/workflow:lite-execute --in-memory") ``` -**User Visibility**: -- User sees real-time task progress -- Current task highlighted as "in_progress" -- Completed tasks marked with checkmark -- Pending tasks remain unchecked +**Execution Handoff**: +- lite-execute reads `executionContext` variable +- All execution logic handled by lite-execute +- lite-plan completes after successful handoff **Progress Tracking**: -- Mark Phase 5 as in_progress throughout execution -- Mark Phase 5 as completed when all tasks done -- Final status summary displayed to user - -**Expected Duration**: Varies by task complexity and execution method -- Low complexity: 5-15 minutes -- Medium complexity: 15-45 minutes -- High complexity: 45-120 minutes - ---- +- Mark Phase 5 completed +- Execution tracking delegated to lite-execute ## Best Practices ### Workflow Intelligence -1. **Dynamic Adaptation**: Workflow automatically adjusts based on task characteristics - - Smart exploration: Only runs when task requires codebase context - - Adaptive planning: Simple tasks get direct planning, complex tasks use specialized agent - - Context-aware clarification: Only asks questions when truly needed +1. **Dynamic Adaptation**: Workflow adjusts based on task characteristics + - Smart exploration: Only when codebase context needed + - Adaptive planning: Simple → direct, complex → specialized agent + - Context-aware clarification: Only when truly needed - Reduces unnecessary steps while maintaining thoroughness -2. **Progressive Clarification**: Gather information at the right time - - Phase 1: Explore codebase to understand current state - - Phase 2: Ask clarifying questions based on exploration findings - - Phase 3: Plan with complete context (task + exploration + clarifications) - - Avoids premature assumptions and reduces rework +2. **Flag-Based Control**: Use `-e`/`--explore` to force exploration when: + - Task appears simple but requires codebase context + - Auto-detection might miss subtle integration points + - Comprehensive code understanding needed -3. **Complexity-Aware Planning**: Planning strategy matches task complexity - - Low complexity (1-2 files): Direct planning by current Claude (fast, 20-30s) - - Medium complexity (3-5 files): CLI planning agent (detailed, 40-50s) - - High complexity (6+ files): CLI planning agent with risk analysis (thorough, 50-60s) - - Balances speed and thoroughness appropriately +3. **Progressive Clarification**: Information gathered at right time + - Phase 1: Explore codebase (current state) + - Phase 2: Ask questions (based on findings) + - Phase 3: Plan with complete context + - Avoids premature assumptions, reduces rework -4. **Two-Dimensional Confirmation**: Separate task approval from execution method - - First dimension: Confirm/Modify/Cancel plan - - Second dimension: Direct execution vs CLI execution +4. **Complexity-Aware Planning**: Strategy matches task complexity + - Low (1-2 files): Direct planning (fast, 20-30s) + - Medium (3-5 files): CLI planning (detailed, 40-50s) + - High (6+ files): CLI planning with risk analysis (thorough, 50-60s) + +5. **Two-Step Confirmation**: Clear separation between plan and control + - Step 1: Display plan as readable text (not in question) + - Step 2: Collect multi-dimensional input + - Plan confirmation (multi-select with supplements) + - Execution method selection + - Code review tool selection (custom via "Other") + - JSON export option - Allows plan refinement without re-selecting execution method - - Supports iterative planning with user feedback ### Task Management -1. **Live Progress Tracking**: TodoWrite provides real-time execution visibility - - Tasks created before execution starts - - Updated in real-time as work progresses - - User sees current task being worked on - - Clear completion status throughout execution - -2. **Phase-Based Organization**: 5 distinct phases with clear transitions - - Phase 1: Task Analysis & Exploration (automatic) +1. **Phase-Based Organization**: 5 distinct phases with clear transitions + - Phase 1: Analysis & Exploration (automatic) - Phase 2: Clarification (conditional, interactive) - Phase 3: Planning (automatic, adaptive) - - Phase 4: Confirmation (interactive, two-dimensional) - - Phase 5: Execution & Tracking (automatic with live updates) + - Phase 4: Confirmation (interactive, multi-dimensional) + - Phase 5: Execution Dispatch (automatic) -3. **Flexible Task Counts**: Task breakdown adapts to complexity - - Low complexity: 3-5 tasks (focused) - - Medium complexity: 5-7 tasks (detailed) - - High complexity: 7-10 tasks (comprehensive) - - Avoids artificial constraints while maintaining focus +2. **Flexible Task Counts**: Adapts to complexity + - Low: 3-5 tasks (focused) + - Medium: 5-7 tasks (detailed) + - High: 7-10 tasks (comprehensive) -4. **Dependency Tracking**: Medium/High complexity tasks include dependencies - - Explicit task ordering when sequence matters - - Parallel execution hints when tasks are independent - - Risk flagging for complex interactions - - Helps agent/CLI execute correctly +3. **No File Artifacts During Planning**: + - All planning stays in memory + - Optional Enhanced Task JSON export (user choice) + - Faster workflow, cleaner workspace + - Plan context passed directly to execution ### Planning Standards 1. **Context-Rich Planning**: Plans include all relevant context - - Exploration findings (code structure, patterns, constraints) + - Exploration findings (structure, patterns, constraints) - User clarifications (requirements, preferences, decisions) - - Complexity assessment (risks, dependencies, time estimates) + - Complexity assessment (risks, dependencies, estimates) - Execution recommendations (Direct vs CLI, specific tool) -2. **Modification Support**: Plans can be iteratively refined - - User can request plan modifications in Phase 4 +2. **Modification Support**: Iterative refinement + - User can request modifications in Phase 4 - Feedback incorporated into re-planning - - No need to restart from scratch - - Supports collaborative planning workflow - -3. **No File Artifacts**: All planning stays in memory - - Faster workflow without I/O overhead - - Cleaner workspace - - Plan context passed directly to execution - - Reduces complexity and maintenance + - No restart from scratch + - Collaborative planning workflow ## Error Handling -### Common Errors - | Error | Cause | Resolution | |-------|-------|------------| -| Phase 1 Exploration Failure | cli-explore-agent unavailable or timeout | Skip exploration, set `explorationContext = null`, log warning, continue to Phase 2/3 with task description only | -| Phase 2 Clarification Timeout | User no response > 5 minutes | Use exploration findings as-is without clarification, proceed to Phase 3 with warning | -| Phase 3 Planning Agent Failure | cli-planning-agent unavailable or timeout | Fallback to direct planning by current Claude (simplified plan), continue to Phase 4 | -| Phase 3 Planning Timeout | Planning takes > 90 seconds | Generate simplified direct plan, mark as "Quick Plan", continue to Phase 4 with reduced detail | -| Phase 4 Confirmation Timeout | User no response > 5 minutes | Save plan context to temporary var, display resume instructions, exit gracefully | -| Phase 4 Modification Loop | User requests modify > 3 times | Suggest breaking task into smaller pieces or using /workflow:plan for comprehensive planning | -| Phase 5 CLI Tool Unavailable | Selected CLI tool not installed | Show installation instructions, offer to re-select (Direct execution or different CLI) | -| Phase 5 Execution Failure | Agent/CLI crashes or errors | Display error details, save partial progress from TodoWrite, suggest manual recovery or retry | +| Phase 1 Exploration Failure | cli-explore-agent unavailable/timeout | Skip exploration, set `explorationContext = null`, continue with task description only | +| Phase 2 Clarification Timeout | User no response > 5 minutes | Use exploration findings as-is, proceed to Phase 3 with warning | +| Phase 3 Planning Agent Failure | cli-lite-planning-agent unavailable/timeout | Fallback to direct planning by current Claude | +| Phase 3 Planning Timeout | Planning > 90 seconds | Generate simplified plan, mark as "Quick Plan", continue | +| Phase 4 Confirmation Timeout | User no response > 5 minutes | Save context to temp var, display resume instructions, exit gracefully | +| Phase 4 Modification Loop | User requests modify > 3 times | Suggest breaking task into smaller pieces or using `/workflow:plan` | -## Input/Output +## Data Structures -### Input Requirements -- Task description: String or path to .md file (required) - - Should be specific and concrete - - Can include context about existing code or requirements - - Examples: - - "Implement user authentication with JWT tokens" - - "Refactor logging module for better performance" - - "Add unit tests for authentication service" -- Flags (optional): - - `--tool `: Preset execution tool (claude|gemini|codex|qwen) - - `--quick`: Skip code exploration phase +### explorationContext -### Output Format +Exploration findings from cli-explore-agent (Phase 1): -**In-Memory Plan Object**: ```javascript { - summary: "2-3 sentence overview of implementation", - approach: "High-level implementation strategy", - tasks: [ - "Task 1: Specific action with file locations", - "Task 2: Specific action with file locations", - // ... 3-7 tasks total - ], - complexity: "Low|Medium|High", - recommended_tool: "Claude|Gemini|Codex|Qwen", - estimated_time: "X minutes" + project_structure: string, // Overall architecture description + relevant_files: string[], // File paths to be modified/referenced + patterns: string, // Existing patterns and conventions + dependencies: string, // Dependencies and integration points + integration_points: string, // Where this connects with existing code + constraints: string, // Technical constraints + clarification_needs: [ // Questions requiring user input + { + question: string, + context: string, + options: string[] + } + ] } ``` -**Execution Result**: -- Immediate dispatch to selected tool/agent with plan context -- No file artifacts generated during planning phase -- Execution starts immediately after user confirmation -- Tool/agent handles implementation and any necessary file operations +### planObject +Implementation plan from Phase 3: + +```javascript +{ + summary: string, // 2-3 sentence overview + approach: string, // High-level implementation strategy + tasks: [ // 3-10 structured task objects + { + title: string, // Task title + file: string, // Target file path + action: string, // Create|Update|Implement|Refactor|Add|Delete + description: string, // What to implement (1-2 sentences) + implementation: string[], // Step-by-step how-to (3-7 steps) + reference: { // What to reference + pattern: string, // Pattern name + files: string[], // Reference file paths + examples: string // Specific guidance + }, + acceptance: string[] // Verification criteria (2-4 items) + } + ], + estimated_time: string, // Total implementation time + recommended_execution: string, // "Agent" (Low) or "Codex" (Medium/High) + complexity: string // "Low" | "Medium" | "High" +} +``` + +### executionContext + +Context passed to lite-execute via --in-memory (Phase 5): + +```javascript +{ + planObject: { // Complete planObject (see above) + summary: string, + approach: string, + tasks: [...], + estimated_time: string, + recommended_execution: string, + complexity: string + }, + explorationContext: {...} | null, // See explorationContext above + clarificationContext: {...} | null, // User responses from Phase 2 + executionMethod: "Agent" | "Codex" | "Auto", + codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string, + originalUserInput: string // User's original task description +} +``` + +### Enhanced Task JSON Export + +When user selects "Export JSON", lite-plan exports this structure: + +```json +{ + "id": "LP-{timestamp}", + "title": "Original task description", + "status": "pending", + + "meta": { + "type": "planning", + "created_at": "ISO timestamp", + "complexity": "Low|Medium|High", + "estimated_time": "X minutes", + "recommended_execution": "Agent|Codex", + "workflow": "lite-plan" + }, + + "context": { + "requirements": ["Original task description"], + "plan": { + "summary": "2-3 sentence overview", + "approach": "High-level strategy", + "tasks": [/* Array of task objects */] + }, + "exploration": {/* explorationContext */} | null, + "clarifications": {/* clarificationContext */} | null, + "focus_paths": ["src/auth", "tests/auth"], + "acceptance": ["Criteria from plan.tasks"] + } +} +``` + +**Schema Notes**: +- Aligns with Enhanced Task JSON Schema (6-field structure) +- `context_package_path` omitted (not used by lite-plan) +- `flow_control` omitted (handled by lite-execute) +- `focus_paths` derived from `exploration.relevant_files` +- `acceptance` derived from `plan.tasks` diff --git a/.claude/skills/command-guide/reference/commands/workflow/plan.md b/.claude/skills/command-guide/reference/commands/workflow/plan.md index d562b3c5..4f5d47cd 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/plan.md +++ b/.claude/skills/command-guide/reference/commands/workflow/plan.md @@ -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 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 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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/resume.md b/.claude/skills/command-guide/reference/commands/workflow/resume.md deleted file mode 100644 index 98dc253a..00000000 --- a/.claude/skills/command-guide/reference/commands/workflow/resume.md +++ /dev/null @@ -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 "" -``` - -## 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* \ No newline at end of file diff --git a/.claude/skills/command-guide/reference/commands/workflow/review.md b/.claude/skills/command-guide/reference/commands/workflow/review.md index aa1e456b..1950d6db 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/review.md +++ b/.claude/skills/command-guide/reference/commands/workflow/review.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/session/complete.md b/.claude/skills/command-guide/reference/commands/workflow/session/complete.md index 7abe395d..a510c872 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/session/complete.md +++ b/.claude/skills/command-guide/reference/commands/workflow/session/complete.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/session/list.md b/.claude/skills/command-guide/reference/commands/workflow/session/list.md index f46c90d9..784bf480 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/session/list.md +++ b/.claude/skills/command-guide/reference/commands/workflow/session/list.md @@ -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 ``` \ No newline at end of file diff --git a/.claude/skills/command-guide/reference/commands/workflow/session/resume.md b/.claude/skills/command-guide/reference/commands/workflow/session/resume.md index 19c8d390..77e99c54 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/session/resume.md +++ b/.claude/skills/command-guide/reference/commands/workflow/session/resume.md @@ -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 ``` diff --git a/.claude/skills/command-guide/reference/commands/workflow/session/start.md b/.claude/skills/command-guide/reference/commands/workflow/session/start.md index 681a27d3..8770c8d1 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/session/start.md +++ b/.claude/skills/command-guide/reference/commands/workflow/session/start.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/status.md b/.claude/skills/command-guide/reference/commands/workflow/status.md index 33070dc1..0e4722e5 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/status.md +++ b/.claude/skills/command-guide/reference/commands/workflow/status.md @@ -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 ``` \ No newline at end of file diff --git a/.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md b/.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md index 3cb1d4b7..f395561b 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md +++ b/.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md @@ -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/ diff --git a/.claude/skills/command-guide/reference/commands/workflow/tdd-verify.md b/.claude/skills/command-guide/reference/commands/workflow/tdd-verify.md index fbfb85da..395c1ed0 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/tdd-verify.md +++ b/.claude/skills/command-guide/reference/commands/workflow/tdd-verify.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/test-cycle-execute.md b/.claude/skills/command-guide/reference/commands/workflow/test-cycle-execute.md index a2ea6fd6..59c40453 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/test-cycle-execute.md +++ b/.claude/skills/command-guide/reference/commands/workflow/test-cycle-execute.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md b/.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md index 0e4119be..edad3b00 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md +++ b/.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/test-gen.md b/.claude/skills/command-guide/reference/commands/workflow/test-gen.md index 6ae03370..00287e8f 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/test-gen.md +++ b/.claude/skills/command-guide/reference/commands/workflow/test-gen.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md b/.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md index 2c8b9fe6..01bd6b98 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md +++ b/.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md b/.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md index 923d4fd2..3e51cd9a 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md +++ b/.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md index c90bd32f..2c99ceea 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md +++ b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md @@ -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), diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md index 7cebed30..04e93a8a 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md +++ b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md @@ -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), diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate.md b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate.md index 1c35fdaf..c3fe5213 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate.md +++ b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate.md @@ -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" } diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/tdd-coverage-analysis.md b/.claude/skills/command-guide/reference/commands/workflow/tools/tdd-coverage-analysis.md index 7f8a7c7d..1bdb1c2f 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/tools/tdd-coverage-analysis.md +++ b/.claude/skills/command-guide/reference/commands/workflow/tools/tdd-coverage-analysis.md @@ -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 ``` diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/test-concept-enhanced.md b/.claude/skills/command-guide/reference/commands/workflow/tools/test-concept-enhanced.md index 2fb173ee..e58aadde 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/tools/test-concept-enhanced.md +++ b/.claude/skills/command-guide/reference/commands/workflow/tools/test-concept-enhanced.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md b/.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md index d05d1d70..84dedb1f 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md +++ b/.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md @@ -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/animation-extract.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/animation-extract.md index 92fdb4d2..4a13387b 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/animation-extract.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/animation-extract.md @@ -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) diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/capture.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/capture.md deleted file mode 100644 index c080ee09..00000000 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/capture.md +++ /dev/null @@ -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 ] [--session ] -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` diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/update.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/design-sync.md similarity index 87% rename from .claude/skills/command-guide/reference/commands/workflow/ui-design/update.md rename to .claude/skills/command-guide/reference/commands/workflow/ui-design/design-sync.md index e654d98f..5b1d8cc2 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/update.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/design-sync.md @@ -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 [--selected-prototypes ""] 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] "" **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. diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md index b5e83643..c467346c 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md @@ -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") diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-layers.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-layers.md deleted file mode 100644 index c0f157ce..00000000 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-layers.md +++ /dev/null @@ -1,611 +0,0 @@ ---- -name: explore-layers -description: Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer -argument-hint: --url --depth <1-5> [--design-id ] [--session ] -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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md index c8cb5f7b..01ba7e6f 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md @@ -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) diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md index 8bcc4472..3c631fd0 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md @@ -67,7 +67,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*) **Optional Parameters**: - `--session `: 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 diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/import-from-code.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/import-from-code.md index 7aa40b89..8aa27a87 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/import-from-code.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/import-from-code.md @@ -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" diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md index 68e8621d..098361bb 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md @@ -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) diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/list.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/list.md deleted file mode 100644 index 11ccafe0..00000000 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/list.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -name: list -description: List all available design runs with metadata (session, created time, prototype count) -argument-hint: [--session ] -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 ' to create a design run" - fi -else - echo "Total: $found_count design run(s)" - echo "" - echo "💡 USE: /workflow:ui-design:generate --design-id \"\"" - echo " OR: /workflow:ui-design:generate --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 \\' to create a design run' - fi - else - echo \"Total: \$found_count design run(s)\" - echo '' - echo '💡 USE: /workflow:ui-design:generate --design-id \"\"' - echo ' OR: /workflow:ui-design:generate --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 "" - OR: /workflow:ui-design:generate --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 "" - OR: /workflow:ui-design:generate --session "" -``` diff --git a/.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md b/.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md index f686a3fe..9a36806b 100644 --- a/.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md +++ b/.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md @@ -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) diff --git a/.claude/workflows/task-core.md b/.claude/workflows/task-core.md index 17a3f574..131ae452 100644 --- a/.claude/workflows/task-core.md +++ b/.claude/workflows/task-core.md @@ -133,8 +133,8 @@ All task files use this simplified 5-field schema: ### Active Session Detection ```bash -# Check for active session marker -active_session=$(ls .workflow/.active-* 2>/dev/null | head -1) +# Check for active session in sessions directory +active_session=$(find .workflow/sessions/ -name 'WFS-*' -type d 2>/dev/null | head -1) ``` ### Workflow Context Inheritance @@ -144,10 +144,10 @@ Tasks inherit from: 3. `IMPL_PLAN.md` - Planning document ### File Locations -- **Task JSON**: `.workflow/WFS-[topic]/.task/IMPL-*.json` (uppercase required) -- **Session State**: `.workflow/WFS-[topic]/workflow-session.json` -- **Planning Doc**: `.workflow/WFS-[topic]/IMPL_PLAN.md` -- **Progress**: `.workflow/WFS-[topic]/TODO_LIST.md` +- **Task JSON**: `.workflow/sessions/WFS-[topic]/.task/IMPL-*.json` (uppercase required) +- **Session State**: `.workflow/sessions/WFS-[topic]/workflow-session.json` +- **Planning Doc**: `.workflow/sessions/WFS-[topic]/IMPL_PLAN.md` +- **Progress**: `.workflow/sessions/WFS-[topic]/TODO_LIST.md` ## Agent Mapping diff --git a/.claude/workflows/workflow-architecture.md b/.claude/workflows/workflow-architecture.md index 4a0949d6..bab11ffc 100644 --- a/.claude/workflows/workflow-architecture.md +++ b/.claude/workflows/workflow-architecture.md @@ -24,48 +24,50 @@ This document defines the complete workflow system architecture using a **JSON-o ## Session Management -### Active Session Marker System -**Ultra-Simple Active Tracking**: `.workflow/.active-[session-name]` +### Directory-Based Session Management +**Simple Location-Based Tracking**: Sessions in `.workflow/sessions/` directory ```bash .workflow/ -├── WFS-oauth-integration/ # Session directory (paused) -├── WFS-user-profile/ # Session directory (paused) -├── WFS-bug-fix-123/ # Session directory (completed) -└── .active-WFS-user-profile # Marker file (indicates active session) +├── sessions/ +│ ├── WFS-oauth-integration/ # Session directory (active or paused) +│ ├── WFS-user-profile/ # Session directory (active or paused) +│ └── WFS-bug-fix-123/ # Session directory (completed) +└── archives/ + └── WFS-old-feature/ # Archived session (completed) ``` -**Marker File Benefits**: -- **Zero Parsing**: File existence check is atomic and instant -- **Atomic Operations**: File creation/deletion is naturally atomic -- **Visual Discovery**: `ls .workflow/.active-*` shows active session immediately -- **Simple Switching**: Delete old marker + create new marker = session switch +**Directory-Based Benefits**: +- **Simple Discovery**: Session location determines state (sessions/ = active/paused, archives/ = completed) +- **No Marker Files**: Location is the state +- **Clean Structure**: Clear separation between active and completed sessions +- **Easy Migration**: Move between sessions/ and archives/ to change state ### Session Operations #### Detect Active Session(s) ```bash -active_sessions=$(find .workflow -name ".active-*" 2>/dev/null) +active_sessions=$(find .workflow/sessions/ -name "WFS-*" -type d 2>/dev/null) count=$(echo "$active_sessions" | wc -l) if [ -z "$active_sessions" ]; then echo "No active session" elif [ "$count" -eq 1 ]; then - session_name=$(basename "$active_sessions" | sed 's/^\.active-//') + session_name=$(basename "$active_sessions") echo "Active session: $session_name" else - echo "Multiple active sessions found:" - echo "$active_sessions" | while read marker; do - session=$(basename "$marker" | sed 's/^\.active-//') + echo "Multiple sessions found:" + echo "$active_sessions" | while read session_dir; do + session=$(basename "$session_dir") echo " - $session" done echo "Please specify which session to work with" fi ``` -#### Switch Session +#### Archive Session ```bash -find .workflow -name ".active-*" -delete && touch .workflow/.active-WFS-new-feature +mv .workflow/sessions/WFS-feature .workflow/archives/WFS-feature ``` ### Session State Tracking @@ -707,41 +709,44 @@ All workflows use the same file structure definition regardless of complexity. * │ │ └── index.html # Navigation page │ └── .run-metadata.json # Run configuration │ -└── WFS-[topic-slug]/ - ├── workflow-session.json # Session metadata and state (REQUIRED) - ├── [.brainstorming/] # Optional brainstorming phase (created when needed) - ├── [.chat/] # CLI interaction sessions (created when analysis is run) - │ ├── chat-*.md # Saved chat sessions - │ └── analysis-*.md # Analysis results - ├── [.process/] # Planning analysis results (created by /workflow:plan) - │ └── ANALYSIS_RESULTS.md # Analysis results and planning artifacts - ├── IMPL_PLAN.md # Planning document (REQUIRED) - ├── TODO_LIST.md # Progress tracking (REQUIRED) - ├── [.summaries/] # Task completion summaries (created when tasks complete) - │ ├── IMPL-*-summary.md # Main task summaries - │ └── IMPL-*.*-summary.md # Subtask summaries - ├── [design-*/] # UI design outputs (created by ui-design workflows) - │ ├── .intermediates/ # Intermediate analysis files - │ │ ├── style-analysis/ # Style analysis data - │ │ │ ├── computed-styles.json # Extracted CSS values - │ │ │ └── design-space-analysis.json # Design directions - │ │ └── layout-analysis/ # Layout analysis data - │ │ ├── dom-structure-{target}.json # DOM extraction - │ │ └── inspirations/ # Layout research - │ │ └── {target}-layout-ideas.txt - │ ├── style-extraction/ # Final design systems - │ │ ├── style-1/ # design-tokens.json, style-guide.md - │ │ └── style-N/ - │ ├── layout-extraction/ # Layout templates - │ │ └── layout-templates.json - │ ├── prototypes/ # Generated HTML/CSS prototypes - │ │ ├── {target}-style-{s}-layout-{l}.html # Final prototypes - │ │ ├── compare.html # Interactive matrix view - │ │ └── index.html # Navigation page - │ └── .run-metadata.json # Run configuration - └── .task/ # Task definitions (REQUIRED) - ├── IMPL-*.json # Main task definitions - └── IMPL-*.*.json # Subtask definitions (created dynamically) +├── sessions/ # Active/paused workflow sessions +│ └── WFS-[topic-slug]/ +│ ├── workflow-session.json # Session metadata and state (REQUIRED) +│ ├── [.brainstorming/] # Optional brainstorming phase (created when needed) +│ ├── [.chat/] # CLI interaction sessions (created when analysis is run) +│ │ ├── chat-*.md # Saved chat sessions +│ │ └── analysis-*.md # Analysis results +│ ├── [.process/] # Planning analysis results (created by /workflow:plan) +│ │ └── ANALYSIS_RESULTS.md # Analysis results and planning artifacts +│ ├── IMPL_PLAN.md # Planning document (REQUIRED) +│ ├── TODO_LIST.md # Progress tracking (REQUIRED) +│ ├── [.summaries/] # Task completion summaries (created when tasks complete) +│ │ ├── IMPL-*-summary.md # Main task summaries +│ │ └── IMPL-*.*-summary.md # Subtask summaries +│ ├── [design-*/] # UI design outputs (created by ui-design workflows) +│ │ ├── .intermediates/ # Intermediate analysis files +│ │ │ ├── style-analysis/ # Style analysis data +│ │ │ │ ├── computed-styles.json # Extracted CSS values +│ │ │ │ └── design-space-analysis.json # Design directions +│ │ │ └── layout-analysis/ # Layout analysis data +│ │ │ ├── dom-structure-{target}.json # DOM extraction +│ │ │ └── inspirations/ # Layout research +│ │ │ └── {target}-layout-ideas.txt +│ │ ├── style-extraction/ # Final design systems +│ │ │ ├── style-1/ # design-tokens.json, style-guide.md +│ │ │ └── style-N/ +│ │ ├── layout-extraction/ # Layout templates +│ │ │ └── layout-templates.json +│ │ ├── prototypes/ # Generated HTML/CSS prototypes +│ │ │ ├── {target}-style-{s}-layout-{l}.html # Final prototypes +│ │ │ ├── compare.html # Interactive matrix view +│ │ │ └── index.html # Navigation page +│ │ └── .run-metadata.json # Run configuration +│ └── .task/ # Task definitions (REQUIRED) +│ ├── IMPL-*.json # Main task definitions +│ └── IMPL-*.*.json # Subtask definitions (created dynamically) +└── archives/ # Completed workflow sessions + └── WFS-[completed-topic]/ # Archived session directories ``` #### Creation Strategy @@ -763,8 +768,8 @@ All workflows use the same file structure definition regardless of complexity. * 4. **One-Off Queries**: Standalone questions or debugging without workflow context **Output Routing Logic**: -- **IF** active session exists AND command is session-relevant: - - Save to `.workflow/WFS-[id]/.chat/[command]-[timestamp].md` +- **IF** active session exists in `.workflow/sessions/` AND command is session-relevant: + - Save to `.workflow/sessions/WFS-[id]/.chat/[command]-[timestamp].md` - **ELSE** (no session OR one-off analysis): - Save to `.workflow/.scratchpad/[command]-[description]-[timestamp].md` @@ -834,10 +839,10 @@ All workflows use the same file structure definition regardless of complexity. * ### Session Management ```bash # Create minimal required structure -mkdir -p .workflow/WFS-topic-slug/.task -echo '{"session_id":"WFS-topic-slug",...}' > .workflow/WFS-topic-slug/workflow-session.json -echo '# Implementation Plan' > .workflow/WFS-topic-slug/IMPL_PLAN.md -echo '# Tasks' > .workflow/WFS-topic-slug/TODO_LIST.md +mkdir -p .workflow/sessions/WFS-topic-slug/.task +echo '{"session_id":"WFS-topic-slug",...}' > .workflow/sessions/WFS-topic-slug/workflow-session.json +echo '# Implementation Plan' > .workflow/sessions/WFS-topic-slug/IMPL_PLAN.md +echo '# Tasks' > .workflow/sessions/WFS-topic-slug/TODO_LIST.md ``` ### Task Operations @@ -861,23 +866,21 @@ mkdir -p .summaries # When first task completes ### Session Consistency Checks & Recovery ```bash -# Validate active session integrity -active_marker=$(find .workflow -name ".active-*" | head -1) -if [ -n "$active_marker" ]; then - session_name=$(basename "$active_marker" | sed 's/^\.active-//') - session_dir=".workflow/$session_name" - if [ ! -d "$session_dir" ]; then - echo "⚠️ Orphaned active marker, removing..." - rm "$active_marker" - fi +# Validate session directory structure +if [ -d ".workflow/sessions/" ]; then + for session_dir in .workflow/sessions/WFS-*; do + if [ ! -f "$session_dir/workflow-session.json" ]; then + echo "⚠️ Missing workflow-session.json in $session_dir" + fi + done fi ``` **Recovery Strategies**: -- **Missing Session Directory**: Remove orphaned active marker -- **Multiple Active Markers**: Keep newest, remove others -- **Corrupted Session File**: Recreate from template -- **Broken Task Hierarchy**: Reconstruct parent-child relationships +- **Missing Session File**: Recreate workflow-session.json from template +- **Corrupted Session File**: Restore from template with basic metadata +- **Broken Task Hierarchy**: Reconstruct parent-child relationships from task JSON files +- **Orphaned Sessions**: Move incomplete sessions to archives/ ## Complexity Classification