forge-workflow 0.0.10 → 0.1.0-beta.3

package/docs/reference/protected-state-surfaces.md

@@ -0,0 +1,59 @@
+# Protected State Surfaces
+
+Forge defines protected runtime state that agents must not hand-edit. When `scripts/protected-state-check.js` is wired into hooks or CI, the protected-state check blocks direct staged additions, copies, modifications, renames, and deletions, then prints a repair hint that points to the owning command or Forge API surface.
+
+The committed manifest is `.forge/protected-paths.yaml`. Runtime enforcement is implemented in `lib/protected-state-surfaces.js`; the manifest keeps the protected surface contract visible to agents and reviewers.
+
+## Protected Categories
+
+| Surface | Examples | Required write surface |
+| --- | --- | --- |
+| `beads_state` | `.beads/issues.jsonl`, `.beads/config.yaml` | `bd` or Forge issue commands |
+| `forge_config` | `.forge/config.yaml`, `.forge/protected-paths.yaml` | Forge config/setup API |
+| `generated_harness` | `AGENTS.md`, `.claude/skills/`, `.codex/skills/`, `.cursor/rules/` | `forge setup` or harness generator |
+| `memory_projection` | `docs/sessions/`, `docs/memory/`, `.forge/memory/` | Forge memory projection writer |
+| `workflows` | `.github/workflows/`, `.claude/commands/`, `.forge/hooks/`, `lefthook.yml` | Forge workflow/setup commands |
+| `lockfiles` | `bun.lock`, `package-lock.json`, `.forge/extensions.lock` | Package manager or extension installer |
+| `extension_manifests` | `.forge/extensions/*/manifest.json`, `plugins/*/{plugin,extension,manifest}.json`, `.github/PLUGIN_TEMPLATE.json` | Forge extension/plugin manager |
+| `secrets` | `.env.local`, `secrets.json`, credential files | Secret manager or local env setup |
+| `immutable` | `.git/` | Git or owning runtime tool |
+| `append_only_logs` | `.forge/log.jsonl`, `.forge/audit.log`, `.beads/interactions.jsonl` | Append-only audit writer |
+
+## Behavior
+
+- Direct edits, additions, modifications, renames, and deletions of protected files are blocked by `scripts/protected-state-check.js`.
+- Allowed Forge API writes must declare the matching required surface. For example, a Forge config writer must call the protected writer with `surface: "forge_config"` and `viaForgeApi: true`.
+- Forge-owned commands that intentionally stage generated protected changes can set `FORGE_PROTECTED_STATE_ALLOWED_SURFACES` to the comma-separated surfaces they own for that command invocation.
+- Blocked decisions include actor, path, decision, required surface, reason, and repair hint.
+- Audit-ready events use kind `protected_state_write` and are recorded through Beads audit when available.
+
+## Repair Hint
+
+Every blocked path prints a repair hint. A repair hint is specific guidance such as using `bd update` for `beads_state`, `forge setup` for generated harness files, or the package manager for `lockfiles`.
+
+Example blocked output shape:
+
+```text
+Protected state write blocked
+path: .forge/config.yaml
+required surface: forge_config
+repair: use the Forge config/setup API for generated config changes
+```
+
+Common support notes:
+
+- If the check is not installed in hooks or CI, the model is documented but not enforced for that repository.
+- If Beads metadata needs to change after a merge and branch protection rejects the push, use a follow-up PR or the configured sync workflow.
+- Forge-owned commands may set `FORGE_PROTECTED_STATE_ALLOWED_SURFACES` narrowly for the surfaces they own.
+
+## Forge API Example
+
+```js
+const { writeProtectedFile } = require('./lib/protected-state-surfaces');
+
+writeProtectedFile(projectRoot, '.forge/config.yaml', yaml, {
+	actor: 'forge',
+	viaForgeApi: true,
+	surface: 'forge_config',
+});
+```

package/docs/reference/shepherd.md

@@ -0,0 +1,155 @@
+# PR Shepherd
+
+The shepherd is a **monitor-driven utility command** that automates the manual
+polling / rerun / escalation loop a human otherwise runs by hand after
+`/review`. It is **not** a workflow stage and does not replace `/review` or
+the pre-merge gate (the embedded documentation-and-handoff gate in `/ship` and `/review`).
+
+```bash
+forge shepherd <pr-number>
+forge shepherd <pr-number> --auto-rebase   # opt-in, default OFF
+forge shepherd <pr-number> --pull          # read-only: WHY it is blocked + what to fix
+forge shepherd <pr-number> --pull --json   # same payload as machine-readable JSON
+forge shepherd <pr-number> --bundle --json # read-only: the COMPLETE PR-state bundle
+```
+
+## `--pull`: the actionable blocker payload
+
+`--pull` is a **strictly read-only** signal-gather. It computes the decision
+state via a dry-run pass (no rerun, no rebase, no merge, no thread resolution)
+and returns ONE bounded, **actionable-only** payload so an agent gets "everything
+blocking this PR + exactly what to fix" in a single call instead of running
+`gh pr checks`, `gh run view --log-failed`, GraphQL thread queries, and branch
+-protection lookups by hand. Default output is a compact human summary; `--json`
+emits the structured payload. Every field is something to ACT on — passing
+checks, resolved/outdated threads, and satisfied policy are omitted.
+
+| Field | Meaning |
+| --- | --- |
+| `state` / `summary` | Decision state + a one-line WHY (leads with the primary blocker). |
+| `mergeable` / `mergeStateStatus` | GitHub's raw merge signals (e.g. `BLOCKED`, `BEHIND`, `DIRTY`, `UNSTABLE`). |
+| `blockers[]` | Ordered `{type, detail}` list — the human-readable WHY. Types: `draft`, `conflict`, `check-failing`, `check-missing`, `check-skipped`, `check-pending`, `behind`, `changes-requested`, `review-required`, `unresolved-threads`, `blocked-unknown`, `unstable`. |
+| `requiredChecks` | Branch-protection required set classified vs what the PR produced: `missing` (never reported), `skipped` (a **required** check that resolved SKIPPED — NOT a pass to branch protection; this is why an all-green PR can stay `BLOCKED`), `pending`, `failing`. Omitted entirely when the required set is all green. |
+| `failures[]` | Per failed check: `name`, `conclusion`, `jobUrl`, the exact failure **excerpt** pulled from the job log, and `alsoFailedOn` (matrix duplicates collapse to one). |
+| `pendingChecks[]` | Names of checks still running. |
+| `reviewThreads[]` | Every UNRESOLVED, non-outdated thread from a human or a review bot (CodeRabbit et al.): `file`, `line`, `author`, `body`, `threadId`, `commentId`. Never the shepherd's own or resolved threads. |
+| `behind` | Commits behind base (present only when > 0). |
+| `conflicts` | `{conflicted, files[]}` — present only when a merge would conflict. |
+| `reviewDecision` | Present only when actionable (`CHANGES_REQUESTED` / `REVIEW_REQUIRED`); `APPROVED` is omitted. |
+| `draft` | Present only when the PR is a draft. |
+| `truncated` | Flags when `failures`/`reviewThreads` were capped for size. |
+
+`--bundle --json` is the sibling COMPLETE (not-only-actionable) read-only state
+bundle; `--pull` and `--bundle` are mutually exclusive.
+
+## Why it is a utility, not a stage
+
+Stages are a frozen, ordered ladder (`plan → dev → validate → ship → review →
+premerge → verify`). Inserting a polling step into that ladder would break the
+stage-transition chain and the harness parity model. The shepherd instead runs
+*alongside* the review handoff: `/review` keeps owning semantic review and its
+stage transition; the shepherd only automates the mechanical waiting and
+re-running.
+
+It is registered as a utility skill in the harness capability matrix
+(`UTILITY_SKILL_IDS`), so cross-harness parity tests cover it without touching
+the frozen stage list.
+
+## Bounded-pass model
+
+Each invocation is **one discrete bounded pass**: read PR state, take at most
+one Tier-A action, then exit. There is no in-process loop. This preserves the
+project's documented ergonomic — poll briefly, then stop and hand off. A pass
+that finds checks still pending returns `PENDING`; the next scheduled pass picks
+up from there.
+
+`--watch`-style behavior, if desired, belongs in an external scheduler (cron, or
+a `/loop`) that re-invokes the bounded pass with a debounce of at least 60
+seconds and cancel-in-progress. The shepherd itself never waits in-process.
+
+## Auto-start on ship (`rail.auto_shepherd`)
+
+`forge shepherd watch <pr>` is the constant, self-stopping local monitor loop
+(≈60 s jittered cadence; appends events to the per-PR NDJSON journal under
+`.forge/pr-monitor/<repo>-<pr>/`; self-stops on `PR_MERGED`/`PR_CLOSED`). On a
+successful `forge ship`, the new PR's watcher is **auto-started detached** so a
+shipped PR is tended without a manual trigger. The spawn is best-effort and
+**never fails ship** (a spawn or config-read error degrades to "not started"),
+and it is idempotent — the watch-lifecycle PID/journal lock prevents a second
+watcher for the same PR.
+
+This auto-start is governed by the default-ON, unlocked **`rail.auto_shepherd`**
+rail. Opt out with `forge gate disable rail.auto_shepherd` (re-enable with
+`forge gate enable rail.auto_shepherd`); when disabled, `forge ship` skips the
+auto-start. This keeps the behavior honestly toggleable through the same config
+surface as every other rail.
+
+## Surfacing events back to the agent (`forge hooks shepherd-events`)
+
+The constant watch loop is the PRODUCER: it writes per-PR NDJSON journals under
+`.forge/pr-monitor/<repo>-<pr>/`, while the `forge shepherd events <pr> --since
+<seq>` pull surface reads existing records back from them. But a journal only
+helps if the working agent sees it. `forge hooks shepherd-events` is the thin,
+agent-agnostic CONSUMER: it reads the NEW budget events across all open-PR journals
+since a persisted per-PR **consumer cursor** (kept in `consumer.cursor`, distinct
+from the watcher's snapshot), renders a **compact, capped** summary of the
+actionable transitions only — verdict changes, failed checks, new review threads,
+merged/closed — then advances the cursor so nothing re-surfaces.
+
+For Claude Code this is wired as a **UserPromptSubmit** context hook (the honest
+capability matrix: only Claude exposes that additionalContext surface; Cursor /
+Codex / Hermes carry an explicit skip reason). It is **additive and FAIL-OPEN** —
+a missing/empty digest, a corrupt journal, or no `.forge/pr-monitor` at all never
+blocks a prompt — and it reads the user's own local journal only: it never
+injects into stdin and never drives the agent. Any other harness can call the
+same verb (or `forge shepherd events`) on its own cadence.
+
+## Terminal states
+
+| State         | Meaning |
+| ------------- | ------- |
+| `MERGE_READY` | Required checks are green and the branch is up to date. The shepherd hands off — **a human merges in the GitHub UI.** |
+| `ESCALATE`    | A Tier-C condition (conflict, unreadable required set, persistent failure, oscillation, budget exhaustion). Context is posted to the PR. |
+| `PENDING`     | A Tier-A action was taken, or checks are still pending. Exit and await the next scheduled pass. |
+| `HARD_STOP`   | A permanent auth/scope failure that retrying cannot fix. Escalate to a human to widen token scope. |
+
+## Action ladder
+
+- **Tier-A (autonomous):** re-run a flaky **required** check via
+  `gh run rerun --failed` (capped by a rerun budget). Post status replies to
+  review threads (reply only).
+- **Tier-B (opt-in, default OFF):** `--auto-rebase` rebases onto base and
+  force-pushes with lease, given a clean tree and an unchanged HEAD. A lease
+  rejection is a hard-stop — the shepherd never re-arms the lease.
+- **Tier-C (escalate):** everything else.
+
+## Safety invariants
+
+- **Never merges.** No merge action, no server-side auto-merge latch.
+- **Never resolves review threads.** It may post a status reply; resolution is
+  semantic and stays with `/review`.
+- **Required-check gate.** Merge-ready is declared only when the
+  branch-protection required-check set is *known* (read from
+  `gh api repos/{owner}/{repo}/branches/{base}/protection/required_status_checks`)
+  and all of it is green. If protection is unreadable, the shepherd escalates
+  rather than guessing.
+- **HEAD-changed abort.** Before any mutating action it re-reads the head SHA; if
+  HEAD moved during the pass, the action aborts. The `shepherd:active` marker is
+  advisory only — it is not mutual exclusion.
+- **Auth taxonomy.** 401 (expiry) pauses and surfaces; 403 insufficient-scope is
+  a hard-stop; 403 with `Retry-After` honors the delay and resumes next pass.
+
+## Per-harness behavior
+
+- **Claude Code / Codex:** invoke `forge shepherd <pr>` directly; an external
+  scheduler may drive repeated bounded passes.
+- **Cursor:** manually-invoked only — run it from a terminal. No polling-loop
+  affordance and no hook reliance on this surface.
+
+## State
+
+Progress is durable in GitHub PR comments and labels plus `git`. The one local
+store is the constant monitor's per-PR journal under
+`.forge/pr-monitor/<repo>-<pr>/` (the append-only `events.ndjson` + snapshot and
+consumer cursors) — the delivery/replay surface for `forge shepherd watch` and
+`events --since`. The bounded shepherd pass itself keeps no separate local state.

package/docs/reference/superpowers-analysis.md

@@ -0,0 +1,320 @@
+# Research: obra/superpowers — Integration Analysis for Forge
+
+**Feature slug**: `superpowers`
+**Status**: Historical analysis. Current user guidance lives in [Docs Index](../INDEX.md), [Command Reference](COMMANDS.md), and [Release Reference](RELEASE.md).
+**Date**: 2026-02-26
+**Sources**: All claims below cite exact URLs.
+
+---
+
+## What Is Superpowers?
+
+**Repository**: https://github.com/obra/superpowers
+**Author**: Jesse Vincent (@obra) — keyboard designer at keyboard.io, creator of K-9 Mail for Android, former Perl 5 project lead
+**Description**: "An agentic skills framework & software development methodology that works."
+**License**: MIT
+**Version**: v4.3.1 (2026-02-21)
+**Language**: Shell
+**Stars**: ~62,000 (4th most installed plugin in Claude Code marketplace, surpassed GitHub's own plugin)
+**Source**: https://www.threads.com/@obrajesse/post/DVANeBYEfuF/ — Jesse Vincent's own announcement
+
+Superpowers is a **Claude Code plugin** (also supports Cursor, Codex, OpenCode) that ships a library of 14 composable "skills" — structured instructions the agent reads and follows automatically. Skills trigger based on context, not user commands. The agent reads the right skill before taking action.
+
+---
+
+## Installation
+
+### Claude Code (Native Plugin Marketplace)
+```bash
+/plugin marketplace add obra/superpowers-marketplace
+/plugin install superpowers@superpowers-marketplace
+```
+Marketplace repo: https://github.com/obra/superpowers-marketplace
+
+### Cursor
+```text
+/plugin-add superpowers
+```
+
+### Codex / OpenCode
+Manual: Fetch and follow `.codex/INSTALL.md` or `.opencode/INSTALL.md`
+
+**Source**: https://github.com/obra/superpowers/blob/main/README.md
+
+---
+
+## Repository Structure
+
+```
+superpowers/
+├── .claude-plugin/          # Claude Code plugin manifest
+├── .codex/                  # Codex integration
+├── .cursor-plugin/          # Cursor integration
+├── .opencode/               # OpenCode integration
+├── agents/
+│   └── code-reviewer.md     # Custom code-reviewer agent definition
+├── commands/                # CLI commands
+├── docs/
+│   ├── README.codex.md
+│   ├── README.opencode.md
+│   ├── plans/               # Design docs written here
+│   └── testing.md
+├── hooks/                   # Git hooks
+├── lib/                     # Shared libraries
+├── skills/                  # 14 skills (core value)
+└── tests/
+```
+
+**Source**: https://github.com/obra/superpowers (file tree)
+
+---
+
+## The 14 Skills (Full List)
+
+| Skill | Purpose |
+|-------|---------|
+| `brainstorming` | Socratic design refinement with hard gate — MUST complete before any code |
+| `writing-plans` | Break approved design into 2-5 minute tasks with exact file paths and code |
+| `executing-plans` | Batch execution with human checkpoints |
+| `subagent-driven-development` | Dispatch fresh subagent per task, two-stage review |
+| `dispatching-parallel-agents` | Concurrent subagent workflows |
+| `test-driven-development` | Enforced RED-GREEN-REFACTOR cycle with anti-patterns reference |
+| `systematic-debugging` | 4-phase root cause analysis (root-cause-tracing, defense-in-depth, condition-based-waiting) |
+| `verification-before-completion` | Verify fix actually works before declaring done |
+| `requesting-code-review` | Pre-review checklist |
+| `receiving-code-review` | Structured response to feedback |
+| `using-git-worktrees` | Isolated workspace per task on new branch |
+| `finishing-a-development-branch` | Merge/PR decision workflow, worktree cleanup |
+| `writing-skills` | Meta-skill: create new skills following best practices |
+| `using-superpowers` | Introduction and dispatch logic |
+
+**Source**: https://github.com/obra/superpowers/tree/main/skills
+
+---
+
+## Core Workflow (How It Runs)
+
+```
+1. brainstorming      → Explore context → ask questions one at a time → propose 2-3 approaches
+                        → present design in sections → user approves → write design doc to
+                        docs/plans/YYYY-MM-DD-<topic>-plan.md → commit
+
+2. using-git-worktrees → Create isolated workspace on new branch → run project setup
+                         → verify clean test baseline
+
+3. writing-plans      → Break approved design into tasks (2-5 min each)
+                        → each task: exact file paths, complete code, verification steps
+
+4. subagent-driven-development OR executing-plans
+                      → Fresh subagent per task
+                        → Two-stage review: (1) spec compliance, (2) code quality
+
+5. test-driven-development → RED fails → GREEN passes → REFACTOR → commit
+                             → Deletes code written before tests
+
+6. requesting-code-review → Reviews against plan, reports by severity
+                            → Critical issues block progress
+
+7. finishing-a-development-branch → Verify tests → present options (merge/PR/keep/discard)
+                                    → clean up worktree
+```
+
+**Key mechanic**: Skills auto-trigger based on context. The agent checks for relevant skills before any task. No user command needed.
+
+**Source**: https://github.com/obra/superpowers/blob/main/README.md and https://blog.fsck.com/2025/10/09/superpowers/
+
+---
+
+## The HARD-GATE Pattern
+
+The brainstorming skill uses explicit blocking tags:
+
+```
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project,
+or take any implementation action until you have presented a design and the user
+has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+```
+
+**Why this matters**: This is a structural enforcement mechanism — not a soft instruction. It explicitly names forbidden actions and conditions. Soft instructions ("read AGENTS.md first") fail. Hard gates with explicit prohibitions work.
+
+**Source**: brainstorming/SKILL.md content from https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md
+
+---
+
+## Community Reception
+
+| Source | Signal |
+|--------|--------|
+| Hacker News | 435 points, 231 comments — https://news.ycombinator.com/item?id=45547344 |
+| Simon Willison | "Jesse is one of the most creative users of coding agents I know" — https://simonwillison.net/2025/Oct/10/superpowers/ |
+| Cornell Innovation Hub | "How I Built a 3600 Line Feature in 4 Hours Without Writing a Single Line of Code" — https://innovationhub.ai.cornell.edu/articles/how-i-built-a-3600-line-feature-in-4-hours-without-writing-a-single-line-of-code/ |
+| Claude Code Marketplace | 4th most installed plugin, surpassed GitHub — https://www.threads.com/@obrajesse/post/DVANeBYEfuF/ |
+| r/ClaudeCode | "actually delivers" — https://www.reddit.com/r/ClaudeCode/comments/1r9y2ka/ |
+| Dev Genius | "the Claude plugin that enforces TDD, subagents, and planning" — https://blog.devgenius.io/superpowers-explained-the-claude-plugin-that-enforces-tdd-subagents-and-planning-c7fe698c3b82 |
+
+---
+
+## Forge vs Superpowers: Side-by-Side
+
+### What Both Do (Overlap)
+
+| Capability | Forge | Superpowers |
+|-----------|-------|------------|
+| TDD enforcement | `/dev` RED-GREEN-REFACTOR | `test-driven-development` skill |
+| Planning phase | `/plan` command + Beads | `writing-plans` skill |
+| Code review | `/review` command | `requesting-code-review` + `receiving-code-review` |
+| Parallel agents | Parallel AI skills | `dispatching-parallel-agents` skill |
+| PR workflow | `/ship`, `/premerge` | `finishing-a-development-branch` |
+
+### What Superpowers Has That Forge Doesn't
+
+| Gap | Superpowers Solution | Forge Status |
+|-----|---------------------|-------------|
+| **Design before code** | `brainstorming` skill with HARD-GATE | No equivalent — `/plan` goes straight to beads/branch |
+| **Git worktree isolation** | `using-git-worktrees` skill | Not in Forge workflow |
+| **Systematic debugging** | `systematic-debugging` (4 phases) | No equivalent |
+| **Verification before done** | `verification-before-completion` | Implicit in `/check` but not explicit |
+| **Meta-skill authoring** | `writing-skills` skill | No equivalent |
+| **Two-stage code review** | spec compliance → code quality | Single-stage review |
+| **Hard gate enforcement** | `<HARD-GATE>` tags | Soft instructions only |
+| **Design docs** | Saved to `docs/plans/YYYY-MM-DD-*.md` | Research docs only (`docs/research/`) |
+| **Plugin distribution** | Claude Code + Cursor marketplace | Not distributable as plugin |
+
+### What Forge Has That Superpowers Doesn't
+
+| Capability | Forge | Superpowers Status |
+|-----------|-------|-------------------|
+| **Web research stage** | `/research` + parallel AI search | No research phase |
+| **Formal spec proposals** | OpenSpec (`openspec/changes/`) | No equivalent |
+| **Issue tracking** | Beads (`bd create`, `bd update`) | `obra/issue-cards` (separate repo, not integrated) |
+| **Multi-agent file support** | AGENTS.md/CLAUDE.md/GEMINI.md | Claude Code + Cursor only |
+| **Security analysis** | OWASP per feature in `/dev` | No security phase |
+| **Full PR lifecycle** | `/ship`, `/review`, `/premerge`, `/verify` | Only `finishing-a-development-branch` |
+| **SonarCloud integration** | `/sonarcloud` command | None |
+| **Greptile integration** | `.claude/rules/greptile-review-process.md` | None |
+| **Post-merge verification** | `/verify` | None |
+
+---
+
+## Integration Options
+
+### Option A: Install Superpowers Plugin Alongside Forge (Non-Breaking)
+
+Install Superpowers as a Claude Code plugin. It adds its skills to your agent's context. Forge commands continue to work. Superpowers skills auto-trigger for gaps Forge doesn't cover.
+
+**Benefit**: Immediately gets brainstorming gate, systematic debugging, git worktrees, verification
+**Risk**: Workflow overlap — both have planning, review phases. Agent may get confused about which to use.
+**Verdict**: Valid short-term, but needs clear role definition in AGENTS.md/CLAUDE.md
+
+**Source on overlap concerns**: https://www.reddit.com/r/ClaudeCode/comments/1qlsdjb/superpowers_vs_gsd_vs_others/
+
+### Option B: Cherry-Pick Key Skills Into Forge (Best Fit)
+
+Import specific Superpowers skills into Forge's `skills/` directory:
+- `brainstorming` → insert between `/research` and `/plan` as a new stage
+- `systematic-debugging` → add as `/debug` command
+- `writing-skills` → use for authoring new Forge skills
+- `verification-before-completion` → integrate into `/check` command
+- HARD-GATE pattern → add to `/research`, `/plan`, `/dev` commands
+
+**Benefit**: Gets Superpowers' best ideas without workflow collision
+**Risk**: Maintenance burden — skills diverge from upstream
+**Verdict**: Best long-term approach for Forge as a standalone workflow
+
+### Option C: Replace OpenSpec With Superpowers' `writing-plans`
+
+Superpowers' `writing-plans` creates detailed task-level implementation plans. OpenSpec creates formal architecture proposals with `proposal.md`, `tasks.md`, `plan.md`.
+
+**Assessment**: These solve different problems.
+- `writing-plans` → task-level implementation checklist (tactical)
+- OpenSpec → architecture-level proposals requiring approval (strategic)
+- **Do not replace** — they are complementary. OpenSpec for "what to build", `writing-plans` for "how to build it."
+
+### Option D: Adopt HARD-GATE Pattern Into Forge Commands (Quickest Win)
+
+Add `<HARD-GATE>` blocks to existing Forge commands. Example for `/plan`:
+
+```
+<HARD-GATE>
+Do NOT proceed to /dev or write any code until:
+1. Research doc exists at docs/research/<slug>.md
+2. Beads issue is created and in_progress
+3. Branch exists at feat/<slug>
+</HARD-GATE>
+```
+
+**Benefit**: Addresses the core scope discipline problem without changing workflow
+**Risk**: None — purely additive
+**Verdict**: Should be done immediately regardless of other options
+
+---
+
+## Key Insight: Skills vs Commands
+
+Superpowers skills auto-trigger. Forge uses explicit commands (`/plan`, `/dev`). These are philosophically different:
+
+- **Forge**: User explicitly controls each stage. Good for learning, transparency.
+- **Superpowers**: Agent decides when to invoke skills. Good for autonomy, fewer user interruptions.
+
+For Forge's use case (multi-agent support, OpenSpec, Beads, full PR lifecycle), the explicit command model is correct. But Superpowers' brainstorming gate and systematic debugging are worth importing as skills, not auto-triggers.
+
+---
+
+## Related obra Repos Worth Knowing
+
+| Repo | Description | URL |
+|------|-------------|-----|
+| `obra/superpowers-marketplace` | Claude Code plugin marketplace | https://github.com/obra/superpowers-marketplace |
+| `obra/issue-cards` | AI-optimized CLI issue tracker (similar to Beads) | https://github.com/obra/issue-cards |
+| `obra/coderabbit-review-helper` | Extract CodeRabbit PR reviews for AI agent consumption | https://github.com/obra/coderabbit-review-helper |
+
+---
+
+## Recommendations for Forge
+
+**Priority 1 (Quick wins, no new features needed):**
+1. Adopt `<HARD-GATE>` pattern in `/research`, `/plan`, `/dev` commands — prevents stage-skipping
+2. Add `brainstorming` as a new stage between `/research` and `/plan` (or make it optional in `/plan`)
+3. Add `verification-before-completion` logic to `/check` command
+
+**Priority 2 (New skills):**
+4. Port `systematic-debugging` as `/debug` command
+5. Port `writing-skills` as `/skill` command for authoring new Forge skills
+6. Add git worktree support to `/dev` command (isolated implementation)
+
+**Priority 3 (Infrastructure):**
+7. Explore distributing Forge as a Claude Code plugin (`.claude-plugin/` directory) — same distribution model as Superpowers
+8. Add two-stage code review to `/review` command (spec compliance first, then code quality)
+
+**What NOT to take:**
+- Don't replace Beads with `obra/issue-cards` — Beads has cross-session persistence and is already integrated
+- Don't replace OpenSpec with `writing-plans` — different purpose levels
+- Don't install Superpowers plugin directly — workflow collision risk until roles are defined
+
+---
+
+## Sources Index
+
+| # | URL | Used For |
+|---|-----|---------|
+| 1 | https://github.com/obra/superpowers | Repo structure, README, skills list |
+| 2 | https://github.com/obra/superpowers/blob/main/README.md | Workflow, installation, philosophy |
+| 3 | https://blog.fsck.com/2025/10/09/superpowers/ | Origin story, session-start hook |
+| 4 | https://simonwillison.net/2025/Oct/10/superpowers/ | Community reception, feelings journal mention |
+| 5 | https://news.ycombinator.com/item?id=45547344 | HN reception (435 pts, 231 comments) |
+| 6 | https://www.threads.com/@obrajesse/post/DVANeBYEfuF/ | 4th most installed in Claude marketplace |
+| 7 | https://github.com/obra/superpowers-marketplace | Marketplace companion repo |
+| 8 | https://github.com/obra/issue-cards | Related obra issue tracker |
+| 9 | https://github.com/obra/coderabbit-review-helper | Related obra PR review tool |
+| 10 | https://mcpmarket.com/server/superpowers | MCP market listing |
+| 11 | https://www.reddit.com/r/ClaudeCode/comments/1r9y2ka/ | User experience reports |
+| 12 | https://www.reddit.com/r/ClaudeCode/comments/1qlsdjb/superpowers_vs_gsd_vs_others/ | Comparison with GSD workflow |
+| 13 | https://www.reddit.com/r/ClaudeCode/comments/1ra8rdy/plan_mode_vs_superpowers_brainstorming_which/ | Plan mode vs brainstorming comparison |
+| 14 | https://blog.devgenius.io/superpowers-explained-the-claude-plugin-that-enforces-tdd-subagents-and-planning-c7fe698c3b82 | Technical explanation |
+| 15 | https://innovationhub.ai.cornell.edu/articles/how-i-built-a-3600-line-feature-in-4-hours-without-writing-a-single-line-of-code/ | Real-world results |
+| 16 | https://sitepoint.com/agentic-engineering-superpowers-framework-agent-capabilities/ | Architecture patterns analysis |
+| 17 | https://st0012.dev/links/2026-01-15-a-claude-code-workflow-with-the-superpowers-plugin/ | `/superpowers:brainstorm` and `/superpowers:write-plan` usage |
+| 18 | https://medium.com/vibe-coding/every-ai-tool-has-plan-mode-none-of-them-do-it-right-6bd540155690 | Plan mode vs Superpowers brainstorming |
+| 19 | https://dev.to/tumf/superpowers-the-technology-to-persuade-ai-agents-why-psychological-principles-change-code-quality-2d2f | Psychological principles in AI instructions |