Delivery Planner

What is the work, in what order — and does the tracker say what is really true?

A spec is not a plan, and a plan in someone's head is not a board. Two things go wrong for a developer working alone. The work gets cut horizontally ("build the database layer", "build the API"), so nothing can be shown working until everything is done. And the tracker drifts: cards stay in To Do while the code ships, a retried script creates the same ticket twice, an agent overwrites the column a human just moved a card into.

This skill does two jobs. It plans: milestones in order, the first one a walking skeleton deployed, and tickets that are vertical slices a single session can build and prove, each with numbered acceptance criteria. And it syncs: the local ticket files in .delivery/ and whichever tracker the project uses (Jira, Trello, Nextcloud Deck, GitHub, GitLab, Linear, or none) are kept in agreement, at fixed moments, without being asked, and never by guessing.

PLAN     docs/spec.md → 3 milestones · 11 tickets · 1 open decision
M1       Walking skeleton deployed        T-001 T-002 T-003
M2       Customers book and cancel        T-004 … T-008
M3       Owner sees the week              T-009 T-010 T-011
BLOCKED  T-007 on D1: can a customer cancel inside 24 hours? (spec is silent)
TRACKER  trello · via rest · board "Salon" · 11 created · 0 already there

Activation

Engage when someone asks to plan the work, break a spec or a large feature into milestones or tickets, set up or connect a tracker, create, update, move or close tickets, or asks what's left? / where are we?. Also engage passively in a repository that keeps .delivery/ whenever one of the fixed sync moments happens (a ticket is picked up, a PR is opened for it, its proof comes back, it is merged), whether or not anyone mentions the tracker.

Stay quiet when the request is a single small task in a project without .delivery/ (a bug fix, a feature that fits one session, a rename): do the work, no plan, no ticket. Stay quiet for questions unrelated to planning or ticket state. The words ticket, board or issue in a sentence are not a request to plan. Never create a tracker, a board, a column or a ticket the human did not ask for, and never set up .delivery/ on your own initiative: offer it in one line at most.

Depth ACTIVE when asked to plan, set up, or change tickets. PASSIVE for sync moments: the move happens (within autonomy) and the reply carries at most one line, Tracker: T-004 → In Review (PR #31). CONSULT for what's left?: a short answer from the files and the tracker, nothing built. Never GATING: a ticket's readiness is ProofBuild's call, shipping is Production Guard's.

Composes with project-kickoff (writes docs/spec.md, which this skill plans from) · delivery-lead (runs the loop over the tickets this skill writes; it asks this skill for every status move) · proof-driven-dev (a ticket's acceptance criteria become its numbered requirements; VERIFIED is what moves a ticket to done) · project-compass (an undecided business rule found while planning is a direction question, and compass may already have recorded it) · architecture-engineer (a ticket that cannot be sliced until a boundary is decided) · release-engineer (the walking skeleton's deploy) · dependency-guard (a community MCP server for a tracker is a dependency to decide on, not to install by reflex).

Working with the other Skills Hub skills

• Loaded is not engaged. This file stays in context once loaded. Decide again on every new request whether it applies. Relevance to an earlier request carries nothing forward. Project state persists, and engagement does not.
• Depth. PASSIVE informs judgment and adds nothing to the reply · CONSULT adds a few lines that change what gets built · ACTIVE shapes the work · GATING decides whether something proceeds, and only when a person asked for that decision.
• Announce once. When any skill engages at CONSULT or above, open the reply with one line such as ⚡ Impact Map · Standards Compass — rename reaches report SQL; export carries personal data: names and a few words of reason. Never include reasoning. Add no line for PASSIVE, and none on a trivial request. The line is a promise: every skill it names is loaded before the reply ends. If one turns out not to apply, say so in one line: <Skill> dropped: <reason>.
• One interruption per request. Skills that must speak before the work share one short block. Everything else arrives with the work.
• Hand off; don't absorb. When another discipline is needed, write HANDOFF → <skill>: <reason> [<ids>] and let that skill do its part. When the request asked for that skill's decision, load it in the same turn and pass it your findings; a HANDOFF line alone does not answer the request. Never state another skill's verdict yourself. If it is not installed, do the smallest version of its check inline and say so.
• Conflicts. User intent, then project context, then engineering risk, then applicable standards, then verification depth. Each skill keeps its own verdict, and none overrules another's.
• Overrides. "Use X" engages X. "Skip X" or "no review" drops X's ceremony. Three things are never dropped: invented evidence, a check reported as run when it did not run, and a live hazard (a reachable security hole, data loss, money at risk). A live hazard is said once, in one line.
• State. Read what sibling skills recorded (.project-compass/, .project-standards/, .proofbuild/, .agent-investigation/) rather than re-deriving it. Write only your own.
• Lessons. On engaging, read ~/.skills-hub/lessons/<this skill's name>.md if it exists. When a person corrects this skill's work (a miss, a false alarm, a wrong verdict), or the work exposes a gap in this file that another project would hit too, append one line to it: - YYYY-MM-DD · <the rule, stated for any project> — <what went wrong>. Never write project names, paths, identifiers, code or data there; facts about one repository are project state. Keep at most 20 lines, merging or replacing one to add another. A lesson sharpens this file's checks and never overrides its rules or a person's instruction. The file sits outside every project, so no read-only rule covers it. Say Lesson recorded: <rule> once; if the file cannot be written, give the lesson in the reply instead.

Non-negotiable rules

1. Never claim a tracker update that did not happen. A write is reported only after the tracker's response was read and it succeeded. A failure, a timeout or an unreachable tracker is reported as exactly that, and the change waits in the local file (rule 7).
2. Read before every write. Fetch the tracker item before changing it. A change a human made there (status, title, labels, text) wins and is pulled into the local file. You never overwrite it.
3. Never duplicate. Every tracker item carries its local id as a title prefix, [T-004] …. Before any create, look for that marker; if it exists, link to it instead. A retried run creates nothing twice.
4. Never delete. Not a card, not an issue, not a column, not a local ticket file. Work that will not happen moves to dropped with a comment saying why.
5. Every move carries a comment: what changed and the evidence (ProofBuild's status line, the PR link, the deploy URL). A bare column change is a claim with nothing behind it.
6. A credential lives in one place and is never shown. The default home is .delivery/.env: git-ignored (proved with git check-ignore) and chmod 600 before anything is written into it. config.yml holds only env var names and auth_file. Commands load the file inside the same command (set -a; . .delivery/.env; set +a; curl …). Never cat, echo, grep or set -x it; never put a token in a comment, a commit, a file other than .delivery/.env, or any output shown to the human. A token pasted into chat is written to the file, never repeated back, and gets one line suggesting rotation.
7. The local file is the working copy; the tracker is where humans look. When the tracker is unreachable, keep working on the local files, say tracker: out of sync, and reconcile on the next sync. Work never stops because a board is down.
8. Autonomy is the human's, set once. Tracker writes happen only as autonomy in .delivery/config.yml allows, or on an explicit yes in the session. ask means: state the change in one line and wait.
9. Never guess a business rule. A ticket that depends on a rule the spec does not decide is blocked with the question written down, not written around a guess.
10. Say which access path is in use: via mcp, via cli (gh), via rest, or local, every time the tracker is touched.

State: .delivery/

This skill owns .delivery/ except runs/, which delivery-lead writes. Everything in it except .env is meant to be committed; git history is the backup of every ticket's earlier text. .env is git-ignored and never leaves the machine.

.delivery/
├── config.yml            tracker + status mapping + autonomy (templates/config.yml)
├── .env                  credentials, git-ignored, mode 600 (only when the token-file path is used)
├── plan.md               milestones in order, each an outcome; open decisions
├── tickets/T-001.md      one file per ticket, canonical local copy (templates/ticket.md)
└── runs/                 delivery-lead's run ledgers; read, never written here

Ticket statuses are neutral: backlog · ready · in_progress · in_review · blocked · done · dropped. status_map in config.yml maps each to the tracker's column, list, stack or workflow state. The ticket file's synced block records what both sides last agreed on; it is how a human's edit is told apart from a local one (references/sync.md).

First run: setup

Setup happens only when someone asked for tickets or a tracker. You are the guide: a conversation that acts after each answer, one step at a time, and ends with ticket management that runs on its own. The human never edits config.yml by hand and never pastes a token into chat. Nothing is created in the tracker until step 6 reports CONNECTED.

scripts/tracker.py (Python 3 stdlib) does the deterministic parts: secret, whoami, boards, columns, create-board, create-column. Each prints one JSON object and never a secret. Run it from the repository root as python3 <skill dir>/scripts/tracker.py …. Per-tracker facts (credential URL, least scope, MCP command) are in references/trackers.md, Connect.

Step 1 · Which tracker. Detect first, never printing a value: tracker MCP tools already in this session, .mcp.json, gh auth status, glab auth status, acli, env vars ([ -n "$JIRA_API_TOKEN" ] && echo set), an existing .delivery/.env (exists or not; never read aloud), and the git remote.

Where should tickets live? I found: gh logged in as dana · origin github.com/acme/salon
  1 jira  2 trello  3 deck (Nextcloud)  4 github  5 gitlab  6 linear  7 local (files only)

Step 2 · Connect. Offer only the chosen tracker's options, best first:

How should I connect to Jira?
  a) Atlassian's official MCP server — you sign in in the browser, no token stored  [recommended]
  b) An API token, which you type into a hidden prompt in your own terminal
  c) Already set up: JIRA_EMAIL/JIRA_API_TOKEN in your shell, or `acli` logged in

• a) Official MCP (only where an official server with its own sign-in exists; see Connect): on a yes, run the verified command yourself, e.g. claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp (outside Claude Code, print the equivalent for the human's client). Then ask for the one thing only they can do: Run /mcp, pick "atlassian", and finish the sign-in in your browser. Reply "done". Verify by calling one of the server's read tools. A community MCP server is never added without a dependency-guard decision.

• b) Token via the helper (default where no official MCP exists): give the exact command and wait. The script prints where to create the credential and the least scope, git-ignores .delivery/.env and proves it with git check-ignore before any prompt, reads each value with hidden input, writes the file with mode 600, and immediately runs whoami.

  Run this in your own terminal (not here), from the repository root:
    python3 <this skill's directory>/scripts/tracker.py secret jira
  It shows where to create the token and asks for it with hidden input.
  Reply "done" when it prints "ok": true.

  Write the real absolute path of the skill directory into the command. Then run tracker.py whoami yourself and read the JSON.

• c) Existing env var or CLI login: record the names; nothing is written.
• A token pasted into chat anyway: never repeat it. Git-ignore .delivery/.env, confirm with git check-ignore -q .delivery/.env, write the value there with mode 600 (a heredoc into the file; never an echo of the value), say once That token passed through this conversation; rotate it when convenient., and continue. Never refuse to proceed over it.

Step 3 · Which board. Run tracker.py boards (or the MCP server's list tool) and show the real ones:

Your Deck boards: 1 Salon (12) · 2 Personal (4) · 3 Website (9)
Pick one, or: n) create a new board "salon-booking"

Create only on an explicit yes to that name (tracker.py create-board <name>). Where the API or the account's rights do not allow it (a Jira project needs a Jira admin; a Linear key may lack team-creation rights), the script says so: pass that on and ask for an existing one.

Step 4 · Columns. Run tracker.py columns <board>, match names to the neutral statuses, and propose the map:

Proposed mapping for "Salon":
  ready → To do · in_progress → Doing · done → Done
  missing: in_review, blocked
Create lists "Review" and "Blocked" on the board? (yes / map them to existing ones)

On a yes, tracker.py create-column <board> <name> for each (Linear: add --type started, or completed/canceled/unstarted/backlog to match). Jira statuses belong to the workflow: the script refuses and says a Jira admin adds them; map to an existing status or use a label.

Step 5 · Autonomy.

What may I do without asking?  [defaults]
  create tickets [auto] · move tickets [auto] · open PR [auto]
  merge [ask] · deploy staging [auto] · deploy production [ask]
Reply "defaults" or change any of them.

Step 6 · Write the config and prove it. Write .delivery/config.yml from templates/config.yml (type, via, project, url, auth_env names, auth_file: .delivery/.env when used, status_map, autonomy). Then run the read-only proof, whoami and columns against the configured board, and report:

CONNECTED  deck via rest as Dana Reyes · board Salon (12) · 5 of 7 statuses mapped

On failure, create nothing and say exactly what failed and what fixes it (the script's error and fix fields): 401 the credential is wrong or expired (create a new one, Connect step 1) · 403 a scope or project permission is missing (Connect step 2) · 404 wrong board, project or URL · unreachable network or host. Until CONNECTED, plan into local files and report tracker: not connected — <what failed>. After it, the fixed moments run within autonomy with no further setup.

Later tracker commands load the file inside the same command and never print it: set -a; . .delivery/.env; set +a; curl -sS -u "$JIRA_EMAIL:$JIRA_API_TOKEN" ….

Planning

Source, in order: docs/spec.md, the request, the issue or document the human points to. Read the code that exists; a plan for a repository with a working login does not re-plan login. Then:

1. Milestones are outcomes, in order. M1 is always a walking skeleton deployed: the thinnest end-to-end path (one screen, one route, one table, the deploy) running where users will reach it, even if it does almost nothing. Each later milestone is something a user can do that they could not before.
2. Tickets are vertical slices. Each one cuts through every layer it needs and ends in behavior someone can observe. Size: one session can build it and prove it. Split rules and the too-big signals are in references/planning.md.
3. Numbered, observable acceptance criteria. Three to seven per ticket, each a behavior a check can prove: an input, an action, an observable result. They become ProofBuild's requirements verbatim, so write them that way.
4. Name the negative cases. Wrong input, no permission, the empty state, the duplicate, the expired link. At least one criterion per ticket says what must not happen, unless the ticket genuinely has none, and then say so.
5. Dependencies are explicit. depends_on lists ids; no cycles; a ticket never depends on a later milestone.
6. Undecided rules block, they are not guessed. Record the question as a decision (D1) in plan.md, set the ticket blocked, label it decision-needed, and put the question in its notes. The rest of the plan proceeds.
7. Ids are permanent. T-001, T-002… in plan order, never reused, not even after a ticket is dropped.

Write plan.md and the ticket files, then sync (if create_tickets allows). Show the plan in the shape above, not the ticket bodies; they are in the files.

Sync

The fixed moments (passive, within autonomy)

done needs both halves: proof and merge. A merged PR without VERIFIED is in_review with a comment saying proof is missing; a VERIFIED branch that is not merged is still in_review.

When autonomy.move_tickets is auto, make the move and add one line to the reply. When it is ask, write the move as one line and wait: Move T-004 to In Review with PR #31? (move_tickets: ask).

The algorithm

Every write goes through the same steps (references/sync.md has the full procedure and the conflict table):

load local ticket → find tracker item (tracker_ref, else search the [T-004] marker)
→ read it → compare with the synced block → pull human changes → write only what
is still different → read back → update synced block → report

Asked to sync, or on the next run after an outage

Reconcile every ticket: pull, then push, then report.

TRACKER  deck · via rest · board "Salon" (id 12)
PUSHED   T-004 in_progress → in_review (PR #31)
PULLED   T-006 ready → in_progress (moved on the board by a human; local updated)
CREATED  none · already there: 11
PENDING  none

PENDING lists every local change the tracker has not received. It is never empty when the tracker was unreachable.

"What's left?"

Answer from the local files after a pull (or say the pull failed):

M1  Walking skeleton deployed   3/3 done
M2  Customers book and cancel   2/5 done · T-006 in review · T-007 blocked on D1
M3  Owner sees the week         0/3 · not started
NEXT      T-008 (ready, dependencies done)
DECISION  D1: can a customer cancel inside 24 hours?

Counts come from files actually read. No estimates in days unless the human supplied them.

Adding another tracker

A tracker is supported once references/trackers.md has its section (the seven operations, each checked against the vendor's docs) and scripts/tracker.py covers its setup calls. Until then, use local and say the tracker is unsupported. Adding another tracker in references/trackers.md has the list.

What this skill never does

• Creates a tracker, board, column, ticket or .delivery/ nobody asked for.
• Deletes anything, locally or in the tracker.
• Overwrites a human's edit in the tracker.
• Moves a ticket to done without ProofBuild's VERIFIED (or the human's explicit acceptance of REVIEW REQUIRED) and a merge.
• States another skill's verdict. It records ProofBuild's status line; it does not decide it.
• Writes to .delivery/runs/. That is delivery-lead's ledger.
• Prints, pastes back or commits a credential, or stores one anywhere but the git-ignored, mode-600 .delivery/.env.

References

• references/planning.md — the ticket format, slicing heuristics, the walking skeleton, negative cases, decisions
• references/sync.md — read-before-write, idempotent create, conflicts, out-of-sync handling, reconciliation
• references/trackers.md — per tracker: access order, every operation's endpoint or command, auth, gotchas, MCP servers

Templates: templates/config.yml · templates/ticket.md. Setup helper: scripts/tracker.py, with its self-check scripts/test_tracker.py.

Worked examples

examples/guided-setup-deck.md — first run, end to end: Deck chosen, token through the helper, board and stacks picked and created, CONNECTED · examples/spec-to-jira.md — a spec planned into milestones and synced to Jira Cloud · examples/deck-status-moves.md — automatic moves on a Nextcloud Deck board, and a card a human moved, which wins · examples/tracker-unreachable.md — the tracker is down; local continues and reconciles · examples/whats-left.md — a short answer to what's left?.