Skip to content

Commit b945e2d

Browse files
catlog22claude
andcommitted
docs: Enhance target_files documentation and fix cross-platform command compatibility
## Target Files Enhancement - Add support for new file creation in target_files format - Update task-generate.md with comprehensive target_files generation guide - Update concept-enhanced.md to output code modification targets - Add examples showing both modification (file:function:lines) and creation (file) formats ## Cross-Platform Command Fixes - Replace ls with find commands for better Windows Git Bash compatibility - Update workflow commands: execute.md, status.md, review.md - Update session commands: list.md, complete.md - Add Bash environment guidelines to context-search-strategy.md - Document forbidden Windows commands (findstr, dir, where, etc.) ## Files Updated - Core workflows: workflow-architecture.md, task-core.md - Command docs: 9 workflow command files - Agent docs: action-planning-agent.md, task-generate-agent.md - Strategy docs: context-search-strategy.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 661cb5b commit b945e2d

File tree

12 files changed

+117
-38
lines changed

12 files changed

+117
-38
lines changed

.claude/agents/action-planning-agent.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,7 @@ Generate individual `.task/IMPL-*.json` files with:
228228
"modification_points": ["Apply requirements"],
229229
"logic_flow": ["Load spec", "Analyze", "Implement", "Validate"]
230230
},
231-
"target_files": ["file:function:lines"]
231+
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
232232
}
233233
}
234234
```

.claude/commands/workflow/execute.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -356,8 +356,8 @@ Task(subagent_type="{meta.agent}",
356356
357357
**WORKFLOW COMPLETION CHECK**:
358358
After updating task status, check if workflow is complete:
359-
total_tasks=\$(ls .workflow/*/\.task/*.json | wc -l)
360-
completed_tasks=\$(ls .workflow/*/\.summaries/*.md 2>/dev/null | wc -l)
359+
total_tasks=\$(find .workflow/*/\.task/ -name "*.json" -type f 2>/dev/null | wc -l)
360+
completed_tasks=\$(find .workflow/*/\.summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
361361
if [ \$total_tasks -eq \$completed_tasks ]; then
362362
SlashCommand(command=\"/workflow:session:complete\")
363363
fi"),
@@ -433,7 +433,7 @@ Task(subagent_type="{meta.agent}",
433433
"task_description": "Implement following consolidated synthesis specification...",
434434
"modification_points": ["Apply synthesis specification requirements..."]
435435
},
436-
"target_files": ["file:function:lines"]
436+
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
437437
}
438438
}
439439
```

.claude/commands/workflow/review.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ if [ ! -d ".workflow/${sessionId}" ]; then
5555
fi
5656

5757
# Check for completed tasks
58-
if [ ! -d ".workflow/${sessionId}/.summaries" ] || [ -z "$(ls .workflow/${sessionId}/.summaries/IMPL-*.md 2>/dev/null)" ]; then
58+
if [ ! -d ".workflow/${sessionId}/.summaries" ] || [ -z "$(find .workflow/${sessionId}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
5959
echo "❌ No completed implementation found. Complete implementation first"
6060
exit 1
6161
fi

.claude/commands/workflow/session/complete.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,8 @@ mv temp.json .workflow/WFS-session/workflow-session.json
4444

4545
### Step 5: Count Final Statistics
4646
```bash
47-
ls .workflow/WFS-session/.task/*.json 2>/dev/null | wc -l
48-
ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
47+
find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
48+
find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
4949
```
5050

5151
### Step 6: Remove Active Marker
@@ -56,12 +56,12 @@ rm .workflow/.active-WFS-session-name
5656
## Simple Bash Commands
5757

5858
### Basic Operations
59-
- **Find active session**: `ls .workflow/.active-*`
59+
- **Find active session**: `find .workflow/ -name ".active-*" -type f`
6060
- **Get session name**: `basename marker | sed 's/^\.active-//'`
6161
- **Update status**: `jq '.status = "completed"' session.json > temp.json`
6262
- **Add timestamp**: `jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
63-
- **Count tasks**: `ls .task/*.json | wc -l`
64-
- **Count completed**: `ls .summaries/*.md | wc -l`
63+
- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
64+
- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
6565
- **Remove marker**: `rm .workflow/.active-session`
6666

6767
### Completion Result
@@ -92,11 +92,11 @@ Session Completion Summary:
9292
### Error Handling
9393
```bash
9494
# No active session
95-
ls .workflow/.active-* 2>/dev/null || echo "No active session found"
95+
find .workflow/ -name ".active-*" -type f 2>/dev/null || echo "No active session found"
9696

9797
# Incomplete tasks
98-
task_count=$(ls .task/*.json | wc -l)
99-
summary_count=$(ls .summaries/*.md 2>/dev/null | wc -l)
98+
task_count=$(find .task/ -name "*.json" -type f | wc -l)
99+
summary_count=$(find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
100100
test $task_count -eq $summary_count || echo "Warning: Not all tasks completed"
101101
```
102102

.claude/commands/workflow/session/list.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,8 @@ jq -r '.session_id, .status, .project' .workflow/WFS-session/workflow-session.js
3535

3636
### Step 4: Count Task Progress
3737
```bash
38-
ls .workflow/WFS-session/.task/*.json 2>/dev/null | wc -l
39-
ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
38+
find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
39+
find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
4040
```
4141

4242
### Step 5: Get Creation Time
@@ -47,11 +47,11 @@ jq -r '.created_at // "unknown"' .workflow/WFS-session/workflow-session.json
4747
## Simple Bash Commands
4848

4949
### Basic Operations
50-
- **List sessions**: `ls .workflow/WFS-*`
51-
- **Find active**: `ls .workflow/.active-*`
50+
- **List sessions**: `find .workflow/ -maxdepth 1 -type d -name "WFS-*"`
51+
- **Find active**: `find .workflow/ -name ".active-*" -type f`
5252
- **Read session data**: `jq -r '.session_id, .status' session.json`
53-
- **Count tasks**: `ls .task/*.json | wc -l`
54-
- **Count completed**: `ls .summaries/*.md | wc -l`
53+
- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
54+
- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
5555
- **Get timestamp**: `jq -r '.created_at' session.json`
5656

5757
## Simple Output Format

.claude/commands/workflow/status.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Generates on-demand views from JSON task data. No synchronization needed - all v
2525

2626
### Step 1: Find Active Session
2727
```bash
28-
ls .workflow/.active-* 2>/dev/null | head -1
28+
find .workflow/ -name ".active-*" -type f 2>/dev/null | head -1
2929
```
3030

3131
### Step 2: Load Session Data
@@ -35,7 +35,7 @@ cat .workflow/WFS-session/workflow-session.json
3535

3636
### Step 3: Scan Task Files
3737
```bash
38-
ls .workflow/WFS-session/.task/*.json 2>/dev/null
38+
find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null
3939
```
4040

4141
### Step 4: Generate Task Status
@@ -45,8 +45,8 @@ cat .workflow/WFS-session/.task/impl-1.json | jq -r '.status'
4545

4646
### Step 5: Count Task Progress
4747
```bash
48-
ls .workflow/WFS-session/.task/*.json | wc -l
49-
ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
48+
find .workflow/WFS-session/.task/ -name "*.json" -type f | wc -l
49+
find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
5050
```
5151

5252
### Step 6: Display Overview
@@ -66,11 +66,11 @@ ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
6666
## Simple Bash Commands
6767

6868
### Basic Operations
69-
- **Find active session**: `ls .workflow/.active-*`
69+
- **Find active session**: `find .workflow/ -name ".active-*" -type f`
7070
- **Read session info**: `cat .workflow/session/workflow-session.json`
71-
- **List tasks**: `ls .workflow/session/.task/*.json`
71+
- **List tasks**: `find .workflow/session/.task/ -name "*.json" -type f`
7272
- **Check task status**: `cat task.json | jq -r '.status'`
73-
- **Count completed**: `ls .summaries/*.md | wc -l`
73+
- **Count completed**: `find .summaries/ -name "*.md" -type f | wc -l`
7474

7575
### Task Status Check
7676
- **pending**: Not started yet
@@ -87,8 +87,8 @@ test -f .workflow/.active-* && echo "Session active"
8787
for f in .workflow/session/.task/*.json; do jq empty "$f" && echo "Valid: $f"; done
8888

8989
# Check summaries match
90-
ls .task/*.json | wc -l
91-
ls .summaries/*.md | wc -l
90+
find .task/ -name "*.json" -type f | wc -l
91+
find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l
9292
```
9393

9494
## Simple Output Format

.claude/commands/workflow/tools/concept-enhanced.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,9 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
141141
RULES:
142142
- Focus on SOLUTION IMPROVEMENTS and KEY DESIGN DECISIONS, NOT task planning
143143
- Provide architectural rationale, evaluate alternatives, assess tradeoffs
144+
- **CRITICAL**: Identify code targets - existing files as "file:function:lines", new files as "file"
145+
- For modifications: specify exact files/functions/line ranges
146+
- For new files: specify file path only (no function or lines)
144147
- Do NOT create task lists, implementation steps, or code examples
145148
- Do NOT generate any code snippets or implementation details
146149
- **MUST write output to .workflow/{session_id}/.process/gemini-solution-design.md**
@@ -172,6 +175,8 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
172175
RULES:
173176
- Focus on TECHNICAL FEASIBILITY and RISK ASSESSMENT, NOT implementation planning
174177
- Validate architectural decisions, identify potential issues, recommend optimizations
178+
- **CRITICAL**: Verify code targets - existing files "file:function:lines", new files "file"
179+
- Confirm exact locations for modifications, identify additional new files if needed
175180
- Do NOT create task breakdowns, step-by-step guides, or code examples
176181
- Do NOT generate any code snippets or implementation details
177182
- **MUST write output to .workflow/{session_id}/.process/codex-feasibility-validation.md**
@@ -301,6 +306,39 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec
301306
- **Module Dependencies**: {dependency_graph_and_order}
302307
- **Quality Assurance**: {qa_approach_and_validation}
303308
309+
### Code Modification Targets
310+
**Purpose**: Specific code locations for modification AND new files to create
311+
312+
**Format**:
313+
- Existing files: `file:function:lines` (with line numbers)
314+
- New files: `file` (no function or lines)
315+
316+
**Identified Targets**:
317+
1. **Target**: `src/auth/AuthService.ts:login:45-52`
318+
- **Type**: Modify existing
319+
- **Modification**: Enhance error handling
320+
- **Rationale**: Current logic lacks validation for edge cases
321+
322+
2. **Target**: `src/auth/PasswordReset.ts`
323+
- **Type**: Create new file
324+
- **Purpose**: Password reset functionality
325+
- **Rationale**: New feature requirement
326+
327+
3. **Target**: `src/middleware/auth.ts:validateToken:30-45`
328+
- **Type**: Modify existing
329+
- **Modification**: Add token expiry check
330+
- **Rationale**: Security requirement for JWT validation
331+
332+
4. **Target**: `tests/auth/PasswordReset.test.ts`
333+
- **Type**: Create new file
334+
- **Purpose**: Test coverage for password reset
335+
- **Rationale**: Test requirement for new feature
336+
337+
**Note**:
338+
- For new files, only specify the file path (no function or lines)
339+
- For existing files without line numbers, use `file:function:*` format
340+
- Task generation will refine these during the `analyze_task_patterns` step
341+
304342
### Feasibility Assessment
305343
- **Technical Complexity**: {complexity_rating_and_analysis}
306344
- **Performance Impact**: {expected_performance_characteristics}

.claude/commands/workflow/tools/task-generate-agent.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,7 @@ Task(
212212
"Validate against acceptance criteria"
213213
]
214214
},
215-
"target_files": ["file:function:lines"]
215+
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
216216
}
217217
}
218218
\`\`\`

.claude/commands/workflow/tools/task-generate.md

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -142,12 +142,12 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
142142
},
143143
{
144144
"step": "analyze_task_patterns",
145-
"action": "Analyze existing code patterns",
145+
"action": "Analyze existing code patterns and identify modification targets",
146146
"commands": [
147147
"bash(cd \"[focus_paths]\")",
148-
"bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze patterns TASK: Review '[title]' CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Pattern analysis RULES: Prioritize synthesis-specification.md\")"
148+
"bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Prioritize synthesis-specification.md, identify exact modification points\")"
149149
],
150-
"output_to": "task_context",
150+
"output_to": "task_context_with_targets",
151151
"on_error": "fail"
152152
}
153153
],
@@ -175,8 +175,40 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
175175
1. Parse analysis results and extract task definitions
176176
2. Detect brainstorming artifacts with priority scoring
177177
3. Generate task context (requirements, focus_paths, acceptance)
178-
4. Build flow_control with artifact loading steps
179-
5. Create individual task JSON files in `.task/`
178+
4. **Determine modification targets**: Extract specific code locations from analysis
179+
5. Build flow_control with artifact loading steps and target_files
180+
6. Create individual task JSON files in `.task/`
181+
182+
#### Target Files Generation (Critical)
183+
**Purpose**: Identify specific code locations for modification AND new files to create
184+
185+
**Source Data Priority**:
186+
1. **ANALYSIS_RESULTS.md** - Should contain identified code locations
187+
2. **Gemini/MCP Analysis** - From `analyze_task_patterns` step
188+
3. **Context Package** - File references from `focus_paths`
189+
190+
**Format**: `["file:function:lines"]` or `["file"]` (for new files)
191+
- `file`: Relative path from project root (e.g., `src/auth/AuthService.ts`)
192+
- `function`: Function/method name to modify (e.g., `login`, `validateToken`) - **omit for new files**
193+
- `lines`: Approximate line range (e.g., `45-52`, `120-135`) - **omit for new files**
194+
195+
**Examples**:
196+
```json
197+
"target_files": [
198+
"src/auth/AuthService.ts:login:45-52",
199+
"src/middleware/auth.ts:validateToken:30-45",
200+
"src/auth/PasswordReset.ts",
201+
"tests/auth/PasswordReset.test.ts",
202+
"tests/auth.test.ts:testLogin:15-20"
203+
]
204+
```
205+
206+
**Generation Strategy**:
207+
- **New files to create** → Use `["path/to/NewFile.ts"]` (no function or lines)
208+
- **Existing files with specific locations** → Use `["file:function:lines"]`
209+
- **Existing files with function only** → Search lines using MCP/grep `["file:function:*"]`
210+
- **Existing files (explore entire)** → Mark as `["file.ts:*:*"]`
211+
- **No specific targets** → Leave empty `[]` (agent explores focus_paths)
180212

181213
### Phase 3: Artifact Detection & Integration
182214

.claude/workflows/context-search-strategy.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ type: search-guideline
66

77
# Context Search Strategy
88

9+
## ⚡ Execution Environment
10+
11+
**CRITICAL**: All commands execute in **Bash environment** (Git Bash on Windows, Bash on Linux/macOS)
12+
13+
**❌ Forbidden**: Windows-specific commands (`findstr`, `dir`, `where`, `type`, `copy`, `del`) - Use Bash equivalents (`grep`, `find`, `which`, `cat`, `cp`, `rm`)
14+
915
## ⚡ Core Search Tools
1016

1117
**rg (ripgrep)**: Fast content search with regex support
@@ -18,6 +24,7 @@ type: search-guideline
1824
- **Use find for files** - Locate files/directories by name
1925
- **Use grep sparingly** - Only when rg unavailable
2026
- **Use get_modules_by_depth.sh first** - MANDATORY for program architecture analysis before planning
27+
- **Always use Bash commands** - NEVER use Windows cmd/PowerShell commands
2128

2229
### Quick Command Reference
2330
```bash

0 commit comments

Comments
 (0)