> ## 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.

# Configuration overview

> shipflow.config.md is the single source every skill reads first.

`shipflow.config.md` is created from `shipflow.config.example.md` the first time you run `init`.
It's meant to be **committed** — the whole team shares one config, and every skill treats it as
authoritative: if a rule here conflicts with a skill's default behavior, the config wins.

## requirements

Where a requirement comes from. shipflow accepts two sources, resolved automatically from your
message: a **tracker** work item (read via the connected MCP server, never raw REST) or a **direct**
free-text requirement given inline or as a local `.md` file.

```yaml theme={null}
provider: ado   # tracker used when a work-item reference is given. or: jira

ado:
  org: myorg
  project: Platform
  id_hint: "AB#<id>"

jira:
  base_url: https://myorg.atlassian.net
  project_key: PLAT

direct:
  enabled: true                          # false → require a tracker reference for every run
  id_prefix: "direct-"                   # workspace/branch id when there's no work-item id
  force_context_gate_when_proposed: true # proposed ACs must be human-confirmed before any code
```

<Note>
  Direct mode keeps shipflow's spine. If you supply acceptance criteria inline they're used as-is;
  if you don't, `feature-context` **proposes** atomic ACs and forces the `after_context` gate so a
  human confirms them — shipflow never silently invents ACs. A direct-mode PR carries no tracker
  link-back, which is expected rather than a defect.
</Note>

## context

The path to your standing "constitution" doc — see [Product Context](/shipflow/configuration/product-context).

```yaml theme={null}
product_doc: product.md
require_product_doc: false   # set true to hard-stop phases until product.md exists
```

## code\_host

Where PRs get opened, and which CLI does it.

```yaml theme={null}
host: github   # or: azure_repos

github:
  default_base_branch: main
  cli: gh

azure_repos:
  default_base_branch: main
  cli: az
```

<Warning>
  shipflow v0 is built and tested against **requirements in ADO/Jira + code in GitHub** — that
  makes `gh` the single correct git-host CLI. Azure Repos is a documented extension point (PR
  creation swaps `gh pr create` for `az repos pr create`), but `gh` itself does **not** work
  against Azure Repos — don't assume it does.
</Warning>

## repos

Empty by default (single-repo mode). Populate this for polyrepo — see the dedicated
[Polyrepo](/shipflow/polyrepo) guide before touching this section.

```yaml theme={null}
repos: []
cross_link_prs: true
```

## git\_conventions

Branch pattern, commit style, and the hard rules every skill that writes git history must follow.

```yaml theme={null}
branch:
  pattern: "feature/{id}-{slug}"
  base: main

commit:
  subject_pattern: "{type}: {summary} ({provider_ref})"
  types: [feat, fix, refactor, test, docs, chore]
  add_co_author: false
  add_generated_by: false

push:
  allow_force: false
```

<Note>
  **Hard rules, not defaults:** no co-author trailer, no "generated-by" trailer, no plain
  `--force` (only `--force-with-lease` after explicit approval), and the base branch is never
  rewritten. These aren't configurable away — they're enforced by every phase skill.
</Note>

## linking

How code links back to the work item so the tracker graph stays honest.

```yaml theme={null}
ado:
  reference_pattern: "AB#{id}"
  place_in: [commit, pr_title, pr_body]

jira:
  reference_pattern: "{project_key}-{id}"
  place_in: [commit, pr_title, pr_body]

require_link: true
```

If the reference can't be placed, that's a **blocker** the verify phase surfaces — never a silent
gap. An unlinked PR is treated as a defect.

## tests

```yaml theme={null}
framework: ""          # blank = auto-detect (package.json, pyproject.toml, *.csproj, go.mod, …)
run_command: ""
require_ac_traceability: true
policy: "every changed public unit has at least one test"
```

In polyrepo, these are the *default*; a repo can override with its own
`repos[].tests.{framework,run_command}` if it uses a different stack.

## governance

The human-in-the-loop gates — the part of the config most worth reading carefully before your
first run.

```yaml theme={null}
gates:
  after_context: true
  after_plan: true
  after_verify: true
  before_workitem_update: true

autonomous:
  create_branch: true
  write_code: true
  run_tests: true
  commit: true

never_autonomous:
  - push_to_remote
  - open_pull_request
  - update_work_item_state
  - merge
```

`never_autonomous` is not just a default — pushing, opening the PR, updating tracker state, and
merging always need a human, regardless of how the gates above are set.

## workspace

Where shipflow keeps its per-work-item scratch files. Add this directory to `.gitignore`.

```yaml theme={null}
dir: ".shipflow/{id}/"
files:
  context: context.md
  plan: plan.md
  tasks: tasks.md
  state: state.json
  verify: verify-report.md
```

`state.json` is what makes a run resumable — in polyrepo, it tracks branch, commit progress, test
result, and PR URL **per touched repo**.