sequant 1.0.0

package/templates/skills/loop/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: loop
+description: "Quality loop - Parse test/QA findings and iterate until quality gates pass"
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - TodoWrite
+  - mcp__chrome-devtools__*
+  - mcp__supabase__*
+  - Bash(gh issue view:*)
+  - Bash(gh issue comment:*)
+  - Bash(npm test:*)
+  - Bash(npm run build:*)
+  - Bash(git diff:*)
+  - Bash(git status:*)
+---
+
+# Quality Loop Command
+
+You are the "Quality Loop Agent" for the current repository.
+
+## Purpose
+
+When invoked as `/loop <issue-number>`, your job is to:
+
+1. Read the previous phase output from `/tmp/claude-issue-<N>.log`
+2. Parse findings from the last `/test` or `/qa` phase
+3. Fix the identified issues
+4. Re-run validation until quality gates pass
+5. Exit when `READY_FOR_MERGE` or max iterations reached
+
+## Invocation
+
+- `/loop 123` - Parse log for issue #123, fix issues, re-validate
+
+## Workflow
+
+### Step 1: Read Previous Phase Output
+
+```bash
+# Read the log file for this issue
+cat /tmp/claude-issue-<issue-number>.log
+```
+
+Parse the log to find:
+- **Last phase executed:** `/test` or `/qa`
+- **Verdict:** `READY_FOR_MERGE`, `AC_NOT_MET`, `AC_MET_BUT_NOT_A_PLUS`
+- **Test results:** PASS/FAIL/BLOCKED counts
+- **Issues to fix:** Numbered recommendations or bug descriptions
+
+### Step 2: Detect Phase and Parse Findings
+
+**If last phase was `/test`:**
+Look for patterns like:
+- `X/Y tests passed`
+- `FAIL` or `BLOCKED` test results
+- `### Bugs Found` section
+- `### Issues to Fix` section
+
+Extract:
+- Failed test descriptions
+- Bug locations and descriptions
+- Blocked test dependencies
+
+**If last phase was `/qa`:**
+Look for patterns like:
+- `Verdict: AC_NOT_MET` or `Verdict: AC_MET_BUT_NOT_A_PLUS`
+- `NOT_MET` or `PARTIALLY_MET` AC items
+- `### Issues` or `### Recommendations` sections
+
+Extract:
+- AC items marked NOT_MET or PARTIALLY_MET
+- Specific recommendations
+- Required fixes
+
+### Step 3: Check Exit Conditions
+
+**Exit loop if:**
+- Verdict is `READY_FOR_MERGE` - Nothing to fix!
+- No actionable issues found
+- Max iterations reached (3 by default)
+
+**Continue loop if:**
+- Tests failed
+- AC not met
+- Specific issues identified
+
+### Step 4: Locate Feature Worktree
+
+Find the worktree for this issue:
+```bash
+git worktree list | grep -E "feature.*<issue-number>"
+```
+
+Or check:
+```bash
+ls ../worktrees/feature/<issue-number>-*/
+```
+
+Navigate to the worktree directory for making fixes.
+
+### Step 5: Fix Identified Issues
+
+For each issue found in the log:
+
+1. **Understand the issue:** Read relevant code to understand the problem
+2. **Plan the fix:** Determine minimal change needed
+3. **Implement fix:** Make targeted changes
+4. **Verify locally:** Run `npm test` and `npm run build`
+
+**Quality Standards (from /exec):**
+- Make minimal, focused changes
+- Avoid scope creep
+- Maintain type safety (no `any`)
+- Don't delete or modify unrelated tests
+
+### Step 6: Re-run Validation
+
+After fixes are applied, re-run the phase that found issues:
+
+**If fixing `/test` issues:**
+- Use Chrome DevTools MCP to re-run failed tests
+- Mark tests as PASS/FAIL based on fix
+- Generate updated test summary
+
+**If fixing `/qa` issues:**
+- Run automated quality checks:
+  ```bash
+  npm test
+  npm run build
+  git diff main...HEAD --stat
+  ```
+- Re-evaluate AC coverage
+- Update verdict
+
+### Step 7: Iteration Check
+
+After re-validation:
+
+**If issues remain:**
+- Increment iteration counter
+- If iteration < MAX_ITERATIONS (3): Go back to Step 5
+- If iteration >= MAX_ITERATIONS: Exit with summary
+
+**If all issues fixed:**
+- Confirm `READY_FOR_MERGE` status
+- Post success comment to GitHub issue
+
+## Output Format
+
+### Progress Updates
+
+For each iteration, output:
+
+```markdown
+## Loop Iteration X/3
+
+### Issues from Previous Phase
+1. [Issue description]
+2. [Issue description]
+
+### Fixes Applied
+- [Fix 1]: [file:line] - [description]
+- [Fix 2]: [file:line] - [description]
+
+### Re-validation Results
+- Tests: X/Y passed
+- Build: PASS/FAIL
+- AC Coverage: X/Y met
+
+### Status
+[FIXED - Continue to QA | NEEDS_MORE_WORK | MAX_ITERATIONS_REACHED]
+```
+
+### Final Summary
+
+```markdown
+## Quality Loop Complete
+
+**Issue:** #<N>
+**Iterations:** X/3
+**Final Status:** [READY_FOR_MERGE | NEEDS_MANUAL_REVIEW]
+
+### Issues Fixed
+1. [Issue] - Fixed in [file:line]
+2. [Issue] - Fixed in [file:line]
+
+### Remaining Issues (if any)
+- [Issue that couldn't be auto-fixed]
+
+### Recommended Next Steps
+- [If READY_FOR_MERGE]: Run `/qa <N>` for final review
+- [If manual review needed]: [Specific guidance]
+```
+
+## Integration with Workflow
+
+**Interactive usage:**
+```bash
+/spec 218          # Plan
+/exec 218          # Implement
+/test 218          # Test - finds 2 bugs
+/loop 218          # Fixes bugs, re-tests, confirms PASS
+/qa 218            # Final QA - READY_FOR_MERGE
+```
+
+**Automated usage (execute-issues.ts):**
+```bash
+QUALITY_LOOP=true npx tsx --env-file=.env.local scripts/dev/execute-issues.ts 218
+# Phases: spec → testgen → exec → test → (loop if needed) → qa → (loop if needed)
+```
+
+## Example Log Parsing
+
+### Test Log Example
+
+```
+/test 218
+## Testing Results for Issue #218
+
+**Summary:** 8/10 tests passed
+
+### Test Results
+
+**Test 1: Basic image selection** - PASS
+**Test 2: External URL validation** - FAIL
+- Expected: URL validation error message
+- Actual: No error shown for invalid URLs
+- Issue: Validation not triggering on blur
+
+**Test 3: Focal point picker** - BLOCKED
+- Blocker: Modal not opening due to Test 2 failure
+
+### Bugs Found
+
+1. **URL validation not working**
+   - Location: components/admin/news/ExternalUrlTab.tsx:45
+   - Issue: onBlur handler missing validation call
+   - Status: needs fix
+```
+
+**Parsed Output:**
+- Last phase: `/test`
+- Failed tests: 2 (Test 2, Test 3)
+- Issues to fix:
+  1. URL validation missing onBlur handler at `ExternalUrlTab.tsx:45`
+  2. Test 3 blocked - depends on Test 2 fix
+
+### QA Log Example
+
+```
+/qa 218
+## QA Review for Issue #218
+
+### AC Coverage
+
+- AC-1: MET
+- AC-2: MET
+- AC-3: PARTIALLY_MET - External URL validation incomplete
+- AC-4: NOT_MET - Focal point not persisted to database
+
+### Verdict: AC_NOT_MET
+
+### Required Fixes
+
+1. Complete URL validation in ExternalUrlTab
+2. Add focal point persistence in updateArticleImage action
+```
+
+**Parsed Output:**
+- Last phase: `/qa`
+- Verdict: `AC_NOT_MET`
+- Issues to fix:
+  1. AC-3: Complete URL validation
+  2. AC-4: Add focal point persistence
+
+## Error Handling
+
+**If log file doesn't exist:**
+```
+Error: Log file not found at /tmp/claude-issue-<N>.log
+Please run /spec, /exec, /test, or /qa first.
+```
+
+**If no issues found but not READY_FOR_MERGE:**
+```
+Warning: No specific issues found in log.
+Recommend running /qa <N> for fresh assessment.
+```
+
+**If worktree not found:**
+```
+Error: Feature worktree not found for issue #<N>
+Expected: ../worktrees/feature/<N>-*/
+Please run /exec <N> first to create the worktree.
+```
+
+## Configuration
+
+**Max iterations:** 3 (prevents infinite loops)
+**Re-validation after each fix:** Required
+**GitHub comment:** Posted after loop completion

package/templates/skills/qa/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: qa
+description: "Code review + QA vs Acceptance Criteria, including A+ status suggestions and review comment draft."
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Bash(npm test:*)
+  - Bash(npm run build:*)
+  - Bash(git diff:*)
+  - Bash(git status:*)
+  - Bash(gh issue view:*)
+  - Bash(gh issue comment:*)
+  - Bash(gh issue edit:*)
+  - Bash(gh pr view:*)
+  - Bash(gh pr diff:*)
+  - Bash(gh pr comment:*)
+  - Task
+  - AgentOutputTool
+---
+
+# QA & Code Review
+
+You are the Phase 3 "QA & Code Review Agent" for the current repository.
+
+## Purpose
+
+When invoked as `/qa`, your job is to:
+
+1. Review the current state of the implementation for a single issue.
+2. Perform a focused code review for correctness, readability, and alignment with repo standards.
+3. Validate behavior against the Acceptance Criteria (AC).
+4. Assess whether the change is "A+ status" or needs more work.
+5. Draft a GitHub review/QA comment summarizing findings and recommendations.
+
+## Behavior
+
+Invocation:
+
+- `/qa 123`: Treat `123` as the GitHub issue/PR identifier in context.
+- `/qa <freeform description>`: Treat the text as context about the change to review.
+
+### Feature Worktree Workflow
+
+**QA Phase:** Review code in the feature worktree.
+
+1. **Locate the worktree:**
+   - The worktree should already exist from the execution phase (`/exec`)
+   - Find the worktree: `git worktree list` or check `../worktrees/feature/` for directories matching the issue number
+   - The worktree path will be: `../worktrees/feature/<issue-number>-<issue-title-slug>/`
+
+2. **Check implementation status:**
+   - Navigate to worktree: `cd <worktree-path>`
+   - Check for uncommitted changes: `git status`
+   - Check for committed changes: `git log --oneline main..HEAD`
+
+   **Status interpretation:**
+   - **No commits AND no uncommitted changes:** Implementation may not be started
+   - **Uncommitted changes exist:** Implementation done but not committed
+   - **Commits exist:** Implementation committed and ready for review
+
+3. **Review in the worktree:**
+   - Navigate to the worktree directory to review the implementation
+   - Use `git diff main...HEAD` to see all changes made in the feature branch
+   - Run `npm test` and `npm run build` in the worktree to verify everything works
+   - Review the code changes against the AC checklist
+
+4. **Pre-merge cleanup check:**
+   - Check for untracked files in main that match PR files: `git status --short`
+   - If found, compare versions and remove older local copies
+
+**Important:** Review the actual implementation in the worktree, not the main branch.
+
+### No Worktree Found
+
+If no feature worktree exists (work was done directly on main):
+
+1. **Identify relevant commits:**
+   ```bash
+   git log --oneline -10
+   ```
+
+2. **Find the base commit** (before the implementation started):
+   ```bash
+   # Look for the last commit before the feature work
+   git log --oneline --before="<date>" -1
+   ```
+
+3. **Review changes from base:**
+   ```bash
+   git diff <base-commit>...HEAD --name-only
+   git diff <base-commit>...HEAD
+   ```
+
+4. **Run quality checks** on the current branch instead of comparing to a worktree.
+
+### Parallel Quality Checks (Multi-Agent)
+
+Before detailed manual review, run quality checks in parallel using specialized agents.
+
+**Spawn agents in a SINGLE message:**
+
+```
+Task(subagent_type="quality-checker", model="haiku",
+     prompt="Run type safety and deleted tests checks. Report: type issues count, deleted tests, verdict.")
+
+Task(subagent_type="quality-checker", model="haiku",
+     prompt="Run scope and size checks. Report: files count, diff size, size assessment.")
+
+Task(subagent_type="quality-checker", model="haiku",
+     prompt="Run security scan on changed files. Report: critical/warning/info counts, verdict.")
+```
+
+**Add RLS check if admin files modified:**
+```bash
+admin_modified=$(git diff main...HEAD --name-only | grep -E "^app/admin/" | head -1)
+```
+
+See [quality-gates.md](references/quality-gates.md) for detailed verdict synthesis.
+
+### Using MCP Tools
+
+- **Sequential Thinking:** For complex multi-step analysis
+- **Context7:** For broader pattern context
+- **Supabase MCP:** For database-related code verification
+
+### 1. Context and AC Alignment
+
+- **Read all GitHub issue comments** for complete context
+- Reconstruct the AC checklist (AC-1, AC-2, ...)
+- If AC unclear, state assumptions explicitly
+
+### 2. Code Review
+
+Perform a code review focusing on:
+
+- Correctness and potential bugs
+- Readability and maintainability
+- Alignment with existing patterns (see CLAUDE.md)
+- TypeScript strictness and type safety
+- **Duplicate utility check:** Verify new utilities don't duplicate existing ones in `docs/patterns/`
+
+See [code-review-checklist.md](references/code-review-checklist.md) for integration verification steps.
+
+### 3. QA vs AC
+
+For each AC item, mark as:
+- `MET`
+- `PARTIALLY_MET`
+- `NOT_MET`
+
+Provide a sentence or two explaining why.
+
+### 4. Failure Path & Edge Case Testing (REQUIRED)
+
+Before any READY_FOR_MERGE verdict, complete the adversarial thinking checklist:
+
+1. **"What would break this?"** - Identify and test at least 2 failure scenarios
+2. **"What assumptions am I making?"** - List and validate key assumptions
+3. **"What's the unhappy path?"** - Test invalid inputs, failed dependencies
+4. **"Did I test the feature's PRIMARY PURPOSE?"** - If it handles errors, trigger an error
+
+See [testing-requirements.md](references/testing-requirements.md) for edge case checklists.
+
+### 5. A+ Status Verdict
+
+Provide an overall verdict:
+
+- `READY_FOR_MERGE` — AC met and code quality is high ("A+")
+- `AC_MET_BUT_NOT_A_PLUS` — AC met, but meaningful improvements recommended
+- `AC_NOT_MET` — AC not fully met; additional implementation needed
+
+See [quality-gates.md](references/quality-gates.md) for detailed verdict criteria.
+
+## Automated Quality Checks
+
+Run these before detailed review (or use parallel agents above):
+
+```bash
+# Type safety
+type_issues=$(git diff main...HEAD | grep -E ":\s*any[,)]|as any" | wc -l | xargs)
+
+# Deleted tests
+deleted_tests=$(git diff main...HEAD --diff-filter=D --name-only | grep -E "\\.test\\.|\\spec\\." | wc -l | xargs)
+
+# Scope check
+files_changed=$(git diff main...HEAD --name-only | wc -l | xargs)
+
+# Size check
+additions=$(git diff main...HEAD --numstat | awk '{sum+=$1} END {print sum+0}')
+deletions=$(git diff main...HEAD --numstat | awk '{sum+=$2} END {print sum+0}')
+
+# Security scan
+npx tsx scripts/lib/__tests__/run-security-scan.ts 2>/dev/null
+```
+
+See [scripts/quality-checks.sh](scripts/quality-checks.sh) for the complete automation script.
+
+### 6. Draft Review/QA Comment
+
+Produce a Markdown snippet for the PR/issue:
+- Short summary of the change
+- AC coverage status (bullet list)
+- Key strengths and issues
+- Clear, actionable next steps
+
+### 7. Update GitHub Issue
+
+Post the draft comment to GitHub and update labels:
+- `AC_NOT_MET`: add `needs-work` label
+- `READY_FOR_MERGE`: add `ready-for-review` label
+- `AC_MET_BUT_NOT_A_PLUS`: add `needs-improvement` label
+
+### 8. Documentation Reminder
+
+If verdict is `READY_FOR_MERGE` or `AC_MET_BUT_NOT_A_PLUS`:
+
+```md
+**Documentation:** Before merging, run `/docs <issue>` to generate feature documentation.
+```
+
+### 9. Script/CLI Execution Verification
+
+**REQUIRED for CLI/script features:** When `scripts/` files are modified, execution verification is required before `READY_FOR_MERGE`.
+
+**Detection:**
+```bash
+scripts_changed=$(git diff main...HEAD --name-only | grep "^scripts/" | wc -l | xargs)
+if [[ $scripts_changed -gt 0 ]]; then
+  echo "Script changes detected. Run /verify before READY_FOR_MERGE"
+fi
+```
+
+**Verification evidence:** Look for "Execution Verification" section in issue comments. This section is posted by the `/verify` skill and includes:
+- Command executed
+- Exit code and duration
+- Output sample (truncated)
+- Human confirmation of expected behavior
+
+**If no verification evidence exists:**
+1. Prompt: "Script changes detected but no execution verification found. Run `/verify <issue> --command \"<test command>\"` before READY_FOR_MERGE verdict."
+2. Do NOT give `READY_FOR_MERGE` verdict until verification is complete
+3. Verdict should be `AC_MET_BUT_NOT_A_PLUS` with note about missing verification
+
+**Why this matters:**
+- Code review + unit tests miss integration issues
+- CLI features must be executed at least once to verify end-to-end behavior
+
+**Example workflow:**
+```bash
+# QA detects scripts/ changes
+# -> Prompt: "Run /verify before READY_FOR_MERGE"
+
+/verify 558 --command "npx tsx scripts/dev/execute-issues.ts 535 --phases spec"
+
+# Human confirms output looks correct
+# -> /verify posts evidence to issue
+
+/qa 558  # Re-run, now sees verification, can give READY_FOR_MERGE
+```

package/templates/skills/qa/references/code-quality-exemplars.md

@@ -0,0 +1,112 @@
+# Code Quality Exemplars
+
+## ✅ Good Example: Content Ideas Queue (Issue #146)
+
+
+
+**AC:** Content Ideas Queue with filtering, pagination, bulk actions, and scoring (17 AC items)
+
+**Changes** (1553 net LOC, 20 files):
+- `components/admin/news/ContentIdeasList.tsx` (new, 349 LOC) - Main queue interface
+- `components/admin/news/IdeaDetailModal.tsx` (new, 205 LOC) - Full-screen review modal
+- `components/admin/news/IdeaScoringForm.tsx` (new, 160 LOC) - Interactive scoring UI
+- `components/admin/news/IdeasFilters.tsx` (new, 134 LOC) - Multi-criteria filtering
+- `components/admin/news/IdeaCard.tsx` (new, 125 LOC) - Compact card view
+- `components/admin/news/IdeaActions.tsx` (new, 44 LOC) - Action buttons
+- `lib/queries/news.ts` (modified, +318 LOC) - Database queries for ideas
+- `app/admin/news/ideas/page.tsx` (modified, +137 LOC) - Main route
+- `types/database.ts` (modified, type regeneration with +383/-554 LOC)
+- `types/news.ts` (new, 87 LOC) - Type definitions
+- 5 API routes (promote, archive, score, bulk actions)
+
+**Why it's A+:**
+- ✅ Every file directly serves an AC item (17 AC → ~1500 LOC = 88 LOC/AC)
+- ✅ Size proportional to scope (complex feature with 6 components + 5 API routes)
+- ✅ Zero scope creep - no refactoring of unrelated code
+- ✅ Type safety improved (removed all 'as never' assertions, added proper types)
+- ✅ Follows existing admin patterns (List + Card + Modal + Actions)
+- ✅ Clear separation of concerns (UI, data, types, API)
+- ✅ Comprehensive: filtering, pagination, bulk operations, scoring
+- ✅ Build succeeds, all 280 tests pass
+
+**Automated Checks:**
+- Type issues: 0 (actually improved type safety)
+- Deleted tests: 0
+- Files changed: 20
+- Diff size: +2107 -554 (net: +1553)
+- LOC per AC: 88 (reasonable for complex feature)
+
+**Verdict:** `READY_FOR_MERGE` - Gold standard A+ implementation
+
+---
+
+## ⚠️ Acceptable but Not A+
+
+**AC:** Add bulk edit modal for shops (6 AC items)
+
+**Changes** (420 net LOC, 12 files):
+- `components/admin/shops/BulkEditModal.tsx` (new, 280 LOC)
+- `lib/queries/shops.ts` (modified, +85 LOC)
+- `app/admin/shops/review/actions.ts` (modified, +45 LOC)
+- 9 other files (minor changes, imports, types)
+
+**Issues:**
+- ⚠️ BulkEditModal is 280 LOC - could be split into smaller components
+- ⚠️ Added 3 utility functions to `lib/utils/formatting.ts` not directly used
+- ⚠️ Changed formatting in 2 unrelated files ("while I was here" changes)
+
+**Why it's acceptable:**
+- ✅ All AC met
+- ✅ No type safety violations
+- ✅ Tests pass
+- ⚠️ Some scope creep (utility functions, formatting)
+- ⚠️ Could be cleaner (large component, unrelated changes)
+
+**Automated Checks:**
+- Type issues: 0
+- Deleted tests: 0
+- Files changed: 12 (higher than expected for 6 AC)
+- Diff size: +445 -25 (net: +420)
+
+**Verdict:** `AC_MET_BUT_NOT_A_PLUS` - Works but has technical debt
+
+**Recommendations:**
+1. Split BulkEditModal into 3 components (Form, Preview, Actions)
+2. Remove unused utility functions
+3. Revert formatting changes in unrelated files
+
+---
+
+## ❌ Needs Rework
+
+**AC:** Display shop reviews on detail page (3 simple AC items)
+
+**Changes** (890 net LOC, 23 files):
+- Rewrote entire reviews system (not in AC)
+- Added new reviews API routes (not in AC)
+- Refactored unrelated shop queries (not in AC)
+- Changed database schema without migration (BLOCKER)
+- Removed type annotations from 5 functions (type safety violation)
+- Deleted 2 test files to "make build pass" (BLOCKER)
+
+**Issues:**
+- ❌ Massive scope creep - AC only asked for display, got full rewrite
+- ❌ Schema changes without migration
+- ❌ Type safety violations
+- ❌ Deleted tests
+- ❌ Changed 20 unrelated files
+
+**Automated Checks:**
+- Type issues: 5
+- Deleted tests: 2 ❌ BLOCKER
+- Files changed: 23 (way too many for 3 simple AC)
+- Diff size: +920 -30 (net: +890)
+
+**Verdict:** `AC_NOT_MET` - Scope creep and quality violations
+
+**Required Fixes:**
+1. Revert all changes
+2. Start over with minimal implementation (display only)
+3. Do NOT refactor, rewrite, or change schema
+4. Do NOT delete tests
+5. Target <100 LOC for 3 simple AC