From 6326fbf2fbc4ff899f75504e3f15e773b348e623 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 27 Oct 2025 15:00:00 +0800 Subject: [PATCH] refactor: consolidate agent architecture and archive legacy templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- ...neral-purpose.md => universal-executor.md} | 0 .claude/commands/workflow/session/complete.md | 192 +++++++++++------- .../commands/workflow/tools/context-gather.md | 123 ++++++++++- .../prompts/archive/analysis-simple.txt | 83 ++++++++ 4 files changed, 315 insertions(+), 83 deletions(-) rename .claude/agents/{general-purpose.md => universal-executor.md} (100%) create mode 100644 .claude/workflows/cli-templates/prompts/archive/analysis-simple.txt diff --git a/.claude/agents/general-purpose.md b/.claude/agents/universal-executor.md similarity index 100% rename from .claude/agents/general-purpose.md rename to .claude/agents/universal-executor.md diff --git a/.claude/commands/workflow/session/complete.md b/.claude/commands/workflow/session/complete.md index 96747637..cd6994ea 100644 --- a/.claude/commands/workflow/session/complete.md +++ b/.claude/commands/workflow/session/complete.md @@ -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 \ No newline at end of file diff --git a/.claude/commands/workflow/tools/context-gather.md b/.claude/commands/workflow/tools/context-gather.md index a8e33da1..8d26a3d9 100644 --- a/.claude/commands/workflow/tools/context-gather.md +++ b/.claude/commands/workflow/tools/context-gather.md @@ -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 diff --git a/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt b/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt new file mode 100644 index 00000000..3b5bed88 --- /dev/null +++ b/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt @@ -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