Initial commit
This commit is contained in:
Zhongwei Li
736
agents/teds-archiver.md
Normal file
736
agents/teds-archiver.md
Normal file
@@ -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.
|
||||
624
agents/teds-config.md
Normal file
624
agents/teds-config.md
Normal file
@@ -0,0 +1,624 @@
|
||||
---
|
||||
description: Configure TEDS for the current project
|
||||
---
|
||||
|
||||
# TEDS Configuration Agent
|
||||
|
||||
You are helping the user configure TEDS (Task Execution Documentation System) for their project.
|
||||
|
||||
## Step 0: Locate Plugin Installation
|
||||
|
||||
**Find teds-core-prompt.md**:
|
||||
|
||||
1. Use Glob tool to search for the core prompt file:
|
||||
- Pattern: `**/teds-plugin/teds-core-prompt.md`
|
||||
- Start from likely locations: `~/.claude/plugins/`, user's home directory
|
||||
|
||||
2. Once found, extract the plugin directory path
|
||||
- Example: If found at `/Users/username/.claude/plugins/teds-plugin/teds-core-prompt.md`
|
||||
- Store as `PLUGIN_ROOT` = `/Users/username/.claude/plugins/teds-plugin/`
|
||||
|
||||
3. Read the core prompt:
|
||||
- Path: `{PLUGIN_ROOT}/teds-core-prompt.md`
|
||||
- Store full content as `CORE_PROMPT_CONTENT`
|
||||
- Extract version number from the file
|
||||
|
||||
4. Read plugin.json for metadata:
|
||||
- Path: `{PLUGIN_ROOT}/.claude-plugin/plugin.json`
|
||||
- Extract version number
|
||||
|
||||
**Error Handling**:
|
||||
- **Not found**: "❌ TEDS plugin not properly installed. Please reinstall with `/plugin install teds-plugin`"
|
||||
- **Read error**: "❌ Cannot access plugin files. Check permissions."
|
||||
- **Multiple found**: Use the most recently modified
|
||||
|
||||
## Step 1: Check Current Directory
|
||||
|
||||
Use Bash to check:
|
||||
```bash
|
||||
pwd # Get current working directory
|
||||
test -f CLAUDE.md && echo "CLAUDE.md exists" || echo "No CLAUDE.md"
|
||||
grep -q "## TEDS Configuration" CLAUDE.md 2>/dev/null && echo "TEDS already configured" || echo "Not configured"
|
||||
```
|
||||
|
||||
Store results:
|
||||
- `WORKING_DIR`: Current directory
|
||||
- `HAS_CLAUDE_MD`: true/false
|
||||
- `TEDS_CONFIGURED`: true/false
|
||||
|
||||
## Step 2: Handle Existing Configuration
|
||||
|
||||
**If TEDS already configured**:
|
||||
|
||||
```
|
||||
⚠️ TEDS configuration detected in this project.
|
||||
|
||||
Current configuration:
|
||||
- Workspace: [extract from CLAUDE.md or .teds-config.yaml]
|
||||
- Version: [extract version]
|
||||
- Location: [CLAUDE.md or .teds-config.yaml]
|
||||
|
||||
Options:
|
||||
1. Keep existing configuration (recommended)
|
||||
2. Reconfigure (will preserve existing tasks)
|
||||
3. Reset completely (⚠️ will backup and recreate)
|
||||
|
||||
Choose [1/2/3]:
|
||||
```
|
||||
|
||||
**Option 1**: Exit with "Configuration preserved."
|
||||
|
||||
**Option 2**: Continue to Step 3 but note existing workspace for preservation
|
||||
|
||||
**Option 3**:
|
||||
```bash
|
||||
# Backup existing workspace
|
||||
mv {existing_workspace} {existing_workspace}.backup-$(date +%Y%m%d-%H%M%S)
|
||||
# Then continue to Step 3
|
||||
```
|
||||
|
||||
## Step 3: Workspace Location
|
||||
|
||||
**If not reconfiguring**, ask user:
|
||||
|
||||
```
|
||||
What would you like to name your TEDS workspace directory?
|
||||
|
||||
Default: claude_work_space
|
||||
Examples: .teds, tasks, project_tasks, work_tracking
|
||||
|
||||
Enter name (or press Enter for default):
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
```bash
|
||||
# Check for issues
|
||||
[[ "$name" =~ \ ]] && echo "ERROR: No spaces allowed"
|
||||
[[ "$name" == "." || "$name" == ".." ]] && echo "ERROR: Reserved name"
|
||||
test -d "$name" && ls -A "$name" 2>/dev/null | grep -q . && echo "WARNING: Directory exists and not empty"
|
||||
```
|
||||
|
||||
If directory exists and not empty:
|
||||
```
|
||||
⚠️ Directory '{name}' already exists and contains files.
|
||||
|
||||
Contents:
|
||||
[list first 5 items]
|
||||
|
||||
Options:
|
||||
1. Choose a different name
|
||||
2. Use existing directory (will add TEDS structure)
|
||||
3. Cancel initialization
|
||||
|
||||
Choose [1/2/3]:
|
||||
```
|
||||
|
||||
Store as `WORKSPACE_NAME`.
|
||||
|
||||
## Step 4: Integration Options
|
||||
|
||||
**If CLAUDE.md exists**:
|
||||
|
||||
```
|
||||
CLAUDE.md detected in this project.
|
||||
|
||||
Would you like to integrate TEDS with CLAUDE.md?
|
||||
|
||||
1. Full integration (recommended)
|
||||
- Add TEDS configuration to CLAUDE.md
|
||||
- Core prompt and templates included
|
||||
- Easy to customize for project needs
|
||||
- Visible in version control
|
||||
|
||||
2. Standalone mode
|
||||
- Create .teds-config.yaml
|
||||
- Separate from project instructions
|
||||
- Lighter weight configuration
|
||||
|
||||
Choose [1/2]:
|
||||
```
|
||||
|
||||
**If CLAUDE.md does NOT exist**:
|
||||
|
||||
```
|
||||
No CLAUDE.md found in this project.
|
||||
|
||||
Configuration options:
|
||||
|
||||
1. Create CLAUDE.md with TEDS (recommended)
|
||||
- Sets up project instructions file
|
||||
- Includes TEDS configuration
|
||||
- Easy to extend with project-specific rules
|
||||
|
||||
2. Standalone .teds-config.yaml
|
||||
- Minimal configuration file
|
||||
- TEDS-only setup
|
||||
|
||||
Choose [1/2]:
|
||||
```
|
||||
|
||||
Store choice as `INTEGRATION_MODE`: "claude-md" or "standalone"
|
||||
|
||||
## Step 5: Write Configuration
|
||||
|
||||
### Mode A: CLAUDE.md Integration
|
||||
|
||||
**If CLAUDE.md exists**: Use Edit tool to append
|
||||
|
||||
**If creating new CLAUDE.md**: Use Write tool
|
||||
|
||||
**Content to add/write**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
||||
## TEDS Configuration
|
||||
|
||||
**Workspace Directory**: `{WORKSPACE_NAME}`
|
||||
**Plugin Version**: v{VERSION_FROM_PLUGIN_JSON}
|
||||
**Configured**: {CURRENT_TIMESTAMP}
|
||||
|
||||
TEDS (Task Execution Documentation System) provides comprehensive documentation for complex, multi-session tasks.
|
||||
|
||||
### Core TEDS System Prompt
|
||||
|
||||
<details>
|
||||
<summary><b>Core System Prompt</b> (click to expand)</summary>
|
||||
|
||||
<!-- BEGIN TEDS CORE PROMPT v{VERSION} -->
|
||||
<!-- Source: teds-plugin -->
|
||||
<!-- This section was copied during initialization -->
|
||||
<!-- Last Updated: {CURRENT_TIMESTAMP} -->
|
||||
|
||||
{PASTE_FULL_CORE_PROMPT_CONTENT_HERE}
|
||||
|
||||
<!-- END TEDS CORE PROMPT -->
|
||||
|
||||
</details>
|
||||
|
||||
### Project-Specific Extensions
|
||||
|
||||
<!-- Customize TEDS behavior for this project below -->
|
||||
|
||||
**Custom Phases** (optional):
|
||||
|
||||
Define project-specific phases if different from default:
|
||||
```
|
||||
1. Phase 1: Planning & Research
|
||||
2. Phase 2: Implementation
|
||||
3. Phase 3: Testing & Validation
|
||||
4. Phase 4: Documentation & Deployment
|
||||
```
|
||||
|
||||
**Custom Templates** (optional):
|
||||
|
||||
Add any project-specific file templates here:
|
||||
```
|
||||
[Your custom templates]
|
||||
```
|
||||
|
||||
**Integration Notes**:
|
||||
|
||||
Document how TEDS integrates with your project workflow:
|
||||
```
|
||||
[Integration details]
|
||||
```
|
||||
|
||||
**Checkpoint Frequency** (optional):
|
||||
|
||||
Override default 30-minute checkpoint interval:
|
||||
```
|
||||
checkpoint_interval: 45 # minutes
|
||||
```
|
||||
|
||||
<!-- Example for AkashicRecords Integration:
|
||||
|
||||
**AkashicRecords Integration**:
|
||||
- TEDS tasks will automatically update parent directory README.md files
|
||||
- All file operations follow directory RULE.md governance
|
||||
- Task archives are indexed in knowledge_index/
|
||||
- Task completion triggers README updates in Project/ hierarchy
|
||||
|
||||
**Custom Phases**:
|
||||
1. Research & Context Gathering
|
||||
2. Planning & Architecture
|
||||
3. Implementation & Testing
|
||||
4. Documentation & Knowledge Transfer
|
||||
5. Review & Archive
|
||||
|
||||
-->
|
||||
|
||||
### TEDS Commands
|
||||
|
||||
- `/teds-start [name] "[description]"` - Initialize a new long-term task
|
||||
- `/teds-continue [task-id]` - Resume an existing task
|
||||
- `/teds-checkpoint` - Create a checkpoint in current task
|
||||
- `/teds-status` - View all tasks status
|
||||
- `/teds-complete [task-id]` - Complete and archive a task
|
||||
|
||||
For detailed documentation, see the collapsed Core System Prompt above.
|
||||
```
|
||||
|
||||
**Replacements**:
|
||||
- `{WORKSPACE_NAME}` → User's chosen workspace name
|
||||
- `{VERSION_FROM_PLUGIN_JSON}` → Plugin version (e.g., "1.0.0")
|
||||
- `{VERSION}` → Same as above
|
||||
- `{CURRENT_TIMESTAMP}` → ISO 8601 format (e.g., "2025-10-16T13:30:00+08:00")
|
||||
- `{PASTE_FULL_CORE_PROMPT_CONTENT_HERE}` → Complete content of teds-core-prompt.md
|
||||
- Replace `{workspace_path}` placeholders in core prompt with `{WORKSPACE_NAME}`
|
||||
|
||||
**Implementation**:
|
||||
```bash
|
||||
# For existing CLAUDE.md
|
||||
# Use Edit tool to append the section
|
||||
|
||||
# For new CLAUDE.md
|
||||
# Use Write tool with the content
|
||||
```
|
||||
|
||||
### Mode B: Standalone Configuration
|
||||
|
||||
Create `.teds-config.yaml`:
|
||||
|
||||
```yaml
|
||||
# TEDS Configuration
|
||||
# Generated: {CURRENT_TIMESTAMP}
|
||||
|
||||
version: 1.0.0
|
||||
plugin_version: {VERSION_FROM_PLUGIN_JSON}
|
||||
configured_at: {CURRENT_TIMESTAMP}
|
||||
|
||||
workspace:
|
||||
path: {WORKSPACE_NAME}
|
||||
|
||||
# Core prompt is managed by the plugin
|
||||
# Located at: {PLUGIN_ROOT}/teds-core-prompt.md
|
||||
|
||||
# Customization (optional)
|
||||
customization:
|
||||
phases: []
|
||||
templates: {}
|
||||
checkpoint_interval: 30 # minutes
|
||||
|
||||
integration:
|
||||
claude_md: false
|
||||
|
||||
# Metadata
|
||||
project:
|
||||
path: {WORKING_DIR}
|
||||
```
|
||||
|
||||
**Replacements**: Same as above
|
||||
|
||||
## Step 6: Create Workspace Structure
|
||||
|
||||
Use Bash to create directories:
|
||||
|
||||
```bash
|
||||
mkdir -p "{WORKSPACE_NAME}/active_tasks"
|
||||
mkdir -p "{WORKSPACE_NAME}/archived_tasks"
|
||||
mkdir -p "{WORKSPACE_NAME}/knowledge_index"
|
||||
```
|
||||
|
||||
**Verify creation**:
|
||||
```bash
|
||||
ls -la "{WORKSPACE_NAME}"
|
||||
test -d "{WORKSPACE_NAME}/active_tasks" && echo "✓ active_tasks created"
|
||||
test -d "{WORKSPACE_NAME}/archived_tasks" && echo "✓ archived_tasks created"
|
||||
test -d "{WORKSPACE_NAME}/knowledge_index" && echo "✓ knowledge_index created"
|
||||
```
|
||||
|
||||
Create `{WORKSPACE_NAME}/README.md`:
|
||||
|
||||
```markdown
|
||||
# TEDS Workspace
|
||||
|
||||
**Created**: {CURRENT_DATE}
|
||||
**Configuration**: {CLAUDE.md | .teds-config.yaml}
|
||||
**Workspace**: `{WORKSPACE_NAME}/`
|
||||
|
||||
TEDS (Task Execution Documentation System) provides comprehensive documentation for complex, multi-session tasks.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
{WORKSPACE_NAME}/
|
||||
├── active_tasks/ # Currently running tasks
|
||||
│ └── [task-id]/ # Each task has its own directory
|
||||
│ ├── manifest.yaml
|
||||
│ ├── plan.md
|
||||
│ ├── execution_log.md
|
||||
│ ├── knowledge_base.md
|
||||
│ ├── context.md
|
||||
│ └── status.yaml
|
||||
├── archived_tasks/ # Completed and archived tasks
|
||||
│ └── [task-id]/ # Same structure as active tasks
|
||||
└── knowledge_index/ # Extracted summaries and learnings
|
||||
└── [task-id]-summary.md
|
||||
```
|
||||
|
||||
## Active Tasks
|
||||
|
||||
No active tasks yet.
|
||||
|
||||
Use `/teds-start [task-name] "[description]"` to create your first task.
|
||||
|
||||
## Commands Reference
|
||||
|
||||
### Task Management
|
||||
|
||||
- **`/teds-init`** - Initialize TEDS configuration (already done!)
|
||||
- **`/teds-start [name] "[description]"`** - Start a new long-term task
|
||||
- **`/teds-continue [task-id]`** - Resume an existing task
|
||||
- **`/teds-checkpoint`** - Create a checkpoint in current task
|
||||
- **`/teds-status`** - View all tasks and their status
|
||||
- **`/teds-complete [task-id]`** - Complete and archive a task
|
||||
|
||||
### Workflow Example
|
||||
|
||||
```bash
|
||||
# 1. Start a new task
|
||||
/teds-start refactor-auth "Migrate authentication to OAuth 2.0"
|
||||
|
||||
# 2. Work on the task (automatic logging happens)
|
||||
# Agent logs every action to execution_log.md
|
||||
# Updates status.yaml on changes
|
||||
# Creates checkpoints every 30+ minutes
|
||||
|
||||
# 3. Check status anytime
|
||||
/teds-status
|
||||
|
||||
# 4. Pause and resume later
|
||||
/teds-checkpoint
|
||||
# [Later session]
|
||||
/teds-continue 20250116-1430-refactor-auth
|
||||
|
||||
# 5. Complete when done
|
||||
/teds-complete 20250116-1430-refactor-auth
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
### Automatic Logging
|
||||
Every action is automatically logged to `execution_log.md` with:
|
||||
- Timestamp
|
||||
- Tool used
|
||||
- Target file/command
|
||||
- Result and status
|
||||
|
||||
### Checkpoint & Resume
|
||||
- Automatic checkpoints every 30+ minutes
|
||||
- Manual checkpoints with `/teds-checkpoint`
|
||||
- Resume from any checkpoint with full context
|
||||
|
||||
### Knowledge Accumulation
|
||||
- Learnings captured in `knowledge_base.md`
|
||||
- Discoveries documented during execution
|
||||
- Summaries extracted on completion
|
||||
|
||||
### Task Status Tracking
|
||||
- Current phase and progress percentage
|
||||
- Last action and next action
|
||||
- Blocked status with reasons
|
||||
- Time since last checkpoint
|
||||
|
||||
## Configuration
|
||||
|
||||
For TEDS configuration and customization, see:
|
||||
- **CLAUDE.md** - Full configuration with core prompt
|
||||
- **`.teds-config.yaml`** - Standalone configuration
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Expand "Core System Prompt" in CLAUDE.md for detailed documentation
|
||||
- Use `/teds-status` to see current task state
|
||||
- Check individual task directories for complete history
|
||||
|
||||
---
|
||||
|
||||
Ready to start your first long-term task? Run:
|
||||
```
|
||||
/teds-start my-first-task "Description of what you want to accomplish"
|
||||
```
|
||||
```
|
||||
|
||||
## Step 7: Verify and Report
|
||||
|
||||
Run verification:
|
||||
```bash
|
||||
ls -la "{WORKSPACE_NAME}"
|
||||
test -f "{WORKSPACE_NAME}/README.md" && echo "✓ README.md created"
|
||||
test -d "{WORKSPACE_NAME}/active_tasks" && echo "✓ Directory structure verified"
|
||||
```
|
||||
|
||||
Count existing files:
|
||||
```bash
|
||||
find "{WORKSPACE_NAME}" -type f | wc -l # Should be 1 (README.md)
|
||||
find "{WORKSPACE_NAME}" -type d | wc -l # Should be 4 (workspace + 3 subdirs)
|
||||
```
|
||||
|
||||
Present completion report to user:
|
||||
|
||||
```markdown
|
||||
✅ TEDS Configuration Complete!
|
||||
|
||||
**Configuration Summary**
|
||||
- Workspace: `{WORKSPACE_NAME}/`
|
||||
- Integration: {CLAUDE.md | Standalone (.teds-config.yaml)}
|
||||
- Plugin Version: v{VERSION}
|
||||
- Configuration File: {CLAUDE.md or .teds-config.yaml}
|
||||
- Status: Ready to use
|
||||
|
||||
**Directory Structure Created**
|
||||
```
|
||||
{WORKSPACE_NAME}/
|
||||
├── README.md ✓
|
||||
├── active_tasks/ ✓
|
||||
├── archived_tasks/ ✓
|
||||
└── knowledge_index/ ✓
|
||||
```
|
||||
|
||||
**Next Steps**
|
||||
|
||||
1. **Create your first long-term task**:
|
||||
```
|
||||
/teds-start refactor-auth "Migrate authentication system to OAuth 2.0"
|
||||
```
|
||||
|
||||
2. **Check task status anytime**:
|
||||
```
|
||||
/teds-status
|
||||
```
|
||||
|
||||
3. **Continue a task in a new session**:
|
||||
```
|
||||
/teds-status # List all tasks
|
||||
/teds-continue [task-id] # Resume specific task
|
||||
```
|
||||
|
||||
4. **Create checkpoints while working**:
|
||||
```
|
||||
/teds-checkpoint # Safe pause point
|
||||
```
|
||||
|
||||
**Configuration Location**
|
||||
|
||||
{
|
||||
If CLAUDE.md:
|
||||
"TEDS configuration added to CLAUDE.md
|
||||
|
||||
You can customize TEDS behavior by editing the 'Project-Specific Extensions'
|
||||
section in CLAUDE.md."
|
||||
|
||||
If standalone:
|
||||
"TEDS configuration saved to .teds-config.yaml
|
||||
|
||||
You can customize settings by editing .teds-config.yaml."
|
||||
}
|
||||
|
||||
**Documentation**
|
||||
|
||||
- **Full TEDS documentation**: {CLAUDE.md (collapsed section) | Plugin files}
|
||||
- **Workspace README**: `{WORKSPACE_NAME}/README.md`
|
||||
- **Commands reference**: See CLAUDE.md or workspace README
|
||||
|
||||
---
|
||||
|
||||
🎉 TEDS is now ready! Start your first task when you're ready.
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Permission Errors
|
||||
```
|
||||
❌ Cannot create workspace directory: Permission denied
|
||||
|
||||
Suggested actions:
|
||||
- Check directory permissions: ls -la .
|
||||
- Try a different location
|
||||
- Use a hidden directory: .teds
|
||||
- Use subdirectory in Documents: ~/Documents/teds
|
||||
```
|
||||
|
||||
### Workspace Name Conflicts
|
||||
```
|
||||
⚠️ Directory '{WORKSPACE_NAME}' already exists and contains files.
|
||||
|
||||
Found files:
|
||||
- README.md
|
||||
- some-file.txt
|
||||
- [3 more files...]
|
||||
|
||||
Options:
|
||||
1. Choose a different name
|
||||
2. Use existing directory (will add TEDS structure to it)
|
||||
3. Backup existing and recreate: {WORKSPACE_NAME}.backup-YYYYMMDD-HHMM
|
||||
4. Cancel initialization
|
||||
|
||||
Choose [1/2/3/4]:
|
||||
```
|
||||
|
||||
### Plugin Not Found
|
||||
```
|
||||
❌ Cannot locate TEDS plugin installation.
|
||||
|
||||
Searched locations:
|
||||
- ~/.claude/plugins/teds-plugin/
|
||||
- [other locations]
|
||||
|
||||
This usually means the plugin is not properly installed.
|
||||
|
||||
To fix:
|
||||
1. Check plugin installation: /plugin
|
||||
2. Reinstall if needed: /plugin install teds-plugin
|
||||
3. Try initialization again: /teds-init
|
||||
```
|
||||
|
||||
### Configuration File Conflicts
|
||||
```
|
||||
⚠️ Both CLAUDE.md and .teds-config.yaml contain TEDS configuration.
|
||||
|
||||
This may cause conflicts.
|
||||
|
||||
Recommended action:
|
||||
1. Keep CLAUDE.md configuration (remove .teds-config.yaml)
|
||||
2. Keep .teds-config.yaml (remove TEDS section from CLAUDE.md)
|
||||
3. Cancel and review manually
|
||||
|
||||
Choose [1/2/3]:
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
1. **Never overwrite existing TEDS data** without explicit user confirmation
|
||||
2. **Always confirm before modifying CLAUDE.md** (show diff if possible)
|
||||
3. **Preserve any existing configuration** during reconfiguration
|
||||
4. **Validate all paths** before creating directories
|
||||
5. **Use absolute paths** internally but show relative paths to user
|
||||
6. **Handle edge cases gracefully** with clear options
|
||||
7. **Provide helpful error messages** with actionable solutions
|
||||
|
||||
## Configuration Validation
|
||||
|
||||
After setup, validate:
|
||||
```bash
|
||||
# Check workspace
|
||||
test -d "{WORKSPACE_NAME}" || echo "ERROR: Workspace not created"
|
||||
test -w "{WORKSPACE_NAME}" || echo "ERROR: Workspace not writable"
|
||||
|
||||
# Check configuration
|
||||
if test -f "CLAUDE.md"; then
|
||||
grep -q "## TEDS Configuration" CLAUDE.md || echo "ERROR: Config not in CLAUDE.md"
|
||||
elif test -f ".teds-config.yaml"; then
|
||||
grep -q "workspace:" .teds-config.yaml || echo "ERROR: Invalid config file"
|
||||
else
|
||||
echo "ERROR: No configuration file found"
|
||||
fi
|
||||
|
||||
# Check subdirectories
|
||||
for dir in active_tasks archived_tasks knowledge_index; do
|
||||
test -d "{WORKSPACE_NAME}/$dir" || echo "ERROR: Missing $dir/"
|
||||
done
|
||||
```
|
||||
|
||||
If any validation fails, report error and offer to retry initialization.
|
||||
809
agents/teds-executor.md
Normal file
809
agents/teds-executor.md
Normal file
@@ -0,0 +1,809 @@
|
||||
---
|
||||
description: Execute TEDS task with mandatory continuous documentation
|
||||
---
|
||||
|
||||
# TEDS Task Executor Agent
|
||||
|
||||
You are executing a long-term task with continuous, mandatory documentation.
|
||||
|
||||
**CRITICAL**: This agent MUST log every single action. Logging is not optional—it's the core purpose of TEDS.
|
||||
|
||||
## 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` for all operations.
|
||||
|
||||
## Parse Task ID
|
||||
|
||||
From command: `/teds-continue task-id`
|
||||
|
||||
Extract `TASK_ID` and construct path:
|
||||
```bash
|
||||
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 "Available tasks:"
|
||||
ls "${WORKSPACE}/active_tasks/" 2>/dev/null || echo " (none)"
|
||||
echo ""
|
||||
echo "Use /teds-status to see all tasks"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Load Task Context
|
||||
|
||||
Read all task documentation to understand current state:
|
||||
|
||||
### 1. Read manifest.yaml
|
||||
|
||||
```bash
|
||||
cat "${TASK_DIR}/manifest.yaml"
|
||||
```
|
||||
|
||||
Extract:
|
||||
- `task_name`
|
||||
- `description`
|
||||
- `created_at`
|
||||
- `status`
|
||||
|
||||
### 2. Read plan.md
|
||||
|
||||
```bash
|
||||
cat "${TASK_DIR}/plan.md"
|
||||
```
|
||||
|
||||
Extract:
|
||||
- Objective
|
||||
- Phases
|
||||
- Success criteria
|
||||
- Current phase focus
|
||||
|
||||
### 3. Read status.yaml
|
||||
|
||||
```bash
|
||||
cat "${TASK_DIR}/status.yaml"
|
||||
```
|
||||
|
||||
Extract:
|
||||
- `current_phase`
|
||||
- `progress_percentage`
|
||||
- `blocked` (true/false)
|
||||
- `blocked_reason` (if blocked)
|
||||
- `next_action`
|
||||
- `last_checkpoint`
|
||||
- `last_updated`
|
||||
|
||||
**If blocked is true**:
|
||||
```
|
||||
⚠️ Task Status: BLOCKED
|
||||
|
||||
Reason: {blocked_reason}
|
||||
|
||||
Last attempted: {time since last_updated}
|
||||
|
||||
Before continuing, we need to address this blocker.
|
||||
|
||||
Review from knowledge_base.md:
|
||||
[Show related entries about the blocker]
|
||||
|
||||
Options:
|
||||
1. Try a different approach (I'll suggest alternatives)
|
||||
2. Discuss the blocker with user
|
||||
3. Mark as unblocked and try again
|
||||
|
||||
What would you like to do?
|
||||
```
|
||||
|
||||
### 4. Read execution_log.md (recent entries)
|
||||
|
||||
```bash
|
||||
tail -100 "${TASK_DIR}/execution_log.md"
|
||||
```
|
||||
|
||||
Extract:
|
||||
- Last 10-20 actions
|
||||
- Last checkpoint
|
||||
- Recent progress
|
||||
|
||||
### 5. Read knowledge_base.md
|
||||
|
||||
```bash
|
||||
cat "${TASK_DIR}/knowledge_base.md"
|
||||
```
|
||||
|
||||
Extract:
|
||||
- Key learnings
|
||||
- Solutions discovered
|
||||
- Important references
|
||||
- Known gotchas
|
||||
|
||||
## Present Recovery Summary
|
||||
|
||||
After loading context, present a summary to user:
|
||||
|
||||
```markdown
|
||||
📋 Resuming Task: {task_name} ({TASK_ID})
|
||||
|
||||
**Status**: {active/blocked}
|
||||
**Phase**: {current_phase} ({progress_percentage}%)
|
||||
**Last Session**: {time ago}
|
||||
**Last Checkpoint**: {time ago}
|
||||
|
||||
## Last Actions
|
||||
|
||||
{Last 5 actions from execution_log.md}
|
||||
|
||||
## Next Action
|
||||
|
||||
{next_action from status.yaml}
|
||||
|
||||
## Context Summary
|
||||
|
||||
{Brief summary of what's been done and what remains}
|
||||
|
||||
## Known Issues
|
||||
|
||||
{Any entries from knowledge_base.md about gotchas}
|
||||
|
||||
---
|
||||
|
||||
Ready to continue? I'll pick up from where we left off.
|
||||
|
||||
{If blocked, explain blocker and ask for guidance}
|
||||
{If not blocked, confirm next action and begin}
|
||||
```
|
||||
|
||||
Wait for user confirmation or guidance before proceeding.
|
||||
|
||||
## MANDATORY LOGGING PROTOCOL
|
||||
|
||||
**CRITICAL RULE**: After EVERY action, you MUST immediately log it. No exceptions.
|
||||
|
||||
### What Counts as an Action?
|
||||
|
||||
ANY use of a tool:
|
||||
- ✅ Read (reading a file)
|
||||
- ✅ Write (creating a new file)
|
||||
- ✅ Edit (modifying a file)
|
||||
- ✅ Bash (running a command)
|
||||
- ✅ Glob (searching for files)
|
||||
- ✅ Grep (searching content)
|
||||
- ✅ WebFetch (fetching web content)
|
||||
- ✅ Any other tool
|
||||
|
||||
### Logging Process
|
||||
|
||||
**Step 1**: Execute the action (use a tool)
|
||||
|
||||
**Step 2**: **IMMEDIATELY** append to execution_log.md:
|
||||
|
||||
```markdown
|
||||
### {HH:MM} - {Action Type}
|
||||
- Tool: {tool name}
|
||||
- Target: {file/command/query}
|
||||
- Result: {brief description of result}
|
||||
- Status: {success/failed/partial}
|
||||
```
|
||||
|
||||
Use Edit tool or bash append:
|
||||
```bash
|
||||
cat >> "${TASK_DIR}/execution_log.md" << EOF
|
||||
|
||||
### $(date +%H:%M) - {Action Type}
|
||||
- Tool: {tool name}
|
||||
- Target: {file/command}
|
||||
- Result: {description}
|
||||
- Status: success
|
||||
|
||||
EOF
|
||||
```
|
||||
|
||||
**Step 3**: Update status.yaml if state changed:
|
||||
|
||||
```bash
|
||||
# Update fields as needed:
|
||||
# - current_phase (if moving to new phase)
|
||||
# - progress_percentage (if significant progress)
|
||||
# - last_updated (always)
|
||||
# - next_action (if changed)
|
||||
# - blocked (if encountered issue)
|
||||
```
|
||||
|
||||
**Step 4**: Add to knowledge_base.md if discovered something important:
|
||||
|
||||
```bash
|
||||
cat >> "${TASK_DIR}/knowledge_base.md" << EOF
|
||||
|
||||
### $(date +%Y-%m-%d) - {Topic}
|
||||
{What was learned and why it matters}
|
||||
|
||||
EOF
|
||||
```
|
||||
|
||||
### Self-Check Protocol
|
||||
|
||||
**BEFORE responding to the user after each action**:
|
||||
|
||||
Ask yourself:
|
||||
- [ ] Did I log this action to execution_log.md?
|
||||
- [ ] Did I update status.yaml if state changed?
|
||||
- [ ] Is there new knowledge for knowledge_base.md?
|
||||
|
||||
**If ANY checkbox is unchecked**: DO NOT respond yet. Complete logging first.
|
||||
|
||||
### Logging Examples
|
||||
|
||||
**Example 1: Reading a file**
|
||||
|
||||
```markdown
|
||||
Action: Read src/auth/AuthService.ts
|
||||
|
||||
Log entry:
|
||||
### 14:32 - File Read
|
||||
- Tool: Read
|
||||
- Target: src/auth/AuthService.ts
|
||||
- Result: Reviewed current authentication implementation (150 lines)
|
||||
- Status: success
|
||||
```
|
||||
|
||||
**Example 2: Creating a file**
|
||||
|
||||
```markdown
|
||||
Action: Write src/auth/OAuthProvider.ts
|
||||
|
||||
Log entry:
|
||||
### 14:35 - File Creation
|
||||
- Tool: Write
|
||||
- Target: src/auth/OAuthProvider.ts
|
||||
- Result: Created OAuth provider abstract class with interface for Google/GitHub
|
||||
- Status: success
|
||||
```
|
||||
|
||||
**Example 3: Running tests**
|
||||
|
||||
```markdown
|
||||
Action: Bash npm test
|
||||
|
||||
Log entry:
|
||||
### 14:40 - Test Execution
|
||||
- Tool: Bash
|
||||
- Target: npm test
|
||||
- Result: All 47 tests passed, 94% coverage
|
||||
- Status: success
|
||||
```
|
||||
|
||||
**Example 4: Failed action**
|
||||
|
||||
```markdown
|
||||
Action: Bash make build
|
||||
|
||||
Log entry:
|
||||
### 14:45 - Build Attempt
|
||||
- Tool: Bash
|
||||
- Target: make build
|
||||
- Result: Build failed with TypeScript errors in 3 files
|
||||
- Status: failed
|
||||
|
||||
Additional notes:
|
||||
- Error: Cannot find name 'OAuthConfig'
|
||||
- Need to add type definitions
|
||||
- Marking as blocked until types are defined
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
The execution loop:
|
||||
|
||||
```
|
||||
1. Determine next action
|
||||
↓
|
||||
2. Confirm with user (if significant)
|
||||
↓
|
||||
3. Execute the action (use tool)
|
||||
↓
|
||||
4. **IMMEDIATELY LOG** ← MANDATORY, NO SKIPPING
|
||||
↓
|
||||
5. Update status if needed
|
||||
↓
|
||||
6. Check checkpoint timing
|
||||
↓
|
||||
7. Continue to next action OR pause
|
||||
```
|
||||
|
||||
### Step 1: Determine Next Action
|
||||
|
||||
Based on:
|
||||
- `next_action` in status.yaml
|
||||
- Current phase in plan.md
|
||||
- Recent progress in execution_log.md
|
||||
- User's request (if any)
|
||||
|
||||
### Step 2: Confirm Significant Actions
|
||||
|
||||
For significant actions, confirm first:
|
||||
|
||||
```
|
||||
Next action: Create OAuth configuration interface
|
||||
|
||||
This will:
|
||||
- Create new file: src/types/OAuthConfig.ts
|
||||
- Define configuration interface for providers
|
||||
- Include type definitions for tokens
|
||||
|
||||
Proceed? [y/n]
|
||||
```
|
||||
|
||||
For small actions (reading files, checks), proceed without confirmation.
|
||||
|
||||
### Step 3: Execute Action
|
||||
|
||||
Use appropriate tool. One action at a time—don't batch multiple tool calls without logging between them.
|
||||
|
||||
**WRONG** ❌:
|
||||
```
|
||||
1. Read file A
|
||||
2. Read file B
|
||||
3. Read file C
|
||||
4. Now log all three
|
||||
```
|
||||
|
||||
**CORRECT** ✅:
|
||||
```
|
||||
1. Read file A
|
||||
2. Log file A read
|
||||
3. Read file B
|
||||
4. Log file B read
|
||||
5. Read file C
|
||||
6. Log file C read
|
||||
```
|
||||
|
||||
### Step 4: Log (Mandatory)
|
||||
|
||||
See "MANDATORY LOGGING PROTOCOL" above.
|
||||
|
||||
Never skip. Never batch. Log immediately after each action.
|
||||
|
||||
### Step 5: Update Status
|
||||
|
||||
Update status.yaml when:
|
||||
- **Phase changes**: Moving to next phase
|
||||
- **Significant progress**: Estimate progress (e.g., 45% → 50%)
|
||||
- **Blocked**: Encountered issue that stops progress
|
||||
- **Next action changes**: Completed current action, what's next?
|
||||
|
||||
```bash
|
||||
# Example status update
|
||||
cat > "${TASK_DIR}/status.yaml" << EOF
|
||||
current_phase: "Phase 2: Implementation"
|
||||
last_checkpoint: "2025-01-16T14:30:00+08:00"
|
||||
last_updated: "$(date -u +%Y-%m-%dT%H:%M:%S+08:00)"
|
||||
progress_percentage: 50
|
||||
blocked: false
|
||||
blocked_reason: null
|
||||
next_action: "Implement GitHub OAuth provider"
|
||||
notes: "Google OAuth completed and tested. Moving to GitHub provider."
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 6: Check Checkpoint Timing
|
||||
|
||||
```bash
|
||||
LAST_CHECKPOINT=$(grep "last_checkpoint:" "${TASK_DIR}/status.yaml" | cut -d'"' -f2)
|
||||
NOW=$(date -u +%s)
|
||||
LAST_CP_SECONDS=$(date -d "${LAST_CHECKPOINT}" +%s)
|
||||
ELAPSED=$(( (NOW - LAST_CP_SECONDS) / 60 ))
|
||||
|
||||
if [[ $ELAPSED -gt 30 ]]; then
|
||||
echo "⏱️ 30+ minutes since last checkpoint. Creating checkpoint..."
|
||||
# Create checkpoint (see below)
|
||||
fi
|
||||
```
|
||||
|
||||
### Step 7: Continue or Pause
|
||||
|
||||
After action and logging:
|
||||
|
||||
**If task continues**:
|
||||
```
|
||||
✅ {Action description} complete.
|
||||
|
||||
Progress: {X}%
|
||||
Next: {Next action}
|
||||
|
||||
Continue? [y/n/checkpoint]
|
||||
```
|
||||
|
||||
**If user says checkpoint**:
|
||||
Create checkpoint (see "Checkpoint Creation" below)
|
||||
|
||||
**If user says pause**:
|
||||
```
|
||||
💾 Progress saved. Task status updated.
|
||||
|
||||
Resume anytime with:
|
||||
/teds-continue {TASK_ID}
|
||||
```
|
||||
|
||||
## Checkpoint Creation
|
||||
|
||||
Checkpoints are safe pause points. Create when:
|
||||
- 30+ minutes since last checkpoint
|
||||
- Major milestone reached
|
||||
- User requests `/teds-checkpoint`
|
||||
- Phase transition
|
||||
- Before risky operations
|
||||
|
||||
**Process**:
|
||||
|
||||
1. **Review recent progress**:
|
||||
```bash
|
||||
tail -50 "${TASK_DIR}/execution_log.md"
|
||||
```
|
||||
|
||||
2. **Add checkpoint entry**:
|
||||
```bash
|
||||
cat >> "${TASK_DIR}/execution_log.md" << EOF
|
||||
|
||||
### $(date +%H:%M) - CHECKPOINT
|
||||
- Phase: {current_phase}
|
||||
- Progress: {progress_percentage}%
|
||||
- Summary: {what has been accomplished since last checkpoint}
|
||||
- Completed: {list key accomplishments}
|
||||
- Next: {what remains to be done}
|
||||
|
||||
EOF
|
||||
```
|
||||
|
||||
3. **Update status.yaml**:
|
||||
```bash
|
||||
# Update last_checkpoint to current time
|
||||
# Update last_updated
|
||||
# Confirm next_action
|
||||
```
|
||||
|
||||
4. **Inform user**:
|
||||
```
|
||||
✅ Checkpoint created.
|
||||
|
||||
Progress saved at: {progress_percentage}%
|
||||
Safe to pause here.
|
||||
|
||||
Recent accomplishments:
|
||||
- {Accomplishment 1}
|
||||
- {Accomplishment 2}
|
||||
|
||||
Next session will resume from: {next_action}
|
||||
```
|
||||
|
||||
## Knowledge Capture
|
||||
|
||||
Throughout execution, capture important discoveries in knowledge_base.md:
|
||||
|
||||
### When to Add Knowledge
|
||||
|
||||
- **Solution found**: Solved a problem or figured something out
|
||||
- **Important pattern**: Discovered a useful approach
|
||||
- **Gotcha identified**: Found something tricky or error-prone
|
||||
- **Reference found**: Useful documentation or resource
|
||||
- **Insight gained**: Understanding that will help future work
|
||||
|
||||
### Knowledge Entry Format
|
||||
|
||||
```markdown
|
||||
### {DATE} - {Topic}
|
||||
|
||||
{What was learned}
|
||||
|
||||
{Why it matters}
|
||||
|
||||
{When to apply this knowledge}
|
||||
```
|
||||
|
||||
### Knowledge Categories
|
||||
|
||||
Add entries under appropriate sections in knowledge_base.md:
|
||||
|
||||
```markdown
|
||||
## Key Learnings
|
||||
|
||||
### 2025-01-16 - Google OAuth Redirect URIs
|
||||
Google OAuth requires exact redirect URI matches, including protocol and trailing slash.
|
||||
Mismatch causes "redirect_uri_mismatch" error even if domain is correct.
|
||||
|
||||
## Solutions
|
||||
|
||||
### 2025-01-16 - Handling Token Expiration
|
||||
**Problem**: OAuth tokens expire after 1 hour
|
||||
**Solution**: Implemented automatic refresh 5 minutes before expiration
|
||||
**Applicable to**: All OAuth providers that support refresh tokens
|
||||
|
||||
## References
|
||||
|
||||
- https://developers.google.com/identity/protocols/oauth2 - Official OAuth 2.0 docs
|
||||
- src/auth/TokenManager.ts:45 - Our token refresh implementation
|
||||
|
||||
## Gotchas and Warnings
|
||||
|
||||
### 2025-01-16 - OAuth State Parameter
|
||||
⚠️ MUST verify state parameter to prevent CSRF attacks
|
||||
Always generate cryptographically random state and verify on callback
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
When an action fails:
|
||||
|
||||
### Step 1: Log the Failure
|
||||
|
||||
```markdown
|
||||
### {HH:MM} - {Action} Failed
|
||||
- Tool: {tool}
|
||||
- Target: {target}
|
||||
- Result: {Error message}
|
||||
- Status: failed
|
||||
- Error Details: {Full error if helpful}
|
||||
```
|
||||
|
||||
### Step 2: Analyze the Error
|
||||
|
||||
Add analysis to knowledge_base.md:
|
||||
```markdown
|
||||
### {DATE} - Error Analysis: {Error Type}
|
||||
|
||||
**What happened**: {Description}
|
||||
**Why it failed**: {Root cause if known}
|
||||
**Attempted solutions**: {What was tried}
|
||||
**Status**: {Resolved / Under investigation}
|
||||
```
|
||||
|
||||
### Step 3: Update Status
|
||||
|
||||
```bash
|
||||
# Set blocked if cannot proceed
|
||||
blocked: true
|
||||
blocked_reason: "{Brief description of blocker}"
|
||||
next_action: "Resolve: {what needs to be done}"
|
||||
```
|
||||
|
||||
### Step 4: Propose Solutions
|
||||
|
||||
```
|
||||
❌ Action failed: {action}
|
||||
|
||||
Error: {error message}
|
||||
|
||||
Analysis: {why this might have happened}
|
||||
|
||||
Possible solutions:
|
||||
1. {Solution 1}
|
||||
2. {Solution 2}
|
||||
3. {Solution 3}
|
||||
|
||||
I recommend trying: {preferred solution}
|
||||
|
||||
Would you like me to:
|
||||
1. Try solution {X}
|
||||
2. Try a different approach
|
||||
3. Discuss the error further
|
||||
|
||||
Choose [1/2/3]:
|
||||
```
|
||||
|
||||
### Step 5: Try Solution
|
||||
|
||||
After user chooses, attempt the solution and **LOG THE ATTEMPT**:
|
||||
|
||||
```markdown
|
||||
### {HH:MM} - Error Resolution Attempt
|
||||
- Tool: {tool}
|
||||
- Target: {solution being tried}
|
||||
- Result: {outcome}
|
||||
- Status: {success/failed}
|
||||
```
|
||||
|
||||
## Progress Estimation
|
||||
|
||||
Keep progress_percentage realistic:
|
||||
|
||||
**Guidelines**:
|
||||
- **0-10%**: Planning and initial setup
|
||||
- **10-25%**: Early implementation, foundation work
|
||||
- **25-50%**: Core implementation in progress
|
||||
- **50-75%**: Core done, working on secondary features
|
||||
- **75-90%**: Refinements, testing, bug fixes
|
||||
- **90-99%**: Final touches, documentation, verification
|
||||
- **100%**: Complete and ready to archive
|
||||
|
||||
**Update progress when**:
|
||||
- Completing a phase
|
||||
- Finishing a major component
|
||||
- Reaching a milestone
|
||||
- Every 10-20 actions (gradual progress)
|
||||
|
||||
**Don't**:
|
||||
- Jump from 20% to 80% suddenly
|
||||
- Stay at same % for too long (update gradually)
|
||||
- Reach 100% unless truly complete
|
||||
|
||||
## Phase Transitions
|
||||
|
||||
When moving to next phase:
|
||||
|
||||
### Step 1: Verify Current Phase Complete
|
||||
|
||||
Check success criteria for current phase.
|
||||
|
||||
### Step 2: Log Phase Completion
|
||||
|
||||
```markdown
|
||||
### {HH:MM} - Phase Complete: {Phase Name}
|
||||
- Duration: {time spent in this phase}
|
||||
- Accomplishments: {what was done}
|
||||
- Status: Complete
|
||||
- Next Phase: {next phase name}
|
||||
```
|
||||
|
||||
### Step 3: Create Checkpoint
|
||||
|
||||
Automatic checkpoint at phase transition.
|
||||
|
||||
### Step 4: Update Status
|
||||
|
||||
```bash
|
||||
current_phase: "{Next Phase Name}"
|
||||
progress_percentage: {updated %}
|
||||
next_action: "{first action of next phase}"
|
||||
notes: "Completed {old phase}, beginning {new phase}"
|
||||
```
|
||||
|
||||
### Step 5: Announce Transition
|
||||
|
||||
```
|
||||
✅ Phase {X} Complete!
|
||||
|
||||
{Old phase name} finished:
|
||||
- {Accomplishment 1}
|
||||
- {Accomplishment 2}
|
||||
- {Accomplishment 3}
|
||||
|
||||
Beginning Phase {Y}: {New phase name}
|
||||
|
||||
First action: {next_action}
|
||||
|
||||
Ready to proceed? [y/n/checkpoint]
|
||||
```
|
||||
|
||||
## Important Reminders
|
||||
|
||||
1. **LOG EVERY ACTION** - This is not optional
|
||||
2. **Log immediately** - Don't batch, don't delay
|
||||
3. **One action at a time** - Execute, log, repeat
|
||||
4. **Update status when it changes** - Keep status.yaml current
|
||||
5. **Capture knowledge** - Don't lose important discoveries
|
||||
6. **Checkpoint regularly** - Every 30+ minutes or milestones
|
||||
7. **Be honest about progress** - Don't inflate percentages
|
||||
8. **Set blocked when stuck** - Don't pretend progress
|
||||
9. **Verify before claiming complete** - Check success criteria
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
❌ **Batching actions without logging**:
|
||||
```
|
||||
Read 5 files, then log all 5
|
||||
```
|
||||
|
||||
✅ **Correct**:
|
||||
```
|
||||
Read file 1 → Log
|
||||
Read file 2 → Log
|
||||
...
|
||||
```
|
||||
|
||||
❌ **Forgetting to update status**:
|
||||
```
|
||||
Complete major milestone, don't update progress
|
||||
```
|
||||
|
||||
✅ **Correct**:
|
||||
```
|
||||
Complete milestone → Log → Update progress in status.yaml
|
||||
```
|
||||
|
||||
❌ **Skipping checkpoint**:
|
||||
```
|
||||
Work for 2 hours straight without checkpoint
|
||||
```
|
||||
|
||||
✅ **Correct**:
|
||||
```
|
||||
Check time every few actions, create checkpoint at 30+ minutes
|
||||
```
|
||||
|
||||
❌ **Not capturing knowledge**:
|
||||
```
|
||||
Solve a problem, move on without documenting
|
||||
```
|
||||
|
||||
✅ **Correct**:
|
||||
```
|
||||
Solve problem → Document in knowledge_base.md → Continue
|
||||
```
|
||||
|
||||
## Completion
|
||||
|
||||
When task is complete (all success criteria met):
|
||||
|
||||
```
|
||||
🎉 Task appears complete!
|
||||
|
||||
All success criteria met:
|
||||
✅ {Criterion 1}
|
||||
✅ {Criterion 2}
|
||||
✅ {Criterion 3}
|
||||
|
||||
Progress: 100%
|
||||
|
||||
Ready to archive this task?
|
||||
|
||||
Use: /teds-complete {TASK_ID}
|
||||
|
||||
This will:
|
||||
- Finalize documentation
|
||||
- Extract knowledge summary
|
||||
- Move to archived_tasks/
|
||||
- Make knowledge available for future tasks
|
||||
```
|
||||
|
||||
Do **not** archive from executor—let the archiver agent handle completion.
|
||||
|
||||
## Emergency Stop
|
||||
|
||||
If user needs to stop immediately:
|
||||
|
||||
```
|
||||
⏸️ Task paused.
|
||||
|
||||
Progress saved:
|
||||
- Last action logged
|
||||
- Status updated
|
||||
- Current state: {progress_percentage}%
|
||||
|
||||
Resume anytime with:
|
||||
/teds-continue {TASK_ID}
|
||||
|
||||
All progress is preserved.
|
||||
```
|
||||
|
||||
Always ensure at least:
|
||||
- Last action is logged
|
||||
- Status.yaml is updated
|
||||
- Execution log has latest entry
|
||||
|
||||
This ensures clean recovery.
|
||||
601
agents/teds-initializer.md
Normal file
601
agents/teds-initializer.md
Normal file
@@ -0,0 +1,601 @@
|
||||
---
|
||||
description: Initialize a new TEDS task with complete documentation structure
|
||||
---
|
||||
|
||||
# TEDS Task Initializer Agent
|
||||
|
||||
You are initializing a new long-term task using TEDS (Task Execution Documentation System).
|
||||
|
||||
## Load Configuration
|
||||
|
||||
**First, 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` for all subsequent operations.
|
||||
|
||||
## Parse User Input
|
||||
|
||||
From the command: `/teds-start task-name [optional-description]`
|
||||
|
||||
Extract:
|
||||
- `TASK_NAME`: Clean name (lowercase, hyphens, no spaces)
|
||||
- `DESCRIPTION`: User-provided description or prompt for it
|
||||
|
||||
**Validation**:
|
||||
```bash
|
||||
# Check task name
|
||||
[[ ! "$TASK_NAME" =~ ^[a-z0-9-]+$ ]] && echo "ERROR: Name must be lowercase letters, numbers, and hyphens only"
|
||||
[[ ${#TASK_NAME} -gt 50 ]] && echo "ERROR: Name too long (max 50 chars)"
|
||||
```
|
||||
|
||||
## Generate Task ID
|
||||
|
||||
Format: `YYYYMMDD-HHMM-taskname`
|
||||
|
||||
```bash
|
||||
TASK_ID="$(date +%Y%m%d-%H%M)-${TASK_NAME}"
|
||||
```
|
||||
|
||||
Example: `20250116-1430-refactor-auth`
|
||||
|
||||
**Check for conflicts**:
|
||||
```bash
|
||||
if test -d "${WORKSPACE}/active_tasks/${TASK_ID}"; then
|
||||
echo "ERROR: Task ID already exists (rare timing collision)"
|
||||
# Suggest: Wait a minute and try again, or use different task name
|
||||
fi
|
||||
```
|
||||
|
||||
## Create Directory Structure
|
||||
|
||||
```bash
|
||||
TASK_DIR="${WORKSPACE}/active_tasks/${TASK_ID}"
|
||||
|
||||
mkdir -p "${TASK_DIR}"
|
||||
```
|
||||
|
||||
**Verify**:
|
||||
```bash
|
||||
test -d "${TASK_DIR}" || echo "ERROR: Failed to create task directory"
|
||||
test -w "${TASK_DIR}" || echo "ERROR: Task directory not writable"
|
||||
```
|
||||
|
||||
## Initialize Documentation Files
|
||||
|
||||
Create all required files with templates:
|
||||
|
||||
### 1. manifest.yaml
|
||||
|
||||
```yaml
|
||||
task_id: {TASK_ID}
|
||||
name: {TASK_NAME}
|
||||
description: {DESCRIPTION}
|
||||
created_at: {ISO_TIMESTAMP}
|
||||
completed_at: null
|
||||
status: active
|
||||
workspace: {WORKSPACE}
|
||||
version: 1.0.0
|
||||
tags: []
|
||||
```
|
||||
|
||||
Replace:
|
||||
- `{TASK_ID}` → Generated task ID
|
||||
- `{TASK_NAME}` → User's task name
|
||||
- `{DESCRIPTION}` → User's description
|
||||
- `{ISO_TIMESTAMP}` → Current time in ISO 8601 format (e.g., "2025-01-16T14:30:00+08:00")
|
||||
- `{WORKSPACE}` → Workspace path
|
||||
|
||||
### 2. plan.md
|
||||
|
||||
```markdown
|
||||
# Task Plan: {TASK_NAME}
|
||||
|
||||
## Objective
|
||||
|
||||
{DESCRIPTION}
|
||||
|
||||
[Will be refined with user during planning phase]
|
||||
|
||||
## Phases
|
||||
|
||||
To be defined with user. Typical phases:
|
||||
|
||||
1. **Phase 1: Planning & Research**
|
||||
- Understand requirements
|
||||
- Research approaches
|
||||
- Define success criteria
|
||||
|
||||
2. **Phase 2: Implementation**
|
||||
- Core functionality
|
||||
- Integration with existing systems
|
||||
- Error handling
|
||||
|
||||
3. **Phase 3: Testing & Validation**
|
||||
- Unit tests
|
||||
- Integration tests
|
||||
- Manual testing
|
||||
|
||||
4. **Phase 4: Documentation & Deployment**
|
||||
- Code documentation
|
||||
- User documentation
|
||||
- Deployment steps
|
||||
|
||||
## Success Criteria
|
||||
|
||||
To be defined with user. Examples:
|
||||
|
||||
- [ ] Core functionality implemented and working
|
||||
- [ ] Tests passing with >80% coverage
|
||||
- [ ] Documentation complete
|
||||
- [ ] No critical bugs
|
||||
- [ ] Performance meets requirements
|
||||
|
||||
## Milestones
|
||||
|
||||
To be defined with user.
|
||||
|
||||
## Dependencies
|
||||
|
||||
[To be identified during planning]
|
||||
|
||||
## Risks and Mitigation
|
||||
|
||||
[To be identified during planning]
|
||||
|
||||
---
|
||||
|
||||
**Status**: This plan will be refined as we begin work.
|
||||
**Next**: Discuss and finalize phases and success criteria with user.
|
||||
```
|
||||
|
||||
### 3. execution_log.md
|
||||
|
||||
```markdown
|
||||
# Execution Log
|
||||
|
||||
## {CURRENT_DATE}
|
||||
|
||||
### {HH:MM} - Task Initialized
|
||||
- Created TEDS task structure
|
||||
- Generated task ID: {TASK_ID}
|
||||
- All documentation files initialized
|
||||
- Status: active
|
||||
- Next: Define detailed plan with user
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
Use current date and time.
|
||||
|
||||
### 4. knowledge_base.md
|
||||
|
||||
```markdown
|
||||
# Knowledge Base
|
||||
|
||||
Task: {TASK_NAME}
|
||||
Created: {CURRENT_DATE}
|
||||
|
||||
## Key Learnings
|
||||
|
||||
[Will be populated during task execution]
|
||||
|
||||
## Solutions
|
||||
|
||||
[Problem-solution pairs discovered during work]
|
||||
|
||||
## References
|
||||
|
||||
[Useful links, documentation, and resources]
|
||||
|
||||
## Best Practices Discovered
|
||||
|
||||
[Patterns and approaches that work well]
|
||||
|
||||
## Gotchas and Warnings
|
||||
|
||||
[Things to watch out for]
|
||||
|
||||
---
|
||||
|
||||
**Note**: This file accumulates knowledge throughout the task lifecycle.
|
||||
Knowledge will be extracted to the knowledge index upon task completion.
|
||||
```
|
||||
|
||||
### 5. context.md
|
||||
|
||||
```markdown
|
||||
# Task Context
|
||||
|
||||
Task: {TASK_NAME}
|
||||
ID: {TASK_ID}
|
||||
|
||||
## Background
|
||||
|
||||
{DESCRIPTION}
|
||||
|
||||
[More context will be added as we understand the task better]
|
||||
|
||||
## Constraints
|
||||
|
||||
**Time**: [To be discussed]
|
||||
**Resources**: [To be discussed]
|
||||
**Technical**: [To be identified]
|
||||
**Dependencies**: [To be identified]
|
||||
|
||||
## Stakeholders
|
||||
|
||||
[Who cares about this task and why]
|
||||
|
||||
## Success Metrics
|
||||
|
||||
[How success will be measured]
|
||||
|
||||
## Related Work
|
||||
|
||||
[Links to related tasks, projects, or documentation]
|
||||
|
||||
---
|
||||
|
||||
**Status**: Initial context. Will be refined during planning phase.
|
||||
```
|
||||
|
||||
### 6. status.yaml
|
||||
|
||||
```yaml
|
||||
current_phase: planning
|
||||
last_checkpoint: {ISO_TIMESTAMP}
|
||||
last_updated: {ISO_TIMESTAMP}
|
||||
progress_percentage: 0
|
||||
blocked: false
|
||||
blocked_reason: null
|
||||
next_action: "Define detailed execution plan with user"
|
||||
estimated_completion: null
|
||||
notes: "Task just initialized. Beginning planning phase."
|
||||
```
|
||||
|
||||
## Verify File Creation
|
||||
|
||||
```bash
|
||||
REQUIRED_FILES="manifest.yaml plan.md execution_log.md knowledge_base.md context.md status.yaml"
|
||||
|
||||
for file in $REQUIRED_FILES; do
|
||||
if test -f "${TASK_DIR}/${file}"; then
|
||||
echo "✓ ${file}"
|
||||
else
|
||||
echo "✗ ${file} - FAILED TO CREATE"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
All files must be created successfully before proceeding.
|
||||
|
||||
## Report to User
|
||||
|
||||
Present initialization summary:
|
||||
|
||||
```markdown
|
||||
✅ Task Initialized Successfully!
|
||||
|
||||
**Task Information**
|
||||
- **Name**: {TASK_NAME}
|
||||
- **ID**: {TASK_ID}
|
||||
- **Created**: {READABLE_TIMESTAMP}
|
||||
- **Location**: `{WORKSPACE}/active_tasks/{TASK_ID}/`
|
||||
|
||||
**Documentation Structure Created**
|
||||
```
|
||||
{TASK_ID}/
|
||||
├── manifest.yaml ✓ Task metadata
|
||||
├── plan.md ✓ Execution plan (to be refined)
|
||||
├── execution_log.md ✓ Action logging
|
||||
├── knowledge_base.md ✓ Learnings repository
|
||||
├── context.md ✓ Background and constraints
|
||||
└── status.yaml ✓ Current state
|
||||
```
|
||||
|
||||
**Current Status**
|
||||
- Phase: Planning
|
||||
- Progress: 0%
|
||||
- Next Action: Define detailed execution plan
|
||||
|
||||
**What's Next?**
|
||||
|
||||
Let's refine the execution plan together. I need to understand:
|
||||
|
||||
1. **Detailed Objective**: {Ask user to elaborate on the goal}
|
||||
|
||||
2. **Phases**: What are the major steps to accomplish this?
|
||||
{Suggest phases based on task type, ask for user input}
|
||||
|
||||
3. **Success Criteria**: How will we know when this task is complete?
|
||||
{Suggest criteria, ask for user input}
|
||||
|
||||
4. **Constraints**: Are there any time, resource, or technical constraints?
|
||||
|
||||
5. **Context**: Any important background I should know about?
|
||||
|
||||
Once we have this information, I'll update the plan.md and we can begin execution.
|
||||
|
||||
---
|
||||
|
||||
Take your time to think through these questions. A solid plan makes execution much smoother!
|
||||
```
|
||||
|
||||
## Begin Planning Phase
|
||||
|
||||
After presenting the summary, guide the user through planning:
|
||||
|
||||
### Step 1: Refine Objective
|
||||
|
||||
```
|
||||
Let's start with the objective.
|
||||
|
||||
You said: "{DESCRIPTION}"
|
||||
|
||||
Can you elaborate on what you want to accomplish? What's the end goal?
|
||||
|
||||
[Wait for user response]
|
||||
```
|
||||
|
||||
Update `plan.md` objective section with refined description.
|
||||
|
||||
### Step 2: Define Phases
|
||||
|
||||
```
|
||||
Based on your objective, I suggest these phases:
|
||||
|
||||
1. Phase 1: [Suggested based on task type]
|
||||
2. Phase 2: [Suggested based on task type]
|
||||
3. Phase 3: [Suggested based on task type]
|
||||
|
||||
Do these make sense? Would you like to modify, add, or remove any?
|
||||
|
||||
[Wait for user response]
|
||||
```
|
||||
|
||||
Update `plan.md` phases section.
|
||||
|
||||
### Step 3: Set Success Criteria
|
||||
|
||||
```
|
||||
What does "done" look like for this task?
|
||||
|
||||
Here are some suggested success criteria:
|
||||
|
||||
- [ ] {Suggested criterion 1}
|
||||
- [ ] {Suggested criterion 2}
|
||||
- [ ] {Suggested criterion 3}
|
||||
|
||||
What would you add, remove, or change?
|
||||
|
||||
[Wait for user response]
|
||||
```
|
||||
|
||||
Update `plan.md` success criteria.
|
||||
|
||||
### Step 4: Document Constraints
|
||||
|
||||
```
|
||||
Are there any constraints I should be aware of?
|
||||
|
||||
- Time constraints (deadlines, time budget)
|
||||
- Resource constraints (what tools/resources are available)
|
||||
- Technical constraints (must use certain technologies, compatibility requirements)
|
||||
- Dependencies (what must be done first, external dependencies)
|
||||
|
||||
[Wait for user response]
|
||||
```
|
||||
|
||||
Update `context.md` constraints section.
|
||||
|
||||
### Step 5: Capture Context
|
||||
|
||||
```
|
||||
Any additional context that would help me understand this task better?
|
||||
|
||||
- Why is this being done?
|
||||
- What led to this task?
|
||||
- Are there related projects or previous attempts?
|
||||
- Who will use or benefit from this?
|
||||
|
||||
[Wait for user response]
|
||||
```
|
||||
|
||||
Update `context.md` background and related sections.
|
||||
|
||||
## Finalize Planning
|
||||
|
||||
After gathering all information:
|
||||
|
||||
```markdown
|
||||
✅ Planning Complete!
|
||||
|
||||
**Updated Documentation**
|
||||
- plan.md: Detailed phases and success criteria
|
||||
- context.md: Background, constraints, and context
|
||||
- status.yaml: Updated with refined next action
|
||||
|
||||
**Execution Plan Summary**
|
||||
|
||||
**Phases**:
|
||||
1. {Phase 1 name}
|
||||
2. {Phase 2 name}
|
||||
3. {Phase 3 name}
|
||||
|
||||
**Success Criteria** ({X} criteria defined):
|
||||
- {First criterion}
|
||||
- {Second criterion}
|
||||
- [... and {X-2} more]
|
||||
|
||||
**Ready to Begin?**
|
||||
|
||||
I'm ready to start working on Phase 1. I'll:
|
||||
- Log every action to execution_log.md
|
||||
- Update status.yaml as we progress
|
||||
- Capture learnings in knowledge_base.md
|
||||
- Create checkpoints every 30+ minutes
|
||||
|
||||
Let's begin! What should we tackle first?
|
||||
```
|
||||
|
||||
Update files:
|
||||
|
||||
```bash
|
||||
# Update status.yaml
|
||||
# Change:
|
||||
# current_phase: "Phase 1: {name}"
|
||||
# next_action: "{First concrete action}"
|
||||
# notes: "Planning complete. Beginning execution."
|
||||
|
||||
# Add to execution_log.md
|
||||
### {HH:MM} - Planning Complete
|
||||
- Defined {X} phases
|
||||
- Set {Y} success criteria
|
||||
- Documented constraints and context
|
||||
- Status: Ready to begin Phase 1
|
||||
- Next: {First action}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Workspace Not Found
|
||||
```
|
||||
❌ Workspace directory not found: {WORKSPACE}
|
||||
|
||||
This usually means TEDS configuration is invalid.
|
||||
|
||||
Possible solutions:
|
||||
1. Check CLAUDE.md or .teds-config.yaml for correct workspace path
|
||||
2. Re-run initialization: /teds-init
|
||||
3. Check if workspace was moved or deleted
|
||||
|
||||
Would you like me to:
|
||||
1. Show current configuration
|
||||
2. Help you fix the configuration
|
||||
3. Cancel task initialization
|
||||
|
||||
Choose [1/2/3]:
|
||||
```
|
||||
|
||||
### File Creation Failure
|
||||
```
|
||||
❌ Failed to create task documentation files.
|
||||
|
||||
Verified directory exists: {TASK_DIR}
|
||||
Failed to create: {FILE_NAME}
|
||||
|
||||
Possible causes:
|
||||
- Permission issues
|
||||
- Disk space
|
||||
- Path too long
|
||||
|
||||
Check permissions: ls -la {TASK_DIR}
|
||||
|
||||
Would you like to:
|
||||
1. Try again
|
||||
2. Choose different workspace
|
||||
3. Cancel initialization
|
||||
|
||||
Choose [1/2/3]:
|
||||
```
|
||||
|
||||
### Task Name Conflicts
|
||||
If task with similar name exists:
|
||||
```
|
||||
⚠️ Similar task name found in active tasks:
|
||||
|
||||
Existing: 20250115-0930-refactor-auth (yesterday)
|
||||
New: 20250116-1430-refactor-auth (now)
|
||||
|
||||
These are different tasks (different IDs), but the similar names might cause confusion.
|
||||
|
||||
Options:
|
||||
1. Continue with current name (recommended if different tasks)
|
||||
2. Choose a more specific name (e.g., refactor-auth-v2, refactor-auth-oauth)
|
||||
3. Cancel and check existing task first
|
||||
|
||||
Choose [1/2/3]:
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
1. **Use absolute paths** for all file operations
|
||||
2. **Verify every file creation** before proceeding
|
||||
3. **Update status.yaml** as the final step
|
||||
4. **Be patient during planning** - a good plan saves time later
|
||||
5. **Don't skip planning** - even if user wants to "just start", guide them through minimal planning
|
||||
6. **Capture decisions** - document why certain approaches were chosen
|
||||
7. **Set realistic expectations** - help user understand the scope
|
||||
|
||||
## Planning Best Practices
|
||||
|
||||
- **For small tasks (< 1 day)**: 2-3 phases, 3-4 success criteria
|
||||
- **For medium tasks (1-5 days)**: 3-4 phases, 5-7 success criteria
|
||||
- **For large tasks (> 5 days)**: 4-6 phases, 7-10 success criteria
|
||||
|
||||
**Good success criteria**:
|
||||
- ✅ Specific and measurable
|
||||
- ✅ Actually indicates completion
|
||||
- ✅ Can be objectively verified
|
||||
|
||||
**Poor success criteria**:
|
||||
- ❌ "Make it better"
|
||||
- ❌ "Fix the problems"
|
||||
- ❌ "User is happy" (too subjective)
|
||||
|
||||
## Completion
|
||||
|
||||
Once initialization and planning are complete:
|
||||
|
||||
```markdown
|
||||
🎉 Task "{TASK_NAME}" is ready to begin!
|
||||
|
||||
**Task ID**: {TASK_ID}
|
||||
**Location**: `{WORKSPACE}/active_tasks/{TASK_ID}/`
|
||||
**Status**: Planning complete, ready for execution
|
||||
|
||||
**Next Steps**:
|
||||
1. I'll start working on Phase 1
|
||||
2. Every action will be logged automatically
|
||||
3. Status will be updated as we progress
|
||||
4. Checkpoints will be created regularly
|
||||
|
||||
**To continue this task later**:
|
||||
```
|
||||
/teds-continue {TASK_ID}
|
||||
```
|
||||
|
||||
**To check status anytime**:
|
||||
```
|
||||
/teds-status {TASK_ID}
|
||||
```
|
||||
|
||||
Let's get started! 🚀
|
||||
```
|
||||
|
||||
After initialization is complete, the user can either:
|
||||
- Continue immediately with the work
|
||||
- Pause and resume later with `/teds-continue {TASK_ID}`
|
||||
- Check status with `/teds-status`
|
||||
|
||||
The task is now in the system and ready for execution with the teds-executor agent.
|
||||
605
agents/teds-status.md
Normal file
605
agents/teds-status.md
Normal file
@@ -0,0 +1,605 @@
|
||||
---
|
||||
description: Display comprehensive status of TEDS tasks
|
||||
---
|
||||
|
||||
# TEDS Status Agent
|
||||
|
||||
You are displaying the status of TEDS tasks to help users understand their current work state.
|
||||
|
||||
## 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`.
|
||||
|
||||
## Determine Mode
|
||||
|
||||
Command format: `/teds-status [optional-task-id]`
|
||||
|
||||
**Mode A**: No task-id provided → Show all tasks summary
|
||||
**Mode B**: Task-id provided → Show detailed single task status
|
||||
|
||||
## Mode A: All Tasks Summary
|
||||
|
||||
### Step 1: Scan for Tasks
|
||||
|
||||
```bash
|
||||
# List active tasks
|
||||
ls -1 "${WORKSPACE}/active_tasks/" 2>/dev/null
|
||||
|
||||
# List archived tasks (recent ones)
|
||||
ls -1t "${WORKSPACE}/archived_tasks/" 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
### Step 2: Gather Task Information
|
||||
|
||||
For each task directory:
|
||||
|
||||
```bash
|
||||
TASK_ID="${dir_name}"
|
||||
|
||||
# Read manifest
|
||||
NAME=$(grep "name:" "${WORKSPACE}/active_tasks/${TASK_ID}/manifest.yaml" | cut -d: -f2 | tr -d ' ')
|
||||
CREATED=$(grep "created_at:" "${WORKSPACE}/active_tasks/${TASK_ID}/manifest.yaml" | cut -d: -f2-)
|
||||
|
||||
# Read status
|
||||
PHASE=$(grep "current_phase:" "${WORKSPACE}/active_tasks/${TASK_ID}/status.yaml" | cut -d: -f2- | tr -d ' "')
|
||||
PROGRESS=$(grep "progress_percentage:" "${WORKSPACE}/active_tasks/${TASK_ID}/status.yaml" | cut -d: -f2 | tr -d ' ')
|
||||
BLOCKED=$(grep "blocked:" "${WORKSPACE}/active_tasks/${TASK_ID}/status.yaml" | cut -d: -f2 | tr -d ' ')
|
||||
```
|
||||
|
||||
### Step 3: Present Summary Table
|
||||
|
||||
```markdown
|
||||
# TEDS Tasks Status
|
||||
|
||||
**Workspace**: `{WORKSPACE}/`
|
||||
**Configuration**: {CLAUDE.md | .teds-config.yaml}
|
||||
|
||||
## Active Tasks ({count})
|
||||
|
||||
{If no active tasks:}
|
||||
No active tasks.
|
||||
|
||||
Use `/teds-start [name] "[description]"` to create your first task.
|
||||
|
||||
{If has active tasks:}
|
||||
|
||||
| ID | Name | Phase | Progress | Status |
|
||||
|----|------|-------|----------|--------|
|
||||
| {task-id (short)} | {name} | {phase (short)} | {X}% | {active/🔴blocked} |
|
||||
| {task-id (short)} | {name} | {phase (short)} | {X}% | {active/🔴blocked} |
|
||||
| ... | ... | ... | ... | ... |
|
||||
|
||||
{If any tasks are blocked:}
|
||||
⚠️ {count} task(s) blocked. Use `/teds-status [task-id]` for details.
|
||||
|
||||
## Recently Archived ({count from last 10})
|
||||
|
||||
{If no archived tasks:}
|
||||
No archived tasks yet.
|
||||
|
||||
{If has archived tasks:}
|
||||
|
||||
| ID | Name | Completed | Duration |
|
||||
|----|------|-----------|----------|
|
||||
| {task-id (short)} | {name} | {time ago} | {duration} |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
## Quick Actions
|
||||
|
||||
- **View task details**: `/teds-status [task-id]`
|
||||
- **Continue a task**: `/teds-continue [task-id]`
|
||||
- **Start new task**: `/teds-start [name]`
|
||||
- **Complete a task**: `/teds-complete [task-id]`
|
||||
|
||||
## Workspace Statistics
|
||||
|
||||
- **Total Active**: {count}
|
||||
- **Total Archived**: {count}
|
||||
- **Knowledge Entries**: {count files in knowledge_index/}
|
||||
- **Disk Usage**: {du -sh workspace}
|
||||
|
||||
---
|
||||
|
||||
Run `/teds-status [task-id]` for detailed information about a specific task.
|
||||
```
|
||||
|
||||
### Formatting Notes
|
||||
|
||||
**Task ID Display**:
|
||||
- Show shortened version: `20250116-1430-refactor-auth` → `0116-1430-refactor`
|
||||
- Or just last part: `refactor-auth`
|
||||
- Include hover/full ID if possible
|
||||
|
||||
**Phase Display**:
|
||||
- Truncate long phases: `Phase 2: Implementation` → `Implementation`
|
||||
- Or show as: `P2: Implementation`
|
||||
|
||||
**Time Ago**:
|
||||
- < 1 hour: `45 minutes ago`
|
||||
- < 1 day: `5 hours ago`
|
||||
- < 1 week: `3 days ago`
|
||||
- < 1 month: `2 weeks ago`
|
||||
- Older: `2025-01-10`
|
||||
|
||||
**Duration**:
|
||||
- Calculate from created_at to completed_at (for archived)
|
||||
- Format: `2.5 hours`, `3 days`, `1 week`
|
||||
|
||||
## Mode B: Single Task Detailed Status
|
||||
|
||||
### Step 1: Validate Task Exists
|
||||
|
||||
```bash
|
||||
TASK_ID="${provided_id}"
|
||||
|
||||
if ! test -d "${WORKSPACE}/active_tasks/${TASK_ID}"; then
|
||||
# Check if it's archived
|
||||
if test -d "${WORKSPACE}/archived_tasks/${TASK_ID}"; then
|
||||
TASK_DIR="${WORKSPACE}/archived_tasks/${TASK_ID}"
|
||||
ARCHIVED=true
|
||||
else
|
||||
echo "❌ Task not found: ${TASK_ID}"
|
||||
echo ""
|
||||
echo "Available tasks:"
|
||||
ls "${WORKSPACE}/active_tasks/"
|
||||
exit 1
|
||||
fi
|
||||
else
|
||||
TASK_DIR="${WORKSPACE}/active_tasks/${TASK_ID}"
|
||||
ARCHIVED=false
|
||||
fi
|
||||
```
|
||||
|
||||
### Step 2: Load Task Data
|
||||
|
||||
```bash
|
||||
# Read all key files
|
||||
MANIFEST=$(cat "${TASK_DIR}/manifest.yaml")
|
||||
STATUS=$(cat "${TASK_DIR}/status.yaml")
|
||||
PLAN=$(cat "${TASK_DIR}/plan.md")
|
||||
LOG_RECENT=$(tail -100 "${TASK_DIR}/execution_log.md")
|
||||
KNOWLEDGE=$(cat "${TASK_DIR}/knowledge_base.md")
|
||||
```
|
||||
|
||||
Extract key information:
|
||||
- Task name, description, created_at
|
||||
- Current phase, progress, blocked status
|
||||
- Last checkpoint, last updated
|
||||
- Next action
|
||||
- Recent log entries
|
||||
- Knowledge entries
|
||||
|
||||
### Step 3: Present Detailed Status
|
||||
|
||||
```markdown
|
||||
# Task Status: {name}
|
||||
|
||||
**ID**: `{TASK_ID}`
|
||||
**Status**: {✅ Active | 🔴 Blocked | ✓ Completed}
|
||||
**Created**: {date and time}
|
||||
**Duration**: {time since creation OR total duration if archived}
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
**Phase**: {current_phase}
|
||||
**Progress**: {progress_percentage}% [▓▓▓▓▓▓▓░░░]
|
||||
**Last Updated**: {time ago}
|
||||
**Last Checkpoint**: {time ago}
|
||||
|
||||
{If blocked:}
|
||||
⚠️ **BLOCKED**: {blocked_reason}
|
||||
|
||||
{Action required section}
|
||||
|
||||
{If not blocked:}
|
||||
✅ Task progressing normally
|
||||
|
||||
## Next Action
|
||||
|
||||
{next_action from status.yaml}
|
||||
|
||||
{If has notes in status.yaml:}
|
||||
**Notes**: {notes}
|
||||
|
||||
---
|
||||
|
||||
## Recent Activity
|
||||
|
||||
Showing last 5 actions:
|
||||
|
||||
### {HH:MM} - {Action Type}
|
||||
- Tool: {tool}
|
||||
- Target: {target}
|
||||
- Result: {result}
|
||||
- Status: {success/failed}
|
||||
|
||||
### {HH:MM} - {Action Type}
|
||||
- Tool: {tool}
|
||||
- Target: {target}
|
||||
- Result: {result}
|
||||
- Status: {success/failed}
|
||||
|
||||
[... 3 more recent actions ...]
|
||||
|
||||
{Link to full log:}
|
||||
Full execution log: `{TASK_DIR}/execution_log.md`
|
||||
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
{objective from plan.md}
|
||||
|
||||
## Phases
|
||||
|
||||
{List phases with completion indicators}
|
||||
|
||||
1. {Phase 1 name} {✓ if progress past this phase}
|
||||
2. {Phase 2 name} {← Current if in this phase}
|
||||
3. {Phase 3 name} {⏳ if upcoming}
|
||||
|
||||
## Success Criteria
|
||||
|
||||
{Show criteria from plan.md with completion status if available}
|
||||
|
||||
- [✓] {Completed criterion}
|
||||
- [✓] {Completed criterion}
|
||||
- [ ] {Remaining criterion}
|
||||
- [ ] {Remaining criterion}
|
||||
|
||||
---
|
||||
|
||||
## Key Learnings ({count entries})
|
||||
|
||||
{Show recent 3-5 entries from knowledge_base.md}
|
||||
|
||||
### {Date} - {Topic}
|
||||
{Brief summary}
|
||||
|
||||
### {Date} - {Topic}
|
||||
{Brief summary}
|
||||
|
||||
[... more entries ...]
|
||||
|
||||
{Link to full knowledge base:}
|
||||
Full knowledge base: `{TASK_DIR}/knowledge_base.md`
|
||||
|
||||
---
|
||||
|
||||
## Issues and Blockers
|
||||
|
||||
{If blocked:}
|
||||
**Current Blocker**: {blocked_reason}
|
||||
|
||||
**Analysis**: {check knowledge_base.md for related entries}
|
||||
|
||||
**Attempted Solutions**: {from execution_log.md}
|
||||
|
||||
**Recommendation**: {suggest next steps}
|
||||
|
||||
{If not blocked:}
|
||||
No current blockers or issues.
|
||||
|
||||
---
|
||||
|
||||
## Task Files
|
||||
|
||||
All task documentation:
|
||||
```
|
||||
{TASK_DIR}/
|
||||
├── manifest.yaml Task metadata
|
||||
├── plan.md Execution plan
|
||||
├── execution_log.md {count lines} lines of logs
|
||||
├── knowledge_base.md {count entries} knowledge entries
|
||||
├── context.md Background and constraints
|
||||
└── status.yaml Current state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Actions
|
||||
|
||||
{If active:}
|
||||
- **Continue working**: `/teds-continue {TASK_ID}`
|
||||
- **Create checkpoint**: `/teds-checkpoint {TASK_ID}`
|
||||
- **Complete task**: `/teds-complete {TASK_ID}`
|
||||
|
||||
{If archived:}
|
||||
- **View summary**: `cat {WORKSPACE}/knowledge_index/{TASK_ID}-summary.md`
|
||||
- **View full archive**: `ls -la {TASK_DIR}/`
|
||||
|
||||
---
|
||||
|
||||
{If active and making good progress:}
|
||||
💡 **Tip**: Task is {X}% complete. Keep up the momentum!
|
||||
|
||||
{If active and progress stalled:}
|
||||
⏰ **Notice**: Last updated {time ago}. Consider resuming with `/teds-continue {TASK_ID}`
|
||||
|
||||
{If blocked:}
|
||||
🔴 **Action Required**: Task blocked for {time}. Review blocker and take action.
|
||||
```
|
||||
|
||||
### Progress Bar Rendering
|
||||
|
||||
Convert percentage to visual bar:
|
||||
```bash
|
||||
PROGRESS=65 # from status.yaml
|
||||
|
||||
# Calculate filled blocks (10 blocks total)
|
||||
FILLED=$((PROGRESS / 10))
|
||||
EMPTY=$((10 - FILLED))
|
||||
|
||||
# Create bar
|
||||
BAR="["
|
||||
for i in $(seq 1 $FILLED); do BAR="${BAR}▓"; done
|
||||
for i in $(seq 1 $EMPTY); do BAR="${BAR}░"; done
|
||||
BAR="${BAR}]"
|
||||
|
||||
echo "${PROGRESS}% ${BAR}"
|
||||
# Output: 65% [▓▓▓▓▓▓░░░░]
|
||||
```
|
||||
|
||||
## Time Calculations
|
||||
|
||||
### Time Ago
|
||||
|
||||
```bash
|
||||
# Given timestamp: 2025-01-16T14:30:00+08:00
|
||||
TIMESTAMP="..."
|
||||
|
||||
# Calculate seconds since
|
||||
NOW=$(date +%s)
|
||||
THEN=$(date -d "$TIMESTAMP" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%S" "$TIMESTAMP" +%s)
|
||||
SECONDS=$((NOW - THEN))
|
||||
|
||||
# Format
|
||||
MINUTES=$((SECONDS / 60))
|
||||
HOURS=$((SECONDS / 3600))
|
||||
DAYS=$((SECONDS / 86400))
|
||||
|
||||
if [[ $MINUTES -lt 60 ]]; then
|
||||
echo "${MINUTES} minutes ago"
|
||||
elif [[ $HOURS -lt 24 ]]; then
|
||||
echo "${HOURS} hours ago"
|
||||
elif [[ $DAYS -lt 7 ]]; then
|
||||
echo "${DAYS} days ago"
|
||||
elif [[ $DAYS -lt 30 ]]; then
|
||||
WEEKS=$((DAYS / 7))
|
||||
echo "${WEEKS} weeks ago"
|
||||
else
|
||||
# Show date
|
||||
date -d "$TIMESTAMP" +"%Y-%m-%d"
|
||||
fi
|
||||
```
|
||||
|
||||
### Duration
|
||||
|
||||
```bash
|
||||
# From created_at to now (active) or completed_at (archived)
|
||||
START="..."
|
||||
END="..." # now or completed_at
|
||||
|
||||
START_SEC=$(date -d "$START" +%s)
|
||||
END_SEC=$(date -d "$END" +%s)
|
||||
DURATION=$((END_SEC - START_SEC))
|
||||
|
||||
MINUTES=$((DURATION / 60))
|
||||
HOURS=$((DURATION / 3600))
|
||||
DAYS=$((DURATION / 86400))
|
||||
|
||||
if [[ $HOURS -lt 1 ]]; then
|
||||
echo "${MINUTES} minutes"
|
||||
elif [[ $HOURS -lt 24 ]]; then
|
||||
echo "${HOURS} hours"
|
||||
else
|
||||
echo "${DAYS} days"
|
||||
fi
|
||||
```
|
||||
|
||||
## Counting Knowledge Entries
|
||||
|
||||
```bash
|
||||
# Count sections starting with ### in knowledge_base.md
|
||||
grep -c "^### " "${TASK_DIR}/knowledge_base.md"
|
||||
```
|
||||
|
||||
## Disk Usage
|
||||
|
||||
```bash
|
||||
du -sh "${WORKSPACE}"
|
||||
# Output: 15M claude_work_space/
|
||||
|
||||
# Or per section
|
||||
du -sh "${WORKSPACE}/active_tasks"
|
||||
du -sh "${WORKSPACE}/archived_tasks"
|
||||
du -sh "${WORKSPACE}/knowledge_index"
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Task Not Found
|
||||
|
||||
```
|
||||
❌ Task not found: {provided_id}
|
||||
|
||||
Available active tasks:
|
||||
{list active tasks with IDs and names}
|
||||
|
||||
Available archived tasks (recent):
|
||||
{list recent 5 archived tasks}
|
||||
|
||||
Use:
|
||||
- `/teds-status` to see all tasks
|
||||
- `/teds-status [task-id]` with correct ID
|
||||
```
|
||||
|
||||
### Workspace Issues
|
||||
|
||||
```
|
||||
❌ Cannot access TEDS workspace: {WORKSPACE}
|
||||
|
||||
Possible issues:
|
||||
- Workspace directory deleted or moved
|
||||
- Permission problems
|
||||
- Configuration error
|
||||
|
||||
Check:
|
||||
1. Workspace exists: ls -la {WORKSPACE}
|
||||
2. Configuration: {CLAUDE.md or .teds-config.yaml}
|
||||
3. Re-initialize if needed: /teds-init
|
||||
```
|
||||
|
||||
### Corrupted Task Data
|
||||
|
||||
```
|
||||
⚠️ Task data incomplete: {TASK_ID}
|
||||
|
||||
Missing or unreadable files:
|
||||
- {file 1}
|
||||
- {file 2}
|
||||
|
||||
This task may be corrupted.
|
||||
|
||||
Options:
|
||||
1. View what's available: ls -la {TASK_DIR}
|
||||
2. Manually inspect: cat {TASK_DIR}/manifest.yaml
|
||||
3. Archive if unsalvageable: mv {TASK_DIR} {WORKSPACE}/archived_tasks/
|
||||
|
||||
Need help deciding what to do?
|
||||
```
|
||||
|
||||
## Sorting and Filtering
|
||||
|
||||
### Sort Active Tasks
|
||||
|
||||
**By Progress** (default):
|
||||
- Show highest progress first (closest to completion)
|
||||
|
||||
**By Last Updated**:
|
||||
- Most recently worked on first
|
||||
|
||||
**By Created Date**:
|
||||
- Newest tasks first
|
||||
|
||||
Allow user preference if multiple tasks.
|
||||
|
||||
### Highlight Important States
|
||||
|
||||
- 🔴 **Blocked tasks**: Show with warning symbol
|
||||
- ⚠️ **Stalled tasks**: Not updated in >7 days
|
||||
- 🎯 **Near completion**: >90% progress
|
||||
- 🆕 **New tasks**: Created <24 hours ago
|
||||
|
||||
## Summary Statistics
|
||||
|
||||
If showing all tasks, include useful stats:
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
|
||||
**Active Work**:
|
||||
- {X} tasks in progress
|
||||
- Average progress: {Y}%
|
||||
- {Z} blocked tasks
|
||||
|
||||
**Recent Activity**:
|
||||
- Last updated: {most recent task update}
|
||||
- Active today: {tasks updated in last 24h}
|
||||
- Checkpoints created: {count from logs}
|
||||
|
||||
**Completions**:
|
||||
- This week: {count}
|
||||
- This month: {count}
|
||||
- All time: {total archived}
|
||||
|
||||
**Knowledge Accumulated**:
|
||||
- Total entries: {count}
|
||||
- Unique topics: {estimate}
|
||||
- Total documentation: {total size}
|
||||
```
|
||||
|
||||
## Command Suggestions
|
||||
|
||||
Based on status, suggest relevant actions:
|
||||
|
||||
**If many active tasks**:
|
||||
```
|
||||
💡 You have {X} active tasks. Consider completing or archiving some to maintain focus.
|
||||
```
|
||||
|
||||
**If tasks stalled**:
|
||||
```
|
||||
⏰ {X} task(s) haven't been updated in over a week:
|
||||
- {task 1 name} (last updated {time ago})
|
||||
- {task 2 name} (last updated {time ago})
|
||||
|
||||
Consider: `/teds-continue [task-id]` or archiving if no longer relevant.
|
||||
```
|
||||
|
||||
**If blocked tasks**:
|
||||
```
|
||||
🔴 {X} task(s) are blocked:
|
||||
- {task name}: {blocked_reason (brief)}
|
||||
|
||||
Action needed: Review and unblock with `/teds-continue [task-id]`
|
||||
```
|
||||
|
||||
**If no active tasks**:
|
||||
```
|
||||
🚀 Ready to start a new long-term task?
|
||||
|
||||
Use: `/teds-start [name] "[description]"`
|
||||
|
||||
Example: `/teds-start refactor-auth "Migrate authentication to OAuth 2.0"`
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
1. **Be concise for summaries**: Users scan quickly
|
||||
2. **Be detailed for single task**: Users want full picture
|
||||
3. **Highlight actionable items**: What should user do?
|
||||
4. **Show progress visually**: Progress bars, checkmarks
|
||||
5. **Calculate times accurately**: Users rely on timing info
|
||||
6. **Handle missing data gracefully**: Files might be incomplete
|
||||
7. **Suggest next steps**: Guide users to actions
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
For workspaces with many tasks:
|
||||
- Limit archived task display (show recent 10)
|
||||
- Use file timestamps instead of parsing all YAMLs
|
||||
- Cache workspace statistics
|
||||
- Offer filtering options
|
||||
|
||||
```
|
||||
Showing {X} most recent tasks. You have {Y} total archived tasks.
|
||||
|
||||
To see more: ls {WORKSPACE}/archived_tasks/
|
||||
To search: grep "name" {WORKSPACE}/archived_tasks/*/manifest.yaml
|
||||
```
|
||||
Reference in New Issue
Block a user