@jamie-tam/forge 6.0.0

package/skills/build-pr-workflow/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: build-pr-workflow
+description: "Use when feature work needs branch isolation, atomic commits, or PR creation — covers the full git lifecycle from worktree to merge."
+---
+
+# PR Workflow
+
+## Overview
+
+Manage the full git workflow lifecycle: create isolated workspaces, make atomic commits during development, and finish work with structured options for merge or PR creation.
+
+**Announce at start:** "I'm using the build-pr-workflow skill to manage the git workflow."
+
+## When to Use
+
+- Starting any feature, bugfix, or refactor that needs branch isolation
+- Creating pull requests from completed work
+- Finishing a development branch (merge, PR, keep, or discard)
+
+## When to load references
+
+- **`references/worktree-setup.md`** — Phase 1 detail: directory selection priority, safety-verification gitignore check, step-by-step worktree creation. Load before starting a new branch.
+- **`references/pr-template.md`** — Phase 3 detail: the full PR description template and the `gh pr create` HEREDOC. Load when ready to open the PR.
+- **`references/subagent-merge.md`** — Protocol for integrating output from subagents dispatched with `isolation: "worktree"`. Load when a worktree-isolated subagent has returned.
+
+## Phase 1: Worktree Creation
+
+The detailed procedure (directory priority, gitignore safety, project setup, baseline verification) lives in **`references/worktree-setup.md`** — load it before starting a new worktree.
+
+In summary:
+
+1. Pick the worktree directory: `.worktrees/` (preferred) → `worktrees/` → CLAUDE.md preference → ask the user.
+2. **Verify it's gitignored.** If not, add to `.gitignore` and commit before creating the worktree.
+3. `git worktree add <path> -b <branch-name>` using the conventional branch prefix (`feat/`, `fix/`, `refactor/`, `hotfix/`).
+4. Run project setup (npm install, pip install, cargo build, go mod download as appropriate).
+5. Verify clean baseline by running the project's test command. If tests fail, report and ask.
+
+## Phase 2: Development
+
+### Commit Discipline
+
+One commit per logical unit of work. Each commit must:
+
+1. **Be atomic** — Contains exactly one logical change
+2. **Pass all tests** — Never commit broken code
+3. **Use conventional commits** — Format: `type(scope): description`
+
+```
+feat(auth): add JWT token validation middleware
+fix(api): handle null email in user creation
+refactor(db): extract connection pool configuration
+test(auth): add integration tests for login flow
+docs(api): update endpoint documentation
+```
+
+### Commit Workflow
+
+```bash
+# 1. Verify tests pass before committing
+npm test  # or equivalent
+
+# 2. Stage specific files (never git add .)
+git add src/auth/middleware.ts tests/auth/middleware.test.ts
+
+# 3. Commit with conventional message
+git commit -m "feat(auth): add JWT token validation middleware"
+```
+
+**Rules:**
+- Run tests before every commit
+- Stage specific files, not everything
+- Never commit `.env`, secrets, or large binaries
+- One logical change per commit, not "save my progress"
+
+### Atomic Commit Splitting
+
+When a changeset touches 3+ files, split into multiple atomic commits along logical boundaries:
+
+| Files Changed | Minimum Commits |
+|---|---|
+| 3-4 files | 2+ commits |
+| 5-9 files | 3+ commits |
+| 10+ files | 5+ commits |
+
+**Split along these boundaries:**
+- Separate module/component boundaries
+- Separate concern types (types, logic, tests, config)
+- Each commit independently revertable without breaking the project
+
+**Before splitting:** Analyze the last 30 commits to detect the project's commit style. If mixed styles, conventional commits take precedence when ≥50% of commits use them. If the repo has fewer than 30 commits or no clear majority, default to conventional commits per git-workflow.md.
+
+### During TDD Cycles
+
+A natural commit rhythm during TDD:
+
+1. RED-GREEN-REFACTOR cycle for behavior A -> commit
+2. RED-GREEN-REFACTOR cycle for behavior B -> commit
+3. RED-GREEN-REFACTOR cycle for behavior C -> commit
+
+Each commit captures one complete TDD cycle. The commit message describes the behavior added, not the test written.
+
+## Phase 3: PR Creation
+
+### PR-Per-Function Strategy
+
+Each PR should cover one logical function or component. This means:
+
+- **One PR per API endpoint** (e.g., "Add POST /api/users endpoint")
+- **One PR per UI component** (e.g., "Add UserProfileCard component")
+- **One PR per service** (e.g., "Add email notification service")
+- **One PR per migration** (e.g., "Add users table migration")
+
+**Not one giant PR** with everything. Not one PR per file either. One PR per logical unit that can be reviewed, tested, and merged independently.
+
+### PR Requirements
+
+Each PR must be:
+
+1. **Independently mergeable** — Does not break anything if merged alone
+2. **Independently testable** — Has its own tests that pass
+3. **Properly described** — Links to feature manifest and requirements
+4. **Small enough to review** — Under 400 lines of diff is ideal
+
+### Creating the PR
+
+The full template and HEREDOC live in **`references/pr-template.md`** — load it when you're ready to open the PR. The required sections are: Summary, Feature Manifest, Requirements Traceability, Changes, Test Plan, Checklist.
+
+## Phase 4: Finishing
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+npm test / pytest / cargo test / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Do not proceed.
+
+**If tests pass:** Continue.
+
+### Step 2: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main -- is that correct?"
+
+### Step 3: Present Options
+
+Present exactly these 4 options:
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+Keep options concise. Do not add lengthy explanations.
+
+### Step 4: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+# Switch to base branch
+git checkout <base-branch>
+
+# Pull latest
+git pull
+
+# Merge feature branch
+git merge <feature-branch>
+
+# Verify tests on merged result
+npm test
+
+# If tests pass, delete feature branch
+git branch -d <feature-branch>
+```
+
+Then: Clean up worktree (Step 5).
+
+#### Option 2: Push and Create PR
+
+Follow **`references/pr-template.md`** for the structured body. Push, create the PR, report the URL. Then: Clean up worktree (Step 5).
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch `<name>`. Worktree preserved at `<path>`."
+
+**Do not clean up worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+```
+This will permanently delete:
+- Branch <name>
+- All commits on this branch
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation. If confirmed:
+
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+```
+
+Then: Clean up worktree (Step 5).
+
+### Step 5: Worktree Cleanup
+
+**For Options 1, 2, 4:**
+
+```bash
+# Check if working in a worktree
+git worktree list | grep <feature-branch>
+
+# If yes, remove it
+git worktree remove <worktree-path>
+```
+
+**For Option 3:** Keep worktree intact.
+
+## Merging Subagent Worktree Output
+
+When dispatching subagents with `isolation: "worktree"`, follow the protocol in **`references/subagent-merge.md`** — it covers: requiring the subagent to commit, verifying commits before merging, merging via `git merge --no-ff` (never `cp`), and worktree cleanup.
+
+## Quick Reference
+
+### Worktree Selection
+
+| Situation | Action |
+|-----------|--------|
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check CLAUDE.md, then ask user |
+| Directory not ignored | Add to .gitignore + commit first |
+| Tests fail during baseline | Report failures + ask |
+
+### Finishing Options
+
+| Option | Merge | Push | Keep Worktree | Delete Branch |
+|--------|-------|------|---------------|---------------|
+| 1. Merge locally | Yes | No | No | Yes (safe) |
+| 2. Create PR | No | Yes | Cleaned up | No |
+| 3. Keep as-is | No | No | Yes | No |
+| 4. Discard | No | No | No | Yes (force) |
+
+## Red Flags
+
+**Never:**
+- Create a worktree without verifying it is ignored (project-local) — pollutes git status with worktree contents.
+- Commit without running tests — breaks bisection and blocks other developers.
+- Proceed with failing tests, force-push without request, or skip the typed "discard" confirmation.
+- Create a PR without a structured description linking to the feature manifest.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Task scope from manifest's `slice_graph` (prototype-driven flow, produced by `harden`) OR `.forge/work/{type}/{name}/tasks.md` (non-prototype fallback, produced by `plan-task-decompose`); work manifest at `.forge/work/{type}/{name}/manifest.yaml` |
+| **Produces** | Git worktree, feature branch, atomic commits, pull request(s) on GitHub/GitLab |
+| **Feeds into** | `deliver-deploy` (PRs ready to merge and deploy) |
+| **Updates manifest** | `branch`, `worktree`, `phase`, PRs created |
+
+## Integration
+
+**Called by:**
+- `/feature` command (worktree setup + PR creation)
+- `/greenfield` command (worktree setup + PR creation)
+- `/bugfix` command (branch + PR)
+- `/refactor` command (branch + PR)
+
+**Pairs with:**
+- `build-tdd` (commits happen during TDD cycles at Phase 6)
+- `quality-code-review` (reviews happen before PR creation)
+- `harden` (prototype-driven flow: slice graph determines PR scope)
+- `plan-task-decompose` (non-prototype fallback flow: tasks determine PR scope)
+- `deliver-deploy` (PRs feed into deployment)

package/skills/build-pr-workflow/references/pr-template.md

@@ -0,0 +1,62 @@
+# PR creation — template and command
+
+Phase 3 of the PR workflow: push the branch and create a PR with a structured description. Load this when ready to open the PR.
+
+## Required sections in the PR description
+
+| Section | Required | Purpose |
+|---------|----------|---------|
+| Summary | Yes | What and why in 2-3 bullets |
+| Feature Manifest | Yes | Link to manifest for traceability |
+| Requirements Traceability | Yes | Which requirements this PR satisfies |
+| Changes | Yes | Key files changed with brief description |
+| Test Plan | Yes | How to verify the PR works |
+| Checklist | Yes | Verification items |
+
+## Creating the PR
+
+```bash
+# 1. Verify all tests pass
+npm test
+
+# 2. Push branch
+git push -u origin <branch-name>
+
+# 3. Create PR with structured description
+gh pr create --title "<type>(scope): description" --body "$(cat <<'PREOF'
+## Summary
+
+- What this PR does (2-3 bullets)
+- Why it is needed
+
+## Feature Manifest
+
+Links to: `.forge/work/{type}/{name}/manifest.yaml` (manifest), slice IDs from `slice_graph` (prototype-driven flow) OR REQ-IDs (non-prototype fallback flow).
+
+## Requirements Traceability
+
+- Implements: [REQ-001] User can create account
+- Satisfies acceptance criteria: [AC-001.1], [AC-001.2]
+
+## Changes
+
+- `src/auth/service.ts` -- New authentication service
+- `src/auth/middleware.ts` -- JWT validation middleware
+- `tests/auth/` -- Unit and integration tests
+
+## Test Plan
+
+- [ ] Unit tests pass (`npm test`)
+- [ ] Integration tests pass
+- [ ] Manual verification: [describe steps]
+
+## Checklist
+
+- [ ] Tests written and passing
+- [ ] No skipped tests
+- [ ] API contract validated
+- [ ] No secrets in code
+- [ ] Conventional commit messages
+PREOF
+)"
+```

package/skills/build-pr-workflow/references/subagent-merge.md

@@ -0,0 +1,47 @@
+# Merging subagent worktree output
+
+When the main agent dispatches subagents with `isolation: "worktree"`, the subagent works in an isolated git worktree. The worktree path and branch name are returned when the subagent completes. Follow this protocol to integrate the work.
+
+Load this when a subagent dispatched with worktree isolation has returned.
+
+## Dispatch
+
+Include in the subagent prompt: **"Commit your changes with a conventional commit message before completing."**
+
+## Post-return integration
+
+After a subagent completes:
+
+```bash
+# 1. Check if the subagent committed
+cd <worktree-path>
+git log --oneline <worktree-branch> --not main | head -5
+
+# 2. If no commits exist, commit on the subagent's behalf
+# Review changed files first, then stage specifically (avoid staging secrets/artifacts)
+git add <changed-source-files>
+git commit -m "feat(scope): description of subagent work"
+
+# 3. Return to main working directory
+cd <main-repo-path>
+
+# 4. Merge via git — NEVER use cp/file copy
+git merge <worktree-branch> --no-ff
+
+# 5. If merge conflicts arise, resolve them manually
+# This is expected when parallel agents touch shared files
+
+# 6. Clean up the worktree
+git worktree remove <worktree-path>
+```
+
+## Rules
+
+- **NEVER** merge subagent work via `cp` or file copy — use `git merge --no-ff`
+- **ALWAYS** verify the subagent committed before merging — commit on their behalf if they didn't
+- **`--no-ff`** preserves the branch in history, making it clear which work came from which subagent
+- If merge conflicts arise, this is a signal that the tasks were too tightly coupled — resolve the conflict, then note it as a gotcha for future task decomposition
+
+## Why not cp
+
+File copy (`cp`) silently overwrites. If two parallel subagents both modified the same file, `cp` from the second agent destroys the first agent's work with no warning. `git merge` surfaces these conflicts explicitly.

package/skills/build-pr-workflow/references/worktree-setup.md

@@ -0,0 +1,125 @@
+# Worktree setup — directory selection and creation
+
+Phase 1 of the PR workflow: pick a worktree directory, verify it's gitignored, create the worktree, install deps, verify the baseline. Load this when starting a new feature/bugfix/refactor that needs an isolated worktree.
+
+## Directory selection process
+
+Follow this priority order:
+
+### 1. Check existing directories
+
+```bash
+# Check in priority order
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+```
+
+**If found:** Use that directory. If both exist, `.worktrees` wins.
+
+### 2. Check CLAUDE.md
+
+```bash
+grep -i "worktree.*director" CLAUDE.md 2>/dev/null
+```
+
+**If preference specified:** Use it without asking.
+
+### 3. Ask user
+
+If no directory exists and no CLAUDE.md preference:
+
+```
+No worktree directory found. Where should I create worktrees?
+
+1. .worktrees/ (project-local, hidden)
+2. worktrees/ (project-local, visible)
+3. Custom path
+
+Which would you prefer?
+```
+
+## Safety verification
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+# Check if directory is ignored (respects local, global, and system gitignore)
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:**
+
+Fix immediately:
+1. Add appropriate line to `.gitignore`
+2. Commit the change
+3. Proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents to the repository.
+
+## Creation steps
+
+### 1. Detect project and branch name
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+# Branch name from feature manifest or task
+branch_name="feat/feature-name"  # or fix/, refactor/ per git-workflow rules
+```
+
+**Branch naming convention:**
+- Features: `feat/short-description`
+- Bug fixes: `fix/short-description`
+- Refactors: `refactor/short-description`
+- Hotfixes: `hotfix/short-description`
+
+### 2. Create worktree
+
+```bash
+# Determine full path
+path=".worktrees/$branch_name"
+
+# Create worktree with new branch
+git worktree add "$path" -b "$branch_name"
+cd "$path"
+```
+
+### 3. Run project setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then pip install -e ".[dev]" || poetry install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. Verify clean baseline
+
+Run tests to ensure the worktree starts clean:
+
+```bash
+# Use project-appropriate command
+npm test / pytest / cargo test / go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### 5. Report
+
+```
+Worktree ready at <full-path>
+Branch: <branch-name>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```