devspecs

Scope keeps expanding?

Keep the agent inside one bounded change

Leave one slice with the agent while you work elsewhere, then return to evidence without granting the rest of the task track.

Starting state

One pinned repository. One concrete goal.

Prepare one agent-ready handoff without granting the whole task track.

  • +The goal is known, but implementation scope is not yet granted.
  • +The developer wants to work elsewhere while the agent owns F02 only.
  • +The FastAPI checkout is pinned and indexed before the workflow starts.
  • +DevSpecs prepares the handoff; an external coding agent makes the edit.
Repository
fastapi/fastapi
Commit
3d2aace4
DevSpecs
v1.3

DevSpecs entry

ds task "Protect custom OAuth redirect behavior" --slice ...
DeveloperDevSpecsCoding agent

Scope control

Keep a failed attempt from silently becoming the next step.

One slice goes to the agent, so you can work elsewhere without granting the rest of the task track. When you return, evidence decides whether the task advances, iterates, changes approach, rolls back, or stops.

An attempt can look complete too early.Evidence chooses the next move.
  1. 01

    Goal

    Protect OAuth redirect behavior

    ds task "Protect custom Swagger UI OAuth2 redirect behavior" --slice ...

    Human or agent shapes the goal and slices.

  2. 02

    Task + slices

    Only F02 is active

    F01validated

    Trace behavior

    F02active

    Add regression

    F03planned

    Document cleanup

    F00 keeps the track; every slice keeps its own gate.

  3. 03

    Bounded handoff

    The prompt names where to stop

    ds apply fastapi-oauth-redirect --target F02
    target
    F02 only
    source
    fastapi/applications.py
    test
    tests/test_custom_swagger_ui_redirect.py
    stop
    checkpoint after validation

    Your coding agent

    Codex, Cursor, Claude, or a terminal agent executes the handoff.

    DevSpecs emits the boundary.

  4. 04

    Checkpointed evidence

    The attempt returns receipts

    read
    fastapi/applications.py
    read
    fastapi/openapi/docs.py
    edited
    tests/test_custom_swagger_ui_redirect.py
    tested
    3 focused tests passed
    learned
    custom route stays out of OpenAPI

    Checkpoint what the agent read, edited, tested, and learned.

  5. 05

    Decision gate

    Evidence earns the next move

    • promotecontinue to F03
    • improvecreate F02-1 under F02
    • reworkretry F02 with a changed approach
    • rollbackreverse or abandon the attempt
    • blockwait for an external decision

    Failure never advances automatically.

The agent gets freedom inside F02. The team keeps control over what F02 is allowed to become.

Workflow

STEP 1 OF 5

Name the slices up front

Developer

Give the task a durable shape before asking an agent to edit. Each `--slice` becomes a separate plan and result pair.

Command

ds task "Protect custom Swagger UI OAuth2 redirect behavior" --id fastapi-oauth-redirect --series F --no-refresh --slice "Trace current custom OAuth2 redirect behavior and tests" --slice "Add OpenAPI exclusion regression for the custom redirect route" --slice "Document custom redirect configuration and finish cleanup"
CLI output
F01 Trace current behavior and tests
F02 Add OpenAPI exclusion regression
F03 Document configuration and cleanup
Warningtwo redirect tests matched on disk but were not indexed
Pack completenesslow

What this tells you

The task boundary is useful, and the warning names the candidate tests that still need manual verification before editing.

Continue with

Trace the warned source and tests before promoting F01.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Normalized task creation JSON · 05-task-create.stdout.txt

STEP 2 OF 5

Carry verified leads into F02

DevSpecs

Checkpoint what F01 actually read, then promote only that slice. The next prompt can use those receipts without widening scope.

Command

ds task checkpoint fastapi-oauth-redirect --target F01 --stage validated --decision promote --next-target F02
CLI output
F01 validated · promote
Next targetF02
Prior sourcefastapi/applications.py, fastapi/openapi/docs.py
Prior teststest_custom_swagger_ui_redirect.py, test_no_swagger_ui_redirect.py

What this tells you

F01 records evidence and earns promotion for that slice only. F02 and F03 keep their own gates.

Continue with

Emit the F02-only handoff.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Normalized F01 checkpoint JSON · 06-checkpoint-f01.stdout.txt

STEP 3 OF 5

Get one bounded prompt

DevSpecs

Resolve F02 and include the prior checkpoint leads, sibling exclusions, acceptance checks, and completion contract.

Command

ds apply fastapi-oauth-redirect --target F02
CLI output
TargetF02 only
Do not implement F01, F03, or the full task track
Verify prior source and test leads before editing
Stop with promote, improve, rework, rollback, or block

What this tells you

`ds apply` prints the next handoff for your chosen coding agent, including scope limits and acceptance checks.

Continue with

Give this prompt to the coding agent that will make the edit.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Normalized F02 apply JSON · 12-apply-f02.stdout.txt

STEP 4 OF 5

Implement and test only F02

Coding agent

Add one explicit assertion that the custom OAuth2 redirect route is absent from OpenAPI paths, then run the focused test file.

Command

uv run pytest tests/test_custom_swagger_ui_redirect.py
CLI output
collected 3 items
tests/test_custom_swagger_ui_redirect.py ... [100%]
3 passed in 1.54s

What this tells you

The bounded test change passes. Dependency installation happened beforehand and sits outside the DevSpecs execution timing.

Continue with

Checkpoint the observed edit and test command.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Normalized focused test output · 19-focused-test.stdout.txt

STEP 5 OF 5

Promote from evidence

DevSpecs

Record the edited test, focused command, decision, and next target after the external agent finishes.

Command

ds task checkpoint fastapi-oauth-redirect --target F02 --stage validated --decision promote --next-target F03
CLI output
F02 validated · promote
Editedtests/test_custom_swagger_ui_redirect.py
Testuv run pytest tests/test_custom_swagger_ui_redirect.py
Next targetF03

What this tells you

F02 is complete enough to advance. F03 remains a separate documentation slice.

Continue with

Continue with F03 later, or stop with the repository in a legible state.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Normalized F02 checkpoint JSON · 20-checkpoint-f02.stdout.txt

Result

One test-only slice moved from a stated goal to a passing focused test and an explicit promote decision. Verified F01 evidence carried into F02; F03 stayed outside the implementation boundary.

  • F00-index.md
  • F01-...-plan.md + result.md
  • F02-...-plan.md + result.md
  • F03-...-plan.md + result.md
  • task.json
  • checkpoints/<timestamp>-validated.md

Common failure

Trusting the generated pack as complete

The real task receipt selected generic tutorial tests and warned that both obvious redirect tests were missing from the indexed candidate set.

Inspect freshness warnings and verify same-stem tests before editing. Checkpoint the files actually used so the next slice starts from observed evidence.

Running repository-bounded agents? Continue to the advanced workspace workflow.