mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-19 18:58:47 +08:00
Implement search and reranking functionality with FTS and embedding support
- Added BaseReranker abstract class for defining reranking interfaces. - Implemented FastEmbedReranker using fastembed's TextCrossEncoder for scoring document-query pairs. - Introduced FTSEngine for full-text search capabilities using SQLite FTS5. - Developed SearchPipeline to integrate embedding, binary search, ANN indexing, FTS, and reranking. - Added fusion methods for combining results from different search strategies using Reciprocal Rank Fusion. - Created unit and integration tests for the new search and reranking components. - Established configuration management for search parameters and models.
This commit is contained in:
catlog22
@@ -1,76 +0,0 @@
|
||||
## Context Acquisition (MCP Tools Priority)
|
||||
|
||||
**For task context gathering and analysis, ALWAYS prefer MCP tools**:
|
||||
|
||||
1. **mcp__ace-tool__search_context** - HIGHEST PRIORITY for code discovery
|
||||
- Semantic search with real-time codebase index
|
||||
- Use for: finding implementations, understanding architecture, locating patterns
|
||||
- Example: `mcp__ace-tool__search_context(project_root_path="/path", query="authentication logic")`
|
||||
|
||||
2. **smart_search** - Fallback for structured search
|
||||
- Use `smart_search(query="...")` for keyword/regex search
|
||||
- Use `smart_search(action="find_files", pattern="*.ts")` for file discovery
|
||||
- Supports modes: `auto`, `hybrid`, `exact`, `ripgrep`
|
||||
|
||||
3. **read_file** - Batch file reading
|
||||
- Read multiple files in parallel: `read_file(path="file1.ts")`, `read_file(path="file2.ts")`
|
||||
- Supports glob patterns: `read_file(path="src/**/*.config.ts")`
|
||||
|
||||
**Priority Order**:
|
||||
```
|
||||
ACE search_context (semantic) → smart_search (structured) → read_file (batch read) → shell commands (fallback)
|
||||
```
|
||||
|
||||
**NEVER** use shell commands (`cat`, `find`, `grep`) when MCP tools are available.
|
||||
### read_file - Read File Contents
|
||||
|
||||
**When**: Read files found by smart_search
|
||||
|
||||
**How**:
|
||||
```javascript
|
||||
read_file(path="/path/to/file.ts") // Single file
|
||||
read_file(path="/src/**/*.config.ts") // Pattern matching
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### edit_file - Modify Files
|
||||
|
||||
**When**: Built-in Edit tool fails or need advanced features
|
||||
|
||||
**How**:
|
||||
```javascript
|
||||
edit_file(path="/file.ts", old_string="...", new_string="...", mode="update")
|
||||
edit_file(path="/file.ts", line=10, content="...", mode="insert_after")
|
||||
```
|
||||
|
||||
**Modes**: `update` (replace text), `insert_after`, `insert_before`, `delete_line`
|
||||
|
||||
---
|
||||
|
||||
### write_file - Create/Overwrite Files
|
||||
|
||||
**When**: Create new files or completely replace content
|
||||
|
||||
**How**:
|
||||
```javascript
|
||||
write_file(path="/new-file.ts", content="...")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Exa - External Search
|
||||
|
||||
**When**: Find documentation/examples outside codebase
|
||||
|
||||
**How**:
|
||||
```javascript
|
||||
mcp__exa__search(query="React hooks 2025 documentation")
|
||||
mcp__exa__search(query="FastAPI auth example", numResults=10)
|
||||
mcp__exa__search(query="latest API docs", livecrawl="always")
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `query` (required): Search query string
|
||||
- `numResults` (optional): Number of results to return (default: 5)
|
||||
- `livecrawl` (optional): `"always"` or `"fallback"` for live crawling
|
||||
@@ -1,64 +0,0 @@
|
||||
# File Modification
|
||||
|
||||
Before modifying files, always:
|
||||
- Try built-in Edit tool first
|
||||
- Escalate to MCP tools when built-ins fail
|
||||
- Use write_file only as last resort
|
||||
|
||||
## MCP Tools Usage
|
||||
|
||||
### edit_file - Modify Files
|
||||
|
||||
**When**: Built-in Edit fails, need dry-run preview, or need line-based operations
|
||||
|
||||
**How**:
|
||||
```javascript
|
||||
edit_file(path="/file.ts", oldText="old", newText="new") // Replace text
|
||||
edit_file(path="/file.ts", oldText="old", newText="new", dryRun=true) // Preview diff
|
||||
edit_file(path="/file.ts", oldText="old", newText="new", replaceAll=true) // Replace all
|
||||
edit_file(path="/file.ts", mode="line", operation="insert_after", line=10, text="new line")
|
||||
edit_file(path="/file.ts", mode="line", operation="delete", line=5, end_line=8)
|
||||
```
|
||||
|
||||
**Modes**: `update` (replace text, default), `line` (line-based operations)
|
||||
|
||||
**Operations** (line mode): `insert_before`, `insert_after`, `replace`, `delete`
|
||||
|
||||
---
|
||||
|
||||
### write_file - Create/Overwrite Files
|
||||
|
||||
**When**: Create new files, completely replace content, or edit_file still fails
|
||||
|
||||
**How**:
|
||||
```javascript
|
||||
write_file(path="/new-file.ts", content="file content here")
|
||||
write_file(path="/existing.ts", content="...", backup=true) // Create backup first
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority Logic
|
||||
|
||||
> **Note**: Search priority is defined in `context-tools.md` - smart_search has HIGHEST PRIORITY for all discovery tasks.
|
||||
|
||||
**Search & Discovery** (defer to context-tools.md):
|
||||
1. **smart_search FIRST** for any code/file discovery
|
||||
2. Built-in Grep only for single-file exact line search (location already confirmed)
|
||||
3. Exa for external/public knowledge
|
||||
|
||||
**File Reading**:
|
||||
1. Unknown location → **smart_search first**, then Read
|
||||
2. Known confirmed file → Built-in Read directly
|
||||
3. Pattern matching → smart_search (action="find_files")
|
||||
|
||||
**File Editing**:
|
||||
1. Always try built-in Edit first
|
||||
2. Fails 1+ times → edit_file (MCP)
|
||||
3. Still fails → write_file (MCP)
|
||||
|
||||
## Decision Triggers
|
||||
|
||||
**Search tasks** → Always start with smart_search (per context-tools.md)
|
||||
**Known file edits** → Start with built-in Edit, escalate to MCP if fails
|
||||
**External knowledge** → Use Exa
|
||||
@@ -1,336 +0,0 @@
|
||||
# Review Directory Specification
|
||||
|
||||
## Overview
|
||||
|
||||
Unified directory structure for all review commands (session-based and module-based) within workflow sessions.
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Session-Based**: All reviews run within a workflow session context
|
||||
2. **Unified Structure**: Same directory layout for all review types
|
||||
3. **Type Differentiation**: Review type indicated by metadata, not directory structure
|
||||
4. **Progressive Creation**: Directories created on-demand during review execution
|
||||
5. **Archive Support**: Reviews archived with their parent session
|
||||
|
||||
## Directory Structure
|
||||
|
||||
### Base Location
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/.review/
|
||||
```
|
||||
|
||||
### Complete Structure
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/.review/
|
||||
├── review-state.json # Review orchestrator state machine
|
||||
├── review-progress.json # Real-time progress for dashboard polling
|
||||
├── review-metadata.json # Review configuration and scope
|
||||
├── dimensions/ # Per-dimension analysis results
|
||||
│ ├── security.json
|
||||
│ ├── architecture.json
|
||||
│ ├── quality.json
|
||||
│ ├── action-items.json
|
||||
│ ├── performance.json
|
||||
│ ├── maintainability.json
|
||||
│ └── best-practices.json
|
||||
├── iterations/ # Deep-dive iteration results
|
||||
│ ├── iteration-1-finding-{uuid}.json
|
||||
│ ├── iteration-2-finding-{uuid}.json
|
||||
│ └── ...
|
||||
├── reports/ # Human-readable reports
|
||||
│ ├── security-analysis.md
|
||||
│ ├── security-cli-output.txt
|
||||
│ ├── architecture-analysis.md
|
||||
│ ├── architecture-cli-output.txt
|
||||
│ ├── ...
|
||||
│ ├── deep-dive-1-{uuid}.md
|
||||
│ └── deep-dive-2-{uuid}.md
|
||||
├── REVIEW-SUMMARY.md # Final consolidated summary
|
||||
└── dashboard.html # Interactive review dashboard
|
||||
```
|
||||
|
||||
## Review Metadata Schema
|
||||
|
||||
**File**: `review-metadata.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"review_id": "review-20250125-143022",
|
||||
"review_type": "module|session",
|
||||
"session_id": "WFS-auth-system",
|
||||
"created_at": "2025-01-25T14:30:22Z",
|
||||
"scope": {
|
||||
"type": "module|session",
|
||||
"module_scope": {
|
||||
"target_pattern": "src/auth/**",
|
||||
"resolved_files": [
|
||||
"src/auth/service.ts",
|
||||
"src/auth/validator.ts"
|
||||
],
|
||||
"file_count": 2
|
||||
},
|
||||
"session_scope": {
|
||||
"commit_range": "abc123..def456",
|
||||
"changed_files": [
|
||||
"src/auth/service.ts",
|
||||
"src/payment/processor.ts"
|
||||
],
|
||||
"file_count": 2
|
||||
}
|
||||
},
|
||||
"dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
|
||||
"max_iterations": 3,
|
||||
"cli_tools": {
|
||||
"primary": "gemini",
|
||||
"fallback": ["qwen", "codex"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Review State Schema
|
||||
|
||||
**File**: `review-state.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"review_id": "review-20250125-143022",
|
||||
"phase": "init|parallel|aggregate|iterate|complete",
|
||||
"current_iteration": 1,
|
||||
"dimensions_status": {
|
||||
"security": "pending|in_progress|completed|failed",
|
||||
"architecture": "completed",
|
||||
"quality": "in_progress",
|
||||
"action-items": "pending",
|
||||
"performance": "pending",
|
||||
"maintainability": "pending",
|
||||
"best-practices": "pending"
|
||||
},
|
||||
"severity_distribution": {
|
||||
"critical": 2,
|
||||
"high": 5,
|
||||
"medium": 12,
|
||||
"low": 8
|
||||
},
|
||||
"critical_files": [
|
||||
"src/auth/service.ts",
|
||||
"src/payment/processor.ts"
|
||||
],
|
||||
"iterations": [
|
||||
{
|
||||
"iteration": 1,
|
||||
"findings_selected": ["uuid-1", "uuid-2", "uuid-3"],
|
||||
"completed_at": "2025-01-25T15:30:00Z"
|
||||
}
|
||||
],
|
||||
"completion_criteria": {
|
||||
"critical_count": 0,
|
||||
"high_count_threshold": 5,
|
||||
"max_iterations": 3
|
||||
},
|
||||
"next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete"
|
||||
}
|
||||
```
|
||||
|
||||
## Session Integration
|
||||
|
||||
### Session Discovery
|
||||
|
||||
**review-session-cycle** (auto-discover):
|
||||
```bash
|
||||
# Auto-detect active session
|
||||
/workflow:review-session-cycle
|
||||
|
||||
# Or specify session explicitly
|
||||
/workflow:review-session-cycle WFS-auth-system
|
||||
```
|
||||
|
||||
**review-module-cycle** (require session):
|
||||
```bash
|
||||
# Must have active session or specify one
|
||||
/workflow:review-module-cycle src/auth/** --session WFS-auth-system
|
||||
|
||||
# Or use active session
|
||||
/workflow:review-module-cycle src/auth/**
|
||||
```
|
||||
|
||||
### Session Creation Logic
|
||||
|
||||
**For review-module-cycle**:
|
||||
|
||||
1. **Check Active Session**: Search `.workflow/active/WFS-*`
|
||||
2. **If Found**: Use active session's `.review/` directory
|
||||
3. **If Not Found**:
|
||||
- **Option A** (Recommended): Prompt user to create session first
|
||||
- **Option B**: Auto-create review-only session: `WFS-review-{pattern-hash}`
|
||||
|
||||
**Recommended Flow**:
|
||||
```bash
|
||||
# Step 1: Start session
|
||||
/workflow:session:start --new "Review auth module"
|
||||
# Creates: .workflow/active/WFS-review-auth-module/
|
||||
|
||||
# Step 2: Run review
|
||||
/workflow:review-module-cycle src/auth/**
|
||||
# Creates: .workflow/active/WFS-review-auth-module/.review/
|
||||
```
|
||||
|
||||
## Command Phase 1 Requirements
|
||||
|
||||
### Both Commands Must:
|
||||
|
||||
1. **Session Discovery**:
|
||||
```javascript
|
||||
// Check for active session
|
||||
const sessions = Glob('.workflow/active/WFS-*');
|
||||
if (sessions.length === 0) {
|
||||
// Prompt user to create session first
|
||||
error("No active session found. Please run /workflow:session:start first");
|
||||
}
|
||||
const sessionId = sessions[0].match(/WFS-[^/]+/)[0];
|
||||
```
|
||||
|
||||
2. **Create .review/ Structure**:
|
||||
```javascript
|
||||
const reviewDir = `.workflow/active/${sessionId}/.review/`;
|
||||
|
||||
// Create directory structure
|
||||
Bash(`mkdir -p ${reviewDir}/dimensions`);
|
||||
Bash(`mkdir -p ${reviewDir}/iterations`);
|
||||
Bash(`mkdir -p ${reviewDir}/reports`);
|
||||
```
|
||||
|
||||
3. **Initialize Metadata**:
|
||||
```javascript
|
||||
// Write review-metadata.json
|
||||
Write(`${reviewDir}/review-metadata.json`, JSON.stringify({
|
||||
review_id: `review-${timestamp}`,
|
||||
review_type: "module|session",
|
||||
session_id: sessionId,
|
||||
created_at: new Date().toISOString(),
|
||||
scope: {...},
|
||||
dimensions: [...],
|
||||
max_iterations: 3,
|
||||
cli_tools: {...}
|
||||
}));
|
||||
|
||||
// Write review-state.json
|
||||
Write(`${reviewDir}/review-state.json`, JSON.stringify({
|
||||
review_id: `review-${timestamp}`,
|
||||
phase: "init",
|
||||
current_iteration: 0,
|
||||
dimensions_status: {},
|
||||
severity_distribution: {},
|
||||
critical_files: [],
|
||||
iterations: [],
|
||||
completion_criteria: {},
|
||||
next_action: "execute_parallel_reviews"
|
||||
}));
|
||||
```
|
||||
|
||||
4. **Generate Dashboard**:
|
||||
```javascript
|
||||
const template = Read('~/.claude/templates/review-cycle-dashboard.html');
|
||||
const dashboard = template
|
||||
.replace('{{SESSION_ID}}', sessionId)
|
||||
.replace('{{REVIEW_TYPE}}', reviewType)
|
||||
.replace('{{REVIEW_DIR}}', reviewDir);
|
||||
Write(`${reviewDir}/dashboard.html`, dashboard);
|
||||
|
||||
// Output to user
|
||||
console.log(`📊 Review Dashboard: file://${absolutePath(reviewDir)}/dashboard.html`);
|
||||
console.log(`📂 Review Output: ${reviewDir}`);
|
||||
```
|
||||
|
||||
## Archive Strategy
|
||||
|
||||
### On Session Completion
|
||||
|
||||
When `/workflow:session:complete` is called:
|
||||
|
||||
1. **Preserve Review Directory**:
|
||||
```javascript
|
||||
// Move entire session including .review/
|
||||
Bash(`mv .workflow/active/${sessionId} .workflow/archives/${sessionId}`);
|
||||
```
|
||||
|
||||
2. **Review Archive Structure**:
|
||||
```
|
||||
.workflow/archives/WFS-auth-system/
|
||||
├── workflow-session.json
|
||||
├── IMPL_PLAN.md
|
||||
├── TODO_LIST.md
|
||||
├── .task/
|
||||
├── .summaries/
|
||||
└── .review/ # Review results preserved
|
||||
├── review-metadata.json
|
||||
├── REVIEW-SUMMARY.md
|
||||
└── dashboard.html
|
||||
```
|
||||
|
||||
3. **Access Archived Reviews**:
|
||||
```bash
|
||||
# Open archived dashboard
|
||||
start .workflow/archives/WFS-auth-system/.review/dashboard.html
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
### 1. Unified Structure
|
||||
- Same directory layout for all review types
|
||||
- Consistent file naming and schemas
|
||||
- Easier maintenance and tooling
|
||||
|
||||
### 2. Session Integration
|
||||
- Review history tracked with implementation
|
||||
- Easy correlation between code changes and reviews
|
||||
- Simplified archiving and retrieval
|
||||
|
||||
### 3. Progressive Creation
|
||||
- Directories created only when needed
|
||||
- No upfront overhead
|
||||
- Clean session initialization
|
||||
|
||||
### 4. Type Flexibility
|
||||
- Module-based and session-based reviews in same structure
|
||||
- Type indicated by metadata, not directory layout
|
||||
- Easy to add new review types
|
||||
|
||||
### 5. Dashboard Consistency
|
||||
- Same dashboard template for both types
|
||||
- Unified progress tracking
|
||||
- Consistent user experience
|
||||
|
||||
## Migration Path
|
||||
|
||||
### For Existing Commands
|
||||
|
||||
**review-session-cycle**:
|
||||
1. Change output from `.workflow/.reviews/session-{id}/` to `.workflow/active/{session-id}/.review/`
|
||||
2. Update Phase 1 to use session discovery
|
||||
3. Add review-metadata.json creation
|
||||
|
||||
**review-module-cycle**:
|
||||
1. Add session requirement (or auto-create)
|
||||
2. Change output from `.workflow/.reviews/module-{hash}/` to `.workflow/active/{session-id}/.review/`
|
||||
3. Update Phase 1 to use session discovery
|
||||
4. Add review-metadata.json creation
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
**For existing standalone reviews** in `.workflow/.reviews/`:
|
||||
- Keep for reference
|
||||
- Document migration in README
|
||||
- Provide migration script if needed
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
- [ ] Update workflow-architecture.md with .review/ structure
|
||||
- [ ] Update review-session-cycle.md command specification
|
||||
- [ ] Update review-module-cycle.md command specification
|
||||
- [ ] Update review-cycle-dashboard.html template
|
||||
- [ ] Create review-metadata.json schema validation
|
||||
- [ ] Update /workflow:session:complete to preserve .review/
|
||||
- [ ] Update documentation examples
|
||||
- [ ] Test both review types with new structure
|
||||
- [ ] Validate dashboard compatibility
|
||||
- [ ] Document migration path for existing reviews
|
||||
@@ -1,214 +0,0 @@
|
||||
# Task System Core Reference
|
||||
|
||||
## Overview
|
||||
Task commands provide single-execution workflow capabilities with full context awareness, hierarchical organization, and agent orchestration.
|
||||
|
||||
## Task JSON Schema
|
||||
All task files use this simplified 5-field schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-1.2",
|
||||
"title": "Implement JWT authentication",
|
||||
"status": "pending|active|completed|blocked|container",
|
||||
|
||||
"meta": {
|
||||
"type": "feature|bugfix|refactor|test-gen|test-fix|docs",
|
||||
"agent": "@code-developer|@action-planning-agent|@test-fix-agent|@universal-executor"
|
||||
},
|
||||
|
||||
"context": {
|
||||
"requirements": ["JWT authentication", "OAuth2 support"],
|
||||
"focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
|
||||
"acceptance": ["JWT validation works", "OAuth flow complete"],
|
||||
"parent": "IMPL-1",
|
||||
"depends_on": ["IMPL-1.1"],
|
||||
"inherited": {
|
||||
"from": "IMPL-1",
|
||||
"context": ["Authentication system design completed"]
|
||||
},
|
||||
"shared_context": {
|
||||
"auth_strategy": "JWT with refresh tokens"
|
||||
}
|
||||
},
|
||||
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "gather_context",
|
||||
"action": "Read dependency summaries",
|
||||
"command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)",
|
||||
"output_to": "auth_design_context",
|
||||
"on_error": "skip_optional"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement JWT authentication system",
|
||||
"description": "Implement comprehensive JWT authentication system with token generation, validation, and refresh logic",
|
||||
"modification_points": ["Add JWT token generation", "Implement token validation middleware", "Create refresh token logic"],
|
||||
"logic_flow": ["User login request → validate credentials", "Generate JWT access and refresh tokens", "Store refresh token securely", "Return tokens to client"],
|
||||
"depends_on": [],
|
||||
"output": "jwt_implementation"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
"src/auth/login.ts:handleLogin:75-120",
|
||||
"src/middleware/auth.ts:validateToken",
|
||||
"src/auth/PasswordReset.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Field Structure Details
|
||||
|
||||
### focus_paths Field (within context)
|
||||
**Purpose**: Specifies concrete project paths relevant to task implementation
|
||||
|
||||
**Format**:
|
||||
- **Array of strings**: `["folder1", "folder2", "specific_file.ts"]`
|
||||
- **Concrete paths**: Use actual directory/file names without wildcards
|
||||
- **Mixed types**: Can include both directories and specific files
|
||||
- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
|
||||
|
||||
**Examples**:
|
||||
```json
|
||||
// Authentication system task
|
||||
"focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
|
||||
|
||||
// UI component task
|
||||
"focus_paths": ["src/components/Button", "src/styles", "tests/components"]
|
||||
```
|
||||
|
||||
### flow_control Field Structure
|
||||
**Purpose**: Universal process manager for task execution
|
||||
|
||||
**Components**:
|
||||
- **pre_analysis**: Array of sequential process steps
|
||||
- **implementation_approach**: Task execution strategy
|
||||
- **target_files**: Files to modify/create - existing files in `file:function:lines` format, new files as `file` only
|
||||
|
||||
**Step Structure**:
|
||||
```json
|
||||
{
|
||||
"step": "gather_context",
|
||||
"action": "Human-readable description",
|
||||
"command": "bash(executable command with [variables])",
|
||||
"output_to": "variable_name",
|
||||
"on_error": "skip_optional|fail|retry_once|manual_intervention"
|
||||
}
|
||||
```
|
||||
|
||||
## Hierarchical System
|
||||
|
||||
### Task Hierarchy Rules
|
||||
- **Format**: IMPL-N (main), IMPL-N.M (subtasks) - uppercase required
|
||||
- **Maximum Depth**: 2 levels only
|
||||
- **10-Task Limit**: Hard limit enforced across all tasks
|
||||
- **Container Tasks**: Parents with subtasks (not executable)
|
||||
- **Leaf Tasks**: No subtasks (executable)
|
||||
- **File Cohesion**: Related files must stay in same task
|
||||
|
||||
### Task Complexity Classifications
|
||||
- **Simple**: ≤5 tasks, single-level tasks, direct execution
|
||||
- **Medium**: 6-10 tasks, two-level hierarchy, context coordination
|
||||
- **Over-scope**: >10 tasks requires project re-scoping into iterations
|
||||
|
||||
### Complexity Assessment Rules
|
||||
- **Creation**: System evaluates and assigns complexity
|
||||
- **10-task limit**: Hard limit enforced - exceeding requires re-scoping
|
||||
- **Execution**: Can upgrade (Simple→Medium→Over-scope), triggers re-scoping
|
||||
- **Override**: Users can manually specify complexity within 10-task limit
|
||||
|
||||
### Status Rules
|
||||
- **pending**: Ready for execution
|
||||
- **active**: Currently being executed
|
||||
- **completed**: Successfully finished
|
||||
- **blocked**: Waiting for dependencies
|
||||
- **container**: Has subtasks (parent only)
|
||||
|
||||
## Session Integration
|
||||
|
||||
### Active Session Detection
|
||||
```bash
|
||||
# Check for active session in sessions directory
|
||||
active_session=$(find .workflow/active/ -name 'WFS-*' -type d 2>/dev/null | head -1)
|
||||
```
|
||||
|
||||
### Workflow Context Inheritance
|
||||
Tasks inherit from:
|
||||
1. `workflow-session.json` - Session metadata
|
||||
2. Parent task context (for subtasks)
|
||||
3. `IMPL_PLAN.md` - Planning document
|
||||
|
||||
### File Locations
|
||||
- **Task JSON**: `.workflow/active/WFS-[topic]/.task/IMPL-*.json` (uppercase required)
|
||||
- **Session State**: `.workflow/active/WFS-[topic]/workflow-session.json`
|
||||
- **Planning Doc**: `.workflow/active/WFS-[topic]/IMPL_PLAN.md`
|
||||
- **Progress**: `.workflow/active/WFS-[topic]/TODO_LIST.md`
|
||||
|
||||
## Agent Mapping
|
||||
|
||||
### Automatic Agent Selection
|
||||
- **@code-developer**: Implementation tasks, coding, test writing
|
||||
- **@action-planning-agent**: Design, architecture planning
|
||||
- **@test-fix-agent**: Test execution, failure diagnosis, code fixing
|
||||
- **@universal-executor**: Optional manual review (only when explicitly requested)
|
||||
|
||||
### Agent Context Filtering
|
||||
Each agent receives tailored context:
|
||||
- **@code-developer**: Complete implementation details, test requirements
|
||||
- **@action-planning-agent**: High-level requirements, risks, architecture
|
||||
- **@test-fix-agent**: Test execution, failure diagnosis, code fixing
|
||||
- **@universal-executor**: Quality standards, security considerations (when requested)
|
||||
|
||||
## Deprecated Fields
|
||||
|
||||
### Legacy paths Field
|
||||
**Deprecated**: The semicolon-separated `paths` field has been replaced by `context.focus_paths` array.
|
||||
|
||||
**Old Format** (no longer used):
|
||||
```json
|
||||
"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts"
|
||||
```
|
||||
|
||||
**New Format** (use this instead):
|
||||
```json
|
||||
"context": {
|
||||
"focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"]
|
||||
}
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Pre-execution Checks
|
||||
1. Task exists and is valid JSON
|
||||
2. Task status allows operation
|
||||
3. Dependencies are met
|
||||
4. Active workflow session exists
|
||||
5. All 5 core fields present (id, title, status, meta, context, flow_control)
|
||||
6. Total task count ≤ 10 (hard limit)
|
||||
7. File cohesion maintained in focus_paths
|
||||
|
||||
### Hierarchy Validation
|
||||
- Parent-child relationships valid
|
||||
- Maximum depth not exceeded
|
||||
- Container tasks have subtasks
|
||||
- No circular dependencies
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
### Common Errors
|
||||
- **Task not found**: Check ID format and session
|
||||
- **Invalid status**: Verify task can be operated on
|
||||
- **Missing session**: Ensure active workflow exists
|
||||
- **Max depth exceeded**: Restructure hierarchy
|
||||
- **Missing implementation**: Complete required fields
|
||||
|
||||
### Recovery Strategies
|
||||
- Session validation with clear guidance
|
||||
- Automatic ID correction suggestions
|
||||
- Implementation field completion prompts
|
||||
- Hierarchy restructuring options
|
||||
@@ -1,216 +0,0 @@
|
||||
# Tool Strategy - When to Use What
|
||||
|
||||
> **Focus**: Decision triggers and selection logic, NOT syntax (already registered with Claude)
|
||||
|
||||
## Quick Decision Tree
|
||||
|
||||
```
|
||||
Need context?
|
||||
├─ Exa available? → Use Exa (fastest, most comprehensive)
|
||||
├─ Large codebase (>500 files)? → codex_lens
|
||||
├─ Known files (<5)? → Read tool
|
||||
└─ Unknown files? → smart_search → Read tool
|
||||
|
||||
Need to modify files?
|
||||
├─ Built-in Edit fails? → mcp__ccw-tools__edit_file
|
||||
└─ Still fails? → mcp__ccw-tools__write_file
|
||||
|
||||
Need to search?
|
||||
├─ Semantic/concept search? → smart_search (mode=semantic)
|
||||
├─ Exact pattern match? → Grep tool
|
||||
└─ Multiple search modes needed? → smart_search (mode=auto)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. Context Gathering Tools
|
||||
|
||||
### Exa (`mcp__exa__get_code_context_exa`)
|
||||
|
||||
**Use When**:
|
||||
- ✅ Researching external APIs, libraries, frameworks
|
||||
- ✅ Need recent documentation (post-cutoff knowledge)
|
||||
- ✅ Looking for implementation examples in public repos
|
||||
- ✅ Comparing architectural patterns across projects
|
||||
|
||||
**Don't Use When**:
|
||||
- ❌ Searching internal codebase (use smart_search/codex_lens)
|
||||
- ❌ Files already in working directory (use Read)
|
||||
|
||||
**Trigger Indicators**:
|
||||
- User mentions specific library/framework names
|
||||
- Questions about "best practices", "how does X work"
|
||||
- Need to verify current API signatures
|
||||
|
||||
---
|
||||
|
||||
### read_file (`mcp__ccw-tools__read_file`)
|
||||
|
||||
**Use When**:
|
||||
- ✅ Reading multiple related files at once (batch reading)
|
||||
- ✅ Need directory traversal with pattern matching
|
||||
- ✅ Searching file content with regex (`contentPattern`)
|
||||
- ✅ Want to limit depth/file count for large directories
|
||||
|
||||
**Don't Use When**:
|
||||
- ❌ Single file read → Use built-in Read tool (faster)
|
||||
- ❌ Unknown file locations → Use smart_search first
|
||||
- ❌ Need semantic search → Use smart_search or codex_lens
|
||||
|
||||
**Trigger Indicators**:
|
||||
- Need to read "all TypeScript files in src/"
|
||||
- Need to find "files containing TODO comments"
|
||||
- Want to read "up to 20 config files"
|
||||
|
||||
**Advantages over Built-in Read**:
|
||||
- Batch operation (multiple files in one call)
|
||||
- Pattern-based filtering (glob + content regex)
|
||||
- Directory traversal with depth control
|
||||
|
||||
---
|
||||
|
||||
### codex_lens (`mcp__ccw-tools__codex_lens`)
|
||||
|
||||
**Use When**:
|
||||
- ✅ Large codebase (>500 files) requiring repeated searches
|
||||
- ✅ Need semantic understanding of code relationships
|
||||
- ✅ Working across multiple sessions (persistent index)
|
||||
- ✅ Symbol-level navigation needed
|
||||
|
||||
**Don't Use When**:
|
||||
- ❌ Small project (<100 files) → Use smart_search (no indexing overhead)
|
||||
- ❌ One-time search → Use smart_search or Grep
|
||||
- ❌ Files change frequently → Indexing overhead not worth it
|
||||
|
||||
**Trigger Indicators**:
|
||||
- "Find all implementations of interface X"
|
||||
- "What calls this function across the codebase?"
|
||||
- Multi-session workflow on same codebase
|
||||
|
||||
**Action Selection**:
|
||||
- `init`: First time in new codebase
|
||||
- `search`: Find code patterns
|
||||
- `search_files`: Find files by path/name pattern
|
||||
- `symbol`: Get symbols in specific file
|
||||
- `status`: Check if index exists/is stale
|
||||
- `clean`: Remove stale index
|
||||
|
||||
---
|
||||
|
||||
### smart_search (`mcp__ccw-tools__smart_search`)
|
||||
|
||||
**Use When**:
|
||||
- ✅ Don't know exact file locations
|
||||
- ✅ Need concept/semantic search ("authentication logic")
|
||||
- ✅ Medium-sized codebase (100-500 files)
|
||||
- ✅ One-time or infrequent searches
|
||||
|
||||
**Don't Use When**:
|
||||
- ❌ Known exact file path → Use Read directly
|
||||
- ❌ Large codebase + repeated searches → Use codex_lens
|
||||
- ❌ Exact pattern match → Use Grep (faster)
|
||||
|
||||
**Mode Selection**:
|
||||
- `auto`: Let tool decide (default, safest)
|
||||
- `exact`: Know exact pattern, need fast results
|
||||
- `fuzzy`: Typo-tolerant file/symbol names
|
||||
- `semantic`: Concept-based ("error handling", "data validation")
|
||||
- `graph`: Dependency/relationship analysis
|
||||
|
||||
**Trigger Indicators**:
|
||||
- "Find files related to user authentication"
|
||||
- "Where is the payment processing logic?"
|
||||
- "Locate database connection setup"
|
||||
|
||||
---
|
||||
|
||||
## 2. File Modification Tools
|
||||
|
||||
### edit_file (`mcp__ccw-tools__edit_file`)
|
||||
|
||||
**Use When**:
|
||||
- ✅ Built-in Edit tool failed 1+ times
|
||||
- ✅ Need dry-run preview before applying
|
||||
- ✅ Need line-based operations (insert_after, insert_before)
|
||||
- ✅ Need to replace all occurrences
|
||||
|
||||
**Don't Use When**:
|
||||
- ❌ Built-in Edit hasn't failed yet → Try built-in first
|
||||
- ❌ Need to create new file → Use write_file
|
||||
|
||||
**Trigger Indicators**:
|
||||
- Built-in Edit returns "old_string not found"
|
||||
- Built-in Edit fails due to whitespace/formatting
|
||||
- Need to verify changes before applying (dryRun=true)
|
||||
|
||||
**Mode Selection**:
|
||||
- `mode=update`: Replace text (similar to built-in Edit)
|
||||
- `mode=line`: Line-based operations (insert_after, insert_before, delete)
|
||||
|
||||
---
|
||||
|
||||
### write_file (`mcp__ccw-tools__write_file`)
|
||||
|
||||
**Use When**:
|
||||
- ✅ Creating brand new files
|
||||
- ✅ MCP edit_file still fails (last resort)
|
||||
- ✅ Need to completely replace file content
|
||||
- ✅ Need backup before overwriting
|
||||
|
||||
**Don't Use When**:
|
||||
- ❌ File exists + small change → Use Edit tools
|
||||
- ❌ Built-in Edit hasn't been tried → Try built-in Edit first
|
||||
|
||||
**Trigger Indicators**:
|
||||
- All Edit attempts failed
|
||||
- Need to create new file with specific content
|
||||
- User explicitly asks to "recreate file"
|
||||
|
||||
---
|
||||
|
||||
## 3. Decision Logic
|
||||
|
||||
### File Reading Priority
|
||||
|
||||
```
|
||||
1. Known single file? → Built-in Read
|
||||
2. Multiple files OR pattern matching? → mcp__ccw-tools__read_file
|
||||
3. Unknown location? → smart_search, then Read
|
||||
4. Large codebase + repeated access? → codex_lens
|
||||
```
|
||||
|
||||
### File Editing Priority
|
||||
|
||||
```
|
||||
1. Always try built-in Edit first
|
||||
2. Fails 1+ times? → mcp__ccw-tools__edit_file
|
||||
3. Still fails? → mcp__ccw-tools__write_file (last resort)
|
||||
```
|
||||
|
||||
### Search Tool Priority
|
||||
|
||||
```
|
||||
1. External knowledge? → Exa
|
||||
2. Exact pattern in small codebase? → Built-in Grep
|
||||
3. Semantic/unknown location? → smart_search
|
||||
4. Large codebase + repeated searches? → codex_lens
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Anti-Patterns
|
||||
|
||||
**Don't**:
|
||||
- Use codex_lens for one-time searches in small projects
|
||||
- Use smart_search when file path is already known
|
||||
- Use write_file before trying Edit tools
|
||||
- Use Exa for internal codebase searches
|
||||
- Use read_file for single file when Read tool works
|
||||
|
||||
**Do**:
|
||||
- Start with simplest tool (Read, Edit, Grep)
|
||||
- Escalate to MCP tools when built-ins fail
|
||||
- Use semantic search (smart_search) for exploratory tasks
|
||||
- Use indexed search (codex_lens) for large, stable codebases
|
||||
- Use Exa for external/public knowledge
|
||||
|
||||
@@ -1,942 +0,0 @@
|
||||
# Workflow Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
This document defines the complete workflow system architecture using a **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition.
|
||||
|
||||
## Core Architecture
|
||||
|
||||
### JSON-Only Data Model
|
||||
**JSON files (.task/IMPL-*.json) are the only authoritative source of task state. All markdown documents are read-only generated views.**
|
||||
|
||||
- **Task State**: Stored exclusively in JSON files
|
||||
- **Documents**: Generated on-demand from JSON data
|
||||
- **No Synchronization**: Eliminates bidirectional sync complexity
|
||||
- **Performance**: Direct JSON access without parsing overhead
|
||||
|
||||
### Key Design Decisions
|
||||
- **JSON files are the single source of truth** - All markdown documents are read-only generated views
|
||||
- **Marker files for session tracking** - Ultra-simple active session management
|
||||
- **Unified file structure definition** - Same structure template for all workflows, created on-demand
|
||||
- **Dynamic task decomposition** - Subtasks created as needed during execution
|
||||
- **On-demand file creation** - Directories and files created only when required
|
||||
- **Agent-agnostic task definitions** - Complete context preserved for autonomous execution
|
||||
|
||||
## Session Management
|
||||
|
||||
### Directory-Based Session Management
|
||||
**Simple Location-Based Tracking**: Sessions in `.workflow/active/` directory
|
||||
|
||||
```bash
|
||||
.workflow/
|
||||
├── active/
|
||||
│ ├── WFS-oauth-integration/ # Active session directory
|
||||
│ ├── WFS-user-profile/ # Active session directory
|
||||
│ └── WFS-bug-fix-123/ # Active session directory
|
||||
└── archives/
|
||||
└── WFS-old-feature/ # Archived session (completed)
|
||||
```
|
||||
|
||||
|
||||
### Session Operations
|
||||
|
||||
#### Detect Active Session(s)
|
||||
```bash
|
||||
active_sessions=$(find .workflow/active/ -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")
|
||||
echo "Active session: $session_name"
|
||||
else
|
||||
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
|
||||
```
|
||||
|
||||
#### Archive Session
|
||||
```bash
|
||||
mv .workflow/active/WFS-feature .workflow/archives/WFS-feature
|
||||
```
|
||||
|
||||
### Session State Tracking
|
||||
Each session directory contains `workflow-session.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-[topic-slug]",
|
||||
"project": "feature description",
|
||||
"type": "simple|medium|complex",
|
||||
"current_phase": "PLAN|IMPLEMENT|REVIEW",
|
||||
"status": "active|paused|completed",
|
||||
"progress": {
|
||||
"completed_phases": ["PLAN"],
|
||||
"current_tasks": ["IMPL-1", "IMPL-2"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Task System
|
||||
|
||||
### Hierarchical Task Structure
|
||||
**Maximum Depth**: 2 levels (IMPL-N.M format)
|
||||
|
||||
```
|
||||
IMPL-1 # Main task
|
||||
IMPL-1.1 # Subtask of IMPL-1 (dynamically created)
|
||||
IMPL-1.2 # Another subtask of IMPL-1
|
||||
IMPL-2 # Another main task
|
||||
IMPL-2.1 # Subtask of IMPL-2 (dynamically created)
|
||||
```
|
||||
|
||||
**Task Status Rules**:
|
||||
- **Container tasks**: Parent tasks with subtasks (cannot be directly executed)
|
||||
- **Leaf tasks**: Only these can be executed directly
|
||||
- **Status inheritance**: Parent status derived from subtask completion
|
||||
|
||||
### Enhanced Task JSON Schema
|
||||
All task files use this unified 6-field schema with optional artifacts enhancement:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-1.2",
|
||||
"title": "Implement JWT authentication",
|
||||
"status": "pending|active|completed|blocked|container",
|
||||
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
|
||||
|
||||
"meta": {
|
||||
"type": "feature|bugfix|refactor|test-gen|test-fix|docs",
|
||||
"agent": "@code-developer|@action-planning-agent|@test-fix-agent|@universal-executor"
|
||||
},
|
||||
|
||||
"context": {
|
||||
"requirements": ["JWT authentication", "OAuth2 support"],
|
||||
"focus_paths": ["src/auth", "tests/auth", "config/auth.json"],
|
||||
"acceptance": ["JWT validation works", "OAuth flow complete"],
|
||||
"parent": "IMPL-1",
|
||||
"depends_on": ["IMPL-1.1"],
|
||||
"inherited": {
|
||||
"from": "IMPL-1",
|
||||
"context": ["Authentication system design completed"]
|
||||
},
|
||||
"shared_context": {
|
||||
"auth_strategy": "JWT with refresh tokens"
|
||||
},
|
||||
"artifacts": [
|
||||
{
|
||||
"type": "role_analyses",
|
||||
"source": "brainstorm_clarification",
|
||||
"path": ".workflow/WFS-session/.brainstorming/*/analysis*.md",
|
||||
"priority": "highest",
|
||||
"contains": "role_specific_requirements_and_design"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "check_patterns",
|
||||
"action": "Analyze existing patterns",
|
||||
"command": "bash(rg 'auth' [focus_paths] | head -10)",
|
||||
"output_to": "patterns"
|
||||
},
|
||||
{
|
||||
"step": "analyze_architecture",
|
||||
"action": "Review system architecture",
|
||||
"command": "gemini \"analyze patterns: [patterns]\"",
|
||||
"output_to": "design"
|
||||
},
|
||||
{
|
||||
"step": "check_deps",
|
||||
"action": "Check dependencies",
|
||||
"command": "bash(echo [depends_on] | xargs cat)",
|
||||
"output_to": "context"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Set up authentication infrastructure",
|
||||
"description": "Install JWT library and create auth config following [design] patterns from [parent]",
|
||||
"modification_points": [
|
||||
"Add JWT library dependencies to package.json",
|
||||
"Create auth configuration file using [parent] patterns"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Install jsonwebtoken library via npm",
|
||||
"Configure JWT secret and expiration from [inherited]",
|
||||
"Export auth config for use by [jwt_generator]"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "auth_config"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Implement JWT generation",
|
||||
"description": "Create JWT token generation logic using [auth_config] and [inherited] validation patterns",
|
||||
"modification_points": [
|
||||
"Add JWT generation function in auth service",
|
||||
"Implement token signing with [auth_config]"
|
||||
],
|
||||
"logic_flow": [
|
||||
"User login → validate credentials with [inherited]",
|
||||
"Generate JWT payload with user data",
|
||||
"Sign JWT using secret from [auth_config]",
|
||||
"Return signed token"
|
||||
],
|
||||
"depends_on": [1],
|
||||
"output": "jwt_generator"
|
||||
},
|
||||
{
|
||||
"step": 3,
|
||||
"title": "Implement JWT validation middleware",
|
||||
"description": "Create middleware to validate JWT tokens using [auth_config] and [shared] rules",
|
||||
"modification_points": [
|
||||
"Create validation middleware using [jwt_generator]",
|
||||
"Add token verification using [shared] rules",
|
||||
"Implement user attachment to request object"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Protected route → extract JWT from Authorization header",
|
||||
"Validate token signature using [auth_config]",
|
||||
"Check token expiration and [shared] rules",
|
||||
"Decode payload and attach user to request",
|
||||
"Call next() or return 401 error"
|
||||
],
|
||||
"command": "bash(npm test -- middleware.test.ts)",
|
||||
"depends_on": [1, 2],
|
||||
"output": "auth_middleware"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
"src/auth/login.ts:handleLogin:75-120",
|
||||
"src/middleware/auth.ts:validateToken",
|
||||
"src/auth/PasswordReset.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Focus Paths & Context Management
|
||||
|
||||
#### Context Package Path (Top-Level Field)
|
||||
The **context_package_path** field provides the location of the smart context package:
|
||||
- **Location**: Top-level field (not in `artifacts` array)
|
||||
- **Path**: `.workflow/WFS-session/.process/context-package.json`
|
||||
- **Purpose**: References the comprehensive context package containing project structure, dependencies, and brainstorming artifacts catalog
|
||||
- **Usage**: Loaded in `pre_analysis` steps via `Read({{context_package_path}})`
|
||||
|
||||
#### Focus Paths Format
|
||||
The **focus_paths** field specifies concrete project paths for task implementation:
|
||||
- **Array of strings**: `["folder1", "folder2", "specific_file.ts"]`
|
||||
- **Concrete paths**: Use actual directory/file names without wildcards
|
||||
- **Mixed types**: Can include both directories and specific files
|
||||
- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
|
||||
|
||||
#### Artifacts Field ⚠️ NEW FIELD
|
||||
Optional field referencing brainstorming outputs for task execution:
|
||||
|
||||
```json
|
||||
"artifacts": [
|
||||
{
|
||||
"type": "role_analyses|topic_framework|individual_role_analysis",
|
||||
"source": "brainstorm_clarification|brainstorm_framework|brainstorm_roles",
|
||||
"path": ".workflow/WFS-session/.brainstorming/document.md",
|
||||
"priority": "highest|high|medium|low"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Types & Priority**: role_analyses (highest) → topic_framework (medium) → individual_role_analysis (low)
|
||||
|
||||
#### Flow Control Configuration
|
||||
The **flow_control** field manages task execution through structured sequential steps. For complete format specifications and usage guidelines, see [Flow Control Format Guide](#flow-control-format-guide) below.
|
||||
|
||||
**Quick Reference**:
|
||||
- **pre_analysis**: Context gathering steps (supports multiple command types)
|
||||
- **implementation_approach**: Implementation steps array with dependency management
|
||||
- **target_files**: Target files for modification (file:function:lines format)
|
||||
- **Variable references**: Use `[variable_name]` to reference step outputs
|
||||
- **Tool integration**: Supports Gemini, Codex, Bash commands, and MCP tools
|
||||
|
||||
## Flow Control Format Guide
|
||||
|
||||
The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow control steps for sequential execution. There are **two distinct formats** used in different scenarios:
|
||||
|
||||
### Format Comparison Matrix
|
||||
|
||||
| Aspect | Inline Format | JSON Format |
|
||||
|--------|--------------|-------------|
|
||||
| **Used In** | Brainstorm workflows | Implementation tasks |
|
||||
| **Agent** | conceptual-planning-agent | code-developer, test-fix-agent, doc-generator |
|
||||
| **Location** | Task() prompt (markdown) | .task/IMPL-*.json file |
|
||||
| **Persistence** | Temporary (prompt-only) | Persistent (file storage) |
|
||||
| **Complexity** | Simple (3-5 steps) | Complex (10+ steps) |
|
||||
| **Dependencies** | None | Full `depends_on` support |
|
||||
| **Purpose** | Load brainstorming context | Implement task with preparation |
|
||||
|
||||
### Inline Format (Brainstorm)
|
||||
|
||||
**Marker**: `[FLOW_CONTROL]` written directly in Task() prompt
|
||||
|
||||
**Structure**: Markdown list format
|
||||
|
||||
**Used By**: Brainstorm commands (`auto-parallel.md`, role commands)
|
||||
|
||||
**Agent**: `conceptual-planning-agent`
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
[FLOW_CONTROL]
|
||||
|
||||
### Flow Control Steps
|
||||
**AGENT RESPONSIBILITY**: Execute these pre_analysis steps sequentially with context accumulation:
|
||||
|
||||
1. **load_topic_framework**
|
||||
- Action: Load structured topic discussion framework
|
||||
- Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
|
||||
- Output: topic_framework
|
||||
|
||||
2. **load_role_template**
|
||||
- Action: Load role-specific planning template
|
||||
- Command: bash($(cat "~/.ccw/workflows/cli-templates/planning-roles/{role}.md"))
|
||||
- Output: role_template
|
||||
|
||||
3. **load_session_metadata**
|
||||
- Action: Load session metadata and topic description
|
||||
- Command: bash(cat .workflow/WFS-{session}/workflow-session.json 2>/dev/null || echo '{}')
|
||||
- Output: session_metadata
|
||||
```
|
||||
|
||||
**Characteristics**:
|
||||
- 3-5 simple context loading steps
|
||||
- Written directly in prompt (not persistent)
|
||||
- No dependency management between steps
|
||||
- Used for temporary context preparation
|
||||
- Variables: `[variable_name]` for output references
|
||||
|
||||
### JSON Format (Implementation)
|
||||
|
||||
**Marker**: `[FLOW_CONTROL]` used in TodoWrite or documentation to indicate task has flow control
|
||||
|
||||
**Structure**: Complete JSON structure in task file
|
||||
|
||||
**Used By**: Implementation tasks (IMPL-*.json)
|
||||
|
||||
**Agents**: `code-developer`, `test-fix-agent`, `doc-generator`
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_role_analyses",
|
||||
"action": "Load role analysis documents from brainstorming",
|
||||
"commands": [
|
||||
"bash(ls .workflow/WFS-{session}/.brainstorming/*/analysis*.md 2>/dev/null || echo 'not found')",
|
||||
"Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md)",
|
||||
"Read(each discovered role analysis file)"
|
||||
],
|
||||
"output_to": "role_analyses",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "local_codebase_exploration",
|
||||
"action": "Explore codebase using local search",
|
||||
"commands": [
|
||||
"bash(rg '^(function|class|interface).*auth' --type ts -n --max-count 15)",
|
||||
"bash(find . -name '*auth*' -type f | grep -v node_modules | head -10)"
|
||||
],
|
||||
"output_to": "codebase_structure"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Setup infrastructure",
|
||||
"description": "Install JWT library and create config following [role_analyses]",
|
||||
"modification_points": [
|
||||
"Add JWT library dependencies to package.json",
|
||||
"Create auth configuration file"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Install jsonwebtoken library via npm",
|
||||
"Configure JWT secret from [role_analyses]",
|
||||
"Export auth config for use by [jwt_generator]"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "auth_config"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Implement JWT generation",
|
||||
"description": "Create JWT token generation logic using [auth_config]",
|
||||
"modification_points": [
|
||||
"Add JWT generation function in auth service",
|
||||
"Implement token signing with [auth_config]"
|
||||
],
|
||||
"logic_flow": [
|
||||
"User login → validate credentials",
|
||||
"Generate JWT payload with user data",
|
||||
"Sign JWT using secret from [auth_config]",
|
||||
"Return signed token"
|
||||
],
|
||||
"depends_on": [1],
|
||||
"output": "jwt_generator"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
"src/auth/login.ts:handleLogin:75-120",
|
||||
"src/middleware/auth.ts:validateToken"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Characteristics**:
|
||||
- Persistent storage in .task/IMPL-*.json files
|
||||
- Complete dependency management (`depends_on` arrays)
|
||||
- Two-phase structure: `pre_analysis` + `implementation_approach`
|
||||
- Error handling strategies (`on_error` field)
|
||||
- Target file specifications
|
||||
- Variables: `[variable_name]` for cross-step references
|
||||
|
||||
### JSON Format Field Specifications
|
||||
|
||||
#### pre_analysis Field
|
||||
**Purpose**: Context gathering phase before implementation
|
||||
|
||||
**Structure**: Array of step objects with sequential execution
|
||||
|
||||
**Step Fields**:
|
||||
- **step**: Step identifier (string, e.g., "load_role_analyses")
|
||||
- **action**: Human-readable description of the step
|
||||
- **command** or **commands**: Single command string or array of command strings
|
||||
- **output_to**: Variable name for storing step output
|
||||
- **on_error**: Error handling strategy (`skip_optional`, `fail`, `retry_once`, `manual_intervention`)
|
||||
|
||||
**Command Types Supported**:
|
||||
- **Bash commands**: `bash(command)` - Any shell command
|
||||
- **Tool calls**: `Read(file)`, `Glob(pattern)`, `Grep(pattern)`
|
||||
- **MCP tools**: `mcp__exa__get_code_context_exa()`, `mcp__exa__web_search_exa()`
|
||||
- **CLI commands**: `gemini`, `qwen`, `codex --full-auto exec`
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"step": "load_context",
|
||||
"action": "Load project context and patterns",
|
||||
"commands": [
|
||||
"bash(ccw tool exec get_modules_by_depth '{}')",
|
||||
"Read(CLAUDE.md)"
|
||||
],
|
||||
"output_to": "project_structure",
|
||||
"on_error": "skip_optional"
|
||||
}
|
||||
```
|
||||
|
||||
#### implementation_approach Field
|
||||
**Purpose**: Define implementation steps with dependency management
|
||||
|
||||
**Structure**: Array of step objects (NOT object format)
|
||||
|
||||
**Step Fields (All Required)**:
|
||||
- **step**: Unique step number (1, 2, 3, ...) - serves as step identifier
|
||||
- **title**: Brief step title
|
||||
- **description**: Comprehensive implementation description with context variable references
|
||||
- **modification_points**: Array of specific code modification targets
|
||||
- **logic_flow**: Array describing business logic execution sequence
|
||||
- **depends_on**: Array of step numbers this step depends on (e.g., `[1]`, `[1, 2]`) - empty array `[]` for independent steps
|
||||
- **output**: Output variable name that can be referenced by subsequent steps via `[output_name]`
|
||||
|
||||
**Optional Fields**:
|
||||
- **command**: Command for step execution (supports any shell command or CLI tool)
|
||||
- When omitted: Agent interprets modification_points and logic_flow to execute
|
||||
- When specified: Command executes the step directly
|
||||
|
||||
**Execution Modes**:
|
||||
- **Default (without command)**: Agent executes based on modification_points and logic_flow
|
||||
- **With command**: Specified command handles execution
|
||||
|
||||
**Command Field Usage**:
|
||||
- **Default approach**: Omit command field - let agent execute autonomously
|
||||
- **CLI tools (codex/gemini/qwen)**: Add ONLY when user explicitly requests CLI tool usage
|
||||
- **Simple commands**: Can include bash commands, test commands, validation scripts
|
||||
- **Complex workflows**: Use command for multi-step operations or tool coordination
|
||||
|
||||
**Command Format Examples** (only when explicitly needed):
|
||||
```json
|
||||
// Simple Bash
|
||||
"command": "bash(npm install package)"
|
||||
"command": "bash(npm test)"
|
||||
|
||||
// Validation
|
||||
"command": "bash(test -f config.ts && grep -q 'JWT_SECRET' config.ts)"
|
||||
|
||||
// Codex (user requested)
|
||||
"command": "codex -C path --full-auto exec \"task\" --skip-git-repo-check -s danger-full-access"
|
||||
|
||||
// Codex Resume (user requested, maintains context)
|
||||
"command": "codex --full-auto exec \"task\" resume --last --skip-git-repo-check -s danger-full-access"
|
||||
|
||||
// Gemini (user requested)
|
||||
"command": "gemini \"analyze [context]\""
|
||||
|
||||
// Qwen (fallback for Gemini)
|
||||
"command": "qwen \"analyze [context]\""
|
||||
```
|
||||
|
||||
**Example Step**:
|
||||
```json
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Implement JWT generation",
|
||||
"description": "Create JWT token generation logic using [auth_config]",
|
||||
"modification_points": [
|
||||
"Add JWT generation function in auth service",
|
||||
"Implement token signing with [auth_config]"
|
||||
],
|
||||
"logic_flow": [
|
||||
"User login → validate credentials",
|
||||
"Generate JWT payload with user data",
|
||||
"Sign JWT using secret from [auth_config]",
|
||||
"Return signed token"
|
||||
],
|
||||
"depends_on": [1],
|
||||
"output": "jwt_generator"
|
||||
}
|
||||
```
|
||||
|
||||
#### target_files Field
|
||||
**Purpose**: Specify files to be modified or created
|
||||
|
||||
**Format**: Array of strings
|
||||
- **Existing files**: `"file:function:lines"` (e.g., `"src/auth/login.ts:handleLogin:75-120"`)
|
||||
- **New files**: `"path/to/NewFile.ts"` (file path only)
|
||||
|
||||
### Tool Reference
|
||||
|
||||
**Available Command Types**:
|
||||
|
||||
**Gemini CLI**:
|
||||
```bash
|
||||
gemini "prompt"
|
||||
gemini --approval-mode yolo "prompt" # For write mode
|
||||
```
|
||||
|
||||
**Qwen CLI** (Gemini fallback):
|
||||
```bash
|
||||
qwen "prompt"
|
||||
qwen --approval-mode yolo "prompt" # For write mode
|
||||
```
|
||||
|
||||
**Codex CLI**:
|
||||
```bash
|
||||
codex -C directory --full-auto exec "task" --skip-git-repo-check -s danger-full-access
|
||||
codex --full-auto exec "task" resume --last --skip-git-repo-check -s danger-full-access
|
||||
```
|
||||
|
||||
**Built-in Tools**:
|
||||
- `Read(file_path)` - Read file contents
|
||||
- `Glob(pattern)` - Find files by pattern
|
||||
- `Grep(pattern)` - Search content with regex
|
||||
- `bash(command)` - Execute bash command
|
||||
|
||||
**MCP Tools**:
|
||||
- `mcp__exa__get_code_context_exa(query="...")` - Get code context from Exa
|
||||
- `mcp__exa__web_search_exa(query="...")` - Web search via Exa
|
||||
|
||||
**Bash Commands**:
|
||||
```bash
|
||||
bash(rg 'pattern' src/)
|
||||
bash(find . -name "*.ts")
|
||||
bash(npm test)
|
||||
bash(git log --oneline | head -5)
|
||||
```
|
||||
|
||||
### Variable System & Context Flow
|
||||
|
||||
**Variable Reference Syntax**:
|
||||
Both formats use `[variable_name]` syntax for referencing outputs from previous steps.
|
||||
|
||||
**Variable Types**:
|
||||
- **Step outputs**: `[step_output_name]` - Reference any pre_analysis step output
|
||||
- **Task properties**: `[task_property]` - Reference any task context field
|
||||
- **Previous results**: `[analysis_result]` - Reference accumulated context
|
||||
- **Implementation outputs**: Reference outputs from previous implementation steps
|
||||
|
||||
**Examples**:
|
||||
```json
|
||||
// Reference pre_analysis output
|
||||
"description": "Install JWT library following [role_analyses]"
|
||||
|
||||
// Reference previous step output
|
||||
"description": "Create middleware using [auth_config] and [jwt_generator]"
|
||||
|
||||
// Reference task context
|
||||
"command": "bash(cd [focus_paths] && npm test)"
|
||||
```
|
||||
|
||||
**Context Accumulation Process**:
|
||||
1. **Structure Analysis**: `get_modules_by_depth.sh` → project hierarchy
|
||||
2. **Pattern Analysis**: Tool-specific commands → existing patterns
|
||||
3. **Dependency Mapping**: Previous task summaries → inheritance context
|
||||
4. **Task Context Generation**: Combined analysis → task.context fields
|
||||
|
||||
**Context Inheritance Rules**:
|
||||
- **Parent → Child**: Container tasks pass context via `context.inherited`
|
||||
- **Dependency → Dependent**: Previous task summaries via `context.depends_on`
|
||||
- **Session → Task**: Global session context included in all tasks
|
||||
- **Module → Feature**: Module patterns inform feature implementation
|
||||
|
||||
### Agent Processing Rules
|
||||
|
||||
**conceptual-planning-agent** (Inline Format):
|
||||
- Parses markdown list from prompt
|
||||
- Executes 3-5 simple loading steps
|
||||
- No dependency resolution needed
|
||||
- Accumulates context in variables
|
||||
- Used only in brainstorm workflows
|
||||
|
||||
**code-developer, test-fix-agent** (JSON Format):
|
||||
- Loads complete task JSON from file
|
||||
- Executes `pre_analysis` steps sequentially
|
||||
- Processes `implementation_approach` with dependency resolution
|
||||
- Handles complex variable substitution
|
||||
- Updates task status in JSON file
|
||||
|
||||
### Usage Guidelines
|
||||
|
||||
**Use Inline Format When**:
|
||||
- Running brainstorm workflows
|
||||
- Need 3-5 simple context loading steps
|
||||
- No persistence required
|
||||
- No dependencies between steps
|
||||
- Temporary context preparation
|
||||
|
||||
**Use JSON Format When**:
|
||||
- Implementing features or tasks
|
||||
- Need 10+ complex execution steps
|
||||
- Require dependency management
|
||||
- Need persistent task definitions
|
||||
- Complex variable flow between steps
|
||||
- Error handling strategies needed
|
||||
|
||||
### Variable Reference Syntax
|
||||
|
||||
Both formats use `[variable_name]` syntax for referencing outputs:
|
||||
|
||||
**Inline Format**:
|
||||
```markdown
|
||||
2. **analyze_context**
|
||||
- Action: Analyze using [topic_framework] and [role_template]
|
||||
- Output: analysis_results
|
||||
```
|
||||
|
||||
**JSON Format**:
|
||||
```json
|
||||
{
|
||||
"step": 2,
|
||||
"description": "Implement following [role_analyses] and [codebase_structure]",
|
||||
"depends_on": [1],
|
||||
"output": "implementation"
|
||||
}
|
||||
```
|
||||
|
||||
### Task Validation Rules
|
||||
1. **ID Uniqueness**: All task IDs must be unique
|
||||
2. **Hierarchical Format**: Must follow IMPL-N[.M] pattern (maximum 2 levels)
|
||||
3. **Parent References**: All parent IDs must exist as JSON files
|
||||
4. **Status Consistency**: Status values from defined enumeration
|
||||
5. **Required Fields**: All 5 core fields must be present (id, title, status, meta, context, flow_control)
|
||||
6. **Focus Paths Structure**: context.focus_paths must contain concrete paths (no wildcards)
|
||||
7. **Flow Control Format**: pre_analysis must be array with required fields
|
||||
8. **Dependency Integrity**: All task-level depends_on references must exist as JSON files
|
||||
9. **Artifacts Structure**: context.artifacts (optional) must use valid type, priority, and path format
|
||||
10. **Implementation Steps Array**: implementation_approach must be array of step objects
|
||||
11. **Step Number Uniqueness**: All step numbers within a task must be unique and sequential (1, 2, 3, ...)
|
||||
12. **Step Dependencies**: All step-level depends_on numbers must reference valid steps within same task
|
||||
13. **Step Sequence**: Step numbers should match array order (first item step=1, second item step=2, etc.)
|
||||
14. **Step Required Fields**: Each step must have step, title, description, modification_points, logic_flow, depends_on, output
|
||||
15. **Step Optional Fields**: command field is optional - when omitted, agent executes based on modification_points and logic_flow
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
### Unified File Structure
|
||||
All workflows use the same file structure definition regardless of complexity. **Directories and files are created on-demand as needed**, not all at once during initialization.
|
||||
|
||||
#### Complete Structure Reference
|
||||
```
|
||||
.workflow/
|
||||
├── [.scratchpad/] # Non-session-specific outputs (created when needed)
|
||||
│ ├── analyze-*-[timestamp].md # One-off analysis results
|
||||
│ ├── chat-*-[timestamp].md # Standalone chat sessions
|
||||
│ ├── plan-*-[timestamp].md # Ad-hoc planning notes
|
||||
│ ├── bug-index-*-[timestamp].md # Quick bug analyses
|
||||
│ ├── code-analysis-*-[timestamp].md # Standalone code analysis
|
||||
│ ├── execute-*-[timestamp].md # Ad-hoc implementation logs
|
||||
│ └── codex-execute-*-[timestamp].md # Multi-stage execution logs
|
||||
│
|
||||
├── [design-run-*/] # Standalone UI design outputs (created when needed)
|
||||
│ └── (timestamped)/ # Timestamped design runs without session
|
||||
│ ├── .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
|
||||
│
|
||||
├── active/ # Active 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
|
||||
│ ├── [.review/] # Code review results (created by review commands)
|
||||
│ │ ├── review-metadata.json # Review configuration and scope
|
||||
│ │ ├── review-state.json # Review state machine
|
||||
│ │ ├── review-progress.json # Real-time progress tracking
|
||||
│ │ ├── dimensions/ # Per-dimension analysis results
|
||||
│ │ ├── iterations/ # Deep-dive iteration results
|
||||
│ │ ├── reports/ # Human-readable reports and CLI outputs
|
||||
│ │ ├── REVIEW-SUMMARY.md # Final consolidated summary
|
||||
│ │ └── dashboard.html # Interactive review dashboard
|
||||
│ ├── [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
|
||||
- **Initial Setup**: Create only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, and `.task/` directory
|
||||
- **On-Demand Creation**: Other directories created when first needed
|
||||
- **Dynamic Files**: Subtask JSON files created during task decomposition
|
||||
- **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
|
||||
- **Design Usage**: `design-{timestamp}/` created by UI design workflows in `.workflow/` directly for standalone design runs
|
||||
- **Review Usage**: `.review/` created by review commands (`/workflow:review-module-cycle`, `/workflow:review-session-cycle`) for comprehensive code quality analysis
|
||||
- **Intermediate Files**: `.intermediates/` contains analysis data (style/layout) separate from final deliverables
|
||||
- **Layout Templates**: `layout-extraction/layout-templates.json` contains structural templates for UI assembly
|
||||
|
||||
#### Scratchpad Directory (.scratchpad/)
|
||||
**Purpose**: Centralized location for non-session-specific CLI outputs
|
||||
|
||||
**When to Use**:
|
||||
1. **No Active Session**: CLI analysis/chat commands run without an active workflow session
|
||||
2. **Unrelated Analysis**: Quick analysis not related to current active session
|
||||
3. **Exploratory Work**: Ad-hoc investigation before creating formal workflow
|
||||
4. **One-Off Queries**: Standalone questions or debugging without workflow context
|
||||
|
||||
**Output Routing Logic**:
|
||||
- **IF** active session exists in `.workflow/active/` AND command is session-relevant:
|
||||
- Save to `.workflow/active/WFS-[id]/.chat/[command]-[timestamp].md`
|
||||
- **ELSE** (no session OR one-off analysis):
|
||||
- Save to `.workflow/.scratchpad/[command]-[description]-[timestamp].md`
|
||||
|
||||
**File Naming Pattern**: `[command-type]-[brief-description]-[timestamp].md`
|
||||
|
||||
**Examples**:
|
||||
|
||||
*Workflow Commands (lightweight):*
|
||||
- `/workflow-lite-plan "feature idea"` (exploratory) → `.scratchpad/lite-plan-feature-idea-20250105-143110.md`
|
||||
- `/workflow:lite-fix "bug description"` (bug fixing) → `.scratchpad/lite-fix-bug-20250105-143130.md`
|
||||
|
||||
> **Note**: Direct CLI commands (`/cli:analyze`, `/cli:execute`, etc.) have been replaced by semantic invocation and workflow commands.
|
||||
|
||||
**Maintenance**:
|
||||
- Periodically review and clean up old scratchpad files
|
||||
- Promote useful analyses to formal workflow sessions if needed
|
||||
- No automatic cleanup - manual management recommended
|
||||
|
||||
### File Naming Conventions
|
||||
|
||||
#### Session Identifiers
|
||||
**Format**: `WFS-[topic-slug]`
|
||||
|
||||
**WFS Prefix Meaning**:
|
||||
- `WFS` = **W**ork**F**low **S**ession
|
||||
- Identifies directories as workflow session containers
|
||||
- Distinguishes workflow sessions from other project directories
|
||||
|
||||
**Naming Rules**:
|
||||
- Convert topic to lowercase with hyphens (e.g., "User Auth System" → `WFS-user-auth-system`)
|
||||
- Add `-NNN` suffix only if conflicts exist (e.g., `WFS-payment-integration-002`)
|
||||
- Maximum length: 50 characters including WFS- prefix
|
||||
|
||||
#### Document Naming
|
||||
- `workflow-session.json` - Session state (required)
|
||||
- `IMPL_PLAN.md` - Planning document (required)
|
||||
- `TODO_LIST.md` - Progress tracking (auto-generated when needed)
|
||||
- Chat sessions: `chat-analysis-*.md`
|
||||
- Task summaries: `IMPL-[task-id]-summary.md`
|
||||
|
||||
### Document Templates
|
||||
|
||||
#### TODO_LIST.md Template
|
||||
```markdown
|
||||
# Tasks: [Session Topic]
|
||||
|
||||
## Task Progress
|
||||
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
|
||||
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
|
||||
- [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2-summary.md)
|
||||
|
||||
- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002-summary.md)
|
||||
|
||||
## Status Legend
|
||||
- `▸` = Container task (has subtasks)
|
||||
- `- [ ]` = Pending leaf task
|
||||
- `- [x]` = Completed leaf task
|
||||
- Maximum 2 levels: Main tasks and subtasks only
|
||||
```
|
||||
|
||||
## Operations Guide
|
||||
|
||||
### Session Management
|
||||
```bash
|
||||
# Create minimal required structure
|
||||
mkdir -p .workflow/active/WFS-topic-slug/.task
|
||||
echo '{"session_id":"WFS-topic-slug",...}' > .workflow/active/WFS-topic-slug/workflow-session.json
|
||||
echo '# Implementation Plan' > .workflow/active/WFS-topic-slug/IMPL_PLAN.md
|
||||
echo '# Tasks' > .workflow/active/WFS-topic-slug/TODO_LIST.md
|
||||
```
|
||||
|
||||
### Task Operations
|
||||
```bash
|
||||
# Create task
|
||||
echo '{"id":"IMPL-1","title":"New task",...}' > .task/IMPL-1.json
|
||||
|
||||
# Update task status
|
||||
jq '.status = "active"' .task/IMPL-1.json > temp && mv temp .task/IMPL-1.json
|
||||
|
||||
# Generate TODO list from JSON state
|
||||
generate_todo_list_from_json .task/
|
||||
```
|
||||
|
||||
### Directory Creation (On-Demand)
|
||||
```bash
|
||||
mkdir -p .brainstorming # When brainstorming is initiated
|
||||
mkdir -p .chat # When analysis commands are run
|
||||
mkdir -p .summaries # When first task completes
|
||||
```
|
||||
|
||||
### Session Consistency Checks & Recovery
|
||||
```bash
|
||||
# Validate session directory structure
|
||||
if [ -d ".workflow/active/" ]; then
|
||||
for session_dir in .workflow/active/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 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
|
||||
|
||||
### Task Complexity Rules
|
||||
**Complexity is determined by task count and decomposition needs:**
|
||||
|
||||
| Complexity | Task Count | Hierarchy Depth | Decomposition Behavior |
|
||||
|------------|------------|----------------|----------------------|
|
||||
| **Simple** | <5 tasks | 1 level (IMPL-N) | Direct execution, minimal decomposition |
|
||||
| **Medium** | 5-15 tasks | 2 levels (IMPL-N.M) | Moderate decomposition, context coordination |
|
||||
| **Complex** | >15 tasks | 2 levels (IMPL-N.M) | Frequent decomposition, multi-agent orchestration |
|
||||
|
||||
### Workflow Characteristics & Tool Guidance
|
||||
|
||||
#### Simple Workflows
|
||||
- **Examples**: Bug fixes, small feature additions, configuration changes
|
||||
- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed
|
||||
- **Agent Coordination**: Direct execution without complex orchestration
|
||||
- **Tool Strategy**: `bash()` commands, `grep()` for pattern matching
|
||||
|
||||
#### Medium Workflows
|
||||
- **Examples**: New features, API endpoints with integration, database schema changes
|
||||
- **Task Decomposition**: Two-level hierarchy when decomposition is needed
|
||||
- **Agent Coordination**: Context coordination between related tasks
|
||||
- **Tool Strategy**: `gemini` for pattern analysis, `codex --full-auto` for implementation
|
||||
|
||||
#### Complex Workflows
|
||||
- **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments
|
||||
- **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation
|
||||
- **Agent Coordination**: Multi-agent orchestration with deep context analysis
|
||||
- **Tool Strategy**: `gemini` for architecture analysis, `codex --full-auto` for complex problem solving, `bash()` commands for flexible analysis
|
||||
|
||||
### Assessment & Upgrades
|
||||
- **During Creation**: System evaluates requirements and assigns complexity
|
||||
- **During Execution**: Can upgrade (Simple→Medium→Complex) but never downgrade
|
||||
- **Override Allowed**: Users can specify higher complexity manually
|
||||
|
||||
## Agent Integration
|
||||
|
||||
### Agent Assignment
|
||||
Based on task type and title keywords:
|
||||
- **Planning tasks** → @action-planning-agent
|
||||
- **Implementation** → @code-developer (code + tests)
|
||||
- **Test execution/fixing** → @test-fix-agent
|
||||
- **Review** → @universal-executor (optional, only when explicitly requested)
|
||||
|
||||
### Execution Context
|
||||
Agents receive complete task JSON plus workflow context:
|
||||
```json
|
||||
{
|
||||
"task": { /* complete task JSON */ },
|
||||
"workflow": {
|
||||
"session": "WFS-user-auth",
|
||||
"phase": "IMPLEMENT"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user