Skip to content

task-format.md

Latest commit

 

History

History
317 lines (210 loc) · 5.3 KB

task-format.md

File metadata and controls

317 lines (210 loc) · 5.3 KB

Task Format Reference (PROMPT.md + STATUS.md)

Taskplane tasks are file-based packets.

Canonical folder:

<task-folder>/
├── PROMPT.md    # task definition
├── STATUS.md    # execution state / memory
├── .reviews/    # reviewer outputs (created by runner)
└── .DONE        # completion marker

PROMPT.md format

Recommended top-level structure

# Task: <ID> — <Name>

**Created:** YYYY-MM-DD
**Size:** S|M|L

## Review Level: 0|1|2|3

## Mission
...

## Dependencies
- **None**
# or dependency list

## Context to Read First
- `path/to/doc.md`

## File Scope
- `src/file.ts`

## Steps
### Step 0: Name
- [ ] checklist item
- [ ] checklist item

### Step 1: Name
- [ ] ...

## Completion Criteria
- [ ] ...

---

## Amendments (Added During Execution)

Required vs optional data

Required (practical)

  • A parseable task ID (prefer heading format)
  • At least one step in ### Step N: ... format
  • Checkbox items (- [ ]) inside steps

Optional but strongly recommended

  • ## Review Level: N
  • **Size:** S|M|L
  • ## Dependencies
  • ## Context to Read First
  • ## File Scope
  • ## Segment DAG (optional, for explicit multi-repo segment ordering)
  • ## Completion Criteria

If omitted, parsers apply defaults in some paths (for example size/review defaults).

Heading and ID conventions

Preferred heading:

# Task: AUTH-014 — Add role checks

Notes:

  • Orchestrator parser prefers # Task: <ID> - <Name> style and falls back to folder name ID extraction.
  • Task-runner parser is more permissive and can also parse # <ID> - <Name>.
  • For consistent behavior across /task and /orch, always use # Task: <ID> — <Name>.

Folder name convention:

AUTH-014-add-role-checks

Step/checklist expectations

Steps must use:

### Step <number>: <name>

Checklist items must use markdown checkbox syntax:

- [ ] Do thing
- [x] Done thing

Task-runner executes by scanning for the first unchecked checkbox in current scope.

Segment markers (multi-repo tasks)

When a task spans multiple repos, use level-4 headings within each step to assign checkboxes to specific repos:

### Step 1: Create utilities and API client

#### Segment: shared-libs

- [ ] Create string utility module
- [ ] Export from package index

#### Segment: web-client

- [ ] Add API client wrapper
- [ ] Wire into app initialization

Rules:

  • Marker format: #### Segment: <repoId> (case-sensitive, must match workspace config)
  • Single-repo tasks do not need segment markers (the engine applies a default)
  • Every step in a multi-repo task should have explicit segment markers
  • The final documentation/delivery step uses the packet repo (the repo containing PROMPT.md)

Dependency notation

Use ## Dependencies section.

Accepted forms include:

None

## Dependencies
- **None**

Unqualified IDs

## Dependencies
- AUTH-003
- BIL-002

Area-qualified IDs

## Dependencies
- auth/AUTH-003
- billing/BIL-002

Requires line

## Dependencies
**Requires:** AUTH-003
**Requires:** billing/BIL-002

Recommendations:

  • Use area-qualified IDs in larger multi-area projects.
  • Keep dependency IDs canonical (PREFIX-NNN).

Context to Read First conventions

Example:

## Context to Read First
- `README.md`
- `docs/architecture.md`

Use backticked file paths. Keep list minimal and task-relevant.

File Scope conventions

Example:

## File Scope
- `extensions/taskplane/engine.ts`
- `.pi/task-orchestrator.yaml`

Describe intended modification surface to improve planning/review quality.

Segment DAG (optional explicit multi-repo ordering)

Use when a task intentionally spans multiple repos and needs explicit intra-task ordering.

## Segment DAG

Repos:
- api
- web-client

Edges:
- api -> web-client

Notes:

  • Optional section — omission keeps legacy behavior.
  • Repos: and Edges: keys may be markdown-decorated (e.g. **Repos:**).
  • Repo IDs are normalized to lowercase.
  • Edge endpoints must appear in Repos:.
  • Self-edges and cycles are invalid and fail discovery.

STATUS.md format (execution memory)

STATUS.md tracks runtime progress. It is updated continuously by task-runner.

Typical header fields:

**Current Step:** ...
**Status:** ...
**Last Updated:** ...
**Review Level:** ...
**Review Counter:** ...
**Iteration:** ...
**Size:** ...

Per-step sections mirror PROMPT.md steps and track checkbox completion.

Task-runner can auto-generate STATUS.md from PROMPT.md if missing.

Divider rule (---)

Use a divider before amendments:

---

## Amendments (Added During Execution)

Treat content above divider as canonical task definition.

Minimal valid example

# Task: TP-001 — Add greeting endpoint

**Created:** 2026-03-14
**Size:** S

## Review Level: 1

## Mission
Add a small HTTP endpoint that returns a greeting.

## Dependencies
- **None**

## Steps
### Step 0: Implement
- [ ] Add endpoint handler
- [ ] Register route

### Step 1: Verify
- [ ] Run unit tests

## Completion Criteria
- [ ] Endpoint responds with 200 and expected payload

---

## Amendments (Added During Execution)

Related