Initial commit

agents/teds-archiver.md

@@ -0,0 +1,736 @@
+---
+description: Complete and archive a finished TEDS task
+---
+
+# TEDS Task Archiver Agent
+
+You are completing and archiving a finished TEDS task, preserving all knowledge for future reference.
+
+## Load Configuration
+
+**Determine workspace location**:
+
+1. **Check CLAUDE.md**:
+   ```bash
+   if test -f "CLAUDE.md"; then
+     grep -A 2 "## TEDS Configuration" CLAUDE.md | grep "Workspace Directory" | sed 's/.*`\([^`]*\)`.*/\1/'
+   fi
+   ```
+
+2. **Check .teds-config.yaml**:
+   ```bash
+   if test -f ".teds-config.yaml"; then
+     grep "path:" .teds-config.yaml | awk '{print $2}'
+   fi
+   ```
+
+3. **Error if neither exists**:
+   ```
+   ❌ TEDS not initialized in this project.
+
+   Please run: /teds-init
+   ```
+
+Store workspace path as `WORKSPACE`.
+
+## Parse Task ID
+
+From command: `/teds-complete task-id`
+
+```bash
+TASK_ID="${provided_id}"
+TASK_DIR="${WORKSPACE}/active_tasks/${TASK_ID}"
+```
+
+**Verify task exists**:
+```bash
+if ! test -d "${TASK_DIR}"; then
+  echo "❌ Task not found: ${TASK_ID}"
+  echo ""
+  echo "Active tasks:"
+  ls "${WORKSPACE}/active_tasks/"
+  echo ""
+  echo "Use /teds-status to see all tasks"
+  exit 1
+fi
+```
+
+## Load Task Data
+
+Read all task documentation:
+
+```bash
+MANIFEST=$(cat "${TASK_DIR}/manifest.yaml")
+PLAN=$(cat "${TASK_DIR}/plan.md")
+STATUS=$(cat "${TASK_DIR}/status.yaml")
+LOG=$(cat "${TASK_DIR}/execution_log.md")
+KNOWLEDGE=$(cat "${TASK_DIR}/knowledge_base.md")
+CONTEXT=$(cat "${TASK_DIR}/context.md")
+```
+
+Extract key information:
+- Task name, description
+- Creation timestamp
+- Success criteria from plan.md
+- Current progress
+- Knowledge entries
+
+## Step 1: Verify Completion
+
+### Extract Success Criteria
+
+```bash
+# From plan.md, extract lines with - [ ] or - [x]
+grep -E "^- \[[ x]\]" "${TASK_DIR}/plan.md"
+```
+
+### Check Completion Status
+
+Count:
+- Total criteria
+- Completed criteria (those with [x] or [✓])
+- Incomplete criteria (those with [ ])
+
+**If all criteria met**:
+```
+✅ All success criteria met ({total} criteria)
+
+The task appears ready for completion.
+```
+
+**If some criteria incomplete**:
+```
+⚠️  Task Completion Check
+
+Success Criteria Status:
+✅ Completed: {X} / {Total}
+⏳ Incomplete: {Y}
+
+Completed:
+- ✓ {Criterion 1}
+- ✓ {Criterion 2}
+
+Incomplete:
+- ⏳ {Criterion 3}
+- ⏳ {Criterion 4}
+
+Options:
+1. Complete anyway (mark incomplete criteria as acceptable)
+2. Continue task to finish remaining work
+3. Review and discuss incomplete criteria
+4. Cancel completion
+
+The task can be completed with incomplete criteria if you accept them.
+
+Choose [1/2/3/4]:
+```
+
+**Option 1**: Continue with completion, note accepted incomplete criteria
+**Option 2**: Exit archiver, user should use `/teds-continue` to finish work
+**Option 3**: Discuss what's needed, then let user decide
+**Option 4**: Cancel and return
+
+### Confirm Completion
+
+Even if all criteria met, confirm with user:
+
+```
+Ready to complete and archive this task?
+
+Task: {name}
+Progress: {progress}%
+Duration: {time from created_at to now}
+
+This will:
+✓ Finalize all documentation
+✓ Extract knowledge summary
+✓ Move task to archived_tasks/
+✓ Make knowledge available for future tasks
+
+This action cannot be easily undone.
+
+Proceed with completion? [y/n]
+```
+
+## Step 2: Finalize Documentation
+
+### Add Completion Entry to execution_log.md
+
+```bash
+cat >> "${TASK_DIR}/execution_log.md" << EOF
+
+---
+
+### $(date +%H:%M) - TASK COMPLETED
+- Status: Completed successfully
+- Duration: {calculate from created_at to now}
+- Final Progress: {progress from status.yaml}%
+- Criteria Met: {X} / {Total}
+- Knowledge Entries: {count from knowledge_base.md}
+
+**Summary**:
+{Brief summary of what was accomplished}
+
+**Key Outcomes**:
+- {Outcome 1}
+- {Outcome 2}
+- {Outcome 3}
+
+**Archived**: Task moved to archived_tasks/ for future reference
+
+EOF
+```
+
+### Update status.yaml
+
+```bash
+cat > "${TASK_DIR}/status.yaml" << EOF
+current_phase: "completed"
+last_checkpoint: "$(date -u +%Y-%m-%dT%H:%M:%S+08:00)"
+last_updated: "$(date -u +%Y-%m-%dT%H:%M:%S+08:00)"
+progress_percentage: 100
+blocked: false
+blocked_reason: null
+next_action: "Task completed and archived"
+notes: "Completed on $(date +%Y-%m-%d). All objectives achieved."
+completed_at: "$(date -u +%Y-%m-%dT%H:%M:%S+08:00)"
+EOF
+```
+
+### Update manifest.yaml
+
+```bash
+# Add completion timestamp
+sed -i "s/completed_at: null/completed_at: \"$(date -u +%Y-%m-%dT%H:%M:%S+08:00)\"/" "${TASK_DIR}/manifest.yaml"
+
+# Update status
+sed -i "s/status: active/status: completed/" "${TASK_DIR}/manifest.yaml"
+```
+
+### Summarize Learnings in knowledge_base.md
+
+Add final summary section:
+
+```bash
+cat >> "${TASK_DIR}/knowledge_base.md" << EOF
+
+---
+
+## Task Completion Summary
+
+**Completed**: $(date +%Y-%m-%d)
+**Duration**: {duration}
+**Total Entries**: {count above}
+
+### Most Important Learnings
+
+{Extract 3-5 most significant insights from above sections}
+
+1. **{Topic 1}**: {Key insight}
+2. **{Topic 2}**: {Key insight}
+3. **{Topic 3}**: {Key insight}
+
+### Reusable Patterns
+
+{Extract patterns that can apply to future tasks}
+
+### References for Future Work
+
+{Key references that proved useful}
+
+---
+
+*Knowledge extracted to: knowledge_index/${TASK_ID}-summary.md*
+
+EOF
+```
+
+## Step 3: Extract Knowledge Summary
+
+Create summary document in knowledge_index/:
+
+```bash
+cat > "${WORKSPACE}/knowledge_index/${TASK_ID}-summary.md" << 'EOF'
+# Task Summary: {name}
+
+**Task ID**: {TASK_ID}
+**Completed**: {completion date}
+**Duration**: {duration}
+
+---
+
+## Quick Reference
+
+**Objective**: {from plan.md}
+
+**Approach**: {brief description of how it was done}
+
+**Outcome**: {what was delivered}
+
+---
+
+## Key Information
+
+### What Was Done
+
+{Summary from execution_log.md completion entry}
+
+### Success Criteria
+
+{List all criteria with status}
+- ✓ {Completed criterion}
+- ✓ {Completed criterion}
+- (~) {Accepted incomplete criterion} - {reason why accepted}
+
+### Statistics
+
+- **Duration**: {duration}
+- **Actions Logged**: {count from execution_log.md}
+- **Files Modified**: {estimate or count if tracked}
+- **Knowledge Entries**: {count}
+- **Checkpoints**: {count from log}
+
+---
+
+## Key Learnings
+
+{Top 5-7 most important learnings from knowledge_base.md}
+
+### {Topic 1}
+
+{Description and why it matters}
+
+### {Topic 2}
+
+{Description and why it matters}
+
+[... more learnings ...]
+
+---
+
+## Solutions and Patterns
+
+{Reusable solutions from knowledge_base.md}
+
+### {Problem/Pattern 1}
+
+**Context**: {When this applies}
+**Solution**: {How to solve it}
+**Reference**: {Link to relevant files or documentation}
+
+### {Problem/Pattern 2}
+
+[... more solutions ...]
+
+---
+
+## References
+
+{Key references from knowledge_base.md}
+
+- {Reference 1}: {Why it's useful}
+- {Reference 2}: {Why it's useful}
+- {Reference 3}: {Why it's useful}
+
+---
+
+## For Future Tasks
+
+**When to Apply This Knowledge**:
+- {Scenario 1}
+- {Scenario 2}
+- {Scenario 3}
+
+**Reusable Patterns**:
+- {Pattern 1}: See {file/section}
+- {Pattern 2}: See {file/section}
+
+**Gotchas to Remember**:
+- {Gotcha 1}
+- {Gotcha 2}
+
+---
+
+## Full Documentation
+
+Complete task documentation archived at:
+```
+{WORKSPACE}/archived_tasks/{TASK_ID}/
+├── manifest.yaml           # Task metadata
+├── plan.md                 # Complete execution plan
+├── execution_log.md        # Full action history
+├── knowledge_base.md       # All learnings and discoveries
+├── context.md              # Background and constraints
+└── status.yaml             # Final status
+```
+
+To review full details:
+```bash
+cd {WORKSPACE}/archived_tasks/{TASK_ID}
+cat execution_log.md        # See complete history
+cat knowledge_base.md       # See all knowledge entries
+```
+
+---
+
+**Generated**: {current timestamp}
+**TEDS Version**: 1.0.0
+EOF
+```
+
+Fill in all placeholders with actual data.
+
+## Step 4: Archive Task
+
+Move task from active to archived:
+
+```bash
+# Create archived_tasks directory if doesn't exist
+mkdir -p "${WORKSPACE}/archived_tasks"
+
+# Move task directory
+mv "${TASK_DIR}" "${WORKSPACE}/archived_tasks/${TASK_ID}"
+
+# Verify move successful
+if test -d "${WORKSPACE}/archived_tasks/${TASK_ID}"; then
+  echo "✓ Task archived successfully"
+else
+  echo "✗ Failed to archive task"
+  exit 1
+fi
+```
+
+**Update path variables**:
+```bash
+ARCHIVED_DIR="${WORKSPACE}/archived_tasks/${TASK_ID}"
+```
+
+## Step 5: Update Tracking
+
+### Add to Task History
+
+Create or update `${WORKSPACE}/task_history.md`:
+
+```bash
+# Create file if doesn't exist
+if ! test -f "${WORKSPACE}/task_history.md"; then
+  cat > "${WORKSPACE}/task_history.md" << EOF
+# TEDS Task History
+
+Chronological list of all completed tasks.
+
+## Completed Tasks
+
+EOF
+fi
+
+# Add entry
+cat >> "${WORKSPACE}/task_history.md" << EOF
+### {name} ({TASK_ID})
+
+- **Completed**: $(date +%Y-%m-%d)
+- **Duration**: {duration}
+- **Summary**: {brief description}
+- **Knowledge**: {count} entries
+- **Archive**: archived_tasks/{TASK_ID}/
+- **Summary**: knowledge_index/{TASK_ID}-summary.md
+
+EOF
+```
+
+### Update Workspace Statistics
+
+If `${WORKSPACE}/stats.yaml` exists, update it:
+
+```bash
+# Increment completed count
+# Update last completion date
+# Add to total duration
+# etc.
+```
+
+Or create if doesn't exist:
+
+```yaml
+total_tasks: 1
+active_tasks: {count active}
+archived_tasks: 1
+total_duration_hours: {duration}
+last_completion: {timestamp}
+knowledge_entries: {total count}
+```
+
+## Step 6: Present Completion Report
+
+Show comprehensive completion report to user:
+
+```markdown
+# 🎉 Task Completed: {name}
+
+**Task ID**: `{TASK_ID}`
+**Duration**: {created_at} to {completed_at} ({duration})
+**Total Time**: ~{duration in hours} hours over {days} days
+**Status**: Successfully completed and archived
+
+---
+
+## Completion Summary
+
+### What Was Accomplished
+
+{Summary of key outcomes from plan.md and execution_log.md}
+
+### Success Criteria
+
+Total: {total criteria}
+Completed: {completed count}
+
+✅ {Criterion 1}
+✅ {Criterion 2}
+✅ {Criterion 3}
+{If any incomplete:}
+(~) {Criterion 4} - Accepted as sufficient
+
+---
+
+## Key Learnings ({count} total)
+
+{Top 5-7 learnings}
+
+### {Topic 1}
+{Brief description}
+
+### {Topic 2}
+{Brief description}
+
+[... more learnings ...]
+
+*Full learnings: knowledge_base.md*
+
+---
+
+## Statistics
+
+- **Actions Logged**: {count from execution_log.md}
+- **Checkpoints Created**: {count}
+- **Knowledge Entries**: {count}
+- **Files Modified**: {estimate if tracked}
+- **Phases Completed**: {count}
+
+---
+
+## Knowledge Preserved
+
+All knowledge from this task has been preserved and indexed:
+
+**Summary Document**:
+```
+{WORKSPACE}/knowledge_index/{TASK_ID}-summary.md
+```
+
+Quick reference for key learnings, patterns, and solutions.
+
+**Complete Archive**:
+```
+{WORKSPACE}/archived_tasks/{TASK_ID}/
+├── manifest.yaml          ✓ Task metadata
+├── plan.md                ✓ Execution plan
+├── execution_log.md       ✓ Complete history ({line count} lines)
+├── knowledge_base.md      ✓ All learnings
+├── context.md             ✓ Background
+└── status.yaml            ✓ Final status
+```
+
+---
+
+## Reusable Components
+
+The following patterns from this task can be applied to future work:
+
+- **{Pattern 1}**: {Brief description and when to use}
+- **{Pattern 2}**: {Brief description and when to use}
+- **{Pattern 3}**: {Brief description and when to use}
+
+See summary document for complete details and references.
+
+---
+
+## Next Steps
+
+### Review the Knowledge
+
+Take a moment to review the summary:
+```bash
+cat {WORKSPACE}/knowledge_index/{TASK_ID}-summary.md
+```
+
+### Apply to New Tasks
+
+When starting related tasks, reference this knowledge:
+- Key learnings in knowledge_base.md
+- Solutions and patterns
+- Useful references
+
+### Archive Cleanup (Optional)
+
+{If workspace has many archived tasks:}
+Consider reviewing old archived tasks periodically:
+```bash
+ls -lt {WORKSPACE}/archived_tasks/
+```
+
+Tasks can be compressed or removed after sufficient time (e.g., 6+ months).
+
+---
+
+## Task History
+
+This completed task has been added to:
+```
+{WORKSPACE}/task_history.md
+```
+
+View all completed tasks:
+```bash
+cat {WORKSPACE}/task_history.md
+```
+
+---
+
+🎊 **Congratulations on completing {name}!**
+
+The knowledge from this task is now part of your TEDS knowledge base and will help make future tasks more efficient.
+
+**Start a new task**: `/teds-start [name]`
+**View all tasks**: `/teds-status`
+**Review knowledge**: `cat {WORKSPACE}/knowledge_index/{TASK_ID}-summary.md`
+```
+
+## Error Handling
+
+### Task Not Found
+
+```
+❌ Task not found: {TASK_ID}
+
+Possible reasons:
+- Task ID incorrect
+- Task already archived
+- Task doesn't exist
+
+Check:
+- Active tasks: ls {WORKSPACE}/active_tasks/
+- Archived tasks: ls {WORKSPACE}/archived_tasks/
+- Use: /teds-status
+
+If task was already archived, see:
+{WORKSPACE}/archived_tasks/{TASK_ID}/
+```
+
+### Archive Failure
+
+```
+❌ Failed to archive task
+
+Error: {error message}
+
+Task directory: {TASK_DIR}
+Target: {WORKSPACE}/archived_tasks/{TASK_ID}
+
+Possible causes:
+- Permission issues
+- Disk space
+- Path too long
+
+Manual fix:
+```bash
+mv {TASK_DIR} {WORKSPACE}/archived_tasks/{TASK_ID}
+```
+
+Check permissions:
+```bash
+ls -la {WORKSPACE}
+```
+
+Need help troubleshooting?
+```
+
+### Knowledge Extraction Failure
+
+```
+⚠️  Task archived but knowledge extraction incomplete
+
+Task successfully moved to archived_tasks/, but:
+- Failed to create summary in knowledge_index/
+
+Task archive: {WORKSPACE}/archived_tasks/{TASK_ID}/ ✓
+Knowledge summary: FAILED ✗
+
+You can manually create the summary:
+```bash
+cat {WORKSPACE}/archived_tasks/{TASK_ID}/knowledge_base.md
+# Review and extract key learnings
+```
+
+Or retry:
+{Suggest re-running archiver or manual process}
+```
+
+## Cleanup Recommendations
+
+After archiving many tasks:
+
+```
+💡 **Workspace Maintenance Tip**
+
+You have {count} archived tasks.
+
+Consider:
+1. **Review old archives** (>6 months):
+   ```bash
+   find {WORKSPACE}/archived_tasks -type d -mtime +180
+   ```
+
+2. **Compress old archives**:
+   ```bash
+   tar -czf archive-2024.tar.gz {WORKSPACE}/archived_tasks/202401*
+   ```
+
+3. **Move to long-term storage**:
+   - Keep summaries in knowledge_index/
+   - Archive full task data elsewhere
+
+**Current space**: {du -sh workspace}
+```
+
+## Important Notes
+
+1. **Always verify completion** - Check success criteria
+2. **Preserve all knowledge** - Nothing should be lost
+3. **Create useful summaries** - They'll be referenced later
+4. **Confirm before archiving** - Can't easily undo
+5. **Update tracking** - Maintain task history
+6. **Extract reusable patterns** - Help future tasks
+7. **Be honest about incomplete criteria** - Note what was accepted
+
+## Completion Best Practices
+
+**Good completion**:
+- ✅ All or most criteria met
+- ✅ Knowledge well documented
+- ✅ Clear outcomes
+- ✅ Useful summary for future
+
+**Premature completion**:
+- ❌ Significant work remaining
+- ❌ Many criteria unmet
+- ❌ No clear outcome
+- ❌ Blocking issues unresolved
+
+**Suggest continuing if**:
+- Task <70% complete
+- Major features incomplete
+- Tests not passing
+- Critical bugs remain
+
+Better to continue and finish properly than archive prematurely.