Git Workflow

Acceptance Criteria

• <criterion 1>
• <criterion 2>

Notes

<out of scope / caveats>

> "Does this look right? I'll create the Jira ticket now."

Once confirmed, create the ticket using the `createJiraIssue` MCP tool:

- `cloudId`: `<from getAccessibleAtlassianResources>`
- `projectKey`: `PDX`
- `issueTypeName`: as chosen above
- `summary`: as drafted
- `description`: full description in markdown
- `contentFormat`: `markdown`
- `additional_fields`: `{ "labels": ["provardx-cli"] }`

The tool returns the new ticket key (e.g. `PDX-193`). Set `TICKET = PDX-<returned-number>`.

Show the user: `Ticket created: https://provartesting.atlassian.net/browse/<TICKET>`

---

### Option C — No ticket (PDX-0)

Set `TICKET = PDX-0`. No Jira steps. Use this only for framework chores, internal tooling, or changes with no observable user or system behaviour change.

---

### Derive branch variables

Ask: "What type of change is this? (feature / fix)" — skip if already obvious from the issue type.

Ask for a short branch slug (kebab-case, ≤ 30 chars, no spaces).

Derive:

- `BRANCH_TYPE` = `feature` or `fix`
- `BRANCH` = `feature/PDX-<number>-<slug>` or `fix/PDX-<number>-<slug>` (or `feature/<slug>` for PDX-0)

**CONFIRM**: "I'll create branch `<BRANCH>` off `develop`. Proceed?"

---

## Step 1 — Create worktree and install dependencies

```sh
# From the main repo root
git worktree add .claude/worktrees/<BRANCH> -b <BRANCH> develop

# Install node_modules so husky hooks work — ALWAYS do this in a new worktree
cd .claude/worktrees/<BRANCH> && yarn install

The yarn install step is mandatory. Without it, the pre-commit hook cannot find wireit and will fail with "wireit is not recognized".

Step 2 — Implement the change

Work in the worktree at .claude/worktrees/<BRANCH>/.

Before every commit attempt, run in the worktree directory:

yarn compile
node_modules/.bin/nyc node_modules/.bin/mocha "test/**/*.test.ts"
node scripts/mcp-smoke.cjs 2>/dev/null
yarn lint

Fix any failures before staging. Do not move to Step 3 until all four pass.

Step 3 — Stage and commit

Stage files explicitly — never git add -A:

git add <file1> <file2> ...

Commit with the required PDX format:

git commit -m "$(cat <<'EOF'
<TICKET>: <type>(<scope>): <subject under 72 chars>

RCA: <at least 40 chars — requirement or root cause>
Fix: <at least 40 chars — what was implemented or changed>
EOF
)"

Valid type values: feat, fix, test, docs, chore, refactor Valid scope values: mcp, prompts, resources, cli, test, docs, ci

If the commit-msg hook rejects the message, read the error and fix the message. Do not use --no-verify unless the user explicitly approves it.

Step 4 — Push and open PR

git push -u origin <BRANCH>

The pre-push hook runs yarn build && yarn test (60–120 seconds). If it fails, fix the issue, commit the fix (Step 3 format), and push again.

Open the PR:

gh pr create \
  --base develop \
  --title "<TICKET>: <short description>" \
  --body "$(cat <<'EOF'
## Summary
- <bullet>

## Jira
https://provartesting.atlassian.net/browse/<TICKET>

## Test plan
- [ ] yarn compile passes
- [ ] yarn test:only passes
- [ ] mcp-smoke.cjs passes
- [ ] yarn lint passes

## Changes
- <file>: <what changed>
EOF
)"

Omit the ## Jira section for PDX-0 work.

CONFIRM: Show the user the PR URL and ask: "PR is open. Should I check the Copilot review now?"

Step 5 — Address Copilot review

gh pr view <pr-number> --comments
gh pr checks <pr-number>

For each Copilot comment:

• Valid concern → fix in the worktree, commit (Step 3 format), push
• Not applicable → reply explaining why: gh pr comment <pr-number> --body "..."
• Security comment → always address; never dismiss w