Complete syntax reference for sprint.md and roadmap.md.

Autopilot uses two manifest files, both stored under .dev/ in your project root:

Both use YAML frontmatter + markdown format. Add .dev/ to .gitignore:

.dev/

sprint.md¶

Frontmatter¶

---
name: my-project
approved: false
status: pending
max_budget_usd: 5.0
max_task_attempts: 3
worktree: false
branch_prefix: autopilot
---

Task syntax¶

Tasks are H3 headings with a checkbox, a slug ID, optional inline metadata, and a body:

### [ ] task-slug-id

Body text describing what the worker should do. Any markdown is valid.
Include file paths, acceptance criteria, implementation notes.

**Done**: A verifiable statement of what "complete" means.

---

### [ ] another-task [depends: task-slug-id]

Body text for this task.

Task ID — the text after [ ]. Must be lowercase-with-dashes and unique within the manifest.

Checkbox states:

Body — everything between the heading and the next --- separator or heading. Write it as instructions for the worker agent. Always include a **Done**: line with a verifiable criterion.

Inline metadata tags¶

Appended to the heading line. Autopilot writes retry/error tags during execution; [depends: ...] is written by you.

### [ ] my-task [depends: other-task] [attempts: 2] [status: failed] [error: exit code 1]

Full example¶

---
name: my-api
approved: true
max_budget_usd: 8.0
max_task_attempts: 3
---

# My API — Sprint 1

## Context

FastAPI service. This sprint adds JWT auth and prepares for a v0.1.0 release.

### [ ] install-deps

Install `python-jose[cryptography]` and `passlib[bcrypt]`:

```bash
uv add python-jose[cryptography] passlib[bcrypt]

Done: uv run python -c "import jose, passlib" exits 0.

[ ] implement-auth [depends: install-deps]¶

Add POST /auth/login to src/api/routes/auth.py. Accept {"email": str, "password": str}, return JWT on success, 401 on failure.

Done: pytest tests/test_auth.py -v exits 0 with all tests passing.

[x] update-readme¶

Rewrote README with install instructions and API overview.

---

## roadmap.md

### Frontmatter

```yaml
---
goal: publish
archetype: python-cli
validate:
  - uv build
  - uv run twine check dist/*
  - pip install dist/*.whl && my-tool --version
---

Body¶

The roadmap body is a human-readable shipping roadmap. The planner uses it as its primary input for task generation. Write it as a concrete plan with phases and steps:

# my-tool — PyPI Publish

**Target**: First release on PyPI at version 0.1.0.

## Current state

Core functionality is implemented. Missing: packaging metadata, docs, CI.

## Phases

### Phase 1: Packaging
- Update pyproject.toml classifiers and project URLs
- Verify `uv build` produces a clean wheel

### Phase 2: Quality
- Add ruff linting; fix violations
- Add smoke tests for CI

### Phase 3: Release
- GitHub Actions for test-on-push and publish-on-tag
- Tag v0.1.0

Notes¶

The .dev/ convention¶

All autopilot working files live under .dev/. This directory should be in .gitignore — it contains orchestration state, not source code.

.dev/
├── sprint.md           # current task manifest
├── roadmap.md          # goal + validate definition
├── sprint-log.md       # sprint history (append-only)
├── project-summary.md  # researcher output
└── research/           # topic research reports
    └── {slug}/
        └── report.md

Manifest evolution¶

sprint.md is a living document. You can:

• Add or edit tasks before they run
• Change approved back to false to re-run the judge
• Remove failed tasks or clear their metadata to retry
• Reorder tasks (dependencies are respected regardless of order)

Autopilot reads the manifest fresh on every run, so edits take effect immediately.