Task Flow

Use ds task when you are starting a change and want the next agent session to stay inside one clear unit of work.

Epics, stories, and tickets describe intended work. DevSpecs records the local AI execution loop underneath them: the prompt boundary, packed repo context, attempt, evidence, decision, and any follow-up iteration.

Create a task

ds task "Serve Swagger UI OAuth2 redirect from a custom docs redirect URL" \
  --profile code-change \
  --slice "Trace Swagger UI OAuth2 redirect flow and tests" \
  --slice "Wire custom docs redirect URL through FastAPI docs helpers" \
  --slice "Add regression coverage and docs examples"

DevSpecs creates a task index and one plan/result pair per slice:

A00  Task index
A01  Trace Swagger UI OAuth2 redirect flow and tests
A02  Wire custom docs redirect URL through FastAPI docs helpers
A03  Add regression coverage and docs examples

Each slice gets packed context: likely source files, likely tests, related docs, evidence receipts, exclusions, and a decision gate.

Start one slice

ds task show A01
ds apply

When the next slice is unambiguous, ds apply is enough. The prompt is intentionally bounded. It tells the agent to work on A01, avoid later slices, run the slice's acceptance checks, and stop with a result.

Use ds apply <task-id> --target A01 when you need to address a specific task or target explicitly.

Record what happened

ds task checkpoint A01 \
  --stage validated \
  --decision promote \
  --file-edited fastapi/openapi/docs.py \
  --test-read tests/test_custom_swagger_ui_redirect.py \
  --test-run "pytest tests/test_custom_swagger_ui_redirect.py"

Checkpoints preserve what the agent actually touched, what tests were run, what was missed, and whether the next move should promote, improve, rework, rollback, or block.

Iterate before moving on

Not every slice should promote on the first attempt. If A01 exposes a missing file, weak test, wrong assumption, or visual/product miss, keep the follow-up under the same slice instead of drifting into A02 or creating a disconnected task.

A01    Trace Swagger UI OAuth2 redirect flow and tests
A01-1  Cover missing redirect edge case found during A01
A01-2  Rework failing docs-helper assumption
A02    Wire custom docs redirect URL through FastAPI docs helpers

Record the learning, create an iteration plan/result pair, then ask for the next bounded prompt:

ds task checkpoint A01 \
  --stage validated \
  --decision improve \
  --learning "test-gap|Swagger redirect edge case was not covered|high|A01|tests/test_custom_swagger_ui_redirect.py" \
  --missed-file tests/test_custom_swagger_ui_redirect.py \
  --next-target A01-1

ds task slice add <task-id> \
  "Cover missing redirect edge case found during A01" \
  --after A01 \
  --reason improve

ds apply

Use improve when the direction is right but incomplete. Use rework when the slice needs a new approach before it can promote. Once the iteration passes, promote the parent path and continue to the next planned slice.

Move to the next slice

ds task checkpoint <task-id> \
  --target A01 \
  --stage validated \
  --decision promote \
  --next-target A02

ds task next <task-id>
ds apply

checkpoint records lifecycle state without rewriting the human-authored task index. next returns the intended next target, and apply emits the bounded prompt so a human or agent does not accidentally treat the full track as one work package.

Profiles

Profiles tune the generated scaffold. Currently available profiles are:

Profile	Use
`code-change`	Default source/test implementation work.
`greenfield`	Planning-heavy work where code targets may not exist yet.

More profiles can be added later, but the artifact shape should stay stable.

Create a task​

Start one slice​

Record what happened​

Iterate before moving on​

Move to the next slice​

Profiles​