Skip to content
FSS Knowledge Base

TASKS.md Template

Section titled “TASKS.md Template”

Templates for per-project task specification files. Use with Superpowers, headless mode, or manual task tracking.

Template 1: Feature Development (Superpowers-Compatible)

Section titled “Template 1: Feature Development (Superpowers-Compatible)”
# Project Tasks


> Generated: YYYY-MM-DD
> Status: [Planning | In Progress | Testing | Complete]


## Current Sprint


### Feature: [Feature Name]


**Context:**
[Brief description of what this feature does and why it's needed]


**Acceptance Criteria:**
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3


**Tasks:**
- [ ] Write failing tests for [component]
- [ ] Verify tests fail (RED)
- [ ] Implement minimal [component] logic
- [ ] Verify tests pass (GREEN)
- [ ] Refactor if needed
- [ ] Commit with message: "feat: [description]"
- [ ] Integration test across [systems]
- [ ] Update documentation


**Dependencies:**
- Blocked by: [Task name or #ID]
- Blocks: [Task name or #ID]


**Notes:**
[Any technical decisions, trade-offs, or context]


---


### Bug Fix: [Bug Name]


**Problem:**
[What's broken and how it manifests]


**Root Cause:**
[What investigation revealed]


**Fix:**
- [ ] Write regression test reproducing bug
- [ ] Verify test fails with current code
- [ ] Implement fix in [file:line]
- [ ] Verify test passes
- [ ] Check for similar patterns in [related files]
- [ ] Commit with message: "fix: [description]"


---


## Backlog


- [ ] [Task description] - [Est: Xh]
- [ ] [Task description] - [Est: Xh]


---


## Completed


- [x] [Completed task] - YYYY-MM-DD
- [x] [Completed task] - YYYY-MM-DD

Template 2: Overnight Autonomous Run (Ralph Loop)

Section titled “Template 2: Overnight Autonomous Run (Ralph Loop)”
# Autonomous Task List


> Run Date: YYYY-MM-DD
> Target: Overnight execution via ralph-loop
> Est. Duration: 6-8 hours
> Max Iterations: 50


## Success Criteria


All tasks below completed with:
- Tests passing
- No grep matches for stale references
- Atomic commit per task
- No manual intervention required


## Tasks


### 1. Refactor Authentication Module


**Goal:** Extract auth logic into standalone service


**Steps:**
- [ ] Create new AuthService class in `services/auth_service.py`
- [ ] Move login logic from views.py to AuthService
- [ ] Update unit tests to mock AuthService
- [ ] Run full test suite: `pytest tests/`
- [ ] Commit: "refactor: extract auth logic into AuthService"


**Completion Check:**
```bash
pytest tests/auth/ && grep -r "TODO_AUTH" src/

2. Update Deprecated API Calls

Section titled “2. Update Deprecated API Calls”

Goal: Replace old API v1 calls with v2

Steps:

  • Find all v1 API calls: grep -r "api/v1" src/
  • Replace with v2 equivalents per migration guide
  • Update response parsing for new schema
  • Run integration tests: pytest tests/integration/
  • Commit: “chore: migrate from API v1 to v2”

Completion Check:

Terminal window
! grep -r "api/v1" src/ && pytest tests/integration/

3. Generate Missing Documentation

Section titled “3. Generate Missing Documentation”

Goal: Add docstrings to all public methods in core/ module

Steps:

  • Scan for missing docstrings: pylint --disable=all --enable=missing-docstring core/
  • Add Google-style docstrings to each flagged method
  • Generate API docs: sphinx-build -b html docs/ docs/_build/
  • Commit: “docs: add docstrings to core module”

Completion Check:

Terminal window
pylint --disable=all --enable=missing-docstring core/ && test -f docs/_build/index.html

Rollback Plan

Section titled “Rollback Plan”

If any task fails after 3 attempts:

  1. Commit current progress with WIP: prefix
  2. Create OVERNIGHT_FAILURES.md with error details
  3. Stop execution (do NOT continue to next task)

Morning Review Checklist

Section titled “Morning Review Checklist”
  • Check git log for commits
  • Run full test suite manually
  • Review code changes for quality
  • Check OVERNIGHT_FAILURES.md if exists
  • Update this file with lessons learned
---


## Template 3: Simple Checklist (Lightweight)


```markdown
# Tasks


## Today
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3


## This Week
- [ ] Task 4
- [ ] Task 5


## Backlog
- [ ] Task 6
- [ ] Task 7


## Done
- [x] Previous task - 2026-02-08

Usage Guidelines

Section titled “Usage Guidelines”

When to Use Which Template

Section titled “When to Use Which Template”
TemplateUse CaseTool Compatibility
Feature DevelopmentInteractive sessions, complex features requiring TDDSuperpowers, manual
Overnight AutonomousBatch operations, refactors, bulk changesRalph Loop, headless CC
Simple ChecklistKB work, quick tasks, personal projectsManual, /ptr command

Best Practices

Section titled “Best Practices”
  1. One TASKS.md per project - Lives in project root, version-controlled
  2. Clear completion criteria - Each task should have verifiable done state
  3. Atomic tasks - Each task = one commit (aids git bisect, rollback)
  4. Include test commands - Make verification automated and repeatable
  5. Link to context - Reference design docs, issues, or requirements

Integration with _Now/_Next Workflow

Section titled “Integration with _Now/_Next Workflow”

_Now.md points to projects:

- Monorepo: see TASKS.md
- Python utils: see TASKS.md
- KB: reorganize 04_AI/ (no TASKS.md needed, simple work)

Next*.md captures cross-project insights:

Source: _Now.md -- "Completed monorepo auth refactor"


## Lessons Learned
- Ralph loop completed 8/10 tasks overnight
- Failed on task 9 due to test environment issue
- Solution: Add env setup check to task 1

Advanced: Multi-Project Coordination

Section titled “Advanced: Multi-Project Coordination”

For complex work spanning multiple repos:

Meta-TASKS.md
## Project: Launch Marketing Site


### Backend (api-repo)
- [ ] See `api-repo/TASKS.md`
- Dependency: Must complete before frontend


### Frontend (web-repo)
- [ ] See `web-repo/TASKS.md`
- Blocked by: Backend API endpoints


### Infrastructure (infra-repo)
- [ ] See `infra-repo/TASKS.md`
- Parallel: Can run alongside backend/frontend

Then use CC Native TaskCreate with addBlockedBy for coordination across parallel agents.

Resources

Section titled “Resources”