brain-task

name: brain-task description: Task management — create, update, list, log, and track progress for spec implementation tasks. argument-hint: " [args] — create|update|list|log|progress" allowed-tools: Glob, Read, Write, Edit, Bash

Brain Task — Task Management

Create, update, list, and log implementation tasks for specs stored in .brain-spec/tasks/.

Usage

/brain-task <subcommand> [arguments]

Subcommands:

create <slug> <title> [--parent <id>] — Create a task for a spec
update <slug> <id> [--status <s>] [--progress <n>] — Update a task
list <slug> [--status <s>] — List tasks for a spec
log <slug> <id> — Log implementation details for a completed task
progress [slug] — Show aggregated progress for one or all specs

Instructions

Parse $ARGUMENTS to determine the subcommand. The first word is the subcommand; remaining words are arguments. Parse --flag value style options.

Reference: Task Schema

Tasks are stored in .brain-spec/tasks/{slug}/tasks.json:

{
  "specSlug": "string",
  "tasks": [
    {
      "id": "string (hierarchical: 1, 2, 2.1, 2.2)",
      "title": "string",
      "description": "string",
      "status": "pending | in-progress | completed",
      "parentTaskId": "string | null",
      "acceptanceCriteria": ["string"],
      "requirements": ["string"],
      "leverage": "string",
      "files": ["string"],
      "prompt": "string",
      "progress": 0,
      "notes": "string",
      "createdAt": "ISO 8601",
      "updatedAt": "ISO 8601"
    }
  ]
}

Reference: ID Generation Algorithm

Top-level tasks: Find the highest existing top-level ID (integer), increment by 1. First task is "1".
Subtasks: Given parent ID (e.g., "2"), find siblings under that parent, take the highest sub-ID, increment. Example: if "2.1" and "2.2" exist, next is "2.3".
IDs are strings, not numbers. "1", "2", "1.1", "1.2", "2.1" etc.

Reference: Implementation Log Template

Logs are written to .brain-spec/tasks/{slug}/logs/{id}.log.md:

# Implementation Log — Task {id}

## Summary
{summary}

## Git Reference
- **Commit**: {commitSha}
- **Branch**: {branch}
- **Date**: {timestamp}
- **Session**: ${CLAUDE_SESSION_ID}

## Files Changed
### Modified
- `{file}`

### Created
- `{file}`

## Code Statistics
- Lines Added: {linesAdded}
- Lines Removed: {linesRemoved}
- Files Changed: {totalFiles}

## Artifacts
### API Endpoints
- **{METHOD}** `{path}` — {purpose}

### Functions
- `{name}` — {purpose}
  - Signature: `{signature}`
  - Exported: yes/no
  - Module: `{module}`

### Classes
- `{name}` — {purpose}
  - Methods: {methods}
  - Module: `{module}`

### UI Components
- `{name}` — {purpose}
  - Props: {props}
  - Module: `{module}`

### Integrations
- {from} → {to}

## Notes
{notes}

Only include sections that have content. Omit empty sections.

Subcommand: `create`

Usage: /brain-task create my-feature "Implement login form" or /brain-task create my-feature "Add validation" --parent 1

Verify .brain-spec/tasks/ exists. If not, tell user to run /brain-init.
Verify the spec exists by checking .brain-spec/specs/{slug}.meta.json. If not found, error.
Create .brain-spec/tasks/{slug}/ directory if it doesn't exist.
Read .brain-spec/tasks/{slug}/tasks.json or create a new one if it doesn't exist:
```
{ "specSlug": "{slug}", "tasks": [] }
```
Parse the title (text after the slug, optionally in quotes).
Parse --parent <id> if present.
Generate the task ID using the ID generation algorithm.
Ask the user for optional details:
- Description (or skip)
- Acceptance criteria (or skip)
Create the task object with defaults:
- status: "pending"
- progress: 0
- parentTaskId: from --parent or null
- createdAt/updatedAt: current ISO timestamp
- All other string fields: empty string
- All other array fields: empty array
Append to the tasks array, write tasks.json.
Display: "Task {id} created: {title}" with the file path.

Subcommand: `update`

Usage: /brain-task update my-feature 1 --status in-progress or /brain-task update my-feature 1.2 --progress 75

Read .brain-spec/tasks/{slug}/tasks.json. If not found, error.
Find the task by ID. If not found, error with available IDs.
Parse flags:
- --status <pending|in-progress|completed>: Update status. If set to "completed", also set progress to 100.
- --progress <0-100>: Update progress percentage.
- --notes <text>: Append to notes.
If no flags provided, show current task details and ask the user what they want to update.
Update updatedAt timestamp.
Save tasks.json.
Display updated task summary.

Subcommand: `list`

Usage: /brain-task list my-feature or /brain-task list my-feature --status pending

Read .brain-spec/tasks/{slug}/tasks.json. If not found, show "No tasks for spec '{slug}'."
If --status provided, filter tasks.
Display a formatted table with indentation for subtasks:

ID    Title                    Status        Progress
────  ───────────────────────  ────────────  ──────────────────
1     Implement login form     in-progress   ━━━━━━━━━─────────  50%
1.1   Add email validation     completed     ━━━━━━━━━━━━━━━━━━ 100%
1.2   Add password rules       pending       ──────────────────   0%
2     Design API endpoints     pending       ──────────────────   0%

Progress bar: Use ━ for filled and ─ for empty, 18 characters wide. Calculate fill: round(progress / 100 * 18).

Subtasks (IDs containing ".") should be indented with 2 spaces.

After the table, show summary: "{completed}/{total} tasks completed ({percentage}%)"

Subcommand: `log`

Usage: /brain-task log my-feature 1

Create an implementation log for a task, documenting what was done.

Read .brain-spec/tasks/{slug}/tasks.json. Find the task by ID. If not found, error.
Create .brain-spec/tasks/{slug}/logs/ directory if it doesn't exist.
Auto-enrich with git data: Run git status --porcelain first to determine which path applies. The dirty/clean state changes both the diff range and which commit metadata is meaningful:
- Dirty working tree (output non-empty — task logged before commit):
  - git rev-parse --abbrev-ref HEAD — current branch
  - Commit SHA: omit (no relevant commit yet) and use the current timestamp instead of a commit timestamp
  - Diff range for file detection: git diff --name-only (unstaged) and git diff --name-only --cached (staged)
- Clean working tree (output empty — task logged after commit):
  - git rev-parse HEAD — current commit SHA (the commit that finished the task)
  - git rev-parse --abbrev-ref HEAD — current branch
  - git log -1 --format=%cI HEAD — that commit's ISO timestamp
  - Diff range for file detection: HEAD~1..HEAD
- If any command fails (not a git repo), omit the Git Reference section entirely.
Ask the user for log details. Pre-fill Files modified and Files created by auto-detecting from the diff range chosen in step 3 (git diff --name-only for dirty, git diff --name-only HEAD~1..HEAD for clean) — confirm with the user before saving:
- Summary: What was implemented? (required)
- Files modified: Which existing files were changed? (auto-detected; user confirms or edits)
- Files created: Which new files were added? (auto-detected via git diff --name-only --diff-filter=A over the same range)
- Artifacts: Any endpoints, functions, classes, components, or integrations created? (optional, ask one at a time)
- Notes: Any additional notes?
Build the log markdown using the template above, omitting empty sections.
Write to .brain-spec/tasks/{slug}/logs/{id}.log.md.
Update the task: set status to "completed", progress to 100, update updatedAt.
Save tasks.json.
Display: "Implementation log saved to .brain-spec/tasks/{slug}/logs/{id}.log.md" and "Task {id} marked as completed."

Subcommand: `progress`

Usage: /brain-task progress or /brain-task progress my-feature

If a slug is provided:
- Read .brain-spec/tasks/{slug}/tasks.json. Calculate and display progress for that spec.
If no slug:
- Use Glob to find all .brain-spec/tasks/*/tasks.json files.
- Read each one and calculate progress.
- Display aggregated progress across all specs.
For each spec, calculate:
- Total tasks (count)
- Completed tasks (status === "completed")
- In-progress tasks (status === "in-progress")
- Pending tasks (status === "pending")
- Completion percentage: (completed / total * 100) or 0 if no tasks
Display format:

Single spec:

Progress: my-feature
━━━━━━━━━━━━━━━━━━━━ 60% (3/5 tasks)

  Completed:   3 tasks
  In Progress: 1 task
  Pending:     1 task

Progress bar: 20 characters wide. Use ━ for filled, ─ for empty.

All specs:

Overall Progress

my-feature      ━━━━━━━━━━━━━━━━━━━━ 60% (3/5)
api-redesign    ━━━━━━━━━━──────────── 25% (1/4)
user-auth       ━━━━━━━━━━━━━━━━━━━━ 100% (2/2)

Total: 6/11 tasks completed (55%)