forge-workflow 0.0.1 → 0.0.3

package/.claude/commands/plan.md

@@ -20,7 +20,7 @@ Before ANY planning work begins:
    - Tell the user: "You are on '<branch>'. Planning must start from a clean worktree on master.
      Run: git checkout master — then re-run /plan."
 3. If on master, create the worktree NOW before asking any questions:
-   a. git worktree add -b feat/<slug> .worktrees/<slug>
+   a. bd worktree create .worktrees/<slug> --branch feat/<slug>
    b. cd .worktrees/<slug>
 4. Confirm: "Working in isolated worktree: .worktrees/<slug> (branch: feat/<slug>)"
 5. ONLY THEN begin Phase 1.
@@ -48,6 +48,62 @@ between parallel features or sessions.
 
 **Goal**: Capture WHAT to build — purpose, constraints, success criteria, edge cases, approach.
 
+### Step 0: Dependency ripple check (advisory)
+
+Before exploring context or asking questions, check for potential conflicts with in-flight work:
+
+```bash
+# If a Beads issue ID is known (e.g., from /status or bd ready):
+bash scripts/dep-guard.sh check-ripple <beads-issue-id>
+
+# If no issue exists yet (first-time plan):
+bd list --status=open,in_progress
+```
+
+Review the output. If overlaps are detected:
+- Consider whether the overlapping issue should be a dependency
+- Note any shared areas for the design Q&A
+- This check is **advisory only** — always proceed to Step 1 regardless of findings
+
+#### Ripple Analyst Agent (spawned when contract overlaps found)
+
+When `check-ripple` detects overlapping issues AND contract metadata is available, spawn a Ripple Analyst subagent with this prompt:
+
+**Input to agent**:
+- Current issue's contract changes (from `extract-contracts` output)
+- Consumer code snippets (from `find-consumers` output for each changed contract)
+- Overlapping issue's title, description, and contract metadata
+
+**Agent instructions**:
+1. For each overlapping contract, imagine 2-3 concrete break scenarios:
+   - "If [contract X] changes [specific behavior], then [consumer Y] will [specific failure]"
+2. Rate overall impact as one of:
+   - **NONE**: No real conflict despite keyword overlap
+   - **LOW**: Consumers need trivial adjustment (add parameter, rename call)
+   - **HIGH**: Consumer needs significant rework (parsing logic, data handling changes)
+   - **CRITICAL**: Consumer is in an active in_progress issue's task list
+3. **When uncertain, default to HIGH** — conservative over permissive
+4. Recommend one action:
+   - Add dependency (`bd dep add <source> <target>`)
+   - Coordinate with other issue's developer
+   - Scope down current feature to avoid overlap
+   - Proceed as-is (no real conflict)
+
+**Output format**:
+```
+Impact: [NONE|LOW|HIGH|CRITICAL]
+Confidence: [high|medium|low]
+
+Break scenarios:
+1. [scenario description]
+2. [scenario description]
+
+Recommendation: [action]
+Reason: [why this action]
+```
+
+This agent is advisory only. The developer always makes the final decision.
+
 ### Step 1: Explore project context
 
 Before asking any questions, read relevant files:
@@ -239,10 +295,9 @@ else
   # Step 2b: Verify .worktrees/ is gitignored — add if missing
   git check-ignore -v .worktrees/ || echo ".worktrees/" >> .gitignore
 
-  # Step 2c: Create branch + worktree in one command (from master)
-  # Using -b with worktree add avoids "branch already checked out" error
+  # Step 2c: Create a Beads-aware worktree rooted on master
   git checkout master
-  git worktree add -b feat/<slug> .worktrees/<slug>
+  bd worktree create .worktrees/<slug> --branch feat/<slug>
   cd .worktrees/<slug>
 fi
 ```
@@ -315,6 +370,38 @@ bash scripts/beads-context.sh set-acceptance <id> "<success-criteria from design
 
 Both commands must exit with code 0. If either fails, investigate (wrong issue ID? missing script?) before continuing.
 
+### Step 5c: Contract extraction and logic-level dependency review
+
+After saving the task list and Beads context, extract and store contract metadata, then run the logic-level Phase 3 dependency review:
+
+```bash
+# Extract contracts — only call store-contracts if extract succeeds (exit 0)
+if bash scripts/dep-guard.sh extract-contracts docs/plans/YYYY-MM-DD-<slug>-tasks.md > /tmp/contracts.txt; then
+  bash scripts/dep-guard.sh store-contracts <id> "$(cat /tmp/contracts.txt)"
+else
+  echo "No contracts found — skipping store-contracts"
+fi
+
+# Re-run ripple check using Beads JSON + logic-level analysis
+bash scripts/dep-guard.sh check-ripple <id>
+```
+
+`extract-contracts` exits 1 when no contracts are found (not an error — just nothing to store). `store-contracts` must exit 0 if called.
+
+`check-ripple` is now advisory but logic-aware. It should:
+- read Beads issue data via JSON
+- analyze import/call-chain, contract, and behavioral dependency signals
+- show rubric score, confidence, issue pairs, and proposed dependency updates with pros/cons
+- stop for user approval whenever a dependency mutation is proposed
+
+If the user approves a dependency mutation, apply it explicitly:
+
+```bash
+bash scripts/dep-guard.sh apply-decision <id> <dependent-id> <depends-on-id> "<approval rationale>"
+```
+
+That approval step must validate with `bd dep cycles`, show `bd graph`, summarize `bd ready`, and persist the decision via `bd set-state` plus `bd comments`. Beads remains the canonical machine-readable decision record; the plan docs hold only the concise summary.
+
 ### Step 6: User review
 
 Present the full task list. Allow the user to reorder, split, or remove tasks.
@@ -332,6 +419,8 @@ Do NOT proceed to /dev until ALL are confirmed:
 6. User has confirmed task list is correct
 7. `beads-context.sh set-design` ran successfully (exit code 0)
 8. `beads-context.sh set-acceptance` ran successfully (exit code 0)
+9. `dep-guard.sh store-contracts` ran successfully (exit code 0) — or skipped if no contracts found
+10. `dep-guard.sh check-ripple` ran successfully and any proposed dependency mutation was reviewed with the user before calling `apply-decision`
 </HARD-GATE>
 ```
 

package/.cline/workflows/dev.md

@@ -0,0 +1,311 @@
+
+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>
+```
+
+---
+
+## 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