> ## Documentation Index
> Fetch the complete documentation index at: https://kowshik-93.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> shipflow takes an existing ADO/Jira work item all the way to an opened pull request — in gated phases, with a human approving every irreversible step.

## What shipflow is

shipflow is a set of portable [Agent Skills](https://code.claude.com/docs/en/skills) —
`SKILL.md` files with a `name` + `description` frontmatter core — that run identically in
**Claude Code** and **GitHub Copilot**. Installed into a repo, they let you say `/shipflow AB#1234`
in chat and get a fully-worked pull request out the other end: requirement read from your tracker,
a plan grounded in your actual codebase, implementation on a branch, tests mapped to each
acceptance criterion, an AC-by-AC gap check, and a linked, opened PR.

<Note>
  shipflow never merges. It opens the PR; you review and merge. Pushing, opening the PR, and
  moving the work item's state are gated — the flow stops and asks before anything irreversible.
</Note>

## How this differs from spec-first tools

Tools like [Spec Kit](https://github.com/github/spec-kit) and OpenSpec are spec *authoring* tools:
you write a spec and they scaffold an implementation from it. shipflow is a *requirement-to-PR
pipeline* — it starts from a work item that already exists in Azure DevOps or Jira, reading the
requirement and acceptance criteria through the MCP server your host already has connected, so there
is no double-entry of a spec you already wrote in your tracker. If you already run work through a
tracker, shipflow meets you there.

The difference isn't only the input. shipflow makes acceptance criteria a **traced spine**
(AC → task → test → one-by-one verify → PR checklist), links back to your tracker and moves the
work item's state, and runs under human gates that never merge, never force-push, and never invent
acceptance criteria.

### Two ways to start: tracker or direct

shipflow accepts both, resolved automatically from what you type:

* **Tracker** — give a work-item reference (`/shipflow AB#1234`, `/shipflow PLAT-567`) and it reads
  the requirement and ACs from ADO/Jira via MCP.
* **Direct** — hand over a requirement inline (or point at a local `.md` file) when there's no
  ticket yet. The AC spine still holds: if you supply acceptance criteria they're used as-is; if you
  don't, `feature-context` **proposes** atomic, testable ACs and the `after_context` gate is forced
  on so you confirm them before any code. shipflow never silently invents ACs, and a direct-mode PR
  simply carries no tracker link-back (that's expected, not a defect). Toggle it with
  `requirements.direct.enabled` in `shipflow.config.md`.

## The shape of the flow

<Steps>
  <Step title="Context">
    `feature-context` reads the work item via MCP, normalizes its acceptance criteria into atomic,
    testable statements, and grounds it against your repo. Read-only.
  </Step>

  <Step title="Plan">
    `feature-plan` turns that into a concrete, file-level plan and a task list — grounded in your
    actual code, not a generic description. In [polyrepo](/shipflow/polyrepo) setups, this is also where the
    touched repos get decided.
  </Step>

  <Step title="Implement">
    `feature-implement` branches and commits, task by task, following your `git_conventions`.
  </Step>

  <Step title="Tests">
    `feature-tests` writes a test for every acceptance criterion and runs until green.
  </Step>

  <Step title="Verify">
    `feature-verify` grades every AC as MET / PARTIAL / MISSING with evidence. Any gap stops the
    flow — it will not quietly ship an unmet criterion.
  </Step>

  <Step title="PR">
    `feature-pr` pushes and opens a linked, gated pull request with the AC checklist and test
    results in the body.
  </Step>
</Steps>

Each phase is also a **standalone skill** — run `/feature-verify AB#1234` on its own any time, you
don't need the whole flow.

## Where to go next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/shipflow/quickstart">
    Install shipflow and run your first work item end to end.
  </Card>

  <Card title="Configuration" icon="gear" href="/shipflow/configuration/overview">
    Every field in `shipflow.config.md`, explained.
  </Card>

  <Card title="Polyrepo" icon="diagram-project" href="/shipflow/polyrepo">
    One work item, multiple repos — branch + PR per repo, cross-linked.
  </Card>

  <Card title="Skills reference" icon="list-check" href="/shipflow/skills/overview">
    What each of the 11 skills does, reads, and writes.
  </Card>
</CardGroup>