Dev Cycle: Start-to-Finish Workflow

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 full-review or deep-audit

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

Before declaring finish-mode complete:

• $FORGE detected from git remote get-url origin before any push/PR/merge step
• All lint/type/test suites green - output inspected, not inferred from "exit code 0". If no toolchain was detectable, user was asked explicitly (not silently skipped)
• 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
• Current source checked: dated versions, CLI flags, API names, and support windows are verified against primary docs before repeating them
• Hidden state identified: local config, credentials, caches, contexts, branches, cluster targets, or previous runs are made explicit before acting
• Verification is real: final checks exercise the actual runtime, parser, service, or integration point instead of only linting prose or happy paths
• Routing overlap checked: overlapping skills, trigger terms, and "When NOT to use" boundaries are checked before returning guidance
• Spec claims verified: claims about tool behavior, output contracts, or repo conventions are checked against current docs, scripts, or skill files
• 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

Performance

• Run the narrowest meaningful checks (e.g., --testPathPattern or go test ./pkg/...) during iteration, then the full required gate (lint + typecheck + test) 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.

Best Practices

• Create the feature branch before any implementation edits; untracked local changes that predate the branch are easy to accidentally bundle into the wrong commit.
• Do not force-push, squash, or merge without explicit user intent - each has a different history rewrite consequence that's hard to undo after others have pulled.
• Put concrete verification evidence (test counts, lint output, CI run URL) in PRs and final summaries rather than vague "tests pass" claims; reviewers cannot approve what they cannot verify.

Workflow

Step 0: Detect mode

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