forge-workflow 0.0.2 → 0.0.4

package/.codex/skills/verify/SKILL.md

@@ -0,0 +1,221 @@
+---
+description: Post-merge health check — confirm merge landed, CI is clean, deployments are up
+---
+
+Verify that the merge landed correctly and everything is running properly after merge.
+
+# Verify
+
+This command runs AFTER the user has merged the PR. It checks system health — not documentation (that was handled in `/premerge`).
+
+## Usage
+
+```bash
+/verify
+```
+
+## What This Command Does
+
+### Step 1: Switch to Main and Pull
+
+```bash
+git checkout master
+git pull
+```
+
+Confirm the merge actually landed on main. If the PR isn't merged yet, stop and tell the user to merge first.
+
+### Step 2: Confirm PR Is Merged
+
+Detect the most recently merged PR from the current HEAD commit:
+
+```bash
+gh pr list --state merged --base master --limit 1 --json number,state,mergedAt,mergedBy
+```
+
+- `state` should be `MERGED`
+- If no PR found: the merge may not have landed yet — stop and tell the user to merge first
+- If the wrong PR appears: user can specify the number directly with `gh pr view <number> --json state,mergedAt,mergedBy`
+
+### Step 3: Check CI on Main After Merge
+
+```bash
+gh run list --branch master --limit 5
+```
+
+Check the most recent workflow runs on `master`:
+- All should be passing or in progress
+- If any failed: identify which workflow and what failed
+- Failed CI on main after merge may need a hotfix PR
+
+### Step 4: Check Deployments (if applicable)
+
+Check if the project has a deployment target:
+
+```bash
+# Check deployment status from latest run
+gh run list --branch master --limit 1
+
+# Check Vercel deployments for the merged PR (use number from Step 2)
+gh pr view <number> --json deployments
+```
+
+If deployments exist:
+- Are they showing as successful?
+- Is the production/preview URL responding?
+
+### Step 5: Report Status
+
+**If everything is clean**:
+```
+✅ Merge verified — everything is healthy
+
+  PR: #<number> merged by <user> at <time>
+  CI on master: ✓ All passing
+  Deployments: ✓ Up (if applicable)
+
+  Ready for next feature → run /status
+```
+
+**If issues found**:
+```
+⚠️  Post-merge issues detected
+
+  PR: #<number> merged ✓
+  CI on master: ✗ <workflow-name> failing
+    - Error: <description>
+    - Action needed: <hotfix or investigation>
+
+  Deployments: ✗ <deployment> not responding
+
+  Next: Create hotfix branch or investigate root cause
+```
+
+### Step 6: Clean Up Worktree and Branch
+
+Only run this step after CI is confirmed healthy (Step 3 passed).
+
+Get the merged branch name:
+
+```bash
+gh pr view <number> --json headRefName --jq '.headRefName'
+```
+
+If the branch name cannot be determined (empty output or error), skip cleanup and tell the user to run `git worktree list` and clean up manually.
+
+Find and remove the matching worktree (if it exists):
+
+```bash
+# Get the worktree path for this exact branch
+WORKTREE_PATH=$(git worktree list --porcelain \
+  | awk -v branch="refs/heads/<branch>" '
+      /^worktree / { path=substr($0, 10) }
+      $0 == "branch " branch { print path }
+    ')
+
+if [ -n "$WORKTREE_PATH" ]; then
+  git worktree remove "$WORKTREE_PATH" --force
+  echo "Worktree: removed ✓ ($WORKTREE_PATH)"
+else
+  echo "Worktree: not found (already removed or never created) — skipping"
+fi
+```
+
+If no worktree is found for that branch, skip gracefully with a note: "Worktree: not found (already removed or never created)".
+
+Delete the local branch (safe delete only):
+
+```bash
+git branch -d <branch> 2>/dev/null || echo "Branch: already deleted — skipping"
+```
+
+The `|| echo` fallback handles the case where the branch is already gone (e.g., deleted by a previous run or the remote), so the command never fails the verify step.
+
+Report cleanup in output:
+```
+Worktree: removed ✓
+Branch: <branch-name> deleted ✓
+```
+
+### Step 7: If Issues Found — Create Beads Issue
+
+**Never commit inline.** If something is wrong, create a tracking issue:
+
+```bash
+bd create --title="Post-merge: <description of issue>" --type=bug --priority=1
+```
+
+### Step 8: Close Beads Issue (if healthy)
+
+If everything is clean, close the Beads issue:
+
+```bash
+bd close <id> --reason="Merged and verified on master"
+```
+
+```
+<HARD-GATE: /verify exit>
+Do NOT declare /verify complete until:
+1. gh run list --branch master --limit 3 shows actual CI output (not "should be fine")
+2. If healthy: Beads issue is closed (bd close <id> run and confirmed)
+3. If issues found: Beads tracking issue created for every problem
+4. Worktree removed (or confirmed already gone) — OR Step 6 was intentionally skipped because CI was unhealthy; if skipped, state explicitly: "cleanup deferred, CI was not healthy"
+"It should be fine" is not evidence. Run the command. Show the output.
+</HARD-GATE>
+```
+
+## Rules
+
+- **Never commits** — this command is read-only
+- **Never creates PRs** — if fixes are needed, that's a new /dev cycle
+- **Runs after user confirms merge** — not before
+- **Reports honestly** — if CI is broken on main, say so clearly
+
+## Example Output (Healthy)
+
+```
+✅ Merge verified — everything is healthy
+
+  PR: #89 merged by harshanandak at 2026-02-24T14:30:00Z
+  Branch: feat/auth-refresh deleted ✓
+  CI on master:
+    ✓ Test Suite (ubuntu, node 20): passing
+    ✓ Test Suite (windows, node 22): passing
+    ✓ ESLint: passing
+    ✓ SonarCloud: passing
+    ✓ CodeQL: passing
+  Deployments: N/A (no deployment configured)
+
+  Ready for next feature → run /status
+```
+
+## Example Output (Issues Found)
+
+```
+⚠️  Post-merge issues detected
+
+  PR: #89 merged ✓
+  CI on master:
+    ✓ Test Suite: passing
+    ✗ SonarCloud: quality gate failing
+      - 2 new code smells introduced
+      - Action: investigate or create hotfix
+
+  Created Beads issue: forge-xyz
+  "Post-merge: SonarCloud quality gate failing on master after PR #89"
+
+  Run /status to assess next steps
+```
+
+## Integration with Workflow
+
+```
+Utility: /status     → Understand current context before starting
+Stage 1: /plan       → Design intent → research → branch + worktree + task list
+Stage 2: /dev        → Implement each task with subagent-driven TDD
+Stage 3: /validate      → Type check, lint, tests, security — all fresh output
+Stage 4: /ship       → Push + create PR
+Stage 5: /review     → Address GitHub Actions, Greptile, SonarCloud
+Stage 6: /premerge   → Update docs, hand off PR to user
+Stage 7: /verify     → Post-merge CI check on main (you are here) ✓
+```

package/.cursor/commands/dev.md

@@ -0,0 +1,337 @@
+
+Implement each task from the /plan task list using a subagent-driven loop: implementer → spec compliance reviewer → code quality reviewer per task.
+
+# Dev
+
+This command reads the task list created by `/plan` and implements each task using a three-stage subagent loop. TDD is enforced inside each implementer subagent.
+
+## Usage
+
+```bash
+/dev
+```
+
+---
+
+## Setup
+
+### Step 1: Load context
+
+```bash
+# Find task list and design doc
+ls docs/plans/
+```
+
+Read:
+- **Task list**: `docs/plans/YYYY-MM-DD-<slug>-tasks.md` — extract ALL task text upfront
+- **Design doc**: `docs/plans/YYYY-MM-DD-<slug>-design.md` — including ambiguity policy section
+
+### Step 2: Create decisions log
+
+Create an empty decisions log at the start of every /dev session:
+
+```bash
+# docs/plans/YYYY-MM-DD-<slug>-decisions.md
+```
+
+Format for each entry:
+```
+## Decision N
+**Date**: YYYY-MM-DD
+**Task**: Task N — <title>
+**Gap**: [what the spec didn't cover]
+**Score**: [filled checklist total]
+**Route**: PROCEED / SPEC-REVIEWER / BLOCKED
+**Choice made**: [if PROCEED: what was decided and why]
+**Status**: RESOLVED / PENDING-DEVELOPER-INPUT
+```
+
+### Step 3: Pre-flight checks
+
+```
+<HARD-GATE: /dev start>
+Do NOT write any code until ALL confirmed:
+1. git branch --show-current output is NOT main or master
+2. git worktree list shows the worktree path for this feature
+3. Task list file confirmed to exist (use Read tool — do not assume)
+4. Decisions log file created
+</HARD-GATE>
+```
+
+---
+
+
+### Multi-developer conflict check (soft block)
+
+Before starting the per-task loop, check for cross-developer conflicts:
+
+```bash
+# Auto-sync to get latest team state
+bash scripts/sync-utils.sh auto-sync
+
+# Check for conflicts with the current beads issue
+bash scripts/conflict-detect.sh --issue <beads-id>
+```
+
+If exit code 2 (validation error): show error message, abort — do not show conflict prompt.
+
+If exit code 1 (conflicts found):
+- Display the conflict output to the developer
+- Ask: "Other developers are working in overlapping areas. Proceed anyway? (y/n)"
+- If `n`: exit cleanly, no side effects
+- If `y`: log override via `bd comments add <id> "Conflict override: proceeding despite overlap with <conflicting-issues>"`, then continue to Per-Task Loop
+- Audit: record conflict override per OWASP A09
+
+If exit code 0: proceed silently to Per-Task Loop.
+
+---
+
+## Per-Task Loop
+
+Repeat for each task in the task list, in order:
+
+### Step A: Dispatch implementer subagent
+
+Provide the subagent with:
+- **Full task text** (copy the complete task content — do NOT send just the file path)
+- **Relevant design doc sections** for this task
+- **Recent git log** showing what has already been implemented
+
+The implementer subagent:
+1. Asks clarifying questions before writing any code
+2. Implements using RED-GREEN-REFACTOR
+3. Self-reviews for correctness
+4. Commits with a descriptive message
+
+```
+<HARD-GATE: TDD enforcement (inside implementer subagent)>
+Do NOT write any production code until:
+1. A FAILING test exists for that code
+2. The test has been run and output shows it FAILING
+3. The failure reason matches the expected missing behavior
+
+If code was written before its test: delete it. Start with the test.
+"The test would obviously fail" is not evidence. Run it and show the output.
+</HARD-GATE>
+```
+
+---
+
+### Step B: Decision gate (when implementer hits a spec gap)
+
+If the implementer encounters something not specified in the design doc, STOP and fill this checklist BEFORE deciding how to proceed:
+
+```
+Gap: [describe exactly what the spec doesn't cover]
+
+Score each dimension (0=No / 1=Possibly / 2=Yes):
+[ ] 1. Files affected beyond the current task?
+[ ] 2. Changes a function signature or public export?
+[ ] 3. Changes a shared module used by other tasks?
+[ ] 4. Changes or touches persistent data or schema?
+[ ] 5. Changes user-visible behavior not discussed in design doc?
+[ ] 6. Affects auth, permissions, or data exposure?
+[ ] 7. Hard to reverse without cascading changes to other files?
+TOTAL: ___ / 14
+
+Mandatory overrides — any of these = automatically BLOCKED:
+[ ] Security dimension (6) scored 2
+[ ] Schema migration or data model change
+[ ] Removes or changes an existing public API endpoint
+[ ] Affects a task that is already implemented and committed
+```
+
+**Score routing**:
+- **0-3**: PROCEED — make the decision, document in decisions log with full reasoning
+- **4-7**: SPEC-REVIEWER — route this decision to spec reviewer. Continue other independent tasks while waiting
+- **8+, or any mandatory override triggered**: BLOCKED — document in decisions log with Status=PENDING-DEVELOPER-INPUT. Complete all other independent tasks first. Surface to developer at /dev exit
+
+Log the decision entry before continuing.
+
+---
+
+### Step C: Spec compliance review
+
+After the implementer finishes the task, dispatch a **spec compliance reviewer** subagent.
+
+Provide:
+- Full task text (what was supposed to be implemented)
+- Relevant design doc sections
+- `git diff` for this task's commits
+
+Reviewer checks:
+- All requirements from the task text are implemented
+- Nothing extra was added beyond task scope
+- Edge cases documented in design doc are handled
+- TDD evidence: test exists, test was run failing, then passing
+
+If spec issues found: implementer fixes → re-review → repeat until ✅
+
+```
+<HARD-GATE: spec before quality>
+Do NOT dispatch code quality reviewer until spec compliance reviewer returns ✅ for this task.
+Running quality review before spec compliance is the wrong order.
+</HARD-GATE>
+```
+
+---
+
+### Step D: Code quality review
+
+After spec ✅, dispatch a **code quality reviewer** subagent.
+
+Provide:
+- git SHAs for this task's commits
+- The changed code (`git diff`)
+
+Reviewer checks:
+- Naming: clear, descriptive, consistent with codebase conventions
+- Structure: functions not too long, proper separation of concerns
+- Duplication: no copy-paste that could be extracted
+- Test coverage: tests cover happy path and at least one error path
+- No magic numbers, no commented-out code, no TODO without a Beads issue
+
+If quality issues found: implementer fixes → re-review → repeat until ✅
+
+---
+
+### Step E: Task completion
+
+```
+<HARD-GATE: task completion>
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
+
+Do NOT mark task complete or move to next task until ALL confirmed in this session:
+1. Spec compliance reviewer returned ✅
+2. Code quality reviewer returned ✅
+3. Identify what command proves this task is done (e.g. `bun test`, a CLI invocation, a script run).
+4. Run it fresh — show the actual output. "Last run was fine" is not evidence.
+5. Tests run fresh — actual output shows passing.
+6. Implementer has committed (git log shows the commit).
+7. `bash scripts/beads-context.sh update-progress <id> <task-num> <total> "<title>" <commit-sha> <test-count> <gate-count>` ran successfully (exit code 0). If it fails: STOP. Show error. Do not proceed to next task.
+
+Forbidden phrases (these are not evidence):
+- "should pass"
+- "looks good"
+- "seems to work"
+</HARD-GATE>
+```
+
+Mark task complete. Move to next task.
+
+---
+
+## /dev Completion
+
+After all tasks are complete (or BLOCKED):
+
+### Final code review
+
+Dispatch a final code reviewer for the full implementation:
+- Overall coherence: does the feature hang together as a whole?
+- Cross-task consistency: naming, patterns, style consistent across all tasks?
+- Integration: do all the pieces connect correctly?
+
+### Surface BLOCKED decisions
+
+If any decisions have Status=PENDING-DEVELOPER-INPUT:
+
+```
+⏸️  /dev blocked — developer input needed
+
+The following decisions were deferred during implementation:
+
+Decision 1: [gap description]
+  Task: Task N — <title>
+  Score: 11/14 (mandatory override: schema change)
+  Options considered: [A] vs [B]
+  Recommendation: [A] because [reason]
+  Blocked tasks: Task 6, Task 7 (depend on this decision)
+
+Decision 2: ...
+
+Please review and respond. After decisions are resolved, the implementer
+will complete the blocked tasks and re-run spec + quality review.
+```
+
+Wait for developer input. After decisions resolved: implement blocked tasks → spec review → quality review → complete.
+
+### /dev exit gate
+
+```
+<HARD-GATE: /dev exit>
+Do NOT declare /dev complete until:
+1. All tasks are marked complete OR have BLOCKED status with PENDING-DEVELOPER-INPUT
+2. BLOCKED decisions have been surfaced to developer and are awaiting input
+3. Final code reviewer has approved (or issues fixed and re-reviewed)
+4. All decisions in decisions log have Status of RESOLVED or PENDING-DEVELOPER-INPUT
+5. No unresolved spec or quality issues remain
+</HARD-GATE>
+```
+
+### Beads update
+
+```bash
+bash scripts/beads-context.sh stage-transition <id> dev validate
+```
+
+---
+
+## Decision Gate Calibration
+
+The frequency of decision gates is a **plan quality metric**:
+- **0 gates fired**: Excellent — Phase 1 Q&A covered all cases
+- **1-2 gates fired**: Good — minor gaps, normal
+- **3-5 gates fired**: Plan was incomplete — note for Phase 1 improvement next feature
+- **5+ gates fired**: Phase 1 Q&A was insufficient — the ambiguity policy field needed to be more specific
+
+Document the gate count in the final commit message.
+
+---
+
+## Example Output (all tasks complete)
+
+```
+✓ Task 1: Types and interfaces — COMPLETE
+  Spec: ✅  Quality: ✅  Tests: 4/4 passing  Commit: abc1234
+  Decision gates: 0
+
+✓ Task 2: Validation logic — COMPLETE
+  Spec: ✅  Quality: ✅  Tests: 8/8 passing  Commit: def5678
+  Decision gates: 1 (PROCEED, score 2 — documented in decisions log)
+
+✓ Task 3: API endpoint — COMPLETE
+  Spec: ✅  Quality: ✅  Tests: 6/6 passing  Commit: ghi9012
+  Decision gates: 0
+
+✓ Final code review: ✅ (coherent, consistent, correctly integrated)
+
+✓ Decisions log: docs/plans/2026-02-26-stripe-billing-decisions.md
+  - Decision 1: RESOLVED (score 2, proceeded with conservative choice)
+  - Decision gates fired: 1 (plan quality: Good)
+
+✓ Beads updated: forge-xyz → implementation complete
+
+Ready for /validate
+```
+
+## Integration with Workflow
+
+```
+Utility: /status     → Understand current context before starting
+Stage 1: /plan       → Design intent → research → branch + worktree + task list
+Stage 2: /dev        → Implement each task with subagent-driven TDD (you are here)
+Stage 3: /validate      → Type check, lint, tests, security — all fresh output
+Stage 4: /ship       → Push + create PR
+Stage 5: /review     → Address GitHub Actions, Greptile, SonarCloud
+Stage 6: /premerge   → Update docs, hand off PR to user
+Stage 7: /verify     → Post-merge CI check on main
+```
+
+## Tips
+
+- **Send full task text to subagents**: Never send the file path — copy the complete task text directly into the subagent prompt
+- **TDD lives inside the implementer**: The implementer subagent is responsible for RED-GREEN-REFACTOR, not the orchestrating /dev session
+- **Spec before quality — always**: A task that passes quality review but fails spec compliance has still failed
+- **Decision gates are rare with a good plan**: If gates fire frequently, the Phase 1 Q&A needs more depth next time
+- **BLOCKED ≠ failed**: Surfacing a blocked decision with documentation and a recommendation is the correct behavior