diff --git a/AGENTS.md b/AGENTS.md index 9c56211..fb55b92 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,15 @@ You are an expert Software Engineer working on this project. Your primary respon ## Core Philosophy **"If it's not documented in `docs/tasks/`, it didn't happen."** +## Superpowers Workflows +To improve feature completeness, this repository integrates a sequence of rigorous software engineering workflows known as the "Superpowers": +- **Brainstorming:** `python3 scripts/design.py brainstorm --title "Feature" ...` +- **Workspace Setup:** `python3 scripts/workspace.py setup [TASK_ID]` +- **Micro Planning:** `scripts/tasks.py breakdown [TASK_ID]` +- **TDD Enforcement:** `python3 scripts/tdd.py state`, `python3 scripts/tdd.py run`, `python3 scripts/tdd.py reset` +- **Orchestration:** `python3 scripts/orchestrator.py run`, `python3 scripts/orchestrator.py assign`, `python3 scripts/orchestrator.py monitor` +- **Local Review:** Pre-PR automated review via `scripts/review.py` (coming soon) + ## Workflow 1. **Pick a Task**: Run `python3 scripts/tasks.py next` to find the best task, `context` to see active tasks, or `list` to see pending ones. 2. **Plan & Document**: diff --git a/docs/tasks/GUIDE.md b/docs/tasks/GUIDE.md new file mode 100644 index 0000000..744c298 --- /dev/null +++ b/docs/tasks/GUIDE.md @@ -0,0 +1,133 @@ +# Task Documentation System Guide + +This guide explains how to create, maintain, and update task documentation. It provides a reusable system for tracking implementation work, decisions, and progress. + +## Core Philosophy +**"If it's not documented in `docs/tasks/`, it didn't happen."** + +## Directory Structure +Tasks are organized by category in `docs/tasks/`: +- `foundation/`: Core architecture and setup +- `infrastructure/`: Services, adapters, platform code +- `domain/`: Business logic, use cases +- `presentation/`: UI, state management +- `features/`: End-to-end feature implementation +- `migration/`: Refactoring, upgrades +- `testing/`: Testing infrastructure +- `review/`: Code reviews and PR analysis + +## Task Document Format + +We use **YAML Frontmatter** for metadata and **Markdown** for content. + +### Frontmatter (Required) +```yaml +--- +id: FOUNDATION-20250521-103000 # Auto-generated Timestamp ID +status: pending # Current status +title: Initial Project Setup # Task Title +priority: medium # high, medium, low +created: 2025-05-21 10:30:00 # Creation timestamp +category: foundation # Category +type: task # task, story, bug, epic (Optional) +sprint: Sprint 1 # Iteration identifier (Optional) +estimate: 3 # Story points / T-shirt size (Optional) +dependencies: TASK-001, TASK-002 # Comma separated list of IDs (Optional) +--- +``` + +### Status Workflow +1. `pending`: Created but not started. +2. `in_progress`: Active development. +3. `review_requested`: Implementation done, awaiting code review. +4. `verified`: Reviewed and approved. +5. `completed`: Merged and finalized. +6. `wip_blocked` / `blocked`: Development halted. +7. `cancelled` / `deferred`: Stopped or postponed. + +### Content Template +```markdown +# [Task Title] + +## Task Information +- **Dependencies**: [List IDs] + +## Task Details +[Description of what needs to be done] + +### Acceptance Criteria +- [ ] Criterion 1 +- [ ] Criterion 2 + +## Implementation Status +### Completed Work +- ✅ Implemented X (file.py) + +### Blockers +[Describe blockers if any] +``` + +## Tools + +Use the `scripts/tasks` wrapper to manage tasks. + +```bash +# Create a new task (standard) +./scripts/tasks create foundation "Task Title" + +# Create an Agile Story in a Sprint +./scripts/tasks create features "User Login" --type story --sprint "Sprint 1" --estimate 5 + +# List tasks (can filter by sprint) +./scripts/tasks list +./scripts/tasks list --sprint "Sprint 1" + +# Find the next best task to work on (Smart Agent Mode) +./scripts/tasks next + +# Update status +./scripts/tasks update [TASK_ID] in_progress +./scripts/tasks update [TASK_ID] review_requested +./scripts/tasks update [TASK_ID] verified +./scripts/tasks update [TASK_ID] completed + +# Migrate legacy tasks (if updating from older version) +./scripts/tasks migrate +``` + +## Superpowers Workflows + +The system has been enhanced with several integrated workflow commands to guide feature development: + +- **Brainstorming:** `python3 scripts/design.py brainstorm --title "Feature" ...` +- **Workspace Setup:** `python3 scripts/workspace.py setup [TASK_ID]` +- **Micro Planning:** `scripts/tasks.py breakdown [TASK_ID]` +- **TDD Enforcement:** `python3 scripts/tdd.py state`, `python3 scripts/tdd.py run`, `python3 scripts/tdd.py reset` +- **Orchestration:** `python3 scripts/orchestrator.py run`, `python3 scripts/orchestrator.py assign`, `python3 scripts/orchestrator.py monitor` +- **Local Review:** Pre-PR automated review via `scripts/review.py` (coming soon) + +## Agile Methodology + +This system supports Agile/Scrum workflows for LLM-Human collaboration. + +### Sprints +- Tag tasks with `sprint: [Name]` to group them into iterations. +- Use `./scripts/tasks list --sprint [Name]` to view the sprint backlog. + +### Estimation +- Use `estimate: [Value]` (e.g., Fibonacci numbers 1, 2, 3, 5, 8) to size tasks. + +### Auto-Pilot +- The `./scripts/tasks next` command uses an algorithm to determine the optimal next task based on: + 1. Status (In Progress > Pending) + 2. Dependencies (Unblocked > Blocked) + 3. Sprint (Current Sprint > Backlog) + 4. Priority (High > Low) + 5. Type (Stories/Bugs > Tasks) + +## Agent Integration + +Agents (Claude, etc.) use this system to track their work. +- Always check `./scripts/tasks context` or use `./scripts/tasks next` before starting. +- Keep the task file updated with your progress. +- Use `review_requested` when you need human feedback. diff --git a/docs/tasks/features/FEATURES-20260305-171438-HMD-update-agentsmd-and-docstasksguidemd-to-reflect-new-workflows.md b/docs/tasks/features/FEATURES-20260305-171438-HMD-update-agentsmd-and-docstasksguidemd-to-reflect-new-workflows.md index 1b56e3f..6a56874 100644 --- a/docs/tasks/features/FEATURES-20260305-171438-HMD-update-agentsmd-and-docstasksguidemd-to-reflect-new-workflows.md +++ b/docs/tasks/features/FEATURES-20260305-171438-HMD-update-agentsmd-and-docstasksguidemd-to-reflect-new-workflows.md @@ -1,6 +1,6 @@ --- id: FEATURES-20260305-171438-HMD -status: pending +status: completed title: Update AGENTS.md and docs/tasks/GUIDE.md to reflect new workflows priority: medium created: 2026-03-05 17:14:38