CLAUDE.md

v5.4.1 — Last updated: 2026-10-31 (v5.4.0 — the 2026-10-31 audit release (#215–#218): a fresh pk init project works, pk doctor names a foreign binary, template placeholders and missing Linear states; MIT license and a README that gets a stranger to a green pk doctor; skill commands are /light-spec, /light-spec-revise, /roadmap-review, /strategy-sync (no numeric prefixes) and /work is the one executor again; no former consumer is named anywhere a sync can carry it. New config keys Merge method, Secrets reference file, Plan path: none; the financial-review issue key is Financial review issue.)

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

This is Pipekit — a portable, structured AI-assisted software delivery system. It is NOT a software project itself. It contains methodology docs, SOPs, templates, and Claude Code skills that get synced into consuming projects via scripts/sync-method.sh.

Extracted from a production finance platform.

Core Principle

No stage may introduce guesswork into the next stage. Specs must be planning-safe. Plans must be execution-safe. When ambiguity is detected, work goes backward, not forward.

Pipeline

Stage 0: Foundation (a contract — see Entry Modes)
  /concept → /define → /strategy-create → /startup → /roadmap-create → /phase-plan

Stages 1-5: Development — the v2 daily loop (repeats per issue)
  pk next → pk branch → /work → /verify → pk ship (Draft) → pk ready → [PR review + preview UAT → merge] → pk done → [dev UAT] → pk promote <env> → (PR merges) → pk promote <env> --finish

pk done runs AFTER the merge and verifies it. --merge is the exception (pk runs gh pr merge for you) — never suggest it for an already-merged PR.

Per session (NOT part of the issue chain): /pk-exit — the last command of whatever session you're in.
  pk done runs from the parent repo and deletes the worktree, so in a worktree session: /pk-exit first, THEN leave the worktree and run pk done from the parent.

Stage 0 is a contract (a set of artifacts the dev pipeline requires), not a script. Three entry modes satisfy the contract: greenfield (full chain), brownfield (skip /concept and /define), inherited (verify and proceed). /startup auto-detects mode and confirms with the user. The v2 daily loop replaces v1's /branch → /launch → /verify → /launch --close chain — see RUNBOOK.md for the one-page flowchart. Full Entry Modes table in method.md.

How Consuming Projects Work

Projects pull from this repo using sync-method.sh. The sync copies skills/, sop/, templates/, and method.md into the project, and writes the How we run block of the project's one runbook (engineering/RUNBOOK.md, v5.0.0 — the former pipekit/RUNBOOK.md; the Now block is /tpm's one-line pointer at the weekly plan engineering/WEEKLY_PLAN.md, which the sync scaffolds and only /tpm writes (v5.1.0), the rest to the project). It never touches project-specific files (method.config.md, .claude/rules/, project-specific skills). Exception: the five pipekit-* canonical rule files in .claude/rules/ are sync-owned; a Skip rules key in method.config.md opts a project out of canonical rules that don't apply to it (v4.21.0+).

Sync-safe overrides: projects can override synced skills/SOPs/method.md without forking by writing to .claude/overrides/. The sync script applies overrides after the upstream copy and surfaces drift warnings when upstream changes a file you override. See method.md § Sync-Safe Overrides.

Initiative Surface Ownership

Native-on-Workflow is the sole executor and the initiative surface is Linear-native. Pipekit owns the whole surface:

• Pipekit owns Linear issues, the initiative surface (Linear Initiatives i{N}. → Projects I{N}.P{N}. → Issues; v4.1.0, project I{N}. prefix added v4.5.0), strategy docs, and method.config.md. "What's next?" is read live from Linear via pk next (derives the current initiative from the initiative/project hierarchy); v2 retired the NEXT.md mirror, v4.1.0 retired PHASES.md/linear-map.json.
• The roadmap is authored directly into Linear, at /roadmap-create — the i{N}./I{N}.P{N}. hierarchy is the roadmap.
• Both levels are completable (v4.28.0, the lanes model): an initiative is a release phase, a project is a lane of ~3–8 issues, and uncut work rests with no project plus an Area: label. The walk reads into a project but never inside one, so a project that keeps accepting work hides its contents from pk next/pk status. Completability lives at the project level; eternity lives at the theme/label level.
• /work is the only executor entry point. It plans inline (parallel Agent grounding) and executes on the saved pk-execute workflow (workflows/pk-execute.js, synced to consumers' .claude/workflows/) — the native-on-Workflow backend — keeping Linear and the pk * state in sync. There is no backend selection.

Full initiative model in method.md (§ Initiative Surface Ownership).

Editing Skills

Edit the source, then run scripts/dogfood-sync.sh. Claude Code loads skills and rules from .claude/, but in this repo those are generated mirrors of skills/, templates/rules/, agents/, and workflows/ — gitignored, and refreshed only by that script (consuming projects get theirs from sync-method.sh). Editing .claude/ directly changes nothing that ships and is silently reverted on the next refresh. A stale mirror means your own /verify, /work, etc. are running old code: measured 2026-07-31, every mirrored skill had drifted, six were missing, and .claude/skills/verify/SKILL.md still carried a gate bug the same release had fixed. tests/pk-smoke.sh fails on drift locally and skips on CI, where the mirrors don't exist.

Skills live in skills/{name}/SKILL.md with YAML frontmatter (name, description). Portable skills must read method.config.md for project-specific values — never hardcode Linear IDs, team names, paths, or model names: subagent model + effort comes from the method.config.md § Model Policy roles (v4.13.0+), cited as "role per § Model Policy, default X" so the skill still works when the section is absent. Skills that reference skill.json use it for metadata only.

Three-Layer Enforcement Model

The executor doesn't call skills — it reads the consuming project's CLAUDE.md directly during execution.

Key Skills

Stage 0 (Foundation): /concept → /define → /strategy-create → /startup (orchestrates the chain, auto-detects entry mode) → /roadmap-create (authors the roadmap into Linear) → /phase-plan (selects the next execution phase; --cut batches backlog issues into a new lane).

Development Pipeline (v2 daily loop):

Orthogonal:

Full skill list + authoring conventions in sop/Skills_SOP.md; daily-loop flowchart in RUNBOOK.md.