shipflow-skills

shipflow

shipflow takes a requirement all the way to an opened pull request — grounded in your real Azure DevOps or Jira context (or a requirement you hand over directly), implemented with tests, and gated by a human at every irreversible step.

shipflow's native input is a work item that already exists: it reads the requirement and acceptance criteria through the ADO/Jira MCP server your host already has connected, so there's no double-entry of a spec you already wrote in your tracker. It also takes a direct requirement (free text, or a local .md file) for the pre-ticket case. Either way it grounds a plan in your actual codebase, implements it on a branch, writes tests mapped to each acceptance criterion, verifies the diff against those criteria, and opens a linked PR. It stops and asks before anything irreversible.

How it differs from spec tools (Speckit, OpenSpec, …): those are spec authoring tools that stop at an implementation. shipflow is a requirement-to-PR pipeline — acceptance criteria are a traced spine (AC → task → test → one-by-one verify → PR checklist), it links back to your tracker and moves the work item's state, and it's governed by human gates that never merge, never force-push, and never invent acceptance criteria. In direct mode without ACs it proposes them and makes you confirm — it never silently assumes.

Full documentation — setup walkthrough, every shipflow.config.md field explained, a dedicated polyrepo guide, and a page per skill. This README stays a quick-reference; the docs site is the complete guide.

Why

Agents are good at writing code and bad at knowing what "done" means. shipflow fixes that by making the acceptance criteria the spine of the whole flow: extracted once from the work item, mapped to tasks, mapped to tests, and checked one-by-one before a PR opens. Nothing ships half-met, and nothing gets invented — an ambiguous requirement comes back as a question, not a guess.

Install

Recommended — npx (cross-platform, no clone): run inside your target repo.

npx shipflow-skills init                 # BOTH .claude/skills and .github/skills, PLUS
                                          # .mcp.json + .vscode/mcp.json seeded automatically

Other install modes (explicit target dir, --global, --claude-only, --no-mcp) and the bash-installer alternative are covered in the installation docs.

The npm package is shipflow-skills (the bare name shipflow is taken); the installed command is still shipflow.

Then:

1. Edit shipflow.config.md — provider (ado|jira), code host, branch/commit conventions, repos, and product/team context.
2. Connect the MCP server(s) — ready-to-copy examples are in mcp/: claude.mcp.json → .mcp.json (Claude Code), copilot.vscode-mcp.json → .vscode/mcp.json (Copilot). GitHub MCP is optional; git ops go through the gh CLI.
3. Add .shipflow/ to .gitignore.
4. In chat: /shipflow AB#1234.

See the quickstart for the full walkthrough.

Works in both Claude Code and Copilot

These are Agent Skills using the portable core of the open standard (name + description + plain Markdown), so the same SKILL.md files run in Claude Code, GitHub Copilot (CLI, VS Code, JetBrains), and other conforming agents — but each host looks in a different directory: Claude Code reads .claude/skills/, Copilot reads .github/skills/. They don't share a directory, so install.sh/init write both by default — one run covers both hosts. Claude-Code-only niceties (disable-model-invocation, $ARGUMENTS, !cmd`` injection) degrade gracefully on hosts that don't support them.

The skills

Skill	What it does	Side effects
shipflow	Orchestrator. Runs the whole flow in phases with approval gates. Resumable.	coordinates the rest
product-context	Creates/maintains product.md, the standing team/product "constitution" every phase reads.	writes one doc
feature-context	Pulls the work item from ADO/Jira via MCP + local git; normalizes acceptance criteria.	read-only
feature-plan	Grounds a technical plan + task list in the real codebase; picks the touched repos.	writes plan files
feature-implement	Branch + conventional commits, task by task, per repo.	branch + commits
feature-tests	Unit tests mapped to each acceptance criterion; runs until green, per repo.	commits
feature-verify	AC-by-AC gap report across repos; non-negotiables as implicit ACs; flags scope creep + missing links.	read-only
feature-pr	Pushes and opens a linked PR per touched repo, cross-linked, with an AC checklist + test results.	push + open PR

Run the whole thing (/shipflow AB#1234) or any phase on its own (/feature-context PLAT-567, /feature-verify AB#1234), and set up standing context once with /product-context. Each phase writes from a template in templates/: context.md, plan.md (the technical plan + task breakdown), and pr-body.md (the PR description with the AC checklist).

Standing context & polyrepo

• Team/product context (product.md). A persistent "constitution" — glossary, architecture boundaries, house-rule conventions, non-negotiables, definition of done — that grounds every work item so none has to restate it. feature-verify treats its non-negotiables as implicit acceptance criteria. The per-work-item context.md answers "what does this need?"; product.md answers "what is always true here?"
• Polyrepo. List the repos a work item may span under repos: in the config. feature-plan picks the actually-touched subset; shipflow then produces one branch + one PR per touched repo, all carrying the same AB#/Jira reference and cross-linked to each other. Acceptance criteria belong to the work item, not a repo — feature-verify aggregates them across repos. Leave repos: empty for the ordinary single-repo flow.

Design decisions

• Requirements via MCP, git via CLI. Reading a work item goes through the connected ADO/Jira MCP server — no raw REST clients to maintain. All git/PR operations go through the gh CLI (GitHub). Azure Repos is a documented extension point (az repos pr create instead of gh pr create) — gh does not work against Azure Repos.
• Human-in-the-loop by default. Context and plan are gated before any code; the verify report is gated before any PR; pushing, opening the PR, and moving the work item's state are never autonomous. See governance in the config.
• Acceptance criteria are the spine. Extracted as atomic, testable statements in phase 1, mapped to tasks in phase 2, to tests in phase 4, checked one-by-one in phase 5. If an AC is unmet, verify says NOT READY and the flow stops.
• Honest linking. Every commit and the PR carry the AB#/Jira reference so the tracker auto-links. A PR that can't be linked is treated as a defect, not a detail.
• Clean history. Commits carry no co-author trailer and no "generated-by" trailer — the author is the human. No --force in the default flow. The base branch is never rewritten.

What it deliberately does not do

• It does not merge. It opens the PR; humans review and merge.
• It does not touch production, deployments, or releases.
• It does not invent acceptance criteria. Missing/ambiguous requirements come back as clarifications, not guesses.

Validate

shipflow has no app runtime — it's skills + config + templates + an installer — so "testing" means the artifacts are well-formed and the installer works:

python scripts/validate.py

See CI for what runs on every PR.

CI

Workflow	Runs on	Does
ci.yml	every PR + push to main	scripts/validate.py + shellcheck install.sh. Required status check.
lint.yml	every PR + push to main	markdownlint-cli2 + eslint (bin/).
codeql.yml	PR/push to main + weekly	Security scanning for JS + Python.
publish.yml	push to main (on version bump)	Auto-tags, GitHub Release, npm publish.

Run the local equivalents any time: npm run lint, npm run lint:md, python scripts/validate.py.

Documentation site (maintainers)

Full docs live in docs/ as Mintlify MDX, hosted (not GitHub Pages), auto-deploying on every push to main that touches docs/. Live at https://kowshik-93.mintlify.site/shipflow/introduction. See the reference docs for maintainer setup details.

Publishing (maintainers)

Version bump = release: bump version in package.json, merge to main, publish.yml validates, tags, releases, and publishes to npm automatically. See CONTRIBUTING.md for the full release process.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a PR.