Initial commit

2025-11-29 18:26:21 +08:00
commit 7e9a12dd5a
14 changed files with 4186 additions and 0 deletions
--- a/agents/teds-initializer.md
+++ 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.