commit 7e9a12dd5a7df8bed4b141c2f2bac8fb19b64f65 Author: Zhongwei Li Date: Sat Nov 29 18:26:21 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..43476db --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "teds", + "description": "Task Execution Documentation System (TEDS) - Comprehensive documentation for complex, multi-session tasks", + "version": "1.0.0", + "author": { + "name": "eternnoir", + "email": "eternnoir@gmail.com" + }, + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..a2bcc08 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# teds + +Task Execution Documentation System (TEDS) - Comprehensive documentation for complex, multi-session tasks diff --git a/agents/teds-archiver.md b/agents/teds-archiver.md new file mode 100644 index 0000000..841008a --- /dev/null +++ b/agents/teds-archiver.md @@ -0,0 +1,736 @@ +--- +description: Complete and archive a finished TEDS task +--- + +# TEDS Task Archiver Agent + +You are completing and archiving a finished TEDS task, preserving all knowledge for future reference. + +## Load Configuration + +**Determine workspace location**: + +1. **Check CLAUDE.md**: + ```bash + if test -f "CLAUDE.md"; then + grep -A 2 "## TEDS Configuration" CLAUDE.md | grep "Workspace Directory" | sed 's/.*`\([^`]*\)`.*/\1/' + fi + ``` + +2. **Check .teds-config.yaml**: + ```bash + if test -f ".teds-config.yaml"; then + grep "path:" .teds-config.yaml | awk '{print $2}' + fi + ``` + +3. **Error if neither exists**: + ``` + ❌ TEDS not initialized in this project. + + Please run: /teds-init + ``` + +Store workspace path as `WORKSPACE`. + +## Parse Task ID + +From command: `/teds-complete task-id` + +```bash +TASK_ID="${provided_id}" +TASK_DIR="${WORKSPACE}/active_tasks/${TASK_ID}" +``` + +**Verify task exists**: +```bash +if ! test -d "${TASK_DIR}"; then + echo "❌ Task not found: ${TASK_ID}" + echo "" + echo "Active tasks:" + ls "${WORKSPACE}/active_tasks/" + echo "" + echo "Use /teds-status to see all tasks" + exit 1 +fi +``` + +## Load Task Data + +Read all task documentation: + +```bash +MANIFEST=$(cat "${TASK_DIR}/manifest.yaml") +PLAN=$(cat "${TASK_DIR}/plan.md") +STATUS=$(cat "${TASK_DIR}/status.yaml") +LOG=$(cat "${TASK_DIR}/execution_log.md") +KNOWLEDGE=$(cat "${TASK_DIR}/knowledge_base.md") +CONTEXT=$(cat "${TASK_DIR}/context.md") +``` + +Extract key information: +- Task name, description +- Creation timestamp +- Success criteria from plan.md +- Current progress +- Knowledge entries + +## Step 1: Verify Completion + +### Extract Success Criteria + +```bash +# From plan.md, extract lines with - [ ] or - [x] +grep -E "^- \[[ x]\]" "${TASK_DIR}/plan.md" +``` + +### Check Completion Status + +Count: +- Total criteria +- Completed criteria (those with [x] or [✓]) +- Incomplete criteria (those with [ ]) + +**If all criteria met**: +``` +✅ All success criteria met ({total} criteria) + +The task appears ready for completion. +``` + +**If some criteria incomplete**: +``` +⚠️ Task Completion Check + +Success Criteria Status: +✅ Completed: {X} / {Total} +⏳ Incomplete: {Y} + +Completed: +- ✓ {Criterion 1} +- ✓ {Criterion 2} + +Incomplete: +- ⏳ {Criterion 3} +- ⏳ {Criterion 4} + +Options: +1. Complete anyway (mark incomplete criteria as acceptable) +2. Continue task to finish remaining work +3. Review and discuss incomplete criteria +4. Cancel completion + +The task can be completed with incomplete criteria if you accept them. + +Choose [1/2/3/4]: +``` + +**Option 1**: Continue with completion, note accepted incomplete criteria +**Option 2**: Exit archiver, user should use `/teds-continue` to finish work +**Option 3**: Discuss what's needed, then let user decide +**Option 4**: Cancel and return + +### Confirm Completion + +Even if all criteria met, confirm with user: + +``` +Ready to complete and archive this task? + +Task: {name} +Progress: {progress}% +Duration: {time from created_at to now} + +This will: +✓ Finalize all documentation +✓ Extract knowledge summary +✓ Move task to archived_tasks/ +✓ Make knowledge available for future tasks + +This action cannot be easily undone. + +Proceed with completion? [y/n] +``` + +## Step 2: Finalize Documentation + +### Add Completion Entry to execution_log.md + +```bash +cat >> "${TASK_DIR}/execution_log.md" << EOF + +--- + +### $(date +%H:%M) - TASK COMPLETED +- Status: Completed successfully +- Duration: {calculate from created_at to now} +- Final Progress: {progress from status.yaml}% +- Criteria Met: {X} / {Total} +- Knowledge Entries: {count from knowledge_base.md} + +**Summary**: +{Brief summary of what was accomplished} + +**Key Outcomes**: +- {Outcome 1} +- {Outcome 2} +- {Outcome 3} + +**Archived**: Task moved to archived_tasks/ for future reference + +EOF +``` + +### Update status.yaml + +```bash +cat > "${TASK_DIR}/status.yaml" << EOF +current_phase: "completed" +last_checkpoint: "$(date -u +%Y-%m-%dT%H:%M:%S+08:00)" +last_updated: "$(date -u +%Y-%m-%dT%H:%M:%S+08:00)" +progress_percentage: 100 +blocked: false +blocked_reason: null +next_action: "Task completed and archived" +notes: "Completed on $(date +%Y-%m-%d). All objectives achieved." +completed_at: "$(date -u +%Y-%m-%dT%H:%M:%S+08:00)" +EOF +``` + +### Update manifest.yaml + +```bash +# Add completion timestamp +sed -i "s/completed_at: null/completed_at: \"$(date -u +%Y-%m-%dT%H:%M:%S+08:00)\"/" "${TASK_DIR}/manifest.yaml" + +# Update status +sed -i "s/status: active/status: completed/" "${TASK_DIR}/manifest.yaml" +``` + +### Summarize Learnings in knowledge_base.md + +Add final summary section: + +```bash +cat >> "${TASK_DIR}/knowledge_base.md" << EOF + +--- + +## Task Completion Summary + +**Completed**: $(date +%Y-%m-%d) +**Duration**: {duration} +**Total Entries**: {count above} + +### Most Important Learnings + +{Extract 3-5 most significant insights from above sections} + +1. **{Topic 1}**: {Key insight} +2. **{Topic 2}**: {Key insight} +3. **{Topic 3}**: {Key insight} + +### Reusable Patterns + +{Extract patterns that can apply to future tasks} + +### References for Future Work + +{Key references that proved useful} + +--- + +*Knowledge extracted to: knowledge_index/${TASK_ID}-summary.md* + +EOF +``` + +## Step 3: Extract Knowledge Summary + +Create summary document in knowledge_index/: + +```bash +cat > "${WORKSPACE}/knowledge_index/${TASK_ID}-summary.md" << 'EOF' +# Task Summary: {name} + +**Task ID**: {TASK_ID} +**Completed**: {completion date} +**Duration**: {duration} + +--- + +## Quick Reference + +**Objective**: {from plan.md} + +**Approach**: {brief description of how it was done} + +**Outcome**: {what was delivered} + +--- + +## Key Information + +### What Was Done + +{Summary from execution_log.md completion entry} + +### Success Criteria + +{List all criteria with status} +- ✓ {Completed criterion} +- ✓ {Completed criterion} +- (~) {Accepted incomplete criterion} - {reason why accepted} + +### Statistics + +- **Duration**: {duration} +- **Actions Logged**: {count from execution_log.md} +- **Files Modified**: {estimate or count if tracked} +- **Knowledge Entries**: {count} +- **Checkpoints**: {count from log} + +--- + +## Key Learnings + +{Top 5-7 most important learnings from knowledge_base.md} + +### {Topic 1} + +{Description and why it matters} + +### {Topic 2} + +{Description and why it matters} + +[... more learnings ...] + +--- + +## Solutions and Patterns + +{Reusable solutions from knowledge_base.md} + +### {Problem/Pattern 1} + +**Context**: {When this applies} +**Solution**: {How to solve it} +**Reference**: {Link to relevant files or documentation} + +### {Problem/Pattern 2} + +[... more solutions ...] + +--- + +## References + +{Key references from knowledge_base.md} + +- {Reference 1}: {Why it's useful} +- {Reference 2}: {Why it's useful} +- {Reference 3}: {Why it's useful} + +--- + +## For Future Tasks + +**When to Apply This Knowledge**: +- {Scenario 1} +- {Scenario 2} +- {Scenario 3} + +**Reusable Patterns**: +- {Pattern 1}: See {file/section} +- {Pattern 2}: See {file/section} + +**Gotchas to Remember**: +- {Gotcha 1} +- {Gotcha 2} + +--- + +## Full Documentation + +Complete task documentation archived at: +``` +{WORKSPACE}/archived_tasks/{TASK_ID}/ +├── manifest.yaml # Task metadata +├── plan.md # Complete execution plan +├── execution_log.md # Full action history +├── knowledge_base.md # All learnings and discoveries +├── context.md # Background and constraints +└── status.yaml # Final status +``` + +To review full details: +```bash +cd {WORKSPACE}/archived_tasks/{TASK_ID} +cat execution_log.md # See complete history +cat knowledge_base.md # See all knowledge entries +``` + +--- + +**Generated**: {current timestamp} +**TEDS Version**: 1.0.0 +EOF +``` + +Fill in all placeholders with actual data. + +## Step 4: Archive Task + +Move task from active to archived: + +```bash +# Create archived_tasks directory if doesn't exist +mkdir -p "${WORKSPACE}/archived_tasks" + +# Move task directory +mv "${TASK_DIR}" "${WORKSPACE}/archived_tasks/${TASK_ID}" + +# Verify move successful +if test -d "${WORKSPACE}/archived_tasks/${TASK_ID}"; then + echo "✓ Task archived successfully" +else + echo "✗ Failed to archive task" + exit 1 +fi +``` + +**Update path variables**: +```bash +ARCHIVED_DIR="${WORKSPACE}/archived_tasks/${TASK_ID}" +``` + +## Step 5: Update Tracking + +### Add to Task History + +Create or update `${WORKSPACE}/task_history.md`: + +```bash +# Create file if doesn't exist +if ! test -f "${WORKSPACE}/task_history.md"; then + cat > "${WORKSPACE}/task_history.md" << EOF +# TEDS Task History + +Chronological list of all completed tasks. + +## Completed Tasks + +EOF +fi + +# Add entry +cat >> "${WORKSPACE}/task_history.md" << EOF +### {name} ({TASK_ID}) + +- **Completed**: $(date +%Y-%m-%d) +- **Duration**: {duration} +- **Summary**: {brief description} +- **Knowledge**: {count} entries +- **Archive**: archived_tasks/{TASK_ID}/ +- **Summary**: knowledge_index/{TASK_ID}-summary.md + +EOF +``` + +### Update Workspace Statistics + +If `${WORKSPACE}/stats.yaml` exists, update it: + +```bash +# Increment completed count +# Update last completion date +# Add to total duration +# etc. +``` + +Or create if doesn't exist: + +```yaml +total_tasks: 1 +active_tasks: {count active} +archived_tasks: 1 +total_duration_hours: {duration} +last_completion: {timestamp} +knowledge_entries: {total count} +``` + +## Step 6: Present Completion Report + +Show comprehensive completion report to user: + +```markdown +# 🎉 Task Completed: {name} + +**Task ID**: `{TASK_ID}` +**Duration**: {created_at} to {completed_at} ({duration}) +**Total Time**: ~{duration in hours} hours over {days} days +**Status**: Successfully completed and archived + +--- + +## Completion Summary + +### What Was Accomplished + +{Summary of key outcomes from plan.md and execution_log.md} + +### Success Criteria + +Total: {total criteria} +Completed: {completed count} + +✅ {Criterion 1} +✅ {Criterion 2} +✅ {Criterion 3} +{If any incomplete:} +(~) {Criterion 4} - Accepted as sufficient + +--- + +## Key Learnings ({count} total) + +{Top 5-7 learnings} + +### {Topic 1} +{Brief description} + +### {Topic 2} +{Brief description} + +[... more learnings ...] + +*Full learnings: knowledge_base.md* + +--- + +## Statistics + +- **Actions Logged**: {count from execution_log.md} +- **Checkpoints Created**: {count} +- **Knowledge Entries**: {count} +- **Files Modified**: {estimate if tracked} +- **Phases Completed**: {count} + +--- + +## Knowledge Preserved + +All knowledge from this task has been preserved and indexed: + +**Summary Document**: +``` +{WORKSPACE}/knowledge_index/{TASK_ID}-summary.md +``` + +Quick reference for key learnings, patterns, and solutions. + +**Complete Archive**: +``` +{WORKSPACE}/archived_tasks/{TASK_ID}/ +├── manifest.yaml ✓ Task metadata +├── plan.md ✓ Execution plan +├── execution_log.md ✓ Complete history ({line count} lines) +├── knowledge_base.md ✓ All learnings +├── context.md ✓ Background +└── status.yaml ✓ Final status +``` + +--- + +## Reusable Components + +The following patterns from this task can be applied to future work: + +- **{Pattern 1}**: {Brief description and when to use} +- **{Pattern 2}**: {Brief description and when to use} +- **{Pattern 3}**: {Brief description and when to use} + +See summary document for complete details and references. + +--- + +## Next Steps + +### Review the Knowledge + +Take a moment to review the summary: +```bash +cat {WORKSPACE}/knowledge_index/{TASK_ID}-summary.md +``` + +### Apply to New Tasks + +When starting related tasks, reference this knowledge: +- Key learnings in knowledge_base.md +- Solutions and patterns +- Useful references + +### Archive Cleanup (Optional) + +{If workspace has many archived tasks:} +Consider reviewing old archived tasks periodically: +```bash +ls -lt {WORKSPACE}/archived_tasks/ +``` + +Tasks can be compressed or removed after sufficient time (e.g., 6+ months). + +--- + +## Task History + +This completed task has been added to: +``` +{WORKSPACE}/task_history.md +``` + +View all completed tasks: +```bash +cat {WORKSPACE}/task_history.md +``` + +--- + +🎊 **Congratulations on completing {name}!** + +The knowledge from this task is now part of your TEDS knowledge base and will help make future tasks more efficient. + +**Start a new task**: `/teds-start [name]` +**View all tasks**: `/teds-status` +**Review knowledge**: `cat {WORKSPACE}/knowledge_index/{TASK_ID}-summary.md` +``` + +## Error Handling + +### Task Not Found + +``` +❌ Task not found: {TASK_ID} + +Possible reasons: +- Task ID incorrect +- Task already archived +- Task doesn't exist + +Check: +- Active tasks: ls {WORKSPACE}/active_tasks/ +- Archived tasks: ls {WORKSPACE}/archived_tasks/ +- Use: /teds-status + +If task was already archived, see: +{WORKSPACE}/archived_tasks/{TASK_ID}/ +``` + +### Archive Failure + +``` +❌ Failed to archive task + +Error: {error message} + +Task directory: {TASK_DIR} +Target: {WORKSPACE}/archived_tasks/{TASK_ID} + +Possible causes: +- Permission issues +- Disk space +- Path too long + +Manual fix: +```bash +mv {TASK_DIR} {WORKSPACE}/archived_tasks/{TASK_ID} +``` + +Check permissions: +```bash +ls -la {WORKSPACE} +``` + +Need help troubleshooting? +``` + +### Knowledge Extraction Failure + +``` +⚠️ Task archived but knowledge extraction incomplete + +Task successfully moved to archived_tasks/, but: +- Failed to create summary in knowledge_index/ + +Task archive: {WORKSPACE}/archived_tasks/{TASK_ID}/ ✓ +Knowledge summary: FAILED ✗ + +You can manually create the summary: +```bash +cat {WORKSPACE}/archived_tasks/{TASK_ID}/knowledge_base.md +# Review and extract key learnings +``` + +Or retry: +{Suggest re-running archiver or manual process} +``` + +## Cleanup Recommendations + +After archiving many tasks: + +``` +💡 **Workspace Maintenance Tip** + +You have {count} archived tasks. + +Consider: +1. **Review old archives** (>6 months): + ```bash + find {WORKSPACE}/archived_tasks -type d -mtime +180 + ``` + +2. **Compress old archives**: + ```bash + tar -czf archive-2024.tar.gz {WORKSPACE}/archived_tasks/202401* + ``` + +3. **Move to long-term storage**: + - Keep summaries in knowledge_index/ + - Archive full task data elsewhere + +**Current space**: {du -sh workspace} +``` + +## Important Notes + +1. **Always verify completion** - Check success criteria +2. **Preserve all knowledge** - Nothing should be lost +3. **Create useful summaries** - They'll be referenced later +4. **Confirm before archiving** - Can't easily undo +5. **Update tracking** - Maintain task history +6. **Extract reusable patterns** - Help future tasks +7. **Be honest about incomplete criteria** - Note what was accepted + +## Completion Best Practices + +**Good completion**: +- ✅ All or most criteria met +- ✅ Knowledge well documented +- ✅ Clear outcomes +- ✅ Useful summary for future + +**Premature completion**: +- ❌ Significant work remaining +- ❌ Many criteria unmet +- ❌ No clear outcome +- ❌ Blocking issues unresolved + +**Suggest continuing if**: +- Task <70% complete +- Major features incomplete +- Tests not passing +- Critical bugs remain + +Better to continue and finish properly than archive prematurely. diff --git a/agents/teds-config.md b/agents/teds-config.md new file mode 100644 index 0000000..237e40f --- /dev/null +++ b/agents/teds-config.md @@ -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 + +
+Core System Prompt (click to expand) + + + + + + +{PASTE_FULL_CORE_PROMPT_CONTENT_HERE} + + + +
+ +### Project-Specific Extensions + + + +**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 +``` + + + +### 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. diff --git a/agents/teds-executor.md b/agents/teds-executor.md new file mode 100644 index 0000000..a4eda59 --- /dev/null +++ b/agents/teds-executor.md @@ -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. diff --git a/agents/teds-initializer.md b/agents/teds-initializer.md new file mode 100644 index 0000000..6449cf6 --- /dev/null +++ b/agents/teds-initializer.md @@ -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. diff --git a/agents/teds-status.md b/agents/teds-status.md new file mode 100644 index 0000000..563d59c --- /dev/null +++ b/agents/teds-status.md @@ -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 +``` diff --git a/commands/teds-checkpoint.md b/commands/teds-checkpoint.md new file mode 100644 index 0000000..02971be --- /dev/null +++ b/commands/teds-checkpoint.md @@ -0,0 +1,105 @@ +--- +description: Create a checkpoint in the current TEDS task +--- + +# Create TEDS Checkpoint + +Create an immediate checkpoint in the currently active TEDS task. + +## Usage + +```bash +/teds-checkpoint [optional-task-id] +``` + +## Examples + +```bash +# Create checkpoint in current task context +/teds-checkpoint + +# Create checkpoint for specific task +/teds-checkpoint 20250116-1430-refactor-auth +``` + +## What is a Checkpoint? + +A checkpoint is a **safe pause point** that captures: +- Current phase and progress percentage +- Summary of what has been accomplished +- What remains to be done +- Timestamp for recovery reference + +Think of it as a "save game" point—you can safely stop work and resume from here later. + +## What This Does + +The agent will: +1. Review recent work from `execution_log.md` +2. Assess current progress +3. Add checkpoint entry to `execution_log.md`: + ```markdown + ### [HH:MM] - CHECKPOINT + - Phase: [current phase] + - Progress: [X%] + - Summary: [accomplishments] + - Next: [what remains] + ``` +4. Update `last_checkpoint` in `status.yaml` +5. Confirm: "Checkpoint created. Safe to pause here." + +## Automatic Checkpoints + +The executor agent automatically creates checkpoints: +- Every 30+ minutes of active work +- At completion of major milestones +- When transitioning between phases + +Manual checkpoints are useful when: +- You want to pause before the automatic interval +- You've reached a logical stopping point +- You're about to try something risky +- You're switching focus to another task + +## Checkpoint Best Practices + +**Good times to checkpoint**: +- ✅ Just completed a significant feature +- ✅ About to refactor or make large changes +- ✅ End of work session +- ✅ Before switching context + +**Don't checkpoint**: +- ❌ In the middle of an incomplete action +- ❌ When build/tests are failing +- ❌ When blocked and unsure how to proceed (mark as blocked instead) + +## Viewing Checkpoints + +To see all checkpoints in a task: +```bash +# View full execution log +cat workspace/active_tasks/[task-id]/execution_log.md | grep "CHECKPOINT" +``` + +Or use: +```bash +/teds-status [task-id] +``` +This shows the last checkpoint time. + +## Recovery from Checkpoint + +When you continue a task with `/teds-continue`, the agent automatically: +1. Finds the most recent checkpoint +2. Reviews what was done +3. Identifies the next action +4. Resumes from there + +No special recovery command needed—it's built into the continue process. + +## Related Commands + +- `/teds-continue [task-id]` - Resume from checkpoint +- `/teds-status` - View last checkpoint time +- `/teds-complete [task-id]` - Finish task diff --git a/commands/teds-complete.md b/commands/teds-complete.md new file mode 100644 index 0000000..e7092cc --- /dev/null +++ b/commands/teds-complete.md @@ -0,0 +1,207 @@ +--- +description: Complete and archive a TEDS task +--- + +# Complete TEDS Task + +Launch the **teds-archiver** agent to complete and archive a finished TEDS task. + +## Usage + +```bash +/teds-complete task-id +``` + +## Examples + +```bash +# Complete a specific task +/teds-complete 20250116-1430-refactor-auth + +# List tasks first, then complete +/teds-status +/teds-complete 20250115-0920-migrate-db +``` + +## What This Does + +The archiver agent will: +1. **Verify completion** against success criteria in `plan.md` +2. **Ask for confirmation** if any criteria are incomplete +3. **Finalize documentation**: + - Add completion entry to `execution_log.md` + - Update `status.yaml`: set status to "completed" + - Summarize all learnings in `knowledge_base.md` + - Set completion timestamp in `manifest.yaml` +4. **Extract knowledge**: + - Create summary document in `knowledge_index/[task-id]-summary.md` + - Include: objectives, approach, learnings, outcomes +5. **Archive task**: + - Move from `active_tasks/` to `archived_tasks/` + - Preserve complete directory structure +6. **Update tracking**: + - Add entry to workspace task history + +## Verification Process + +Before archiving, the agent checks: + +``` +Reviewing task completion... + +Success Criteria (from plan.md): +✅ All OAuth providers integrated (Google, GitHub) +✅ Tests passing with >90% coverage +✅ Documentation updated +⚠️ Performance benchmarks not run + +Incomplete: 1 criterion + +Options: +1. Complete anyway (mark as acceptable) +2. Continue task to finish remaining work +3. Cancel and return to task + +Choose [1/2/3]: +``` + +## Completion Report + +After successful archival: + +``` +# Task Completed: refactor-auth + +**Task ID**: 20250116-1430-refactor-auth +**Duration**: 2025-01-16 14:30 to 2025-01-18 16:45 +**Total Time**: ~12 hours over 2 days +**Status**: Successfully completed + +## Key Outcomes + +✅ OAuth 2.0 authentication fully implemented +✅ Google and GitHub providers integrated +✅ Comprehensive test suite (94% coverage) +✅ Documentation complete with examples +✅ Migration guide for existing users + +## Key Learnings + +1. **Google OAuth Setup** + - Requires web credentials, not service account + - Redirect URIs must match exactly (including trailing slash) + +2. **Token Management** + - Refresh tokens expire after 6 months if unused + - Implemented automatic refresh 5 minutes before expiration + +3. **Security Considerations** + - PKCE extension essential for public clients + - State parameter prevents CSRF attacks + +4. **Testing Insights** + - Mock OAuth providers for unit tests + - Integration tests need real credentials (use staging) + +## Statistics + +- **Files Modified**: 23 +- **Tests Added**: 47 +- **Documentation Pages**: 8 +- **Checkpoints Created**: 6 +- **Knowledge Entries**: 12 + +## Files Archived + +- **Location**: claude_work_space/archived_tasks/20250116-1430-refactor-auth/ +- **Summary**: claude_work_space/knowledge_index/20250116-1430-refactor-auth-summary.md + +## Reusable Components + +The following patterns can be applied to future tasks: +- OAuth provider abstract class design +- Token refresh mechanism +- Integration testing strategy + +--- + +Task successfully archived. Knowledge preserved for future reference. +``` + +## Archived Task Structure + +Completed tasks maintain full structure: + +``` +archived_tasks/20250116-1430-refactor-auth/ +├── manifest.yaml # Includes completion timestamp +├── plan.md # Original plan with all criteria +├── execution_log.md # Complete action history +├── knowledge_base.md # All learnings +├── context.md # Background preserved +└── status.yaml # Final status: completed +``` + +## Knowledge Index + +The summary in `knowledge_index/` provides quick reference: + +```markdown +# Task Summary: refactor-auth + +**Completed**: 2025-01-18 +**Duration**: 12 hours over 2 days + +## Quick Reference + +**Objective**: Implement OAuth 2.0 authentication with Google and GitHub + +**Approach**: +- Abstract provider pattern +- Separate token management service +- Comprehensive test coverage + +**Key Learnings**: [3-5 most important insights] + +**Outcomes**: [What was delivered] + +**For Future Tasks**: [Reusable patterns and approaches] + +Full details: ../archived_tasks/20250116-1430-refactor-auth/ +``` + +## When to Complete a Task + +**Good times to complete**: +- ✅ All success criteria met +- ✅ Documentation complete +- ✅ Tests passing +- ✅ No known issues +- ✅ Ready for handoff or deployment + +**Consider continuing if**: +- ⚠️ Critical criteria not met +- ⚠️ Tests failing +- ⚠️ Blockers unresolved +- ⚠️ Documentation incomplete + +You can always archive with incomplete criteria if you explicitly accept them, but the agent will prompt for confirmation. + +## Accessing Archived Tasks + +Archived tasks remain fully accessible: + +```bash +# View archived task +cd workspace/archived_tasks/20250116-1430-refactor-auth +cat execution_log.md + +# Quick summary +cat workspace/knowledge_index/20250116-1430-refactor-auth-summary.md +``` + +## Related Commands + +- `/teds-status` - View all tasks including archived +- `/teds-start [name]` - Start new task (potentially reusing patterns) +- `/teds-continue [task-id]` - Resume if you need to reopen diff --git a/commands/teds-continue.md b/commands/teds-continue.md new file mode 100644 index 0000000..d4dd601 --- /dev/null +++ b/commands/teds-continue.md @@ -0,0 +1,96 @@ +--- +description: Continue working on an existing TEDS task +--- + +# Continue TEDS Task + +Launch the **teds-executor** agent to resume work on an existing long-term task. + +## Usage + +```bash +/teds-continue task-id +``` + +## Examples + +```bash +# Continue specific task +/teds-continue 20250116-1430-refactor-auth + +# List available tasks first +/teds-status +# Then continue one +/teds-continue 20250116-1430-migrate-database +``` + +## What This Does + +The executor agent will: +1. Load TEDS configuration +2. Read all task documentation: + - `manifest.yaml` - Task info + - `plan.md` - Execution plan + - `execution_log.md` - Recent actions (last 20 entries) + - `knowledge_base.md` - Accumulated learnings + - `status.yaml` - Current state +3. Identify last completed action +4. Check for any blocked status +5. Resume from `next_action` in status.yaml +6. Continue with **mandatory logging** after every action + +## Task Recovery + +If you're resuming after a break, the agent will: +- Show you what was accomplished previously +- Identify where work stopped +- Confirm the next action before proceeding +- Catch you up on any important context + +Example output: +``` +📋 Resuming Task: refactor-auth (20250116-1430-refactor-auth) + +Last session: 2 hours ago +Progress: 45% (Phase 2: Implementation) +Last action: Created new AuthService class + +Status: Active (not blocked) +Next: Implement OAuth flow integration + +Continue with next action? [y/n] +``` + +## Mandatory Logging + +While working, the executor agent will: +- Log EVERY action to `execution_log.md` +- Update `status.yaml` on state changes +- Add discoveries to `knowledge_base.md` +- Create checkpoints every 30+ minutes + +You don't need to remind the agent to log—it's built into the system. + +## Checkpoints + +The agent automatically creates checkpoints: +- Every 30+ minutes of work +- At major milestones +- When you request: `/teds-checkpoint` + +Checkpoints are safe pause points where you can stop and resume later. + +## If Task is Blocked + +If the status shows `blocked: true`, the agent will: +1. Explain what caused the block +2. Review attempted solutions +3. Propose new approaches or ask for guidance +4. Update status once unblocked + +## Related Commands + +- `/teds-status` - View all tasks and their status +- `/teds-checkpoint` - Create a checkpoint now +- `/teds-complete [task-id]` - Finish and archive +- `/teds-start [name]` - Start a new task diff --git a/commands/teds-init.md b/commands/teds-init.md new file mode 100644 index 0000000..63cbf22 --- /dev/null +++ b/commands/teds-init.md @@ -0,0 +1,49 @@ +--- +description: Initialize TEDS configuration for this project +--- + +# TEDS Configuration Initialization + +Launch the **teds-config** agent to set up TEDS (Task Execution Documentation System) for this project. + +## What This Does + +1. Prompts for workspace directory name +2. Checks if CLAUDE.md exists in the project +3. Offers integration options (CLAUDE.md or standalone) +4. Creates initial directory structure +5. Saves configuration + +## Usage + +```bash +/teds-init +``` + +## First Time Setup + +Run this command once per project before using other TEDS commands. + +You'll be asked: +- What to name your workspace directory (default: `claude_work_space`) +- Whether to integrate with CLAUDE.md (if it exists) + +## What Gets Created + +``` +your-workspace-name/ +├── active_tasks/ # Currently running tasks +├── archived_tasks/ # Completed tasks +└── knowledge_index/ # Extracted summaries +``` + +Plus configuration in either: +- `CLAUDE.md` (recommended if file exists) +- `.teds-config.yaml` (standalone mode) + +## Next Steps + +After initialization: +1. Start your first task: `/teds-start task-name "description"` +2. Check status: `/teds-status` +3. View help: `/teds-help` (if available) diff --git a/commands/teds-start.md b/commands/teds-start.md new file mode 100644 index 0000000..6264bf3 --- /dev/null +++ b/commands/teds-start.md @@ -0,0 +1,83 @@ +--- +description: Start a new long-term task with TEDS +--- + +# Start New TEDS Task + +Launch the **teds-initializer** agent to create and initialize a new long-term task. + +## Usage + +```bash +/teds-start task-name [optional-description] +``` + +## Examples + +```bash +# Simple task +/teds-start refactor-auth + +# With description +/teds-start migrate-database "Migrate from MySQL to PostgreSQL" + +# Complex project +/teds-start implement-oauth "Implement OAuth 2.0 authentication system with Google and GitHub providers" +``` + +## What This Does + +The agent will: +1. Load TEDS configuration (from CLAUDE.md or .teds-config.yaml) +2. Generate a unique task ID (format: `YYYYMMDD-HHMM-taskname`) +3. Create complete directory structure for the task +4. Initialize all documentation files: + - `manifest.yaml` - Task metadata + - `plan.md` - Execution plan (will work with you to define) + - `execution_log.md` - Action logging + - `knowledge_base.md` - Learnings repository + - `context.md` - Background and constraints + - `status.yaml` - Current state +5. Set initial status to "active" +6. Begin planning with you + +## Task Naming Guidelines + +**Good task names**: +- `refactor-auth` - Clear and concise +- `migrate-database` - Specific action +- `implement-oauth` - Feature-focused + +**Avoid**: +- `task1` - Too generic +- `fix-bug` - Not specific enough +- `update-everything` - Too broad + +## After Initialization + +Once the task is initialized, you'll see: +``` +✅ Task initialized: 20250116-1430-refactor-auth +Location: claude_work_space/active_tasks/20250116-1430-refactor-auth/ +Status: Ready to begin +``` + +The agent will then help you: +1. Define detailed phases in `plan.md` +2. Set success criteria +3. Document context and constraints +4. Begin execution with continuous logging + +## Continuing Later + +To resume this task in a future session: +```bash +/teds-continue 20250116-1430-refactor-auth +``` + +## Related Commands + +- `/teds-status` - View all tasks +- `/teds-continue [task-id]` - Resume a task +- `/teds-checkpoint` - Save progress +- `/teds-complete [task-id]` - Finish and archive diff --git a/commands/teds-status.md b/commands/teds-status.md new file mode 100644 index 0000000..4e38647 --- /dev/null +++ b/commands/teds-status.md @@ -0,0 +1,168 @@ +--- +description: View status of TEDS tasks +--- + +# View TEDS Task Status + +Launch the **teds-status** agent to display comprehensive status of your TEDS tasks. + +## Usage + +```bash +# View all tasks +/teds-status + +# View specific task details +/teds-status task-id +``` + +## Examples + +```bash +# List all active tasks +/teds-status + +# Detailed status for one task +/teds-status 20250116-1430-refactor-auth +``` + +## All Tasks View + +When called without arguments, shows summary of all tasks: + +``` +# TEDS Tasks Status + +## Active Tasks (2) + +ID | Name | Phase | Progress | Status +----------------------------|-------------------|----------------|----------|-------- +20250116-1430-refactor-auth | refactor-auth | Implementation | 45% | active +20250115-0920-migrate-db | migrate-database | Testing | 78% | active + +## Recently Completed (1) + +ID | Name | Completed | Duration +----------------------------|-------------------|-----------------|---------- +20250114-1100-update-deps | update-deps | 2 hours ago | 3.5 hours + +Run `/teds-status [task-id]` for detailed information. +``` + +## Single Task View + +When called with a task ID, shows detailed status: + +``` +# Task Status: refactor-auth + +**ID**: 20250116-1430-refactor-auth +**Status**: Active (not blocked) +**Phase**: Phase 2 - Implementation +**Progress**: 45% +**Created**: 2025-01-16 14:30 +**Last Updated**: 2 minutes ago +**Last Checkpoint**: 45 minutes ago + +## Next Action + +Implement OAuth flow integration with Google provider + +## Recent Activity (Last 5 actions) + +### 16:45 - File Edit +- Tool: Edit +- Target: src/auth/AuthService.ts +- Result: Added OAuth configuration interface +- Status: success + +### 16:42 - File Creation +- Tool: Write +- Target: src/auth/OAuthProvider.ts +- Result: Created OAuth provider abstract class +- Status: success + +### 16:38 - Read Documentation +- Tool: Read +- Target: docs/oauth-spec.md +- Result: Reviewed OAuth 2.0 specification +- Status: success + +[... 2 more recent actions ...] + +## Key Learnings + +- Google OAuth requires web credentials, not service account +- Need to handle refresh token expiration gracefully +- PKCE extension recommended for enhanced security + +## Issues + +None - task is progressing normally + +--- + +Continue: `/teds-continue 20250116-1430-refactor-auth` +Checkpoint: `/teds-checkpoint 20250116-1430-refactor-auth` +Complete: `/teds-complete 20250116-1430-refactor-auth` +``` + +## Status Indicators + +### Task Status +- **Active**: Task is progressing normally +- **Blocked**: Task encountered an issue (shows reason) +- **Completed**: Task finished and archived + +### Progress Indicators +- **0-25%**: Early stages / Planning +- **26-50%**: Active implementation +- **51-75%**: Main work done, refinements ongoing +- **76-99%**: Final touches, testing, documentation +- **100%**: Ready to complete + +### Blocked Status + +If a task shows `blocked: true`, the status will include: +``` +⚠️ Status: BLOCKED + +Blocked Reason: Cannot connect to production database for migration testing + +Last Attempted: 30 minutes ago +Proposed Solution: Set up staging database mirror + +Action Required: User decision on staging environment setup +``` + +## Workspace Information + +The status view also shows: +``` +Workspace: claude_work_space/ +Active Tasks: 2 +Archived Tasks: 15 +Total Knowledge Entries: 47 +``` + +## Using Status for Task Management + +**Daily workflow**: +1. Morning: `/teds-status` to see all active tasks +2. Choose task: `/teds-continue [task-id]` +3. Work with continuous logging +4. Check progress: `/teds-status [task-id]` +5. End of day: `/teds-checkpoint` + +**Weekly review**: +- Review all active tasks +- Identify blocked tasks +- Archive completed tasks +- Extract learnings + +## Related Commands + +- `/teds-start [name]` - Start new task +- `/teds-continue [task-id]` - Resume task +- `/teds-checkpoint` - Save current progress +- `/teds-complete [task-id]` - Archive task diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..7b701d0 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,85 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:eternnoir/claude-tool:teds", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "92a0c2d7b8357e04403bd32e8642e52346d850af", + "treeHash": "593e3ee67c01cca6ad5cfaabe3249197a3468a506d42d301395c23c1f2b796db", + "generatedAt": "2025-11-28T10:16:49.109227Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "teds", + "description": "Task Execution Documentation System (TEDS) - Comprehensive documentation for complex, multi-session tasks", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "5ec4de8e5be3d5300770ae9a31e390e778ca21fa4c21f6a6caa8b4189ab5be78" + }, + { + "path": "agents/teds-status.md", + "sha256": "1ae988d60e451413b844d3e9c9925b0ccb60986dcc5a053225da46b64756dcec" + }, + { + "path": "agents/teds-initializer.md", + "sha256": "a34fc92cec94402a1f299bd55ed664fa9017eee6dcd8e5e48b557b01bf493508" + }, + { + "path": "agents/teds-archiver.md", + "sha256": "70c1b4ee49719e24fd6b91f2fe60d12accbaa4349e34014b4067290f9914a5ce" + }, + { + "path": "agents/teds-executor.md", + "sha256": "6c828ae40c2eee6eb7b9709b930d6aa626755e2ea673ad324acdd3bde64b2375" + }, + { + "path": "agents/teds-config.md", + "sha256": "5c4a43838f57bffb2310f0a3587d36ff929fc34d7df1dd3a54bedab89167a11a" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "fe033940d5d70229ba03d3eb9f083d1d21ccd22f07e9e04e9731c4c01bfcd992" + }, + { + "path": "commands/teds-status.md", + "sha256": "2bb0e1a9d003647828244df3a40a73e444e9fab7d4d4537d2b297db239cf4ba0" + }, + { + "path": "commands/teds-start.md", + "sha256": "0d797735ab0acec9f35253b92c9df28adef6854d85f526935e244f1228d1c34b" + }, + { + "path": "commands/teds-init.md", + "sha256": "71bfb675fa06ed364dbf11f5ab771d9f709d5a35c8a042afd1c3a66bce92a457" + }, + { + "path": "commands/teds-complete.md", + "sha256": "244570919f061f9c36e1c130f99c8e036718a67a2bec3f6232dbed4415acd91b" + }, + { + "path": "commands/teds-checkpoint.md", + "sha256": "e50d1a8a103a3dbfee3d848a7bf06d4f05744d837180c0b299b207153d804f41" + }, + { + "path": "commands/teds-continue.md", + "sha256": "fdf9e0d9a841726a3acdba97f725cc05a1386b35b69456f2e4f369f8c15b22be" + } + ], + "dirSha256": "593e3ee67c01cca6ad5cfaabe3249197a3468a506d42d301395c23c1f2b796db" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file