Skip to main content

Workflow

hatch3r provides a full project lifecycle, from setup to release. This guide walks through the typical flow and links to the deeper view of the four-phase pickup pipeline and review loop.

:::info Last verified 2026-06-11 against hatch3r 2.0.0. The init flow described in Step 1 mirrors the canonical prompt order in src/cli/commands/init.ts; the copy-paste-runnable version lives in the Quick Start. Re-verified each audit cycle (P3 — Adapter & MCP Currency). :::

1. Initialize​

npx hatch3r init

Interactive setup (~2 minutes) detects your repository from its git remote and walks a short prompt sequence. On a fresh GitHub greenfield repo it asks 6 prompts:

  1. Platform — GitHub, Azure DevOps, or GitLab, auto-detected from your git remote (press Enter to accept).
  2. Repo identity — owner + repo (GitHub), namespace + project (GitLab), or org + project + repo (Azure DevOps), auto-filled from the remote where possible.
  3. Content profile — minimal, standard (recommended), full, or custom.
  4. Custom content items — only when custom is selected at step 3.
  5. Tools — multi-select from the 3 supported adapters (Claude Code, Cursor, Copilot).
  6. CLI tools — tier-grouped picker (tier-1 + trigger-matched tier-2 pre-checked; enter-through equals the --yes smart default). MCP is not prompted — opt in with npx hatch3r init --mcp or npx hatch3r mcp setup later.

Default branch, project type (greenfield/brownfield), and team size (solo/team) are inferred, not prompted — branch from git, the others from repository signals. If detected CLI tools are missing from PATH, hatch3r prints copy-paste install commands and adds one Mark these tools as 'install pending' and continue? confirm. Headless --yes skips every prompt and falls back to the CLI-tools smart default.

:::tip CLI tools default-on since 1.7.5 hatch3r's primary agent-tooling surface is CLI tools (ripgrep, fd, jq, yq, gh, delta, bat, sd, ast-grep, zstd as the tier-1 default; 19 more across tier-2 conditional and tier-3 opt-in). MCP is opt-in. See CLI Tools for the full catalog, decision tree, and trade-off discussion. :::

Next steps after init:

Starting pointCommandWhat it does
Full project (either kind)/hatch3r-specAuto-detects greenfield vs brownfield and runs the matching spec flow
Single feature/hatch3r-feature-planPlan one feature with parallel researchers — no board needed
Tiny change/hatch3r-quick-changeOne-shot flow for a typo, config tweak, or one-file refactor

Full project (greenfield or brownfield)​

  1. Run /hatch3r-spec -- on a new project it generates specs from your vision; on an existing codebase it reverse-engineers specs from the current code. It picks the branch by detecting project state, so you do not choose greenfield vs brownfield yourself. Produces docs/specs/, docs/adr/, and todo.md.
  2. Run /hatch3r-roadmap to refine the plan into dependency-ordered epics broken into milestones.
  3. Continue with board fill (step 4 below).

To force one branch, the split commands remain as a legacy path: /hatch3r-project-spec (greenfield only) or /hatch3r-codebase-map (brownfield only), each followed by /hatch3r-roadmap.

2. Set up the board​

:::note Board workflows are team-scoped Steps 2-5 (board init / fill / pickup) install only when your repo resolved to team size. hatch3r init infers team size from git history (more than one distinct commit-author email ⇒ team) and defaults a single-author or fresh repo to solo, where the board cluster is not installed and init prints a one-line note saying so. Re-run with --team-size team (or switch later via hatch3r config) to add the board chain. Solo developers can drive single features without a board via /hatch3r-feature-plan. :::

Invoke the hatch3r-board-init skill from your editor (Claude Code: Skill: hatch3r-board-init; Cursor: load it from the skills picker; Copilot: reference it in chat) to create or connect a project board on your detected platform.

Board-init handles:

  • Project creation via GraphQL (GitHub Projects V2), or the Azure DevOps / GitLab equivalent
  • Status field configuration (Backlog, Ready, In Progress, In Review, Done)
  • Full label taxonomy creation
  • Writing the resolved board owner / project number / area labels back to hatch.json

3. Define work​

Create a todo.md file at the project root with your planned work -- epics, features, bugs, refactors, migrations, anything. One item per line.

- Add OIDC login support for the customer portal
- Migrate analytics events to the new schema
- Replace Stripe webhook polling with idempotent event ingestion

4. Fill the board​

Run /hatch3r-board-fill to parse todo.md and turn items into platform issues.

Board-fill:

  • Deduplicates against existing issues
  • Classifies each item by type (feature / bug / refactor / migration / test), priority, executor, area, and risk
  • Groups items into epics
  • Builds a dependency DAG and determines implementation order
  • Marks issues as status:ready when all readiness criteria are met

For backlog hygiene later, invoke the hatch3r-board-groom skill — it surfaces stale items, priority imbalances, and decomposition candidates.

5. Pick up work​

Run /hatch3r-board-pickup to auto-select the next status:ready issue by dependency order and priority.

Board-pickup:

  • Performs collision detection against in-progress work and open PRs
  • Creates a feature branch
  • Runs the four-phase agent pipeline: research → implement → review loop (reviewer + fixer, max 3 iterations) → final quality gates (test-writer + security-auditor)
  • Opens a pull request with full board status sync when the loop converges clean

Repeat this step until the board drains. The reviewer + fixer loop is automatic — there is no separate review command.

6. Review cycle​

The reviewer, test-writer, and security-auditor agents review the work inside the pickup pipeline. When you need to address feedback by hand, push fixes and re-request review. For a standalone feature (no board), run /hatch3r-workflow (Quick Mode) after /hatch3r-feature-plan to walk the implement → review → test pipeline directly.

7. Release​

Invoke the hatch3r-release skill, or run the /hatch3r-release orchestrator command for delegated execution with the review-loop and final-quality gate.

/hatch3r-release is a cut-and-verify workflow that stops before publish — it never publishes, merges, tags-and-pushes, or deploys on a bare invocation. It:

  • Classifies merged PRs to determine the semantic version bump (patch / minor / major)
  • Generates a grouped changelog (Added / Changed / Deprecated / Removed / Fixed / Security)
  • Runs quality gates and emits supply-chain artifacts (CycloneDX SBOM, npm provenance, SLSA, cosign)
  • Creates the annotated tag locally (reversible), then stops and hands the publish decision to you

The irreversible steps — tag push, npm publish, GitHub release create, production deploy — are default-OFF behind a --publish flag or a typed confirmation. Before invoking, run npx hatch3r validate to confirm canonical content has not drifted.

That closes the loop: init → spec → board → pickup → release.