mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
refactor: split task JSON templates and improve CLI mode support
- Split task-json-schema.txt into two mode-specific templates: - task-json-agent-mode.txt: Agent execution (no command field) - task-json-cli-mode.txt: CLI execution (with command field) - Update task-generate.md: - Remove outdated Codex resume mechanism description - Add clear execution mode examples (Agent/CLI) - Simplify CLI Execute Mode Details section - Update task-generate-agent.md: - Add --cli-execute flag support - Command selects template path before invoking agent - Agent receives template path and reads it (not content) - Clarify responsibility: Command decides, Agent executes - Improve architecture: - Clear separation: Command layer (template selection) vs Agent layer (content generation) - Template selection based on flag, not agent logic - Agent simplicity: receives path, reads template, generates content 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -0,0 +1,119 @@
|
||||
Task JSON Schema - Agent Mode (No Command Field)
|
||||
|
||||
## Schema Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N[.M]",
|
||||
"title": "Descriptive task name",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "feature|bugfix|refactor|test|docs",
|
||||
"agent": "@code-developer|@test-fix-agent|@general-purpose"
|
||||
},
|
||||
"context": {
|
||||
"requirements": ["extracted from analysis"],
|
||||
"focus_paths": ["src/paths"],
|
||||
"acceptance": ["measurable criteria"],
|
||||
"depends_on": ["IMPL-N"],
|
||||
"artifacts": [
|
||||
{
|
||||
"type": "synthesis_specification",
|
||||
"path": "{synthesis_spec_path}",
|
||||
"priority": "highest",
|
||||
"usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
|
||||
},
|
||||
{
|
||||
"type": "role_analysis",
|
||||
"path": "{role_analysis_path}",
|
||||
"priority": "high",
|
||||
"usage": "Technical/design/business details from specific roles. Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)"
|
||||
}
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_synthesis_specification",
|
||||
"action": "Load consolidated synthesis specification",
|
||||
"commands": [
|
||||
"Read({synthesis_spec_path})"
|
||||
],
|
||||
"output_to": "synthesis_specification",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "load_context_package",
|
||||
"action": "Load context package for project structure",
|
||||
"commands": [
|
||||
"Read({context_package_path})"
|
||||
],
|
||||
"output_to": "context_pkg",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "mcp_codebase_exploration",
|
||||
"action": "Explore codebase using MCP",
|
||||
"command": "mcp__code-index__find_files(pattern=\"{file_pattern}\") && mcp__code-index__search_code_advanced(pattern=\"{search_pattern}\")",
|
||||
"output_to": "codebase_structure",
|
||||
"on_error": "skip_optional"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement task following synthesis specification",
|
||||
"description": "Implement '{title}' following [synthesis_specification] requirements and [context_pkg] patterns. Use synthesis-specification.md as primary source, consult artifacts for technical details.",
|
||||
"modification_points": [
|
||||
"Apply consolidated requirements from synthesis-specification.md",
|
||||
"Follow technical guidelines from synthesis",
|
||||
"Consult artifacts for implementation details when needed",
|
||||
"Integrate with existing patterns"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Load synthesis specification and context package",
|
||||
"Analyze existing patterns from [codebase_structure]",
|
||||
"Implement following specification",
|
||||
"Consult artifacts for technical details when needed",
|
||||
"Validate against acceptance criteria"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key Features - Agent Mode
|
||||
|
||||
**Execution Model**: Agent interprets `modification_points` and `logic_flow` to execute autonomously
|
||||
|
||||
**No Command Field**: Steps in `implementation_approach` do NOT include `command` field
|
||||
|
||||
**Context Loading**: Context loaded via `pre_analysis` steps, available as variables (e.g., [synthesis_specification], [context_pkg])
|
||||
|
||||
**Agent Execution**:
|
||||
- Agent reads modification_points and logic_flow
|
||||
- Agent performs implementation autonomously
|
||||
- Agent validates against acceptance criteria
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
**implementation_approach**: Array of step objects (NO command field)
|
||||
- **step**: Sequential step number
|
||||
- **title**: Step description
|
||||
- **description**: Detailed instructions with variable references
|
||||
- **modification_points**: Specific code modifications to apply
|
||||
- **logic_flow**: Business logic execution sequence
|
||||
- **depends_on**: Step dependencies (empty array for independent steps)
|
||||
- **output**: Expected deliverable variable name
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
1. **Load Context**: Use pre_analysis to load synthesis, context package, and explore codebase
|
||||
2. **Reference Variables**: Use [variable_name] to reference outputs from pre_analysis steps
|
||||
3. **Clear Instructions**: Provide detailed modification_points and logic_flow for agent
|
||||
4. **No Commands**: Never add command field to implementation_approach steps
|
||||
5. **Agent Autonomy**: Let agent interpret and execute based on provided instructions
|
||||
@@ -0,0 +1,178 @@
|
||||
Task JSON Schema - CLI Execute Mode (With Command Field)
|
||||
|
||||
## Schema Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N[.M]",
|
||||
"title": "Descriptive task name",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "feature|bugfix|refactor|test|docs",
|
||||
"agent": "@code-developer|@test-fix-agent|@general-purpose"
|
||||
},
|
||||
"context": {
|
||||
"requirements": ["extracted from analysis"],
|
||||
"focus_paths": ["src/paths"],
|
||||
"acceptance": ["measurable criteria"],
|
||||
"depends_on": ["IMPL-N"],
|
||||
"artifacts": [
|
||||
{
|
||||
"type": "synthesis_specification",
|
||||
"path": "{synthesis_spec_path}",
|
||||
"priority": "highest",
|
||||
"usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
|
||||
},
|
||||
{
|
||||
"type": "role_analysis",
|
||||
"path": "{role_analysis_path}",
|
||||
"priority": "high",
|
||||
"usage": "Technical/design/business details from specific roles"
|
||||
}
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_synthesis_specification",
|
||||
"action": "Load consolidated synthesis specification",
|
||||
"commands": [
|
||||
"Read({synthesis_spec_path})"
|
||||
],
|
||||
"output_to": "synthesis_specification",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "load_context_package",
|
||||
"action": "Load context package",
|
||||
"commands": [
|
||||
"Read({context_package_path})"
|
||||
],
|
||||
"output_to": "context_pkg",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "mcp_codebase_exploration",
|
||||
"action": "Explore codebase using MCP",
|
||||
"command": "mcp__code-index__find_files(pattern=\"{file_pattern}\")",
|
||||
"output_to": "codebase_structure",
|
||||
"on_error": "skip_optional"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement task with Codex",
|
||||
"description": "Implement '{title}' using Codex CLI tool",
|
||||
"command": "bash(codex -C {focus_path} --full-auto exec \"PURPOSE: {purpose} TASK: {task_description} MODE: auto CONTEXT: @{{synthesis_spec_path}} @{{context_package_path}} EXPECTED: {expected_output} RULES: Follow synthesis specification\" --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": [
|
||||
"Create/modify implementation files",
|
||||
"Follow synthesis specification requirements",
|
||||
"Integrate with existing patterns"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Codex loads context package and synthesis",
|
||||
"Codex implements according to specification",
|
||||
"Codex validates against acceptance criteria"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Multi-Step Example (Complex Task with Resume)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-002",
|
||||
"title": "Implement RBAC system",
|
||||
"flow_control": {
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Create RBAC models",
|
||||
"description": "Create role and permission data models",
|
||||
"command": "bash(codex -C src/models --full-auto exec \"PURPOSE: Create RBAC models TASK: Define role and permission models MODE: auto CONTEXT: @{{synthesis_spec_path}} @{{context_package_path}} EXPECTED: Models with migrations RULES: Follow synthesis spec\" --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Define role model", "Define permission model"],
|
||||
"logic_flow": ["Design schema", "Implement models", "Generate migrations"],
|
||||
"depends_on": [],
|
||||
"output": "rbac_models"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Implement RBAC middleware",
|
||||
"description": "Create route protection middleware",
|
||||
"command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Create permission checker", "Add route decorators"],
|
||||
"logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"],
|
||||
"depends_on": [1],
|
||||
"output": "rbac_middleware"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key Features - CLI Execute Mode
|
||||
|
||||
**Execution Model**: Commands in `command` field execute steps directly
|
||||
|
||||
**Command Field Required**: Every step in `implementation_approach` MUST include `command` field
|
||||
|
||||
**Context Delivery**: Context provided via CONTEXT field in command prompt using `@{path}` syntax
|
||||
|
||||
**Multi-Step Support**:
|
||||
- First step: Full context with `-C directory` and complete CONTEXT field
|
||||
- Subsequent steps: Use `resume --last` to maintain session continuity
|
||||
- Step dependencies: Use `depends_on` array to specify step order
|
||||
|
||||
## Command Templates
|
||||
|
||||
### Single-Step Codex Command
|
||||
```bash
|
||||
bash(codex -C {focus_path} --full-auto exec "PURPOSE: {purpose} TASK: {task} MODE: auto CONTEXT: @{{synthesis_spec_path}} @{{context_package_path}} EXPECTED: {expected} RULES: {rules}" --skip-git-repo-check -s danger-full-access)
|
||||
```
|
||||
|
||||
### Multi-Step Codex with Resume
|
||||
```bash
|
||||
# First step
|
||||
bash(codex -C {path} --full-auto exec "..." --skip-git-repo-check -s danger-full-access)
|
||||
|
||||
# Subsequent steps
|
||||
bash(codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access)
|
||||
```
|
||||
|
||||
### Gemini/Qwen Commands (Analysis/Documentation)
|
||||
```bash
|
||||
bash(~/.claude/scripts/gemini-wrapper -p "PURPOSE: {purpose} TASK: {task} MODE: analysis CONTEXT: @{{synthesis_spec_path}} EXPECTED: {expected} RULES: {rules}")
|
||||
|
||||
# With write permission
|
||||
bash(~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "PURPOSE: {purpose} TASK: {task} MODE: write CONTEXT: @{{context}} EXPECTED: {expected} RULES: {rules}")
|
||||
```
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
**implementation_approach**: Array of step objects (WITH command field)
|
||||
- **step**: Sequential step number
|
||||
- **title**: Step description
|
||||
- **description**: Brief step description
|
||||
- **command**: Complete CLI command to execute the step
|
||||
- **modification_points**: Specific code modifications (for reference)
|
||||
- **logic_flow**: Execution sequence (for reference)
|
||||
- **depends_on**: Step dependencies (array of step numbers, empty for independent)
|
||||
- **output**: Expected deliverable variable name
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
1. **Always Include Command**: Every step MUST have a `command` field
|
||||
2. **Context via CONTEXT Field**: Provide context using `@{path}` syntax in command prompt
|
||||
3. **First Step Full Context**: First step should include `-C directory` and full context package
|
||||
4. **Resume for Continuity**: Use `resume --last` for subsequent steps in same task
|
||||
5. **Step Dependencies**: Use `depends_on: [1, 2]` to specify execution order
|
||||
6. **Parameter Position**:
|
||||
- Codex: `--skip-git-repo-check -s danger-full-access` at END
|
||||
- Gemini/Qwen: `--approval-mode yolo` AFTER wrapper command, BEFORE -p
|
||||
@@ -1,200 +0,0 @@
|
||||
Task JSON Schema - Enhanced 5-Field Schema with Artifacts Integration
|
||||
|
||||
## Schema Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N[.M]",
|
||||
"title": "Descriptive task name",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "feature|bugfix|refactor|test|docs",
|
||||
"agent": "@code-developer|@test-fix-agent|@general-purpose"
|
||||
},
|
||||
"context": {
|
||||
"requirements": ["extracted from analysis"],
|
||||
"focus_paths": ["src/paths"],
|
||||
"acceptance": ["measurable criteria"],
|
||||
"depends_on": ["IMPL-N"],
|
||||
"artifacts": [
|
||||
{
|
||||
"type": "synthesis_specification",
|
||||
"path": "{synthesis_spec_path}",
|
||||
"priority": "highest",
|
||||
"usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
|
||||
},
|
||||
{
|
||||
"type": "role_analysis",
|
||||
"path": "{role_analysis_path}",
|
||||
"priority": "high",
|
||||
"usage": "Technical/design/business details from specific roles. Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)",
|
||||
"note": "Dynamically discovered - multiple role analysis files included based on brainstorming results"
|
||||
},
|
||||
{
|
||||
"type": "topic_framework",
|
||||
"path": "{topic_framework_path}",
|
||||
"priority": "low",
|
||||
"usage": "Discussion context and framework structure"
|
||||
}
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_synthesis_specification",
|
||||
"action": "Load consolidated synthesis specification",
|
||||
"commands": [
|
||||
"bash(ls {synthesis_spec_path} 2>/dev/null || echo 'not found')",
|
||||
"Read({synthesis_spec_path})"
|
||||
],
|
||||
"output_to": "synthesis_specification",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "mcp_codebase_exploration",
|
||||
"action": "Explore codebase using MCP",
|
||||
"command": "mcp__code-index__find_files(pattern=\"[patterns]\") && mcp__code-index__search_code_advanced(pattern=\"[patterns]\")",
|
||||
"output_to": "codebase_structure"
|
||||
},
|
||||
{
|
||||
"step": "analyze_task_patterns",
|
||||
"action": "Analyze existing code patterns",
|
||||
"commands": [
|
||||
"bash(cd \"[focus_paths]\")",
|
||||
"bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze patterns TASK: Review '[title]' CONTEXT: [synthesis_specification] EXPECTED: Pattern analysis RULES: Prioritize synthesis-specification.md\")"
|
||||
],
|
||||
"output_to": "task_context",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement task following synthesis specification",
|
||||
"description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
|
||||
"modification_points": [
|
||||
"Apply consolidated requirements from synthesis-specification.md",
|
||||
"Follow technical guidelines from synthesis",
|
||||
"Consult artifacts for implementation details when needed",
|
||||
"Integrate with existing patterns"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Load synthesis specification and relevant role artifacts",
|
||||
"Execute MCP code-index discovery for relevant files",
|
||||
"Analyze existing patterns and identify modification targets",
|
||||
"Implement following specification",
|
||||
"Consult artifacts for technical details when needed",
|
||||
"Validate against acceptance criteria"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
### Required Fields
|
||||
|
||||
**id**: Task identifier following format IMPL-N or IMPL-N.M for subtasks
|
||||
- Top-level: IMPL-1, IMPL-2, ...
|
||||
- Subtasks: IMPL-1.1, IMPL-1.2, ...
|
||||
|
||||
**title**: Clear, descriptive task name indicating the work to be done
|
||||
|
||||
**status**: Current task state
|
||||
- "pending": Not started
|
||||
- "active": Currently in progress
|
||||
- "completed": Successfully finished
|
||||
- "blocked": Waiting on dependencies
|
||||
- "container": Parent task with subtasks
|
||||
|
||||
**meta**: Metadata for task execution
|
||||
- type: Category of work (feature, bugfix, refactor, test, docs)
|
||||
- agent: Designated agent for execution (@code-developer, @test-fix-agent, @general-purpose)
|
||||
|
||||
**context**: Rich context for task execution
|
||||
- requirements: Clear, extracted requirements from analysis
|
||||
- focus_paths: Specific directories/modules to work on
|
||||
- acceptance: Measurable criteria for task completion
|
||||
- depends_on: Array of task IDs that must complete first
|
||||
- artifacts: Brainstorming outputs with usage guidance
|
||||
|
||||
### Artifacts Array Structure
|
||||
|
||||
Each artifact entry includes:
|
||||
- **type**: Category (synthesis_specification, role_analysis, topic_framework)
|
||||
- **path**: Relative path from project root
|
||||
- **priority**: highest | high | medium | low
|
||||
- **usage**: Clear description of when and how to use this artifact
|
||||
- **note**: Optional additional context or discovery information
|
||||
|
||||
### Flow Control Structure
|
||||
|
||||
**pre_analysis**: Preparatory steps before implementation
|
||||
- load_synthesis_specification: Load primary requirements source
|
||||
- mcp_codebase_exploration: Discover relevant files using MCP tools
|
||||
- analyze_task_patterns: Analyze existing patterns for consistency
|
||||
|
||||
**implementation_approach**: Detailed implementation steps
|
||||
- step: Sequential step number
|
||||
- title: Step description
|
||||
- description: Detailed instructions with artifact usage guidance
|
||||
- modification_points: Specific code locations or patterns to modify
|
||||
- logic_flow: Execution sequence
|
||||
- depends_on: Step dependencies
|
||||
- output: Expected deliverable
|
||||
|
||||
**target_files**: Specific files to modify in format "file:function:lines" or "path/to/NewFile.ts"
|
||||
|
||||
## MCP Tool Integration Examples
|
||||
|
||||
### Code Index Usage
|
||||
```javascript
|
||||
// Discover authentication-related files
|
||||
mcp__code-index__find_files(pattern="*auth*")
|
||||
|
||||
// Search for OAuth patterns
|
||||
mcp__code-index__search_code_advanced(
|
||||
pattern="oauth|jwt|authentication",
|
||||
file_pattern="*.{ts,js}"
|
||||
)
|
||||
|
||||
// Get file summary for key components
|
||||
mcp__code-index__get_file_summary(
|
||||
file_path="src/auth/index.ts"
|
||||
)
|
||||
```
|
||||
|
||||
### Exa Research Usage
|
||||
```javascript
|
||||
// Get best practices for task implementation
|
||||
mcp__exa__get_code_context_exa(
|
||||
query="TypeScript OAuth2 implementation patterns",
|
||||
tokensNum="dynamic"
|
||||
)
|
||||
|
||||
// Research specific API usage
|
||||
mcp__exa__get_code_context_exa(
|
||||
query="Express.js JWT middleware examples",
|
||||
tokensNum=5000
|
||||
)
|
||||
```
|
||||
|
||||
## Artifact Priority Guidelines
|
||||
|
||||
1. **synthesis-specification.md** (highest): Use as primary requirement source for all tasks
|
||||
2. **role-specific analysis** (high): Consult for technical details, design specifications, or business context
|
||||
3. **topic-framework.md** (low): Reference for discussion context and framework structure
|
||||
|
||||
## Usage in Agent Prompts
|
||||
|
||||
When generating task JSONs, ensure:
|
||||
- Extract requirements from ANALYSIS_RESULTS.md
|
||||
- Map artifacts based on task domain (UI → ui-designer, Backend → system-architect)
|
||||
- Include MCP tool integration in pre_analysis steps
|
||||
- Provide clear artifact usage guidance in implementation_approach
|
||||
- Specify exact modification targets in target_files
|
||||
Reference in New Issue
Block a user