--- name: project-git-workflow description: Use when starting isolated feature work, committing changes, finishing a development branch, or deciding between merge, PR, keep, or discard. Ensures git isolation and review discipline while preserving PRD Plugin IDs and evidence. --- # Project Git Workflow Adapted from Superpowers by Jesse Vincent, MIT licensed: https://github.com/obra/superpowers Use this skill to keep code work isolated, reviewable, and traceable. ## Iron Law ```text NEVER COMMIT DIRECTLY TO MAIN WITHOUT EXPLICIT USER CONSENT ``` ## Commit Discipline (the positive rule) The Iron Law forbids one thing: committing to `main`. It is **not** a reason to avoid committing altogether. - **Commit every verified increment on a work branch.** A change that passes its tests and has evidence is a commit. Uncommitted work has no history and no rollback — leaving a whole build untracked is a failure, not caution. - **Local commits on a work branch never need consent — pushing, merging, and publishing are governed by the autonomy tier** (explicit consent in `key_decision`/`guided`; standing consent in `autonomous`, ship gate-green). Force-push and edits to another repo always require explicit consent, in any tier. See `project-decision-policy` (Part 3). You do not need permission to commit your own work locally. - **Fresh repo, or the only branch is `main`/`master`?** Create a work branch first (`git checkout -b /`), then commit freely on it. That satisfies the Iron Law without stranding the work. - **Autonomous runs commit.** "Do not ask the owner" plus "never commit to main" must never resolve to "never commit". Branch, commit, and report — the owner reviews history, not an untracked working tree. ## When To Use - Starting feature work that should not pollute the current branch. - Committing progress during implementation. - Finishing a branch and deciding how to integrate it. - Receiving a request to merge, push, create a PR, or discard work. ## Step 0: Detect Existing Isolation Before creating a branch or worktree, check whether the workspace is already isolated: ```bash git rev-parse --git-dir git rev-parse --git-common-dir git branch --show-current git rev-parse --show-superproject-working-tree 2>/dev/null ``` - If `GIT_DIR != GIT_COMMON_DIR` and not inside a submodule: already in a linked worktree. Skip creation. - Otherwise: in a normal checkout. Proceed to Step 1. ## Step 1: Create Isolated Workspace Prefer the host agent's native workspace tool (e.g., Codex worktree commands, opencode workspace tools) when available. Fall back to git commands only when no native tool exists. ### Branch Naming Use descriptive branch names. Link to the durable PRD Plugin work ID when one exists: ```text -- ``` Examples: - `trk-042-add-blocker-resolution-skill` - `req-007-fix-version-advice-downstream-path` - `imp-task-003-refactor-state-validator` ### Git Worktree Fallback If no native tool is available and the user consents to isolation: 1. Check existing conventions: `.worktrees/`, `worktrees/`, or project config. 2. Verify the directory is ignored before creating it: `git check-ignore -q `. 3. Create the worktree: `git worktree add -b `. 4. Change to the worktree directory. Do not create nested worktrees. Do not remove a worktree the host agent owns. ### Parallel Tracking Setup This setup is permitted only when the user explicitly requested subagents or parallel agent work. Use at most three child agents, and subagents must not spawn subagents or delegate further. If the user did not make that explicit request, keep the work single-agent even when tracking branching is enabled. When multiple agents will write in separate worktrees and `tracking.branching.require_for_parallel_agents` is enabled: 1. Before fan-out, the lead calls `prd_open_tracking_branch` once per worker. 2. Commit the resulting separate files under `.prd_plugin/state/tracking-branches/` before creating worker worktrees. 3. Give every worker exactly one branch ID and owner label, and launch it with `PRD_WORKER_SESSION=1`, `PRD_TRACKING_BRANCH_ID=`, and `PRD_TRACKING_BRANCH_OWNER=`. The worker uses only `prd_update_tracking_branch`; it does not edit canonical state or the registry. 4. Merge worker code branches and their distinct tracking files through the lead. 5. Call `prd_promote_tracking_branch` serially in the canonical checkout, then run the state and graph checks. Pre-allocation is the safety property: isolated worktrees do not share the same filesystem lock or live registry, so workers must not allocate numeric IDs. ## Step 2: Baseline Verification After creating or entering the workspace, verify it starts clean: 1. Run the project's test command. 2. If tests fail, report failures and ask whether to proceed. 3. If tests pass, record the baseline as `EV-*` when the work is significant. ## Step 3: Commit Discipline Commit frequently. Each commit should represent one coherent change. ### Commit Message Shape ```text : Body (optional): - What changed. - Why it changed. - Linked PRD Plugin IDs: TRK-*, REQ-*, IMP-TASK-*, HLT-*, EV-*, CHG-*. ``` Examples: ```text feat(skills): add project-blocker-resolution skill - Adds BLK-* ID prefix and escalation workflow. - Links TRK-023, CHG-004, EV-006. ``` ### Pre-Commit Checks Before each commit: 1. Run focused tests for the changed code. 2. Run the relevant lint/typecheck command if one exists. 3. Check that PRD Plugin state files are still valid JSON/JSONL. 4. Ensure no secrets or `.prd_plugin/local/` paths leak into the commit. ## Step 4: Finishing A Development Branch Use this when implementation is complete and all tests pass. ### Step 4a: Verify Tests Build the current verification plan. Run its complete focused scope when the strategy is `impact_scoped`; run the project full suite when the plan says `full`. A focused result is valid only when every changed file is accounted for and impact data is neither degraded nor unmapped. Do not present finish options until the selected verification plan passes. ### Step 4b: Determine Base Branch ```bash git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null ``` Confirm the base branch with the user if uncertain. ### Step 4c: Apply The Autonomy Tier In `autonomous`, do **not** present finish options. Once the selected verification plan is green and the commit is clean, complete the intended integration and push the clean verified commit to the configured remote without presenting finish options or asking again. A successful local commit is not completion while its intended remote is still behind. In `key_decision` / `guided`, present exactly these options for a normal repo or named-branch worktree: 1. **Merge locally** into the base branch. 2. **Push and create a Pull Request**. 3. **Keep the branch as-is** (user handles later). 4. **Discard this work**. For detached HEAD in `key_decision` / `guided`, present exactly these options: 1. **Push as new branch and create a Pull Request**. 2. **Keep as-is**. 3. **Discard this work**. ### Step 4d: Execute Choice #### Option 1: Merge Locally ```bash git checkout git pull git merge ``` Only after the merge succeeds: 1. Remove the worktree if it was created by this workflow (`git worktree remove `). 2. Delete the feature branch (`git branch -d `). #### Option 2: Push And Create PR ```bash git push -u origin ``` Then create the PR. Preserve the worktree for iteration on review feedback. Use the PR body to summarize: - What changed. - Linked PRD Plugin IDs. - Verification commands and results. - Remaining follow-ups. #### Option 3: Keep As-Is Report the branch name and path. Preserve the worktree. Record a `TRK-*` or `HLT-*` if the branch risks becoming stale. #### Option 4: Discard Require explicit confirmation. Show what will be deleted: - Branch name. - Commit list. - Worktree path. If confirmed: 1. Remove the worktree if this workflow created it. 2. Force-delete the branch (`git branch -D `). ## PRD Plugin Hooks - Create or update `TRK-*` records for the active branch and task. - Add `EV-*` for baseline verification, test results, and merge/PR completion. - Add `CHG-*` when project truth, skills, templates, config, or behavior changed. - Link `REQ-*` graduation to the branch or PR. - Use `project-blocker-resolution` if finishing the branch requires authority, external input, or crosses repo boundaries. ## PRD Plugin Hub Release Publication Plan and run `hub.release` for the release-boundary mechanics. It is the shipped workflow that deliberately runs release-wide verification, package checks, release hygiene, and the final gate. Use the receipt rather than reconstructing those commands ad hoc. In the PRD Plugin hub, the remote v* tag push is the publication action. .github/workflows/npm-publish.yml checks out that tag, runs tests and npm pack --dry-run, then publishes to npm with the repository's Actions secret. Push main first and then the annotated version tag. Do not run npm publish locally, probe local npm authentication, or classify absent local npm credentials as a release blocker. After a successful tag push, treat the release as published unless the owner reports otherwise; do not poll Actions or npm by default. If the owner reports that publication is missing or failed, inspect the GitHub Actions **Publish to npm** run, distinguish workflow failure from registry lag, and rerun it when needed. This hub-only rule does not apply to downstream repos. ## Boundaries - In `key_decision` / `guided`, do not push to a remote or merge to `main`/`master` without explicit user consent. - Do not delete branches the user created outside this workflow. - Do not remove worktrees created by the host agent. - Do not force-push without explicit user consent. ### Autonomy Autonomy here is governed by `project-decision-policy` and the configured `automation.autonomy_level`. Normal push and merge are ship actions governed by that tier; force-push remains on the hard floor in every tier. - `autonomous` tier (or the user clearly said "continue autonomously" / "finish this yourself") with no blocker (unresolved `HLT-*`, uncommitted secrets, failing verification, or a `project-blocker-resolution` escalation): complete the full workflow, integrate onto the intended branch, and push the clean verified commit to the configured remote without presenting finish options or asking again. - `key_decision` (default) / `guided`: present the Step 4c finish options and confirm the merge/push/PR decision before executing it. In every tier, still create `TRK-*`, `EV-*`, and `CHG-*` records as normal and report what you did at closeout. ## Staleness Coverage Apply the shared policy in `.prd_plugin/method/staleness-rules.md`. Before creating a new branch, check for stale branches covering the same `TRK-*`, `REQ-*`, or `IMP-TASK-*`. Reuse or close them instead of opening duplicate workstreams. If a branch has been open longer than `health.stale_tracking_after_days` without activity, refresh its `TRK-*` status or open an `HLT-*` before continuing. ## Output Shape When reporting git workflow work, include: 1. Branch name and isolation state. 2. Baseline test result. 3. Commit summary. 4. Finish option chosen and actions taken. 5. New or updated `TRK-*`, `EV-*`, `CHG-*`, or `HLT-*` records.