Dev Cycle

---
name: dev-cycle
description: >
  Run a requested full development workflow: branch, implement, check, review, PR, merge, and release.
license: MIT
compatibility: "Requires git. Optional forge CLIs by host: gh (GitHub), glab (GitLab), fj (Forgejo), tea (Gitea). Bitbucket uses web UI or REST API. Bare git (no remote) works via format-patch/bundle. Uses jq for JSON output and rg (ripgrep) for version search. Delegates to git, testing, code-review, update-docs, and a brainstorming skill if installed."
metadata:
  source: iuliandita/skills
  date_added: "2026-04-14"
  effort: high
  argument_hint: "[start|finish] [description]"
---

# Dev Cycle: Start-to-Finish Workflow

Dev Cycle gets invoked once to start a task and again later to ship it, keeping git, testing, and review calls out of a single freeform session.

Orchestrates a unit of work from branch creation to merge and release. Runs in
two modes that typically span different sessions:

- **Start mode**: pull latest, size-detect, create feature branch, brainstorm
  spec for large work or hand off to coding for small work.
- **Finish mode**: verify green, sync docs/versions, review, push, open PR,
  watch CI, merge, cut release when conventions exist.

Each mode delegates to purpose-built skills (`git`, `testing`, `code-review`,
`update-docs`, brainstorming skills) rather than reimplementing them. This
skill is the glue, not the engine.

## When to use

- User signals the start of a unit of work: "start working on X", "let's add Y",
  "kick off the Z refactor", "new feature branch for ..."
- User signals the end of a unit of work: "wrap this up", "ship this", "ready
  to merge", "finish and release", "close out", "finalize"
- Branch is clearly a feature branch and the user is about to stop touching code
- A PR is about to be opened, or CI just went green on one

## When NOT to use

- Heavyweight, planned milestones with phases and formal requirements - use a dedicated milestone/phase skill if your environment has one (e.g., the GSD family `gsd-new-milestone` / `gsd-plan-phase` / `gsd-execute-phase`). Skip this skill entirely for multi-week coordinated initiatives with stakeholders.
- Single git operations (just commit, just push, just cut a release) - use **git**
- Roadmap idea capture without starting code - use **roadmap**
- Pure brainstorming without any start-of-work intent - use a brainstorming skill directly
- Post-merge retrospective or documentation cleanup alone - use **update-docs**
- Full repo audits (security, bugs, slop) - use **repo-audit** (quick or exhaustive mode)

## Related Skills

- **git** - branch creation, commits, push, PR/MR. This skill calls git for the mechanical steps; git knows the forge conventions.
- **testing** - runs lint/type/unit/integration suites. Finish mode invokes it before review.
- **code-review** - final correctness pass before push. Finish mode invokes it after tests are green.
- **update-docs** - sweeps README/CHANGELOG/roadmap/instruction files for drift. Finish mode invokes it to close the doc-gap you've noticed.
- **docker** - when the unit of work touches `Dockerfile`, `docker-compose*.yml`, or container images. Finish mode's version-bump step updates image tags here.
- **kubernetes** - when the work touches K8s manifests, Kustomize overlays, or Helm charts. Version-bump step touches `Chart.yaml` and image references.
- **ci-cd** - when the change modifies pipeline config. The CI-watch step in finish mode depends on working pipelines; if CI itself changed, exercise caution.
- **roadmap** - if the repo has a gitignored ROADMAP.md, finish mode checks off shipped items.

**External dependencies (not in this collection):**
- `superpowers:brainstorming` (optional) - start mode uses it for large work if installed. Falls back to other brainstorming skills (e.g., `gsd-explore`), then inline Socratic questioning. See start.md Step A4 for the full fallback chain.

---

## AI Self-Check

Before declaring start-mode complete:

- [ ] Ran `git status` and `git pull --ff-only` (or equivalent) - working tree is clean and up to date
- [ ] New branch created from the base branch (not from another feature branch); branch name follows repo convention
- [ ] Size classification stated explicitly (small/medium/large) with the signals that drove it
- [ ] For large work: a spec file was produced, or a brainstorming skill was invoked and its output captured
- [ ] Handoff line told the user what skill(s) to reach for next (e.g., "this touches Postgres - use **databases** when modifying migrations")
- [ ] No code was written in start mode unless the task was explicitly small, or the user explicitly asked for the full cycle (start through finish, release, deploy) in this session, in which case start mode continues into finish without pausing at the handoff

Before declaring finish-mode complete:

- [ ] `$FORGE` detected from `git remote get-url origin` before any push/PR/merge step
- [ ] Applicable checks and every required repository gate passed with output inspected. Missing verification remains unresolved; independent preparation does not make merge or release ready
- [ ] `update-docs` ran over tracked AND gitignored context files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.claude/`, `.codex/`, `.opencode/`, `.planning/`); findings addressed or deferred with a note. Only tracked files were staged for commit; gitignored edits remain local
- [ ] Current version sourced from primary manifest (or user confirmation) before proposing bumps
- [ ] Version-bump sites checked: Dockerfile, K8s manifests, Helm Chart.yaml/values, package.json/pyproject.toml/Cargo.toml, CHANGELOG
- [ ] `git fetch --tags origin` run before release-signal detection (local-only tag check misses remote history)
- [ ] Release convention detected via 2+ independent signals before attempting a release
- [ ] `code-review` ran on the diff against base, not against HEAD alone
- [ ] PR/MR body includes summary + test plan; no AI attribution trailers
- [ ] CI watched to completion with forge-appropriate verification (e.g., `gh pr view --json statusCheckRollup`, `glab ci status`, manual confirmation for Bitbucket/bare) - not merged on "probably fine"
- [ ] For releases: tag matches the bumped version; CHANGELOG has a new section dated today; release-workflow watch used forge-appropriate exit-status flag (`gh run watch --exit-status` etc.)
- [ ] No `--no-verify`, no `--force-push`, no destructive reset - if blocked, fix the root cause
- [ ] **Dirty tree protected**: unrelated user changes are identified and left intact
- [ ] **Remote/branch target checked**: base branch, upstream, and PR target are verified before push, merge, or release
- [ ] Cross-cutting agent hygiene applied - see `references/agent-hygiene.md`

---

## Performance

- Run the narrowest meaningful checks (e.g., `--testPathPattern` or `go test ./pkg/...`) during iteration, then every required repository gate once before finishing. Running the full suite on every edit wastes minutes per cycle.
- Keep commits batch-sized by review concern - one logical change per commit - so bisect, revert, and blame stay useful on a branch with many commits.
- Invoke existing project scripts (`Makefile`, `justfile`, `scripts/`) instead of reconstructing ad hoc command sequences; those scripts encode project conventions that ad hoc commands silently skip.

## Workflow

### Step 0: Detect mode

Pick the mode from user intent + repo state. Do not assume.

| Signal | Likely mode |
|--------|-------------|
| "start", "kick off", "new branch for", "let's build", no feature branch yet | **start** |
| "ship", "wrap up", "merge this", "release", "finalize", feature branch active with commits ahead of base | **finish** |
| Branch clean + no explicit signal | ask the user which mode |
| User ran the skill with `start` or `finish` as an argument | honor the argument |
| "full cycle", "start through finish", "release and deploy in one go" | **start**, then continue into finish without pausing at the handoff |

If in doubt, determine the base branch first (`git symbolic-ref --quiet refs/remotes/origin/HEAD | sed 's|refs/remotes/origin/||'`), then:

```bash
git branch --show-current
git log --oneline @{u}.. 2>/dev/null || git log --oneline "$BASE_BRANCH"..HEAD
```

A feature branch with commits ahead of base strongly signals finish mode.

---

## Mode A: Start

Detailed steps live in `references/start.md`. Summary:

### Step A1: Verify clean state and pull

Run these, stopping on any failure:

```bash
git rev-parse --is-inside-work-tree  # must be inside a git repo
git diff --quiet && git diff --cached --quiet  # tracked worktree and index must be clean
git status --porcelain               # inspect untracked files; allowed, but report them and never auto-stash or auto-commit
git fetch origin --prune
git checkout "$BASE_BRANCH"          # usually main or master
git pull --ff-only                   # refuse non-fast-forward
```

If `BASE_BRANCH` is unknown, read it from `git symbolic-ref refs/remotes/origin/HEAD` or ask the user. Never guess between `main` and `master` - wrong base means a botched branch.
Report the detected base branch and the exact clean-state, fetch, and fast-forward checks that ran,
including any untracked files or unavailable remote update.

### Step A2: Size-detect

Read `references/size-heuristics.md` for the full table. Fast path:

- **Small** (dive in): typo, rename, dep bump, single-file fix, <20 LOC estimated, user said "quick"/"tiny"
- **Large** (brainstorm): new feature, refactor, new dependency, public API change, multi-module, user said "properly" or "design"
- **Ambiguous**: ask 1-2 disambiguating questions; default to large if uncertain

State the classification and the signals: "Classifying this as **large** because it adds a new public endpoint and touches the auth module."

### Step A3: Create the feature branch

Delegate branch naming and creation to the **git** skill. If it isn't available, use the repo's convention (grep recent branches for pattern) or a sensible default like `type/short-description` (e.g., `feat/oauth-login`, `fix/token-refresh-race`).

```bash
git checkout -b "$BRANCH_NAME"
```

### Step A4: For large work, brainstorm or spec

Try skills in this order, stopping at the first that succeeds:

1. `superpowers:brainstorming` (the superpowers brainstorming skill)
2. Any other installed brainstorming skill (e.g., `brainstorm`, `brainstorming`, `gsd-explore`)
3. **Inline Socratic fallback** - ask the user these questions one at a time, then write a spec file:
   - What's the goal in one sentence?
   - What does success look like (measurable outcome)?
   - What's explicitly out of scope?
   - What are the hardest constraints (performance, compatibility, deadlines)?
   - What could go wrong or surprise us?
   - Any existing code/skills/patterns to reuse?

**Headless/non-interactive contexts** (Claude Code `--bare`, Codex `exec`, Cursor Automations) cannot prompt the user. If a brainstorming skill is unavailable AND the environment is non-interactive, write a minimal `SPEC.md` with Goal/Constraints/Risks populated from available context (issue body, branch name, git log), mark unknowns with `TODO:` so they're easy to find later, and continue to handoff. Do not block waiting for answers that can't come.

Write the spec to `SPEC.md` at the repo root (or `specs/<branch-name>.md` if the repo already has a `specs/` dir). Commit it as the first commit on the new branch so the start point is recorded. Spec file format in `references/start.md`.

### Step A5: Hand off

End start mode with a clear handoff:

- State the branch name
- State the classification
- Point the user at skills that fit the domain ("touches Dockerfile - use **docker** when editing", "adds K8s manifests - use **kubernetes**")
- Remind the user to invoke **dev-cycle** in finish mode when ready to ship
- Name whether **testing**, **update-docs**, and **security-audit** will apply at finish time. Justify
  any skipped handoff from the change scope.

Do not continue into implementation - that's the user's next session, unless the user explicitly asked for the full cycle (start through finish, release, deploy) in this session, in which case continue.

---

## Mode B: Finish

Detailed steps live in `references/finish.md`. Summary:

Copy this checklist and track progress:

```
- [ ] B1: Forge, base branch, and branch scope confirmed
- [ ] B2: Checks and required gates pass (fix and re-run until green)
- [ ] B3: Docs and version sites synced; tests re-run if version strings changed
- [ ] B4: Code review on BASE..HEAD; blocking fixes return to B2
- [ ] B5: Pushed and PR/MR opened
- [ ] B6: CI verified green by explicit status query; failures return to B2
- [ ] B7: Merged with an explicit conventional subject; merge SHA recorded
- [ ] B8: Release cut and workflow verified, or skipped with the signal count
```

### Step B1: Pre-close audit and forge detection

First, detect the forge - every later step (push, PR, CI watch, merge, release) dispatches on it. See `references/finish.md` Step B1 for the full detection block. Short version: read `git remote get-url origin`, pattern-match on host, set `$FORGE` to one of `github | gitlab | forgejo | gitea | bitbucket | unknown | bare`. Forgejo uses the Forgejo CLI (`fj`); Gitea gets its own value and uses the Gitea community CLI (`tea`).

Before any push or PR command, report the detected forge, the exact origin URL evidence used for
that classification, and the base branch used for the comparison. Stop when forge or base evidence
is ambiguous.

Then sanity-check the branch:

```bash
# Staged or modified files block closing. Untracked files are fine (not part of HEAD).
git diff --cached --stat; git diff --stat
git log --oneline "$BASE_BRANCH"..HEAD   # commits exist on this branch
git diff "$BASE_BRANCH"..HEAD --stat     # scope sanity check
```

If the branch has no commits or the diff is empty, stop - there's nothing to ship.

### Step B2: Run lint, type, and tests

Use the **testing** skill to run checks appropriate to the changed behavior and every required
repository gate. Delegate only when the check workload benefits from a separate worker.
Do not add tests that merely mirror a reversible, low-impact edit. After checks pass, expand
or repeat them only for new changes, failures, or unresolved concerns.

If the testing skill isn't installed, detect the toolchain. Check in order - first match wins. If no language manifest matches, **continue** to task runners and custom scripts; don't give up:

- **Language manifests**: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`, `pom.xml`, `build.gradle*`, `mix.exs`, `Package.swift`
- **Task runners**: `Makefile` with `lint`/`test`/`check` targets, `justfile`, `Taskfile.yml`
- **Custom scripts**: executable files in `scripts/` or `bin/` whose names match `lint|test|check|ci|validate|verify`
- **Documented commands**: grep `README.md` / `CONTRIBUTING.md` for script invocations

Full detection table and the quick-scan commands live in `references/finish.md`.

**If nothing detectable**: report that verification is unresolved. Inspect the changed artifact
with a suitable parser or direct check when available; do not call that a passed test suite.
Complete independent authorized preparation, then ask for the missing verification command
before merge or release. Never silently waive a required check.

Inspect the actual output. "Exit 0" is not verification - tests that didn't run also return 0. Confirm the suite was exercised.

**Failed required checks block merge and release.** Diagnose whether the failure comes from
this change or the baseline. Fix in-scope failures and re-run affected checks. Report unrelated
failures without silently fixing them; continue independent authorized documentation and review
preparation. Keep the release gate blocked and state what remains. Never use `--no-verify` or
skip failing tests to manufacture a pass.

### Step B3: Sync docs and versions

Docs and versions get left behind. Address in two parts:

**Part 1 - Delegate to `update-docs`** for README, CHANGELOG, roadmap, instruction files, companion-file drift. Invoke as a review-and-fix pass, not read-only.

**Refresh affected gitignored docs too.** Include relevant instruction and companion files when this branch changes their guidance. Keep private edits local. Do not sweep unrelated private automation or configuration; stage only reviewed public documentation.

**Part 2 - Version-bump sites**. The detection script needs `jq` and `rg` (`for t in jq rg; do command -v "$t" >/dev/null || echo "missing: $t"; done`). First read the current version from the primary source (see `references/version-bump-sites.md` for the detection script - it checks `package.json`, `pyproject.toml`, `Cargo.toml`, then falls back to the latest semver tag). If no primary source exists, ask the user what the current version is before proceeding.

Then find and update version strings. Common sites:

- `Dockerfile` (LABEL version, image tags, default ARGs)
- `docker-compose*.yml` (image tags)
- `k8s/**/*.yaml` and `kustomize/**/*.yaml` (`image:` fields)
- `helm/**/Chart.yaml` (`version` and `appVersion`) and `values.yaml` (image tag)
- `package.json` (`version`)
- `pyproject.toml` (`version` under `[project]` or `[tool.poetry]`)
- `Cargo.toml` (`version`)
- `CHANGELOG.md` (new section with today's date)
- Version badges in `README.md`

Explain the version and prepare a concrete diff. Apply within existing release authorization; ask only when authority or an agreed version decision is missing.

**Part 3 - Tests reflect new version**. If tests reference version strings (snapshots, integration tests pulling images by tag, fixtures hardcoding versions), update them and rerun the suite.

### Step B4: Final code review

Delegate to the **code-review** skill with the diff scope: `BASE_BRANCH..HEAD`. The review covers the full change, not just the last commit.

If the review surfaces blocking issues, fix them and loop back to Step B2 (tests may now be affected).

### Step B5: Push and open PR

Delegate to the **git** skill - it handles forge routing. If unavailable, dispatch on `$FORGE` from Step B1. Full per-forge commands in `references/finish.md`.

| `$FORGE` | Push + PR |
|----------|-----------|
| `github` | `git push -u origin <branch>` + `gh pr create` |
| `gitlab` | same push + `glab mr create --target-branch` |
| `forgejo` | same push + `fj pr create "<title>" --base <base>` |
| `gitea` | same push + `tea pulls create --base --head` |
| `bitbucket` | push + announce web-UI URL (no official CLI) |
| `unknown` (self-hosted) | push + announce branch URL; ask user what forge this is |
| `bare` (no remote) | `git format-patch` or `git bundle` - share file with reviewer |

No AI attribution in commit messages, PR titles/bodies, or release notes: no `Co-Authored-By` trailers, no "Generated with Claude Code" lines, no robot emoji. Strip them from any commit-helper template before committing.

### Step B6: Watch CI

Dispatch on `$FORGE`. Every tool has a watch trap - default exit code may not reflect failure.

| `$FORGE` | Command | Trap |
|----------|---------|------|
| `github` | `gh pr checks --watch --fail-fast` then verify via `gh pr view --json statusCheckRollup` | exits 0/1/8; treat anything non-zero as not-ready |
| `gitlab` | `glab ci status --live` then `glab mr view --output json` | `--live` doesn't always exit non-zero on failure; verify explicitly |
| `forgejo` | `fj pr status --wait`, then `fj actions tasks` to list runs | `fj` has no log streaming or re-run; confirm the run in the web UI |
| `gitea` | `tea actions runs list` (per-PR status in the web UI) | `tea pulls` has no `status` subcommand; run listing is `tea actions runs list` on tea versions that support it, else the web UI |
| `bitbucket` | No CLI - watch web UI or poll Pipelines REST API | Manual confirmation before merge |
| `unknown` | Ask user which CI is wired (Jenkins, Drone, Woodpecker, Buildkite, Teamcity) and point them at the URL | Assume nothing |
| `bare` | No remote CI; rely on B2 local output | N/A |

If CI fails, fix the root cause, return to Step B2, then push and watch again - don't retry hoping for flakiness to resolve. If genuinely flaky (rerunning the identical commit passes), rerun and note it in the PR body.

### Step B7: Merge

Once CI is green, dispatch on `$FORGE`:

| `$FORGE` | Merge command | Delete-branch flag |
|----------|---------------|--------------------|
| `github` | `gh pr merge --squash --subject "..." --body "..."` / `--rebase` / `--merge` | `--delete-branch` |
| `gitlab` | `glab mr merge --squash --squash-message "..."` / `--rebase` / (default = merge commit) | `--remove-source-branch` |
| `forgejo` | `fj pr merge <pr> --method squash --title "..." --message "..."` / `merge\|rebase\|rebase-merge` | `--delete` removes the source branch |
| `gitea` | `tea pulls merge <pr> --style squash --title "..." --message "..."` / `merge\|rebase\|rebase-merge` | Delete via web UI or follow-up `git push origin --delete <branch>` |
| `bitbucket` | Web UI or REST API with `"merge_strategy": "squash"` (no subject/body field - set the commit message field manually) | `"close_source_branch": true` |
| `unknown`/`bare` | Local: `git merge --no-ff` (or `--ff-only` after rebase) on base, push, `git branch -d` | N/A |

For squash merges, always pass an explicit conventional subject such as
`type(scope): desc (#PR_NUMBER)` and a `Closes #ISSUE_NUMBER` body. Without it, the forge falls
back to the PR title as the commit subject, which is not always conventional. Keep the PR and
issue numbers distinct. Per-forge commands are in `references/finish.md`.

Check the repo's merge convention before picking a style. If multiple are allowed, match recent merge history: `git log --merges --oneline "$BASE_BRANCH" | head -5`.

### Step B8: Release (conditional)

**First, `git fetch --tags origin` if a remote exists** - local-only tag checks miss remote release history and cause false-negative skips. Then:

**Auto-skip unless at least 2 independent release signals are present.** A single stale tag or lonely CHANGELOG is not a convention. Signal catalog and detection commands live in `references/finish.md` Step B8. Summary:

- Semver tags (`git tag -l 'v[0-9]*'` after `git fetch --tags`)
- CHANGELOG / CHANGES / HISTORY file
- Release workflow file (GitHub Actions, GitLab CI, Forgejo/Gitea Actions, Woodpecker, Drone)
- Forge-native release history (`gh release list`, `glab release list`, `fj release`, `tea releases list`)
- Published package (non-private `package.json`, `[project]` in `pyproject.toml`, `[package]` in `Cargo.toml`)

**Hard skips**: `package.json` has `"private": true`, or `$FORGE=bare` with no local-tag-only intent (ask user).

If release-capable:

1. Determine bump type (breaking -> major, feature -> minor, fix -> patch). Ask if unclear.
2. Guard against existing tag via `git rev-parse --verify --quiet "refs/tags/v$NEW_VERSION"` (note: `git tag -l` always exits 0 so it cannot be used as a guard).
3. Tag the merge commit on `$BASE_BRANCH` and push.
4. Create a forge-native release object (`gh release create`, `glab release create`, `fj release`, `tea releases create`) - Bitbucket and bare have no platform release object; the tag itself IS the release.
5. Watch the release workflow with the forge-appropriate exit-status flag. **Every forge has a default-exit trap** (see the "Inspect CI output" rule and `references/finish.md` for per-forge commands).

Full procedures, extract-changelog function, and per-forge release-watch commands in `references/finish.md`.

---

## Concrete end-to-end finish on GitHub

Branch `feat/oauth-login` on a Node repo with `gh` available, Dockerfile, Helm chart, `"version": "1.4.2"` in `package.json`, CHANGELOG present, GitHub Actions release workflow.

```
B1  git remote get-url origin  -> github.com  -> FORGE=github, FORGE_CLI=gh
    git log main..HEAD          -> 6 commits; diff 340 lines across 12 files
B2  bun run lint && bun run typecheck && bun test  -> all green, 184 tests
B3  update-docs: README badges, CHANGELOG [1.5.0] section dated 2026-04-16
    Bump: package.json 1.4.2 -> 1.5.0, Dockerfile LABEL, helm/Chart.yaml appVersion, values.yaml image tag
B4  code-review on main..HEAD   -> 2 nits addressed, re-run tests green
B5  git push -u origin feat/oauth-login
    gh pr create --base main --title "feat(auth): OAuth login" --body-file .github/pr-body.md
B6  gh pr checks --watch --fail-fast     # then:
    gh pr view --json headRefOid,statusCheckRollup
    # Match the tested head SHA and inspect required check runs and legacy status contexts.
B7  PR_NUMBER=$(gh pr view --json number --jq '.number')
    gh pr merge "$PR_NUMBER" --squash --delete-branch \
      --subject "feat(auth): OAuth login (#$PR_NUMBER)" --body "Closes #118"
B8  # Set RELEASE_SHA to the verified merged release commit before tagging.
    git fetch --tags origin
    if git show-ref --verify --quiet refs/tags/v1.5.0; then
      echo "Tag exists; verify the existing release before proceeding" >&2; exit 1
    fi
    git tag -a v1.5.0 -m "v1.5.0" "$RELEASE_SHA" && git push origin refs/tags/v1.5.0
    gh release create v1.5.0 --title v1.5.0 --notes-file <(extract_changelog 1.5.0)  # helper in references/finish.md
    # Resolve RELEASE_SHA from the merged release commit, not the former feature HEAD.
    # Select the exact workflow/tag/SHA/event using references/finish.md, then:
    gh run watch "$RUN_ID" --exit-status
```

GitLab substitutes `glab mr create`, `glab ci status --live`, `glab mr merge --squash --remove-source-branch`, `glab release create`. Forgejo substitutes `fj pr create`, `fj pr merge --method squash --delete`, `fj release`. Gitea substitutes `tea pulls create`, `tea pulls merge --style squash`, `tea releases create`. Bitbucket and bare paths skip B5-B8 CLI steps and use web UI / `format-patch` respectively.

---

## Output Contract

See `references/output-contract.md` for the full contract.

- **Skill name:** DEV-CYCLE
- **Deliverable bucket:** `audits`
- **Mode:** conditional. When invoked to **analyze, review, audit, or improve** existing repo content, apply the reporting size and evidence rules in `references/output-contract.md` and write the deliverable to `docs/local/audits/dev-cycle/<YYYY-MM-DD>-<slug>.md`. When invoked to **answer a question, teach a concept, build a new artifact, or generate content**, respond freely without the contract.
- **Severity scale:** `P0 | P1 | P2 | P3 | info` (see shared contract; only used in audit/review mode).

## Reference Files

- `references/start.md` - detailed start-mode workflow, branch naming conventions, spec file template, brainstorming fallback chain (including headless-mode behavior)
- `references/finish.md` - detailed finish-mode workflow with per-forge commands (GitHub/GitLab/Forgejo/Gitea/Bitbucket) and bare-git paths (format-patch, bundle, local merge). Covers forge detection, toolchain detection with custom-script fallback, CI watch traps, release cutting, and rollback
- `references/size-heuristics.md` - complete size-classification table with concrete signals, edge cases, and the ambiguity-resolution questions
- `references/version-bump-sites.md` - grep patterns and locations for version strings across common ecosystems (Docker, K8s, Helm, package managers)

## Rules

The AI Self-Check and the workflow steps carry the per-step guards (no `--no-verify` or
force-push, no AI attribution). These add:

1. **Read before edit.** Always read files you're about to modify in the current session. No exceptions.
2. **Delegate, don't reimplement.** `git`, `testing`, `code-review`, `update-docs`, and brainstorming skills know their domains better than this skill does. Call them.
3. **Inspect CI output, don't infer it.** Every forge's watch command has a default-exit trap: `gh run watch` exits 0 on workflow failure without `--exit-status`; `gh pr checks --watch` returns when done, not only when green; `glab ci status --live` prints but doesn't always exit non-zero on pipeline failure. After any watch, verify with an explicit status query (`gh pr view --json statusCheckRollup`, `glab api projects/$PROJECT_ID/pipelines/$PIPELINE_ID`, or web-UI confirmation for forges without a CLI). Confirm every check actually passed.
4. **Squash and merge only with explicit intent.** Each fixes history in a way that is hard to undo after others pull; a finish-mode request is that intent, a start-mode request is not. Force-push stays off-limits (AI Self-Check).
5. **Preserve release authorization.** Announce the version, bump sites, and concrete plan. Existing authorization remains valid within its scope; ask before pushing the tag only when that authority is missing or scope changes.
6. **Show evidence, not claims.** Put concrete verification (test counts, lint output, CI run URL) in PRs and final summaries; reviewers cannot approve what they cannot verify.
7. **Don't bundle unrelated work.** If mid-finish you notice a bug outside the branch's scope, file it (roadmap skill or an issue) - don't sneak it into the PR.
8. **Release detection is conservative.** If no convention signals are present, skip. A missing `CHANGELOG.md` plus no tags means this isn't a release-cut situation - don't create one.
9. **Plain ASCII only.** No em-dashes, no `--` substitutes, no curly quotes, no decorative emoji. Functional status markers (`[OK]`, `[FAIL]`, severity emoji in reports from delegated skills) are fine.
10. **Mode boundaries are sacred.** Start mode ends with a handoff, not implementation. Finish mode starts with verification, not committing new code. Don't blur them - except when the user explicitly asks for the full cycle in one session (e.g. "do the full dev-cycle, release, deploy"): then run start through finish back to back, still starting finish with verification.