# Tasks and Initiatives

The autobuilder organizes work in a two-tier hierarchy: **initiatives** (product specs) contain **tasks** (one-commit work items).

## Initiatives

An initiative is a bounded product specification that describes what to build or improve. Each initiative lives in its own directory under `.autobuilder/initiatives/`.

### Structure

```
.autobuilder/initiatives/
├── 0001-social-trading/
│   ├── spec.md               # What to build (required)
│   ├── constraints.md        # Hard rules and boundaries (optional)
│   ├── review-screenshots/   # Visual evidence from reviews
│   └── tasks/
│       ├── 0001-root.md      # Root task (auto-created from spec)
│       ├── 0002-auth.md      # Sub-tasks (builder-generated)
│       └── ...
├── 0002-screener-v2/
│   ├── spec.md
│   └── tasks/
└── ...
```

### Naming Convention

Initiatives follow a `NNNN-slug` pattern (e.g., `0001-social-trading`, `0002-screener-v2`). The number is sequential, the slug is human-readable.

### spec.md

The initiative specification. This is the primary scope document that drives all reviews, planning, and execution.

```markdown
---
title: "Social Trading Platform"
---

# Social Trading Platform

## What
A real-time social trading platform that lets users follow and copy top traders.

## Objectives
1. Real-time portfolio tracking
2. One-click copy trading
3. Leaderboard with performance metrics

## Acceptance Criteria
- Users can browse and filter traders
- Copy trading executes within 500ms
- Mobile-responsive design
```

### constraints.md

Optional hard rules that the builder must follow. Common uses:
- Technology constraints (use Next.js, use Tailwind)
- Design constraints (match competitor X's UX)
- Performance requirements (Lighthouse score > 90)
- API constraints (use specific endpoints)

### Active Initiative

Only one initiative is active at a time. The active initiative is stored in `.autobuilder/active-initiative` (a plain text file containing the directory name like `0001-social-trading`).

The daemon only reviews, plans, and executes tasks within the active initiative. To switch initiatives, update the `active-initiative` file or use the `steer` skill.

## Tasks

Tasks are granular, one-commit work items stored as markdown files with YAML frontmatter.

### Task File Format

```markdown
---
id: my-app-0042-fix-chart-tooltip
title: "Fix chart tooltip positioning on mobile"
parent: my-app-0040-chart-widget
deps: [my-app-0041-chart-data]
split: false
depth: 2
planned: true
executed: false
severity: HIGH
area: Charts
---

## Problem Statement
The chart tooltip renders off-screen on viewports narrower than 375px.

## Implementation Plan
1. Add viewport boundary detection to TooltipContainer
2. Flip tooltip position when near edge
3. Add unit tests for boundary cases

## Acceptance Criteria
- Tooltip stays within viewport on 320px, 375px, 768px widths
- No layout shift when tooltip flips
```

### Frontmatter Fields

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique task identifier (project-id + number + slug) |
| `title` | string | Human-readable task title |
| `parent` | string | ID of parent task (root task or split parent) |
| `deps` | list | IDs of tasks that must complete first |
| `split` | bool | Whether this task has been split into children |
| `depth` | int | Nesting depth (0 = root, 1 = direct child, etc.) |
| `planned` | bool | Whether the task has been planned (implementation details added) |
| `executed` | bool | Whether the task has been implemented and committed |
| `severity` | string | CRITICAL, HIGH, MEDIUM, LOW (optional, set by reviewer) |
| `area` | string | Product area (optional, used for memory index grouping) |

### Task Lifecycle

```
created → planned → executed (locked)
   ↓
 split → children created
```

1. **Created** — The reviewer creates a task file with a problem statement. `planned: false`, `executed: false`.
2. **Planned** — The planner adds implementation details, architecture, and acceptance criteria. `planned: true`, `executed: false`.
3. **Executed** — The executor implements the task, commits the code, and marks `executed: true`. The task is now locked.
4. **Split** (optional) — If a task is too large, the planner sets `split: true` and creates child tasks with `parent` pointing to the original.

### Task Numbering

Tasks are numbered sequentially within an initiative's `tasks/` directory: `0001-root.md`, `0002-auth.md`, `0003-api-layer.md`, etc. The daemon tracks the next available number across iterations to prevent collisions.

### Dependencies

Tasks declare dependencies via the `deps` field. The planner uses topological sorting to determine execution order. A task cannot be executed until all its dependencies are marked `executed: true`.

### Task Template

New tasks follow the template in `skills/build-feature/TASK_TEMPLATE.md`:

```markdown
---
id: {project_id}-{number:04d}-{slug}
title: "{title}"
parent: {parent_id}
deps: [{comma_separated_dep_ids}]
split: false
depth: {depth}
planned: false
executed: false
severity: {CRITICAL|HIGH|MEDIUM|LOW}
area: {area_name}
---

## Problem Statement
{What is wrong or missing}

## Evidence
{Screenshots, error messages, test failures}

## Acceptance Criteria
{What "done" looks like}
```

## PRODUCT.md

When a project has more than one initiative, the `create-initiative` skill generates `.autobuilder/PRODUCT.md`. This file captures project-wide context:

- What the application is
- Who it's for
- Design language and conventions
- Initiative history (what was built in each initiative)
- Cross-cutting concerns

PRODUCT.md is included as reference material in every prompt but does not override the active initiative's spec.

## Memory Index

The daemon generates `.autobuilder/memory-index.md` after each iteration. This provides the agent with a compact view of:

- **Task state** — Pending, planned, executed counts
- **Area coverage** — Which product areas have tasks
- **Strategy effectiveness** — Which review strategies have been productive
- **Recent iterations** — Compact log of last N iterations
- **Initiative map** — All initiatives and their status

The memory index prevents the agent from re-discovering known issues or duplicating existing tasks.
