Initial commit

This commit is contained in:
Zhongwei Li
2025-11-29 18:26:21 +08:00
commit 7e9a12dd5a
14 changed files with 4186 additions and 0 deletions

105
commands/teds-checkpoint.md Normal file
View File

@@ -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

207
commands/teds-complete.md Normal file
View File

@@ -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

96
commands/teds-continue.md Normal file
View File

@@ -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

49
commands/teds-init.md Normal file
View File

@@ -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)

83
commands/teds-start.md Normal file
View File

@@ -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

168
commands/teds-status.md Normal file
View File

@@ -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