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.

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 task prompt A01
ds task start A01

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.

Record what happened

ds task checkpoint A01 \
  --stage validated \
  --decision promote \
  --actual-file fastapi/openapi/docs.py \
  --actual-test tests/test_custom_swagger_ui_redirect.py \
  --test "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.

Move to the next slice

ds task finish A01 --decision promote
ds task next <task-id>
ds task prompt A02

finish records lifecycle state without rewriting the human-authored task index. next returns the intended next target so a human or agent does not accidentally treat the full track as one work package.

Profiles

Profiles tune the generated scaffold. In v1.1, use:

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.