catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor: consolidate agent architecture and archive legacy templates

Browse Source 
- Remove general-purpose agent in favor of universal-executor
- Enhance workflow session completion with better state management
- Improve context-gather with advanced filtering and validation
- Archive legacy prompt templates for reference

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-10-27 15:00:00 +08:00
parent 367040037a
commit 6326fbf2fb
4 changed files with 315 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
.claude/agents/general-purpose.md → .claude/agents/universal-executor.md
View File

192
.claude/commands/workflow/session/complete.md
View File

@@ -1,6 +1,6 @@
---
name: complete
description: Mark the active workflow session as complete and remove active flag
description: Mark the active workflow session as complete, archive it with lessons learned, and remove active flag
examples:
- /workflow:session:complete
- /workflow:session:complete --detailed
@@ -9,7 +9,7 @@ examples:
# Complete Workflow Session (/workflow:session:complete)
## Overview
Mark the currently active workflow session as complete, update its status, and remove the active flag marker.
Mark the currently active workflow session as complete, analyze it for lessons learned, move it to the archive directory, and remove the active flag marker.
## Usage
```bash
@@ -19,87 +19,129 @@ Mark the currently active workflow session as complete, update its status, and r
## Implementation Flow
### Step 1: Find Active Session
### Phase 1: Prepare for Archival (Minimal Manual Operations)
**Purpose**: Find active session, move to archive location, pass control to agent. Minimal operations.
#### Step 1.1: Find Active Session and Get Name
```bash
ls .workflow/.active-* 2>/dev/null | head -1
```
# Find active marker
bash(find .workflow/ -name ".active-*" -type f | head -1)
### Step 2: Get Session Name
# Extract session name from marker path
bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
```
**Output**: Session name `WFS-session-name`
#### Step 1.2: Move Session to Archive
```bash
basename .workflow/.active-WFS-session-name | sed 's/^\.active-//'
# Create archive directory if needed
bash(mkdir -p .workflow/.archives/)
# Move session to archive location
bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
```
**Result**: Session now at `.workflow/.archives/WFS-session-name/`
### Phase 2: Agent-Orchestrated Completion (All Data Processing)
**Purpose**: Agent analyzes archived session, generates metadata, updates manifest, and removes active marker.
#### Agent Invocation
Invoke `universal-executor` agent to complete the archival process.
**Agent Task**:
```
Task(
subagent_type="universal-executor",
description="Complete session archival",
prompt=`
Complete workflow session archival. Session already moved to archive location.
## Context
- Session: .workflow/.archives/WFS-session-name/
- Active marker: .workflow/.active-WFS-session-name
## Tasks
1. **Extract session data** from workflow-session.json (session_id, description/topic, started_at/timestamp, completed_at, status)
- If status != "completed", update it with timestamp
2. **Count files**: tasks (.task/*.json) and summaries (.summaries/*.md)
3. **Generate lessons**: Use gemini with ~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt (fallback: analyze files directly)
- Return: {successes, challenges, watch_patterns}
4. **Build archive entry**:
- Calculate: duration_hours, success_rate, tags (3-5 keywords)
- Construct complete JSON with session_id, description, archived_at, archive_path, metrics, tags, lessons
5. **Update manifest**: Initialize .workflow/.archives/manifest.json if needed, append entry
6. **Remove active marker**
7. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}
## Error Handling
- On failure: return {"status": "error", "task": "...", "message": "..."}
- Do NOT remove marker if failed
`
)
```
### Step 3: Update Session Status
**Expected Output**:
- Agent returns JSON result confirming successful archival
- Display completion summary to user based on agent response
## Workflow Execution Strategy
### Two-Phase Approach (Optimized)
**Phase 1: Minimal Manual Setup** (2 simple operations)
- Find active session and extract name
- Move session to archive location
- **No data extraction** - agent handles all data processing
- **No counting** - agent does this from archive location
- **Total**: 2 bash commands (find + move)
**Phase 2: Agent-Driven Completion** (1 agent invocation)
- Extract all session data from archived location
- Count tasks and summaries
- Generate lessons learned analysis
- Build complete archive metadata
- Update manifest
- Remove active marker
- Return success/error result
## Quick Commands
```bash
jq '.status = "completed"' .workflow/WFS-session/workflow-session.json > temp.json
mv temp.json .workflow/WFS-session/workflow-session.json
# Phase 1: Find and move
bash(find .workflow/ -name ".active-*" -type f | head -1)
bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
bash(mkdir -p .workflow/.archives/)
bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
# Phase 2: Agent completes archival
Task(subagent_type="universal-executor", description="Complete session archival", prompt=`...`)
```
### Step 4: Add Completion Timestamp
## Archive Query Commands
After archival, you can query the manifest:
```bash
jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
mv temp.json .workflow/WFS-session/workflow-session.json
# List all archived sessions
jq '.archives[].session_id' .workflow/.archives/manifest.json
# Find sessions by keyword
jq '.archives[] | select(.description | test("auth"; "i"))' .workflow/.archives/manifest.json
# Get specific session details
jq '.archives[] | select(.session_id == "WFS-user-auth")' .workflow/.archives/manifest.json
# List all watch patterns across sessions
jq '.archives[].lessons.watch_patterns[]' .workflow/.archives/manifest.json
```
### Step 5: Count Final Statistics
```bash
find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
```
### Step 6: Remove Active Marker
```bash
rm .workflow/.active-WFS-session-name
```
## Simple Bash Commands
### Basic Operations
- **Find active session**: `find .workflow/ -name ".active-*" -type f`
- **Get session name**: `basename marker | sed 's/^\.active-//'`
- **Update status**: `jq '.status = "completed"' session.json > temp.json`
- **Add timestamp**: `jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
- **Remove marker**: `rm .workflow/.active-session`
### Completion Result
```
Session WFS-user-auth completed
- Status: completed
- Started: 2025-09-15T10:00:00Z
- Completed: 2025-09-15T16:30:00Z
- Duration: 6h 30m
- Total tasks: 8
- Completed tasks: 8
- Success rate: 100%
```
### Detailed Summary (--detailed flag)
```
Session Completion Summary:
├── Session: WFS-user-auth
├── Project: User authentication system
├── Total time: 6h 30m
├── Tasks completed: 8/8 (100%)
├── Files generated: 24 files
├── Summaries created: 8 summaries
├── Status: All tasks completed successfully
└── Location: .workflow/WFS-user-auth/
```
### Error Handling
```bash
# No active session
find .workflow/ -name ".active-*" -type f 2>/dev/null || echo "No active session found"
# Incomplete tasks
task_count=$(find .task/ -name "*.json" -type f | wc -l)
summary_count=$(find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
test $task_count -eq $summary_count || echo "Warning: Not all tasks completed"
```
## Related Commands
- `/workflow:session:list` - View all sessions including completed
- `/workflow:session:start` - Start new session
- `/workflow:status` - Check completion status before completing

123
.claude/commands/workflow/tools/context-gather.md
View File

@@ -76,17 +76,19 @@ Execute complete context-search-agent workflow for implementation planning:
3. **Analysis**: Extract keywords, determine scope, classify complexity
### Phase 2: Multi-Source Context Discovery
Execute all 3 discovery tracks:
- **Track 1**: Reference documentation (CLAUDE.md, architecture docs)
- **Track 2**: Web examples (use Exa MCP for unfamiliar tech/APIs)
- **Track 3**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
Execute all 4 discovery tracks:
- **Track 1**: Historical archive analysis (query manifest.json for lessons learned)
- **Track 2**: Reference documentation (CLAUDE.md, architecture docs)
- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs)
- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
### Phase 3: Synthesis, Assessment & Packaging
1. Apply relevance scoring and build dependency graph
2. Synthesize 3-source data (docs > code > web)
2. Synthesize 4-source data (archive > docs > code > web)
3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
4. Perform conflict detection with risk assessment
5. Generate and validate context-package.json
5. **Inject historical conflicts** from archive analysis into conflict_detection
6. Generate and validate context-package.json
## Output Requirements
Complete context-package.json with:
@@ -95,7 +97,7 @@ Complete context-package.json with:
- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
- **dependencies**: {internal[], external[]} with dependency graph
- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy}
- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]}
## Quality Validation
Before completion verify:
@@ -141,7 +143,112 @@ Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json`
- **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
- **dependencies**: Internal and external dependency graphs
- **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
- **conflict_detection**: Risk assessment with mitigation strategies
- **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts
## Historical Archive Analysis
### Track 1: Query Archive Manifest
The context-search-agent MUST perform historical archive analysis as Track 1 in Phase 2:
**Step 1: Check for Archive Manifest**
```bash
# Check if archive manifest exists
if [[ -f .workflow/.archives/manifest.json ]]; then
# Manifest available for querying
fi
```
**Step 2: Extract Task Keywords**
```javascript
// From current task description, extract key entities and operations
const keywords = extractKeywords(task_description);
// Examples: ["User", "model", "authentication", "JWT", "reporting"]
```
**Step 3: Search Archive for Relevant Sessions**
```javascript
// Query manifest for sessions with matching tags or descriptions
const relevantArchives = archives.filter(archive => {
return archive.tags.some(tag => keywords.includes(tag)) ||
keywords.some(kw => archive.description.toLowerCase().includes(kw.toLowerCase()));
});
```
**Step 4: Extract Watch Patterns**
```javascript
// For each relevant archive, check watch_patterns for applicability
const historicalConflicts = [];
relevantArchives.forEach(archive => {
archive.lessons.watch_patterns?.forEach(pattern => {
// Check if pattern trigger matches current task
if (isPatternRelevant(pattern.pattern, task_description)) {
historicalConflicts.push({
source_session: archive.session_id,
pattern: pattern.pattern,
action: pattern.action,
files_to_check: pattern.related_files,
archived_at: archive.archived_at
});
}
});
});
```
**Step 5: Inject into Context Package**
```json
{
"conflict_detection": {
"risk_level": "medium",
"risk_factors": ["..."],
"affected_modules": ["..."],
"mitigation_strategy": "...",
"historical_conflicts": [
{
"source_session": "WFS-auth-feature",
"pattern": "When modifying User model",
"action": "Check reporting-service and auditing-service dependencies",
"files_to_check": ["src/models/User.ts", "src/services/reporting.ts"],
"archived_at": "2025-09-16T09:00:00Z"
}
]
}
}
```
### Risk Level Escalation
If `historical_conflicts` array is not empty, minimum risk level should be "medium":
```javascript
if (historicalConflicts.length > 0 && currentRisk === "low") {
conflict_detection.risk_level = "medium";
conflict_detection.risk_factors.push(
`${historicalConflicts.length} historical conflict pattern(s) detected from past sessions`
);
}
```
### Archive Query Algorithm
```markdown
1. IF .workflow/.archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
2. IF manifest exists:
a. Load manifest.json
b. Extract keywords from task_description (nouns, verbs, technical terms)
c. Filter archives where:
- ANY tag matches keywords (case-insensitive) OR
- description contains keywords (case-insensitive substring match)
d. For each relevant archive:
- Read lessons.watch_patterns array
- Check if pattern.pattern keywords overlap with task_description
- If relevant: Add to historical_conflicts array
e. IF historical_conflicts.length > 0:
- Set risk_level = max(current_risk, "medium")
- Add to risk_factors
3. Continue to Track 2 (reference documentation)
```
## Usage Examples

83
.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt Normal file
View File

@@ -0,0 +1,83 @@
You are the archive-analysis-agent. Your mission is to analyze a completed workflow session and extract actionable lessons in JSON format.
## Input Context
You will analyze the session directory structure containing:
- workflow-session.json: Session metadata
- IMPL_PLAN.md: Implementation plan
- .task/*.json: Task definitions
- .summaries/*.md: Task completion summaries
- .process/context-package.json: Initial context and conflict detection
## Analysis Tasks
### 1. Identify Successes
Find design patterns, architectural decisions, or solutions that worked well.
- Look for elegant solutions in .summaries/
- Identify reusable patterns from IMPL_PLAN.md
- Include file references using @path/to/file.ext format
### 2. Document Challenges
Identify problems encountered during implementation.
- Failed tasks or iterations from .process/ logs
- Issues mentioned in summaries
- Unexpected complications or blockers
### 3. Extract Watch Patterns
Create actionable conflict prevention rules for future sessions.
- Review context-package.json conflict_detection section
- Analyze what files were modified together
- Identify dependencies that weren't initially obvious
- Format: "When doing X, check/verify Y"
## Output Format
Return ONLY a valid JSON object (no markdown, no explanations):
{
"successes": [
"Success pattern description @path/to/file.ext",
"Another success with file reference @another/file.ts"
],
"challenges": [
"Challenge or problem encountered",
"Another issue that required extra effort"
],
"watch_patterns": [
{
"pattern": "When modifying X component/model/service",
"action": "Check Y and Z for dependencies/impacts",
"related_files": ["path/to/file1.ts", "path/to/file2.ts"]
}
]
}
## Quality Guidelines
**Successes**:
- Be specific about what worked and why
- Include file paths for pattern reuse
- Focus on reusable architectural decisions
**Challenges**:
- Document what made the task difficult
- Include lessons about what to avoid
- Note any tooling or process gaps
**Watch Patterns**:
- Must be actionable and specific
- Include trigger condition (pattern)
- Specify what to check (action)
- List relevant files to review
- Minimum 1, maximum 5 patterns per session
**File References**:
- Use relative paths from project root
- Use @ prefix for inline references: "@src/models/User.ts"
- Array format for related_files: ["src/models/User.ts"]
## Analysis Depth
- Keep each item concise (1-2 sentences)
- Focus on high-impact insights
- Prioritize patterns that prevent future conflicts
- Aim for 2-4 successes, 1-3 challenges, 1-3 watch patterns