---
name: github-workflow
description: >-
  Use the GitHub CLI (gh) to (1) RAISE issues for gaps found while building this
  app — especially a missing @dreamtree-org/twreact-ui component (never duplicate
  UI — file an issue instead), a korm-js data-layer gap, or an app bug/feature —
  and (2) PICK UP an issue and resolve it through a branch → PR → merge → deploy
  cycle. Triggers: "raise an issue", "file a bug/gap", "missing component",
  "pick up issue", "start work on #", "create a branch", "open a PR", "deploy".
---

# GitHub workflow (gh)

This app is built by **composing** `@dreamtree-org/twreact-ui` (UI) and
`@dreamtree-org/korm-js` (data). A capability gap is **an issue to file, not code
to duplicate**. Use `gh` for the whole loop.

## 0. Prerequisites
- `gh auth status` (run `gh auth login` if needed).
- Confirm the working repo: `gh repo view --json nameWithOwner -q .nameWithOwner`.

## 1. Resolve the RIGHT repo for a gap
Read the target from the installed package, never hard-code a slug:
```bash
# twreact-ui (UI gaps) and korm-js (data gaps) repos:
node -p "require('@dreamtree-org/twreact-ui/package.json').repository?.url || require('@dreamtree-org/twreact-ui/package.json').repository"
node -p "require('@dreamtree-org/korm-js/package.json').repository?.url || require('@dreamtree-org/korm-js/package.json').repository"
```
- **Missing/insufficient UI component** → twreact-ui repo. **Do not** build a local component.
- **Missing data-layer capability** (operator/action korm can't express) → korm-js repo.
- **App bug / feature / module work** → this app's own repo.

## 2. RAISE an issue (a gap found while building)
First check it isn't already filed: `gh issue list -R <repo> --search "<keywords>" --state all`.
```bash
gh issue create -R <repo> \
  --title "[component] <Name> — needed by __APP_NAME__" \
  --label "enhancement" \
  --body "$(cat <<'EOF'
**Need:** <what the app needs and where (page/feature)>
**Proposed API:** props / variants / sizes
**A11y:** keyboard, ARIA, reduced-motion
**Usage example:**
\`\`\`jsx
<NewComponent ... />
\`\`\`
**Why not local:** compose-only policy — this belongs in twreact-ui, not the app.
EOF
)"
```
Until it ships, mark the spot `// TODO(twreact-ui#<n>)` and use the closest existing
primitive — never harden a one-off component into the app.

## 3. PICK UP an issue to resolve
```bash
gh issue list --state open --assignee @me        # or browse all open
gh issue view <n>
gh issue develop <n> --checkout                   # creates+checks out a linked branch
# (or branch manually per the strategy below)
```

## 4. Work isolation (git worktree) + branching standards
Use a **dedicated git worktree per task** so parallel agents/humans never clobber
each other's working tree (each gets its own dir + branch over the shared `.git`):
```bash
git worktree add -b <type>/<issue#>-<slug> ../<repo>-worktrees/<slug> main
cd ../<repo>-worktrees/<slug> && npm install   # node_modules is NOT shared
# … code, commit, push, open PR …
git worktree remove ../<repo>-worktrees/<slug> # after the PR merges
git worktree list                              # see active worktrees
```

**Branching standards (trunk-based):**
| Rule | Standard |
| --- | --- |
| Base | always branch off `main` |
| Name | `<type>/<issue#>-<slug>` — type ∈ `feat`·`fix`·`chore`·`docs`·`refactor`·`test`·`perf` |
| Scope | one branch per issue; short-lived; sync from `main` often |
| Commits | Conventional Commits referencing the issue — `feat: passbook list (#42)` |
| Staging | stage files **explicitly** — never `git add -A` / `git add .` |
| main | never commit directly; merge via PR only |

## 5. Test gates — what runs at which step
| Step | Run | Gate |
| --- | --- | --- |
| While coding (every change / pre-commit) | `npm run test:unit` — Vitest backend + client (fast) | green before commit |
| Before opening a PR | `npm test` + `npm run test:e2e` (after `npm run e2e:setup` + `npx playwright install`) | green before PR |
| On PR / push (CI) | `.github/workflows/ci.yml` → unit **and** e2e | red CI blocks merge |
| Before deploy | CI green on `main` | deploy only from green `main` |

- Every **bug fix** ships a regression test. Every **user-facing** change adds/updates
  a journey in `tests/USER-JOURNEYS.md` + its Playwright spec.
- Unit (Vitest) covers pure logic — rbac/auth/token utils, client permission helpers,
  components. E2E (Playwright) covers the user journeys end-to-end.

## 6. Open the PR → review → merge
```bash
git push -u origin HEAD
gh pr create --base main --fill --body "Closes #<n>

## What
## How tested (unit + e2e)
"
gh pr checks --watch        # CI must be green
gh pr merge --squash --delete-branch
```

## 7. Deploy cycle
- Merge to `main` triggers CI (`.github/workflows/ci.yml`).
- Deploy from `main` (your platform's deploy step / `deploy.sh` / CD).
- Tag releases if you cut versions: `gh release create vX.Y.Z --generate-notes`.

## Guardrails
- Compose twreact-ui; a UI gap is a twreact-ui **issue**, never a local component.
- All data access via korm-js (`/api/crud/:Model`); never raw SQL.
- Never push secrets (`.env` is gitignored). One issue → one branch → one PR.