@northbridge-security/secureai 0.1.13

package/.claude/commands/pr.md

@@ -0,0 +1,503 @@
+---
+description: End-to-end PR workflow from validation through creation, CI monitoring, and review triage
+argument-hint: [--draft] [--base=branch] [--skip-deploy] [--skip-tests] [--skip-ci]
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep, Task, mcp__github__*, AskUserQuestion
+---
+
+# PR Workflow: $ARGUMENTS
+
+End-to-end workflow from code changes to PR creation, CI monitoring, and review triage.
+
+## Arguments
+
+Parse from `$ARGUMENTS`:
+
+- `--draft`: Create PR as draft (default for new PRs)
+- `--base=BRANCH`: Target branch (auto-detected from branch naming)
+- `--skip-deploy`: Skip deploy phase
+- `--skip-tests`: Skip test phase (use rarely)
+- `--skip-ci`: Skip CI monitoring phase (create PR and exit)
+
+**Default**: Create draft PR, run all phases, auto-detect base branch.
+
+---
+
+## Phase 1: Validate
+
+Run quality checks and ensure code is ready for PR.
+
+### 1.1 Run Tests
+
+```bash
+# Detect available test tasks
+if task --list 2>/dev/null | grep -q "^qa:"; then
+  task qa
+elif task --list 2>/dev/null | grep -q "^test:"; then
+  task test
+else
+  # Direct commands
+  bun run lint && bun run typecheck && bun test
+fi
+```
+
+**If tests fail:**
+
+- Analyze error output
+- Apply fixes automatically
+- Re-run tests
+- Iterate until all pass
+
+### 1.2 Run Deploy (if applicable)
+
+```bash
+# Check if deploy task exists
+if task --list 2>/dev/null | grep -q "^deploy"; then
+  task deploy
+fi
+```
+
+**If deploy fails:**
+
+- Analyze deployment errors
+- Fix infrastructure or configuration
+- Re-deploy
+- Iterate until successful
+
+**Skip with `--skip-deploy` flag.**
+
+---
+
+## Phase 2: Create or Update PR
+
+### 2.1 Detect Repository Context
+
+```bash
+# Get current branch
+BRANCH=$(git branch --show-current)
+
+# Get remote info
+REMOTE_URL=$(git remote get-url origin)
+# Parse: github.com/owner/repo
+OWNER=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]([^/]+)/.*|\1|')
+REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/][^/]+/([^.]+).*|\1|')
+
+# Detect base branch from naming convention
+if [[ "$BRANCH" =~ ^(fix|hotfix)/ ]]; then
+  BASE_BRANCH="main"
+elif [[ "$BRANCH" =~ ^(feat|feature)/ ]]; then
+  BASE_BRANCH="development"  # or "main" if no development branch
+else
+  BASE_BRANCH="main"
+fi
+
+# Override with --base flag if provided
+```
+
+### 2.2 Check for Existing PR
+
+Use GitHub MCP to check for existing PR:
+
+```javascript
+const result = await mcp__github__list_pull_requests({
+  owner: OWNER,
+  repo: REPO,
+  head: `${OWNER}:${BRANCH}`,
+  state: "open",
+});
+```
+
+**If PR exists:**
+
+- Display PR number and URL
+- Set UPDATE_MODE=true
+- Will update existing PR
+
+### 2.3 Gather Context
+
+**Analyze commits:**
+
+```bash
+git log --oneline $(git merge-base HEAD $BASE_BRANCH)..HEAD
+git diff --stat $(git merge-base HEAD $BASE_BRANCH)..HEAD
+```
+
+**Find PRD files (if referenced):**
+
+```bash
+# Check docs/requirements/ for PRD matching branch/ticket
+ls docs/requirements/*.md 2>/dev/null
+
+# Extract ticket ID from branch name
+TICKET_ID=$(echo "$BRANCH" | grep -oE '[A-Z]+-[0-9]+' | head -1)
+```
+
+**Read PR template:**
+
+```bash
+if [ -f .github/PULL_REQUEST_TEMPLATE.md ]; then
+  TEMPLATE=".github/PULL_REQUEST_TEMPLATE.md"
+elif [ -f .github/pull_request_template.md ]; then
+  TEMPLATE=".github/pull_request_template.md"
+fi
+```
+
+### 2.4 Generate PR Content
+
+Write to `.tmp/pr.md`:
+
+**Title format:** `[TICKET-ID] Brief description` or just `Brief description`
+
+**Writing style rules (mandatory):**
+
+- No emojis anywhere in the PR title or body
+- Use a professional, direct tone
+- Use clear, concise language — avoid business jargon and overly complex sentences
+- Assume the reader has little prior knowledge of the change
+- Assume other maintainers may not use English as their first language
+- Avoid adjectives that add no information: "robust", "comprehensive", "seamless", "extensive"
+- Use active voice and specific, quantified facts where possible
+
+**Body structure:**
+
+- Follow the repository PR template strictly if one is found
+- If no template exists, use this minimal format:
+
+```markdown
+## Summary
+
+**Why:** [Problem or motivation from commits/PRD]
+
+**What:** [Changes implemented]
+
+## Changes
+
+- Change 1
+- Change 2
+
+## Testing
+
+- Unit tests: [status]
+- Manual testing: [what was verified]
+```
+
+**For trivial changes** (docs only, formatting, typos):
+
+- Use minimal description
+- Skip testing section
+
+### 2.5 Detect PR Creation Method
+
+Determine whether to use GoTask or GitHub MCP for PR creation.
+
+**Detection logic:**
+
+```bash
+# Step 1: Check if GoTask is installed and `task git` runs
+TASK_GIT_OUTPUT=$(task git 2>&1)
+TASK_GIT_EXIT=$?
+
+# Step 2: If GoTask works, check if git:pr:create is available
+if [ $TASK_GIT_EXIT -eq 0 ] && echo "$TASK_GIT_OUTPUT" | grep -q "git:pr:create"; then
+  USE_GOTASK=true
+else
+  USE_GOTASK=false
+fi
+```
+
+**If `USE_GOTASK=true`:** ALWAYS use GoTask for PR creation and updates. Do not fall back to MCP.
+
+**If `USE_GOTASK=false`:** Use GitHub MCP tools.
+
+### 2.6 Create or Update PR
+
+**GoTask method (when `USE_GOTASK=true`):**
+
+```bash
+if [ "$UPDATE_MODE" = "true" ]; then
+  task git:pr:update PR="$PR_NUMBER" FILE=".tmp/pr.md"
+else
+  task git:pr:create FILE=".tmp/pr.md" DRAFT=true
+fi
+```
+
+**GitHub MCP method (when `USE_GOTASK=false`):**
+
+```javascript
+if (UPDATE_MODE) {
+  await mcp__github__update_pull_request({
+    owner: OWNER,
+    repo: REPO,
+    pullNumber: PR_NUMBER,
+    title: PR_TITLE,
+    body: PR_BODY,
+  });
+} else {
+  await mcp__github__create_pull_request({
+    owner: OWNER,
+    repo: REPO,
+    title: PR_TITLE,
+    body: PR_BODY,
+    head: BRANCH,
+    base: BASE_BRANCH,
+    draft: true,
+  });
+}
+```
+
+**Output:**
+
+```text
+PR #123: [TICKET-ID] Description
+https://github.com/owner/repo/pull/123
+
+Status: Draft
+Base: development
+```
+
+**If `--skip-ci` flag, exit here.**
+
+---
+
+## Phase 3: CI Monitoring
+
+### 3.1 Monitor Check Status
+
+Poll every 30 seconds:
+
+```javascript
+const status = await mcp__github__pull_request_read({
+  owner: OWNER,
+  repo: REPO,
+  pullNumber: PR_NUMBER,
+  method: "get_status",
+});
+
+// Report progress
+console.log(`Checks: ${status.state}`);
+for (const check of status.statuses) {
+  const icon = check.state === "success" ? "✓" : check.state === "pending" ? "⏳" : "✗";
+  console.log(`  ${icon} ${check.context}`);
+}
+```
+
+Continue polling until all checks complete (success or failure).
+
+### 3.2 Handle CI Failures
+
+**If checks fail:**
+
+1. Download logs:
+
+   ```bash
+   task git:runs:log STATE=all
+   # Logs saved to .tmp/ or .logs/
+   ```
+
+2. Analyze failure:
+   - Read log files
+   - Identify root cause
+   - Apply fixes automatically
+
+3. Commit fixes:
+
+   ```bash
+   git add -A
+   git commit -m "fix(ci): [description of fix]"
+   ```
+
+4. **Ask user to push:**
+
+   ```text
+   CI fixes committed. Please push to trigger new checks:
+
+     git push
+
+   Reply when pushed, or I'll continue monitoring.
+   ```
+
+5. Return to monitoring (step 3.1)
+
+### 3.3 Mark PR Ready
+
+Once all CI checks pass:
+
+```javascript
+// If PR was created as draft, mark ready
+await mcp__github__update_pull_request({
+  owner: OWNER,
+  repo: REPO,
+  pullNumber: PR_NUMBER,
+  draft: false,
+});
+```
+
+```text
+All CI checks passed. PR marked as ready for review.
+```
+
+---
+
+## Phase 4: Review Triage
+
+### 4.1 Wait for Reviews
+
+Monitor for automated reviews (CodeRabbit, SonarCloud, etc.) by polling GitHub MCP for review status, or wait for user notification that reviews are ready.
+
+### 4.2 Fetch Comments
+
+```bash
+task git:pr:comments
+# Output saved to .logs/github/comments/YYYYMMDD-HHMMSS.log
+```
+
+Or via GitHub MCP:
+
+```javascript
+const comments = await mcp__github__pull_request_read({
+  owner: OWNER,
+  repo: REPO,
+  pullNumber: PR_NUMBER,
+  method: "get_review_comments",
+});
+```
+
+### 4.3 Triage and Fix
+
+For each comment:
+
+| Type                    | Action                              |
+| ----------------------- | ----------------------------------- |
+| **Actionable fix**      | Apply automatically                 |
+| **Security issue**      | Fix immediately, prioritize         |
+| **Needs clarification** | **Ask user for decision**           |
+| **Nitpick/optional**    | Apply if beneficial, otherwise skip |
+| **Question**            | Respond in PR comment               |
+
+**Apply fixes:**
+
+- Make code changes
+- Commit all fixes together:
+
+  ```bash
+  git add -A
+  git commit -m "fix: address review feedback
+
+  - Fixed issue 1
+  - Fixed issue 2"
+  ```
+
+**Ask user to push:**
+
+```text
+Review fixes committed. Please push:
+
+  git push
+
+Addressed:
+- [x] Security: Shell injection in utils.ts
+- [x] Bug: Null check missing in parser.ts
+- [ ] Skipped: Rename variable suggestion (cosmetic)
+
+Reply when pushed.
+```
+
+### 4.4 Complete Workflow
+
+Once all comments addressed and CI passes:
+
+```text
+PR #123 is ready for human review.
+
+Summary:
+- CI: All checks passing
+- CodeRabbit: All comments addressed
+- Status: Ready for review
+
+Next steps:
+- Assign reviewers in GitHub
+- Or run `/pr` again if more changes needed
+```
+
+---
+
+## Human Checkpoints
+
+The workflow runs autonomously except:
+
+1. **Pushing to GitHub** - Always ask user to run `git push`
+2. **Triage decisions** - When review comments need human judgment
+3. **Final notification** - When PR is ready for reviewer assignment
+
+---
+
+## Taskfile Dependencies
+
+This command expects these tasks (create stubs if missing):
+
+| Task                           | Purpose          | Required                                       |
+| ------------------------------ | ---------------- | ---------------------------------------------- |
+| `task test` or `task qa`       | Run tests        | Yes                                            |
+| `task lint`                    | Run linting      | Optional                                       |
+| `task deploy`                  | Deploy to stage  | Optional                                       |
+| `task git`                     | List git tasks   | Used for detection (see 2.5)                   |
+| `task git:pr:create FILE=path` | Create PR        | If detected, always used instead of MCP        |
+| `task git:pr:update`           | Update PR        | If detected, always used instead of MCP        |
+| `task git:pr:comments`         | Fetch comments   | Optional (MCP fallback)                        |
+| `task git:runs:log`            | Download CI logs | Optional                                       |
+
+---
+
+## Error Recovery
+
+| Error                   | Recovery                                  |
+| ----------------------- | ----------------------------------------- |
+| Tests fail              | Analyze, fix, retry                       |
+| Deploy fails            | Analyze infrastructure errors, fix, retry |
+| GoTask not available    | Use GitHub MCP (detected in step 2.5)     |
+| PR creation fails       | Report error and ask user for guidance     |
+| CI fails                | Download logs, fix, ask user to push      |
+| Review comments unclear | Ask user for decision                     |
+
+---
+
+## Examples
+
+### Basic usage
+
+```bash
+/pr
+```
+
+Runs full workflow: test → deploy → create draft PR → monitor CI → triage reviews.
+
+### Skip deploy
+
+```bash
+/pr --skip-deploy
+```
+
+For repos without deployment or when deploying separately.
+
+### Create and exit
+
+```bash
+/pr --skip-ci
+```
+
+Just create/update PR without monitoring CI.
+
+### Target specific branch
+
+```bash
+/pr --base=main
+```
+
+Override auto-detected base branch.
+
+### Non-draft PR
+
+```bash
+/pr --no-draft
+```
+
+Create PR as ready for review immediately (skip draft state).

package/.claude/commands/todo.md

@@ -0,0 +1,99 @@
+# Todo: Manage Project Todos
+
+List or add todos in `docs/TODO.md`. This file is gitignored - personal task tracking that doesn't clutter the repo.
+
+## File Location
+
+- **Path**: `docs/TODO.md`
+- **Git status**: Ignored (add to `.gitignore` if not present)
+- **Scope**: Personal/local - not shared with team
+
+## Tasks
+
+### Prerequisites
+
+- If `docs/TODO.md` doesn't exist: Create it with template:
+  ```markdown
+  # Project TODOs
+
+  Personal task tracking. This file is gitignored.
+
+  ## In Progress
+
+  | Task | Priority | Notes |
+  |------|----------|-------|
+
+  ## Backlog
+
+  | Task | Priority | Notes |
+  |------|----------|-------|
+
+  ## Done
+
+  | Task | Completed | Notes |
+  |------|-----------|-------|
+  ```
+
+- If `docs/TODO.md` not in `.gitignore`: Add `docs/TODO.md` to `.gitignore`
+
+### Without arguments: List todos
+
+1. Read `docs/TODO.md`
+2. Display "In Progress" and "Backlog" tables
+3. Show count: "X in progress, Y in backlog"
+
+### With arguments: Add todo
+
+1. Read `docs/TODO.md`
+2. **Check for duplicates**: If similar task exists, ask whether to update or add new
+3. Assess complexity:
+
+   **Simple** (bug fix, config change, small task):
+   - Add to Backlog table
+   - Example: `| Fix typo in README | Low | Header spelling |`
+
+   **Complex** (feature, multi-session, needs design):
+   - Create ADR in `docs/ADR.md` with problem and proposed solution
+   - Add to Backlog with ADR reference
+   - Example: `| Add OAuth2 auth | High | See ADR-003 |`
+
+4. Confirm what was added
+
+### Mark as in progress: `/todo start <task>`
+
+1. Move task from Backlog to In Progress
+2. Add timestamp to Notes
+
+### Mark as done: `/todo done <task>`
+
+1. Move task from In Progress to Done
+2. Add completion date
+
+## Priority Guidelines
+
+| Priority | When |
+|----------|------|
+| High | Blocking other work, urgent |
+| Medium | Next planned work |
+| Low | Nice to have, future idea |
+
+## Examples
+
+```
+/todo
+→ In Progress: 2 tasks, Backlog: 5 tasks
+  [lists tables]
+
+/todo Fix login timeout bug
+→ Added to Backlog: "Fix login timeout bug | Medium | |"
+
+/todo Add caching layer
+→ Complex task - created ADR-004 in docs/ADR.md
+→ Added to Backlog: "Add caching layer | High | See ADR-004 |"
+
+/todo start Fix login timeout bug
+→ Moved to In Progress
+
+/todo done Fix login timeout bug
+→ Moved to Done (2024-02-03)
+```