Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ the audit trail — and the whole interface between you and the autonomous skill
| Stage | What docket commits | Where it lives |
|---|---|---|
| Plan | The change file: why, what changes, out of scope, dependencies, priority, type | `docs/changes/active/` on the `docket` metadata branch; rendered on `BOARD.md` |
| Design | The spec, linked from the change (or `trivial: true` for small mechanical work) | `docs/superpowers/specs/` on the metadata branch |
| Design | The spec, linked from the change | `docs/superpowers/specs/` on the metadata branch |
| Build | A dated reconcile log, the implementation plan, one verified commit per task | The change body and `docs/superpowers/plans/` on the metadata branch; the commits on the feature branch |
| Test | The build-evidence record — suite command, result, head SHA — plus the results file and the review's disposition table | The change body's `## Build evidence` section and `docs/results/` on the metadata branch; the table in the PR body |
| Deploy | The merge (proven reachable), the archived change record, a cleaned branch and worktree, a re-rendered board | `docs/changes/archive/`; `BOARD.md` |
Expand Down
2 changes: 1 addition & 1 deletion agents/docket-auto-groom-critic.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: docket-auto-groom-critic
description: Adversarial reviewer of an auto-groom draft spec or trivial verdict — attacks it, never improves it, and returns exactly one verdict per the dispatching skill's protocol.
description: Adversarial reviewer of an auto-groom draft spec — attacks it, never improves it, and returns exactly one verdict per the dispatching skill's protocol.
skills: [docket-convention]
worktree-scope: metadata
---
Expand Down
2 changes: 1 addition & 1 deletion agents/docket-auto-groom.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: docket-auto-groom
description: Use when individual stubs opted into autonomous grooming (their `auto_groomable` is `true`) and you want the auto-groomable needs-grooming queue drained with no human — selecting each auto-groomable stub deterministically and designing it via a default-biased self-brainstorm gated by an adversarial critic, exiting each stub with a linked spec, a trivial verdict, or an abstain back to the human queue. Kill and defer are never autonomous. Writes markdown only — never branches, worktrees, or code.
description: Use when individual stubs opted into autonomous grooming (their `auto_groomable` is `true`) and you want the auto-groomable needs-grooming queue drained with no human — selecting each auto-groomable stub deterministically and designing it via a default-biased self-brainstorm gated by an adversarial critic, exiting each stub with a linked spec or an abstain back to the human queue. Kill and defer are never autonomous. Writes markdown only — never branches, worktrees, or code.
skills: [docket-auto-groom, docket-convention]
worktree-scope: metadata
launch: root-coordinator
Expand Down
6 changes: 3 additions & 3 deletions cursor-rules/dispatch/docket-auto-groom-critic.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
## docket-auto-groom-critic — dispatch only

This agent wraps no skill and is normally dispatched **by** docket-auto-groom as its adversarial gate,
not invoked directly. If you are asked to adversarially review an auto-groom draft spec or trivial
verdict, dispatch it rather than reviewing inline.
not invoked directly. If you are asked to adversarially review an auto-groom draft spec, dispatch it
rather than reviewing inline.

Dispatch to the subagent `docket-auto-groom-critic`, foreground, using this mode's subagent-launch
mechanism. The prompt must include the draft spec / trivial verdict under review and the dispatching
mechanism. The prompt must include the draft spec under review and the dispatching
skill's verdict protocol.

Do NOT let it improve the draft — it only attacks and returns exactly one verdict.
Expand Down
7 changes: 3 additions & 4 deletions docs/comparison/ai-native-sdlc-playbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,11 @@ fail-closed operations. In return docket has depth the playbook never mentions.

| Capability | Playbook | docket | Status |
|---|---|---|---|
| Spec committed beside the intent | `spec.md` beside `intent.md` as the audit record. | Spec on the metadata branch; `spec:`, `## Artifacts`, and the backlink written in one commit. Build-ready = spec or trivial. | Both |
| Spec committed beside the intent | `spec.md` beside `intent.md` as the audit record. | Spec on the metadata branch; `spec:`, `## Artifacts`, and the backlink written in one commit. Build-ready = spec. | Both |
| Flagged concerns resolved before build | Policy concerns resolved with policy owners. | Consultant critique concerns; auto-groom critic verdicts (sound / fixable / needs-human). Design concerns, not organisational policy. | Both (different source) |
| Organisational policy skills at spec time | Brand, security, compliance, UX skills guide the session. | docket ships no policy skills; the harness's own may fire. | Playbook only |
| Autonomous design with an adversarial gate | Not described. | `docket-auto-groom` + isolated critic; one revision round; abstain writes `## Auto-groom blocked`; kill and defer never autonomous. | docket only |
| Pinned-model spec author | Not described. | `docket-brainstorm` dispatches `docket-brainstorm-consultant` once; capture-then-groom pins the whole conversation. | docket only |
| Trivial path | Not described. | `trivial: true` keeps a small change build-ready with no spec. | docket only |
| Grooming queue and selection bands | Not described. | Deterministic next-stub selection; abstained, then human-only, then auto-groomable. Grooming takes no claim. | docket only |
| Measurement | Intent-to-spec time; rework by spec commits after the first plan commit. | None; reconcile-log entries make rework derivable. | Playbook only |

Expand Down Expand Up @@ -130,7 +129,7 @@ fail-closed operations. In return docket has depth the playbook never mentions.
| Stage | Playbook artifact | docket artifact |
|---|---|---|
| 1 | `intent.md` | Change file on `docket`: frontmatter + Why / What changes / Out of scope / Open questions; board row. |
| 2 | `spec.md` | Spec file on `docket` with a backlink header; `spec:` and `## Artifacts` on the change; or `trivial: true`. |
| 2 | `spec.md` | Spec file on `docket` with a backlink header; `spec:` and `## Artifacts` on the change. |
| 3 | `plan.md` + the diff | `## Reconcile log` and `reconciled: true`; plan on the metadata branch (frozen once closed out); one verified commit per task. |
| 4 | PR with test results | Build-evidence record in the change record; results file; review disposition table in the PR body. |
| 5 | Merged PR / commit | Merge proven reachable; change archived as `archive/<date>-<id>-<slug>.md` with optional `## Closeout notes`; branch and worktree cleaned; board re-rendered. |
Expand Down Expand Up @@ -163,7 +162,7 @@ no-test-edits guard during repair; an intake path from production or scanner fin
| Page (goal) | Stage | Content | From today's README |
|---|---|---|---|
| README — what docket automates, and where you stay in control | Landing | Thesis in the playbook's vocabulary; artifact chain; reconcile; install; daily loop; map | Intro, How it works, Why docket, Quickstart |
| Capturing work that outlives the session | 1 | Change file and manifest; lifecycle and board; priorities, types, dependencies, stacking; scan mode, trivial, discovered work | Lifecycle, convention manifest, auto_capture / change_types |
| Capturing work that outlives the session | 1 | Change file and manifest; lifecycle and board; priorities, types, dependencies, stacking; scan mode, discovered work | Lifecycle, convention manifest, auto_capture / change_types |
| Designing before building | 2 | Interactive grooming; autonomous grooming and the critic; consultant specs | Quickstart step 2, consultant brainstorm |
| Building without supervision | 3 | implement-next; reconcile; plan authoring; build tiers and escalation; worktrees, claims, /loop, dispositions | Why docket, docket-build, draining hands-free |
| Proving the build | 4 | Build gate and evidence; gate driver and budgets; integration repair; configuring the suite | docket-build gate paragraphs, gate references, tests/README |
Expand Down
11 changes: 5 additions & 6 deletions docs/concepts/change-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ human has to memorize a flowchart to file a piece of work.
├──────────────► needs-grooming ────(design a spec)──┐
│ (no spec yet) │
│ ▼
└──(has a spec or trivial mark, deps done)───────► build-ready
└──(has a spec, deps done)───────────────────────► build-ready
│
(build takes a claim)
▼
Expand All @@ -50,11 +50,10 @@ human has to memorize a flowchart to file a piece of work.
killed — abandoned as obsolete; final, kept in the archive
```

- **proposed** is the raw entry. A proposed change with neither a spec nor a
trivial mark is **needs-grooming** — it needs a design conversation first. A
proposed change that has a **spec** (the design document a change links to,
written before building) or is marked trivial, and whose dependencies are all
`done`, is **build-ready**. A build-ready change on hold reads **on-hold**:
- **proposed** is the raw entry. A proposed change with no spec is
**needs-grooming** — it needs a design conversation first. A proposed change
that has a **spec** (the design document a change links to, written before
building) and whose dependencies are all `done` is **build-ready**. A build-ready change on hold reads **on-hold**:
autonomous drains skip it, and it is built only when named.
- **in-progress** means a build has taken a **claim** — the moment a change is
picked up for building; it records which branch will carry the work and when it
Expand Down
4 changes: 2 additions & 2 deletions docs/guide/building-without-supervision.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,8 @@ any work continues.

A single implement-next run walks a fixed path and then stops:

1. **Pick.** It selects the next **build-ready** change (a proposed change that has a spec or is
marked trivial and whose dependencies are all `done`). It never touches work that is not ready.
1. **Pick.** It selects the next **build-ready** change (a proposed change that has a spec and
whose dependencies are all `done`). It never touches work that is not ready.
2. **Claim.** It takes a **claim** on that change (the moment a change is picked up for building; it
records which branch will carry the work and when it was taken) with a conflict-checked write on the
change's status, so two runs in parallel can never grab the same change. The claim carries a
Expand Down
15 changes: 6 additions & 9 deletions docs/guide/capturing-work.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,8 @@ write in prose. As you meet them, the manifest fields are:
- `depends_on` — the ids of other changes that must be `done` before this one can start.
- `spec`, `plan`, `results` — the design document a change links to, written before building;
the task-by-task breakdown a build follows, written on the metadata branch; and the required
close-out record of what a build actually did (one per implemented change, trivial included).
close-out record of what a build actually did (one per implemented change).
Filled in as the change moves through its life.
- `trivial` — a flag that says "this is small and mechanical enough to skip the design step."
- `branch`, `pr` — the feature branch and pull request, recorded once the build starts.

The exact field list and its rules are owned by the reference tier — see
Expand All @@ -47,8 +46,8 @@ proposed → in-progress → implemented → done
```

- **proposed** — captured, waiting to be built. A proposed change that has not been designed
enough to build (no spec, not marked `trivial`) sits in a **needs-grooming** state (a
proposed change with neither a spec nor a trivial mark; it needs a design conversation first)
enough to build (no spec) sits in a **needs-grooming** state (a proposed change with no spec;
it needs a design conversation first)
until it is groomed — see [Designing before building](./designing-before-building.md).
- **in-progress** — a run has claimed it and is building.
- **implemented** — a pull request is open, waiting for your merge.
Expand Down Expand Up @@ -120,7 +119,7 @@ is when you write it down.
**A fully designed change.** When you already know what you want, capture it with the
`docket-new-change` skill — a **skill** being a named, reusable instruction set an agent loads for
one job. You describe the idea, docket brainstorms it with you into a **build-ready** change (a
proposed change that has a spec or is marked trivial and whose dependencies are all `done`) — a
proposed change that has a spec and whose dependencies are all `done`) — a
spec written, dependencies noted — and commits the change file to the backlog. Because the
backlog is durable, you can capture now and build later; the idea does not evaporate with the
session.
Expand All @@ -130,10 +129,8 @@ design step — it lands at `needs-grooming` and waits. You groom it later, in a
whatever model you choose. Grooming is its own page: [Designing before
building](./designing-before-building.md).

**Small and mechanical.** When the work is so small and mechanical that a design conversation
would be ceremony — a rename, a dependency bump — mark it `trivial`. A trivial change skips
needs-grooming entirely and is build-ready the moment its dependencies are clear, without a
spec.
**Small and mechanical.** Small work — a rename, a dependency bump — still gets a spec, just a
short one.

**Scan mode.** Instead of describing one idea, you can point the new-change skill at the project
and have it *scan* for candidate work — gaps, TODOs, obvious follow-ups — and mint them as
Expand Down
11 changes: 5 additions & 6 deletions docs/guide/designing-before-building.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,10 @@ an adversarial check, and have a high-tier consultant write the final design doc

A **change** (one unit of planned work, roughly one pull request, tracked as one markdown file)
that was captured as a rough stub lands in the **needs-grooming** state (a proposed change
with neither a spec nor a trivial mark; it needs a design conversation first). Grooming is what
moves it out of that state and into **build-ready** (a proposed change that has a spec or is
marked trivial and whose dependencies are all `done`). The output of grooming is a **spec** (the
design document a change links to, written before building) — or, for genuinely mechanical work,
a `trivial` mark that skips the spec.
with no spec; it needs a design conversation first). Grooming is what moves it out of that
state and into **build-ready** (a proposed change that has a spec and whose dependencies are all
`done`). The output of grooming is a **spec** (the design document a change links to, written
before building).

## Grooming a stub with a conversation

Expand All @@ -36,7 +35,7 @@ auto-groom skill drains the ones you have marked auto-groomable with **no human
Each stub is designed by a default-biased self-brainstorm, and — this is the safety rail — every
resulting design is gated by an **adversarial critic**: a separately-run reviewer whose only job
is to attack the draft. A design that survives the critic exits as a build-ready spec; one the
critic rejects (or that comes out genuinely trivial) is handled accordingly, and anything the
critic rejects is handled accordingly, and anything the
groomer cannot settle confidently is handed back to your interactive queue rather than forced
through.
Such a stub shows as **auto-groom blocked — needs you** on the board. Once you have supplied the
Expand Down
2 changes: 1 addition & 1 deletion docs/install/models-and-effort.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ worker with its own context, pinned to a model and effort (`docket-implement-nex

The two interactive skills, `docket-new-change` and `docket-groom-next`, run at whatever model and
effort your session uses, so you choose them. Pick by preference and by how complex you expect the
change to be: a quick stub, a trivial verdict, or a small revise needs little, while a net-new
change to be: a quick stub or a small revise needs little, while a net-new
design, a cross-cutting change, or a stub whose premise needs tracing through the code is worth
your strongest model at higher effort.

Expand Down
Loading
Loading