diff --git a/.claude/agents/implementer.md b/.claude/agents/implementer.md index fbd54d88..c298ba1d 100644 --- a/.claude/agents/implementer.md +++ b/.claude/agents/implementer.md @@ -9,8 +9,9 @@ You are the **implementer** for a single Pair user story. You own the *authoring ## Operating rules - **The skills are the process of record — execute them, don't improvise.** Implementation follows `/pair-process-implement` (produce its artifacts); the checkpoint is written via `/pair-capability-checkpoint`; the PR follows the PR template (`.pair/knowledge/guidelines/collaboration/templates/pr-template.md`) and, once it exists, `/pair-capability-publish-pr` (#255); commits/branches follow their templates. Read `CLAUDE.md` and the relevant `.pair/` guidelines first. +- **One PR per story (the open-PR step is create-or-update).** A story is delivered on ONE branch with ONE PR. If the story already has an open PR, push to its branch and UPDATE that PR; NEVER open a second PR for the same story — even for a new task/feature — unless the orchestrator explicitly instructs it. Further tasks are commits within that one PR, not new PRs. - **Handoff discipline (context reset).** You may be a *fresh instance resuming prior work*. At start, if `.pair/working/checkpoints/.md` exists, read it via `/pair-capability-checkpoint $mode=resume` and continue from there — do not re-derive from scratch. Before you finish a step, update the checkpoint (`$mode=write`) so the next fresh instance can resume with zero prior context. -- **Test-first for bugs** (per `CLAUDE.md`): write the failing test before the fix. +- **Test-first for bugs** (per `CLAUDE.md`): write the failing test before the fix. Gate/tooling logic lives in tested production modules — never unit-test scripts; verify script/CLI behavior via smoke tests (see ADL `.pair/adoption/decision-log/2026-07-13-gate-tooling-code-in-tested-modules.md`). - **Quality gates** must pass (scoped) before you report a code step complete. - **Fix step:** when given review findings, address each, commit, and post a remediation comment on the PR summarizing what changed per finding. Do not argue with the reviewer in code — fix or, for a genuine design disagreement, flag it for the orchestrator to escalate. - **Commit only the files you changed** — stage explicit paths, **never `git add -A`** (a repo-wide pre-push formatter can otherwise sweep unrelated reformats into your commit). diff --git a/.claude/skills/pair-process-implement/SKILL.md b/.claude/skills/pair-process-implement/SKILL.md index 5503a0b9..fc042cfa 100644 --- a/.claude/skills/pair-process-implement/SKILL.md +++ b/.claude/skills/pair-process-implement/SKILL.md @@ -9,6 +9,8 @@ author: Foomakers Implement a user story by processing its tasks sequentially. Each task follows a 5-step cycle: context → branch → implementation → quality → commit. The story-level process has 5 phases (0–4): analysis, setup, implementation, PR creation, and post-review merge. Creates a single PR when all tasks are done. +**One PR per story:** the story lands on ONE branch with ONE PR; subsequent work on the story (further tasks/features) updates that same PR, never a new one unless explicitly requested. + ## Composed Skills | Skill | Type | Required | diff --git a/.claude/workflows/implement-batch.js b/.claude/workflows/implement-batch.js index 647a5e27..194afeb9 100644 --- a/.claude/workflows/implement-batch.js +++ b/.claude/workflows/implement-batch.js @@ -6,9 +6,16 @@ export const meta = { } // ── Input ──────────────────────────────────────────────────────────────── -// args.stories = the batch to drive THIS run. MUST be pre-filtered to be -// mutex-safe: no two stories here may touch the same shared skill/file -// (pair-next, pair-process-review, record-decision, apps/pair-cli, templates). +// args.stories = the batch of STORIES (never tasks) to drive THIS run. A batch +// ITEM IS A STORY, not a task: each story is delivered on ONE branch with ONE +// PR — opened the first time and UPDATED for all subsequent work on that story +// (further tasks/features included). NEVER one-PR-per-task, and NEVER a second +// PR for the same story: continuing a story that already has a PR reuses its +// existing branch/{prNumber} and updates that PR (create-or-update). A second +// PR for the same story is forbidden unless a human explicitly instructs it. +// MUST be pre-filtered to be mutex-safe: no two stories here may touch the same +// shared skill/file (pair-next, pair-process-review, record-decision, +// apps/pair-cli, templates). // Chains advance ACROSS runs: after you merge these PRs, re-run with the next // batch (the now-unblocked heads). A story's dependency must be MERGED, not // just PR-ready, before its dependent enters a batch. diff --git a/.pair/knowledge/guidelines/technical-standards/git-workflow/development-process.md b/.pair/knowledge/guidelines/technical-standards/git-workflow/development-process.md index 2e78c509..61da1ada 100644 --- a/.pair/knowledge/guidelines/technical-standards/git-workflow/development-process.md +++ b/.pair/knowledge/guidelines/technical-standards/git-workflow/development-process.md @@ -21,6 +21,7 @@ This document establishes a comprehensive Git workflow that supports our rapid d - **Lifecycle**: Short-lived (days, not weeks) - **Origin**: Always branch from latest `main` - **Merge**: Via pull request with squash +- **PR granularity — one PR per story**: A story is delivered on ONE branch with ONE PR, opened the first time and updated for all subsequent work on it (further tasks are commits/checkboxes within that same PR). Never open a second PR for the same story unless a human explicitly says so. #### Hotfix Branches diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/git-workflow/development-process.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/git-workflow/development-process.md index 2e78c509..61da1ada 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/git-workflow/development-process.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/git-workflow/development-process.md @@ -21,6 +21,7 @@ This document establishes a comprehensive Git workflow that supports our rapid d - **Lifecycle**: Short-lived (days, not weeks) - **Origin**: Always branch from latest `main` - **Merge**: Via pull request with squash +- **PR granularity — one PR per story**: A story is delivered on ONE branch with ONE PR, opened the first time and updated for all subsequent work on it (further tasks are commits/checkboxes within that same PR). Never open a second PR for the same story unless a human explicitly says so. #### Hotfix Branches diff --git a/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md b/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md index dc895215..531f248c 100644 --- a/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md +++ b/packages/knowledge-hub/dataset/.skills/process/implement/SKILL.md @@ -9,6 +9,8 @@ author: Foomakers Implement a user story by processing its tasks sequentially. Each task follows a 5-step cycle: context → branch → implementation → quality → commit. The story-level process has 5 phases (0–4): analysis, setup, implementation, PR creation, and post-review merge. Creates a single PR when all tasks are done. +**One PR per story:** the story lands on ONE branch with ONE PR; subsequent work on the story (further tasks/features) updates that same PR, never a new one unless explicitly requested. + ## Composed Skills | Skill | Type | Required |