ship-tracker

Opinionated scaffolder for a docs-driven sprint-tracking workflow. One init always drops the complete bundle:

• CONTEXT.md — project domain vocabulary (repo root).
• docs/tracker/ — workflow docs: CONVENTIONS.md, Roadmap.md, Releases.md, decisions-log.md, testing.md, migrations.md, adr/, and ONBOARDING.md.
• package-backed tracker commands — ship-tracker serves the tracker website/API from the installed package against the current repo and keeps derived runtime files under docs/tracker/.runtime/.
• .agents/skills/ — AI-agent skills (setup-docs, ship-a-story, auto-ship, pick-next-story, write-adr, log-decision, reflect).
• Task runner scripts (tracker, story:next, story:status, story:stats, decision:new, tracker:migrate-checkboxes).

Install

No permanent install needed — npx runs the latest published version in a project-bound way:

npx ship-tracker init

Usage

# Scaffold the full workflow in the current directory
npx ship-tracker init

# Re-run init after upgrading ship-tracker — refreshes
# .agents/skills/ and shipped ADRs; your Roadmap and CONTEXT stay intact
npx ship-tracker init

# Overwrite everything including user docs (careful)
npx ship-tracker init --force

# Wire skills into your AI assistant (only when that assistant is already in use)
npx ship-tracker link auto
npx ship-tracker link claude
npx ship-tracker link all   # same as auto — detected assistants only

# Pull template updates: adds missing files, refreshes managed bundles,
# and migrates legacy tools/tracker repos to the package-hosted runtime
npx ship-tracker update --apply

# Health check
npx ship-tracker doctor

What it does

init writes domain-neutral templates with <!-- TODO: ... --> markers everywhere a project needs to fill in their own domain content.

The scaffold's entry point is docs/tracker/ONBOARDING.md — a 14-prompt guided sequence in 5 phases (foundations → cross-cutting rules → roadmap seeding → adapt existing code → ship first story) that you paste into your AI assistant one prompt at a time. The CLI prints a short pointer to that file at the end of init.

The scaffolded skills do the heavy lifting:

• /setup-docs — bootstrap all the docs above from an existing brief/PRD/spec: grills the document, fills CONTEXT.md, docs/tracker/Roadmap.md, docs/tracker/Releases.md, the first ADR, and adapts existing code (brownfield). The fast path through ONBOARDING.md when you already have a source document.
• /log-decision — append Q/A grilling decisions to docs/tracker/decisions-log.md.
• /write-adr — author Architecture Decision Records under docs/tracker/adr/.
• /pick-next-story — identify the next pending Roadmap story without shipping.
• /ship-a-story — pick + work the next story end-to-end (TDD, lint, types, tracker toggle).
• /auto-ship — drive a whole sprint hands-off: loops pick-next → plan → grill → ship → commit per story with no prompts, pausing only when a sprint completes to ask continue/stop.

Story state is canonical in docs/tracker/Roadmap.md checkboxes. The tracker (pnpm tracker) and the CLI (pnpm story:next) read and atomically toggle them. History and other derived runtime files live under docs/tracker/.runtime/ so the integration stays easy to remove.

Why

The same skills + tracker + CONVENTIONS workflow benefits any project that wants AI-driven backlog execution. Without a CLI, each new project re-copies and drifts. This package keeps templates in one place.

Project layout

packages/ship-tracker/
├── src/
│   ├── cli.mjs               # argv dispatcher
│   ├── commands/             # init, link, update, doctor
│   ├── lib/                  # fs, pm, package-json, symlinks, templates
│   └── prompts.mjs           # post-init next-steps text
└── templates/                # copied/rendered into target projects
    ├── CONTEXT.md.tmpl
    ├── docs/
    │   ├── README.md.tmpl
    │   └── tracker/          # workflow docs
    └── .agents/skills/       # AI-agent skill definitions

Runtime model

• ship-tracker tracker --cwd . serves the tracker UI/API from the package, not from checked-in repo files.
• Generated runner tasks keep the familiar names: tracker, story:next, story:status, story:stats, decision:new, tracker:migrate-checkboxes.
• ship-tracker update --apply removes legacy tools/tracker/ files from older scaffolds and rewires tasks to the package CLI.
• Runtime-only local data is written to docs/tracker/.runtime/ and gitignored by default.