@lovehlmmm/primekit 1.0.0

package/skills/git/references/gh-cli-guide.md

@@ -0,0 +1,109 @@
+# GitHub CLI Guide
+
+## Authentication
+```bash
+gh auth login        # Interactive login
+gh auth status       # Check auth state
+gh auth logout       # Logout
+```
+
+## Pull Requests
+
+### Create PR
+```bash
+# Basic
+gh pr create --base main --head feature-branch --title "feat: add login" --body "Summary"
+
+# With HEREDOC body
+gh pr create --base main --title "feat(auth): add OAuth" --body "$(cat <<'EOF'
+## Summary
+- Added OAuth2 provider support
+- Implemented token refresh
+
+## Test plan
+- [ ] Unit tests pass
+- [ ] Manual login test
+EOF
+)"
+
+# Draft mode
+gh pr create --draft --title "WIP: new feature"
+
+# Assign reviewers
+gh pr create --reviewer @user1,@user2
+
+# Add labels
+gh pr create --label "bug,priority:high"
+```
+
+### View/Review PR
+```bash
+gh pr list                    # List PRs
+gh pr view 123                # View PR details
+gh pr view 123 --web          # Open in browser
+gh pr checkout 123            # Checkout PR locally
+gh pr diff 123                # View PR diff
+gh pr status                  # Your PRs + reviews
+```
+
+### Merge PR
+```bash
+gh pr merge 123               # Default merge commit
+gh pr merge 123 --squash      # Squash commits
+gh pr merge 123 --rebase      # Rebase merge
+gh pr merge 123 --auto        # Auto-merge when checks pass
+gh pr merge 123 --delete-branch  # Delete branch after
+```
+
+### PR Comments
+```bash
+gh pr comment 123 --body "LGTM!"
+gh api repos/{owner}/{repo}/pulls/123/comments  # View all
+```
+
+## Issues
+
+```bash
+gh issue list                 # List issues
+gh issue view 42              # View issue
+gh issue create --title "Bug" --body "Description"
+gh issue develop 42 -c        # Create branch from issue
+```
+
+## Repository
+
+```bash
+gh repo view                  # Current repo info
+gh repo clone owner/repo      # Clone
+gh browse                     # Open repo in browser
+gh browse path/to/file:42     # Open file at line
+```
+
+## Workflow Runs
+
+```bash
+gh run list                   # List workflow runs
+gh run view <run-id>          # View run details
+gh run watch                  # Watch running workflow
+gh run rerun <run-id>         # Rerun failed workflow
+```
+
+## JSON Output (scripting)
+
+```bash
+gh pr list --json number,title,author
+gh pr view 123 --json commits,reviews
+gh issue list --json number,title --jq '.[].title'
+```
+
+## Common Patterns
+
+### Create PR with auto-merge
+```bash
+gh pr create --fill && gh pr merge --auto --squash
+```
+
+### Close stale PRs
+```bash
+gh pr list --state open --json number -q '.[].number' | xargs -I {} gh pr close {}
+```

package/skills/git/references/safety-protocols.md

@@ -0,0 +1,69 @@
+# Git Safety Protocols
+
+## Secret Detection Patterns
+
+### Scan Command
+```bash
+git diff --cached | grep -iE "(AKIA|api[_-]?key|token|password|secret|credential|private[_-]?key|mongodb://|postgres://|mysql://|redis://|-----BEGIN)"
+```
+
+### Patterns to Detect
+
+| Category | Pattern | Example |
+|----------|---------|---------|
+| API Keys | `api[_-]?key`, `apiKey` | `API_KEY=abc123` |
+| AWS | `AKIA[0-9A-Z]{16}` | `AKIAIOSFODNN7EXAMPLE` |
+| Tokens | `token`, `auth_token`, `jwt` | `AUTH_TOKEN=xyz` |
+| Passwords | `password`, `passwd`, `pwd` | `DB_PASSWORD=secret` |
+| Private Keys | `-----BEGIN PRIVATE KEY-----` | PEM files |
+| DB URLs | `mongodb://`, `postgres://`, `mysql://` | Connection strings |
+| OAuth | `client_secret`, `oauth_token` | `CLIENT_SECRET=abc` |
+
+### Files to Warn About
+- `.env`, `.env.*` (except `.env.example`)
+- `*.key`, `*.pem`, `*.p12`
+- `credentials.json`, `secrets.json`
+- `config/private.*`
+
+### Action on Detection
+1. **BLOCK commit immediately**
+2. Show matching lines: `git diff --cached | grep -B2 -A2 <pattern>`
+3. Suggest: "Add to .gitignore or use environment variables"
+4. Offer to unstage: `git reset HEAD <file>`
+
+## Branch Protection
+
+### Never Force Push To
+- `main`, `master`, `production`, `prod`, `release/*`
+
+### Pre-Merge Checks
+```bash
+# Check for conflicts before merge
+git merge --no-commit --no-ff origin/{branch} && git merge --abort
+```
+
+### Remote-First Operations
+Always use `origin/{branch}` for comparisons:
+- ✅ `git diff origin/main...origin/feature`
+- ❌ `git diff main...HEAD` (includes local uncommitted)
+
+## Error Recovery
+
+### Undo Last Commit (unpushed)
+```bash
+git reset --soft HEAD~1  # Keep changes staged
+git reset HEAD~1         # Keep changes unstaged
+```
+
+### Abort Merge
+```bash
+git merge --abort
+```
+
+### Discard Local Changes
+```bash
+git checkout -- <file>   # Single file
+git reset --hard HEAD    # All files (DANGER)
+```
+
+**Always confirm with user before destructive operations.**

package/skills/git/references/workflow-commit.md

@@ -0,0 +1,58 @@
+# Commit Workflow
+
+Execute via `git-manager` subagent.
+
+## Tool 1: Stage + Analyze
+```bash
+git add -A && \
+echo "=== STAGED ===" && git diff --cached --stat && \
+echo "=== SECURITY ===" && \
+git diff --cached | grep -c -iE "(api[_-]?key|token|password|secret|credential)" | awk '{print "SECRETS:"$1}' && \
+echo "=== GROUPS ===" && \
+git diff --cached --name-only | awk -F'/' '{
+  if ($0 ~ /\.(md|txt)$/) print "docs:"$0
+  else if ($0 ~ /test|spec/) print "test:"$0
+  else if ($0 ~ /\.claude/) print "config:"$0
+  else if ($0 ~ /package\.json|lock/) print "deps:"$0
+  else print "code:"$0
+}'
+```
+
+**If SECRETS > 0:** STOP, show matches, block commit.
+
+## Tool 2: Split Decision
+
+NOTE: 
+- Search for related issues on GitHub and add to body.
+- Only use `feat`, `fix`, or `perf` prefixes for files in `.claude` directory (do not use `docs`).
+
+**From groups, decide:**
+
+**A) Single commit:** Same type/scope, FILES ≤ 3, LINES ≤ 50
+
+**B) Multi commit:** Mixed types/scopes, group by:
+- Group 1: `config:` → `chore(config): ...`
+- Group 2: `deps:` → `chore(deps): ...`
+- Group 3: `test:` → `test: ...`
+- Group 4: `code:` → `feat|fix: ...`
+- Group 5: `docs:` → `docs: ...`
+
+## Tool 3: Commit
+
+**Single:**
+```bash
+git commit -m "type(scope): description"
+```
+
+**Multi (sequential):**
+```bash
+git reset && git add file1 file2 && git commit -m "type(scope): desc"
+```
+Repeat for each group.
+
+## Tool 4: Push (if requested)
+```bash
+git push && echo "✓ pushed: yes" || echo "✓ pushed: no"
+```
+
+**Only push if user explicitly requested** ("push", "commit and push").

package/skills/git/references/workflow-merge-pr.md

@@ -0,0 +1,198 @@
+# Merge PR Workflow (`merge-pr`)
+
+Merge a GitHub pull request via `gh`, then watch post-merge CI on the target branch until green and verify the result before stopping.
+
+## Variables
+
+- PR_REF: PR number or URL (required)
+- MERGE_METHOD: repo convention (`--squash`, `--rebase`, or default merge commit)
+- TO_BRANCH: target branch (`baseRefName` from Step 1)
+
+## GitHub API compatibility
+
+Every bash block in this workflow that reads or writes PR state MUST source the `pk:review-pr` compatibility helper first — it probes the GitHub GraphQL API once and provides REST fallbacks for environments (notably Claude Cloud Environment) that block GraphQL at the egress proxy. Native `gh pr view / checks / merge / list` all issue GraphQL and 403 in that environment.
+
+```bash
+_ak_lib=.claude/skills/primekit-review-pr/references/gh-api-helpers.sh
+[ -f "$_ak_lib" ] || _ak_lib="${HOME:-}/.claude/skills/primekit-review-pr/references/gh-api-helpers.sh"
+[ -f "$_ak_lib" ] || _ak_lib=kits/core/skills/primekit-review-pr/references/gh-api-helpers.sh
+[ -f "$_ak_lib" ] || { (set +u; [ -n "${CLAUDE_PLUGIN_ROOT}" ]) && _ak_lib="${CLAUDE_PLUGIN_ROOT}/skills/primekit-review-pr/references/gh-api-helpers.sh"; }
+[ -f "$_ak_lib" ] || { echo "gh-api-helpers.sh not found" >&2; exit 1; }
+. "$_ak_lib"
+read OWNER REPO NUMBER < <(_ak_split_pr "$PR_REF")
+```
+
+`_ak_pr_meta` / `_ak_pr_checks` mirror the native `gh pr view --json …` / `gh pr checks` outputs and branch on `AK_GH_REST` internally. For the merge write there is no REST auto-merge endpoint — GitHub's `enablePullRequestAutoMerge` is GraphQL-only — so when `AK_GH_REST=1` this workflow degrades from "merge with `--auto` while checks pending" to "poll checks until terminal-green, then `PUT /pulls/{n}/merge`" (see Step 3).
+
+## Step 1: Pre-merge readiness gate
+
+All checks must pass before merging. On any failure, STOP and report — never merge past a red gate.
+
+```bash
+_ak_pr_meta   "$OWNER" "$REPO" "$NUMBER"
+_ak_pr_checks "$OWNER" "$REPO" "$NUMBER"
+```
+
+REST `_ak_pr_meta` returns snake_case fields (`base.ref`, `head.ref`, `mergeable`, `mergeable_state`) instead of the native camelCase (`baseRefName`, `headRefName`, `mergeStateStatus`); parse accordingly when `AK_GH_REST=1`. REST `mergeable` may be `null` while GitHub computes it asynchronously — re-fetch once (with a short sleep) before treating `null` as a blocker. `reviewDecision` is not in the REST pulls payload; when needed, read the latest review event from `gh api "repos/$OWNER/$REPO/pulls/$NUMBER/reviews" --jq '.[-1].state'`.
+
+Gate conditions:
+
+| Check | Requirement |
+|-------|-------------|
+| `state` | `OPEN` |
+| `mergeable` | `MERGEABLE` (no conflicts) |
+| CI checks | All passing, or only pending (pending → use `--auto`) |
+| `reviewDecision` | Not `CHANGES_REQUESTED` |
+| Branch | Never merge into a branch the repo forbids; respect branch protection |
+
+If any check fails deterministically (red CI, conflicts), report the blocker instead of merging.
+
+## Step 2: Pick merge method
+
+Follow repository convention, in priority order:
+
+1. Method documented in the project's `CLAUDE.md` / `CONTRIBUTING.md`.
+2. Method used by recent merged PRs. When `AK_GH_REST=0`, `gh pr list --state merged --limit 5 --json mergedAt,number` and inspect. When `AK_GH_REST=1` fall back to REST: `gh api "repos/$OWNER/$REPO/pulls?state=closed&per_page=5" --jq '.[] | select(.merged_at) | {number, merged_at}'`.
+3. Repo settings: if only one method is allowed, the merge call fails with a clear error — retry with the allowed method.
+4. Default: merge commit.
+
+## Step 3: Merge
+
+**Native path (`AK_GH_REST=0`)** — GitHub GraphQL available; `gh pr merge --auto` is the preferred pending-checks flow:
+
+```bash
+# All checks green:
+gh pr merge "$PR_REF" {MERGE_METHOD}
+
+# Required checks still pending:
+gh pr merge "$PR_REF" {MERGE_METHOD} --auto
+```
+
+**REST path (`AK_GH_REST=1`)** — no auto-merge REST endpoint exists. Poll checks to terminal-green first, then `PUT /pulls/{n}/merge`. The poll is bounded: a `"No checks found"` response is retried once (guards against `_ak_pr_checks`' swallowed API errors) then treated as terminal and refused rather than merged blind, and the pending-poll loop is capped at `MAX_ITERS=60` (30 min) — the same stall budget documented below for the native path — instead of spinning indefinitely:
+
+```bash
+# Map MERGE_METHOD to REST payload:
+#   --squash  -> squash
+#   --rebase  -> rebase
+#   (default) -> merge
+REST_METHOD=merge   # override to squash/rebase per convention
+
+# Poll checks — stop when every check_run's status is 'completed'.
+# Bounded: 60 x 30s = 30 min, matching the stall budget this workflow already
+# documents in prose for the native --auto path (see rules below and the
+# Error Handling table's "CI stuck pending > 30 min" row).
+MAX_ITERS=60
+no_checks_retried=0
+_ak_iter=0
+while :; do
+  checks="$(_ak_pr_checks "$OWNER" "$REPO" "$NUMBER")"
+  # _ak_pr_checks swallows API errors (2>/dev/null) internally, so a lone
+  # "No checks found" is indistinguishable from a transient failure — retry
+  # once before treating it as terminal, same precedent as the `mergeable:
+  # null` re-fetch in Step 1 above.
+  if [ -z "$checks" ] || [ "$checks" = "No checks found" ]; then
+    if [ "$no_checks_retried" -eq 0 ]; then
+      no_checks_retried=1
+      sleep 5
+      continue
+    fi
+    echo "REST merge blocked: no check-runs reported for this commit after retry — repo may have no CI configured, may use legacy commit statuses (unsupported by this path), or the checks API call failed. Verify manually before merging." >&2
+    exit 1
+  fi
+  no_checks_retried=0   # good snapshot — restore the retry budget for the next blip
+  pending="$(printf '%s\n' "$checks" | awk -F'\t' '$2 != "completed"' | wc -l)"
+  [ "$pending" -eq 0 ] && break
+  _ak_iter=$((_ak_iter + 1))
+  if [ "$_ak_iter" -ge "$MAX_ITERS" ]; then
+    echo "REST merge blocked: checks still pending after ${MAX_ITERS} polls (~30 min) — stall, not spinning further. Last observed checks:" >&2
+    printf '%s\n' "$checks" >&2
+    exit 1
+  fi
+  sleep 30
+done
+
+# Refuse if any check concluded non-success. Reuses the loop's final
+# snapshot instead of re-querying (avoids a second round trip and a
+# same-instant race where checks could change between two separate calls).
+failed="$(printf '%s\n' "$checks" | awk -F'\t' '$3 != "success" && $3 != "neutral" && $3 != "skipped"' | wc -l)"
+[ "$failed" -eq 0 ] || { echo "REST merge blocked: $failed check(s) not green" >&2; exit 1; }
+
+# Merge:
+gh api -X PUT "repos/$OWNER/$REPO/pulls/$NUMBER/merge" -f "merge_method=$REST_METHOD"
+```
+
+Rules (apply to both paths):
+- Never force push. Never direct-push to protected target branches.
+- Do not pass `--delete-branch` (or REST `delete_branch=true`) unless the repo convention deletes head branches.
+- With native `--auto`, poll until the PR actually merges before moving to Step 4:
+
+```bash
+# Native
+gh pr view "$PR_REF" --json state,mergedAt   # repeat with sleep 30 until state == MERGED
+# REST equivalent
+gh api "repos/$OWNER/$REPO/pulls/$NUMBER" --jq '{state, merged_at}'
+```
+
+If auto-merge waits on a check that never completes (stuck > 30 min), report the stall as a blocker.
+
+## Step 4: Watch post-merge CI
+
+Run only after Step 3 confirms `state == MERGED` — before that, the merge commit SHA is empty and `gh run list --commit ""` silently returns nothing. Watch the target-branch workflows triggered by the merge commit:
+
+```bash
+# Native (AK_GH_REST=0):
+MERGE_SHA=$(gh pr view "$PR_REF" --json mergeCommit -q .mergeCommit.oid)
+# REST (AK_GH_REST=1):
+MERGE_SHA=$(gh api "repos/$OWNER/$REPO/pulls/$NUMBER" --jq .merge_commit_sha)
+
+# `gh run list/watch` uses REST already — no fallback needed.
+gh run list --branch {TO_BRANCH} --commit "$MERGE_SHA" --json databaseId,name,status,conclusion
+gh run watch <run-id> --exit-status
+```
+
+Repeat until every run for the merge commit concludes. `sleep 30` between polls if `gh run watch` is unavailable.
+
+## Step 5: Handle CI failure
+
+If a post-merge run fails with a deterministic, repo-fixable error:
+
+1. Inspect logs: `gh run view <run-id> --log-failed`.
+2. Create a follow-up fix branch from the target branch (never fix on the merged head branch).
+3. Activate `pk:fix --auto` with the exact failing command and error evidence.
+4. Ship the fix through the repo's normal PR flow, merge it with this same workflow, and watch again.
+
+Stop conditions — stop and report when any of:
+- target-branch CI is green (success)
+- the failure is an external blocker (infra outage, missing secret, flaky third-party)
+- the same failure survives 3 fix attempts (not converging)
+
+## Step 6: Verify follow-up
+
+Before declaring done:
+
+- Confirm PR state is `MERGED` and the merge commit exists on the target branch:
+  `git fetch origin && git log origin/{TO_BRANCH} --oneline -5`
+- Confirm all CI runs for the merge commit concluded `success`.
+- If the repo has post-merge automation (release tagging, deploy workflows), confirm those runs also succeeded or are intentionally out of scope.
+- **Close a plan-backed change's index row.** Match this merged PR to a plan by
+  its recorded `--linked-pr`, or by plan branch == the PR head branch (`primekit plan
+  list --json` — post-merge you are on the target branch, so `resolve`, scoped to
+  the current branch, will not find the head-branch plan). On a unique match,
+  `primekit plan close <id>` — an
+  index-only transition; the plan files already carry `status: completed` from
+  the ship commit. A match miss means the plan is already closed or there is no
+  plan — skip silently; on ambiguity, skip and report. Optionally append (never
+  edit) a completion comment to a linked issue per the "Delivery finalization"
+  section of `kits/core/skills/primekit-cook/references/plan-state-files-first.md`.
+  Never delete or hand-edit plan files.
+- Report: PR URL, merge commit SHA, merge method, CI runs watched and their conclusions, follow-up fixes shipped (if any).
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Merge conflicts (`CONFLICTING`) | Report; suggest updating the head branch, do not resolve on the target branch |
+| Branch protection blocks merge | Report required approvals/checks; never bypass |
+| `gh` not authenticated | Report; suggest `gh auth login` |
+| Self-merge forbidden by repo policy | Report; hand off to a human maintainer |
+| CI stuck pending > 30 min | Report stall with run URL |

package/skills/git/references/workflow-merge.md

@@ -0,0 +1,48 @@
+# Merge Workflow
+
+Execute via `git-manager` subagent.
+
+## Variables
+- TO_BRANCH: target (defaults to `main`)
+- FROM_BRANCH: source (defaults to current branch)
+
+## Step 1: Sync with Remote
+
+**IMPORTANT: Always merge `main` (or any default branch) to current branch first.**
+
+```bash
+git fetch origin
+git checkout {TO_BRANCH}
+git pull origin {TO_BRANCH}
+```
+
+## Step 2: Merge from REMOTE
+```bash
+git merge origin/{FROM_BRANCH} --no-ff -m "merge: {FROM_BRANCH} into {TO_BRANCH}"
+```
+
+**Why `origin/{FROM_BRANCH}`:** Ensures merging only committed+pushed changes, not local WIP.
+
+## Step 3: Resolve Conflicts
+If conflicts:
+1. Resolve manually
+2. `git add . && git commit`
+3. If clarifications needed, report to main agent
+
+## Step 4: Push
+```bash
+git push origin {TO_BRANCH}
+```
+
+## Pre-Merge Checklist
+- Fetch latest: `git fetch origin`
+- Ensure FROM_BRANCH pushed to remote
+- Check for conflicts: `git merge --no-commit --no-ff origin/{FROM_BRANCH}` then abort
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Merge conflicts | Resolve manually, then commit |
+| Branch not found | Verify branch name, ensure pushed |
+| Push rejected | `git pull --rebase`, retry |

package/skills/git/references/workflow-pr.md

@@ -0,0 +1,58 @@
+# Pull Request Workflow
+
+Execute via `git-manager` subagent.
+
+## Variables
+- TO_BRANCH: target (defaults to `main`)
+- FROM_BRANCH: source (defaults to current branch)
+
+## CRITICAL: Use REMOTE diff
+PRs based on remote branches. Local diff includes unpushed changes.
+
+## Tool 1: Sync + Analyze
+
+**IMPORTANT: Always merge `main` (or any default branch) to current branch first.**
+
+```bash
+git fetch origin && \
+git push -u origin HEAD 2>/dev/null || true && \
+BASE=${BASE_BRANCH:-main} && \
+HEAD=$(git rev-parse --abbrev-ref HEAD) && \
+echo "=== PR: $HEAD → $BASE ===" && \
+echo "=== COMMITS ===" && \
+git log origin/$BASE...origin/$HEAD --oneline && \
+echo "=== FILES ===" && \
+git diff origin/$BASE...origin/$HEAD --stat
+```
+
+**If "Branch not on remote":** Push first, retry.
+
+## Tool 2: Generate Content
+**Title:** Conventional commit format, <72 chars, NO version numbers
+**Body:** Summary bullets + Test plan checklist
+
+## Tool 3: Create PR
+```bash
+gh pr create --base $BASE --head $HEAD --title "..." --body "$(cat <<'EOF'
+## Summary
+- Bullet points
+
+## Test plan
+- [ ] Test item
+EOF
+)"
+```
+
+## DO NOT use (local comparison)
+- ❌ `git diff main...HEAD`
+- ❌ `git diff --cached`
+- ❌ `git status`
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Branch not on remote | `git push -u origin HEAD`, retry |
+| Empty diff | Warn: "No changes for PR" |
+| Push rejected | `git pull --rebase`, resolve, push |
+| No upstream | `git push -u origin HEAD` |

package/skills/git/references/workflow-push.md

@@ -0,0 +1,52 @@
+# Push Workflow
+
+Execute via `git-manager` subagent.
+
+## Pre-Push Checklist
+1. All changes committed
+2. Secrets scanned (see `safety-protocols.md`)
+3. Branch pushed to remote
+
+## Tool 1: Verify State
+```bash
+git status && \
+git log origin/$(git rev-parse --abbrev-ref HEAD)..HEAD --oneline 2>/dev/null || echo "NO_UPSTREAM"
+```
+
+**If uncommitted changes:** Warn user, suggest commit first.
+**If NO_UPSTREAM:** Use `git push -u origin HEAD`.
+
+## Tool 2: Push
+```bash
+git push origin HEAD
+```
+
+**On success:** Report commit hashes pushed.
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `rejected - non-fast-forward` | Remote has newer commits | `git pull --rebase`, resolve conflicts, push again |
+| `no upstream branch` | Branch not tracked | `git push -u origin HEAD` |
+| `Authentication failed` | Invalid credentials | Check `gh auth status` or SSH keys |
+| `Repository not found` | Wrong remote URL | Verify `git remote -v` |
+| `Permission denied` | No write access | Check repository permissions |
+
+## Force Push (DANGER)
+
+**NEVER force push to main/master/production branches.**
+
+If user explicitly requests force push on feature branch:
+```bash
+git push -f origin HEAD
+```
+
+**Warn user:** "Force push rewrites history. Collaborators may lose work."
+
+## Output Format
+```
+✓ pushed: N commits to origin/{branch}
+  - abc123 feat(auth): add login
+  - def456 fix(api): resolve timeout
+```