forgedock 1.1.5 → 1.1.7

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="https://avatars.githubusercontent.com/in/3731547?s=200&u=b38eba537e011502c010d4b682d641f802591845&v=4" alt="ForgeDock" width="80" />
+<img src="https://avatars.githubusercontent.com/in/4051319?s=200&v=4" alt="ForgeDock" width="80" />
 
 <h1>ForgeDock</h1>
 
@@ -227,6 +227,8 @@ npx forgedock --global # global install: installs into ~/.claude/commands/ — a
 
 **Project-scoped is the default.** `npx forgedock` installs commands scoped to the current project directory. Use `--global` only when you want the commands available across all your projects on this machine.
 
+> **Want engine-mode dispatch?** `npx forgedock` is transient — the `forgedock` binary isn't persisted in PATH after install. `/orchestrate` and `/autopilot` use agent dispatch mode by default, which is fully functional. To enable engine-mode dispatch (`forgedock run-issue`) with its durable phase table and fail-closed review gate, run `npm install -g forgedock` instead.
+
 One command does everything: it checks your environment, installs the slash commands into Claude Code, detects your repo (owner, branches, paths), and hands you a single annotated `forge.yaml` to review — press Enter to accept. Run `npx forgedock init` any time afterward to re-generate the config only.
 
 Installing also registers a SessionStart hook, so every Claude Code session

package/bin/journey.mjs

@@ -238,13 +238,40 @@ export function detectDescription(cwd) {
 // Journey context (Task 5)
 // ---------------------------------------------------------------------------
 
-import { execFileSync } from "child_process";
+import { execFileSync, spawnSync } from "child_process";
 import os from "os";
 import {
   renderMark, ember, shimmer, revealRows, moltenBar, fixCard,
   colorMode, motionEnabled, CHROME_STOPS, HERO_MARK, COMPACT_MARK, sleep,
 } from "./cinema.mjs";
 
+// ---------------------------------------------------------------------------
+// URL opener (default openFn implementation — injectable for tests)
+// ---------------------------------------------------------------------------
+
+/**
+ * Open a URL in the system default browser. Best-effort: errors are swallowed
+ * so the caller's journey continues even when no browser is available.
+ *
+ * Platform dispatch:
+ *   Linux   → xdg-open
+ *   macOS   → open
+ *   Windows → start (via shell)
+ */
+export function openUrl(url) {
+  try {
+    if (process.platform === "win32") {
+      spawnSync("cmd", ["/c", "start", "", url], { stdio: "ignore", windowsHide: true });
+    } else if (process.platform === "darwin") {
+      spawnSync("open", [url], { detached: true, stdio: "ignore" });
+    } else {
+      spawnSync("xdg-open", [url], { detached: true, stdio: "ignore" });
+    }
+  } catch {
+    // Best-effort — if the browser can't be opened, the journey continues.
+  }
+}
+
 /**
  * Build the shared journey context. Every act takes this as its first arg.
  * All process-touching values are injectable for tests.
@@ -255,6 +282,7 @@ export function makeCtx(overrides = {}) {
   const argv = overrides.argv ?? process.argv.slice(2);
   const nodeVersion = overrides.nodeVersion ?? process.versions.node;
   const enrichFn = overrides.enrichFn ?? enrich;
+  const openFn = overrides.openFn ?? openUrl;
   return {
     cwd: process.cwd(),
     home: env.HOME || env.USERPROFILE || os.homedir(),
@@ -267,6 +295,7 @@ export function makeCtx(overrides = {}) {
     nodeVersion,
     linkStrategy: "symlink",
     enrichFn,
+    openFn,
     exec: (cmd, args) =>
       execFileSync(cmd, args, {
         encoding: "utf-8",
@@ -755,7 +784,7 @@ export async function forge(ctx) {
 
 import { detectConfig } from "./init-detect.mjs";
 import { enrich } from "./init-enrich-api.mjs";
-import { annotatedReviewScreen, box } from "./tui.mjs";
+import { annotatedReviewScreen, box, confirm } from "./tui.mjs";
 
 const badgeOf = (field) => field.confidence;
 
@@ -872,10 +901,11 @@ export function celebrate(ctx, summary) {
   w.write(
     box(
       [
-        `  1. run npx forgedock labels setup — bootstrap GitHub labels`,
-        `  2. run npx forgedock doctor     — verify the install is green`,
-        `  3. open claude in this repo`,
-        `  4. run /issue <title> then /work-on <number>`,
+        `  1. install GitHub App       — github.com/apps/rapiercraft-forgedock`,
+        `  2. run npx forgedock labels setup — bootstrap GitHub labels`,
+        `  3. run npx forgedock doctor     — verify the install is green`,
+        `  4. open claude in this repo`,
+        `  5. run /issue <title> then /work-on <number>`,
       ],
       { title: "what's next" },
     ),
@@ -883,6 +913,45 @@ export function celebrate(ctx, summary) {
   w.write("  " + dimLine(ctx, "docs: github.com/RapierCraftStudios/ForgeDock · ⭐ a star is the whole marketing budget") + "\n\n");
 }
 
+// ---------------------------------------------------------------------------
+// Act V.5 — Connect: GitHub App install prompt (Issue #1719)
+// ---------------------------------------------------------------------------
+
+const GITHUB_APP_URL = "https://github.com/apps/rapiercraft-forgedock/installations/new";
+
+/**
+ * Act V.5: prompt the user to install the ForgeDock GitHub App on their
+ * account. Non-blocking — declining or non-interactive mode both continue
+ * the journey without error.
+ *
+ * Uses ctx.openFn (injectable for tests) to open the URL in the default
+ * browser. In non-TTY environments (piped stdin, --fast) confirm() resolves
+ * immediately to false (the defaultValue), so no prompt is shown.
+ *
+ * @returns {Promise<{ opened: boolean }>}
+ */
+export async function connect(ctx) {
+  const { stdout: w } = ctx;
+  w.write("\n  " + ember("Connect to GitHub", ctx.mode) + "\n\n");
+
+  const yes = await confirm(
+    "Install the ForgeDock GitHub App for automatic pipeline triggers?",
+    false,
+  );
+
+  if (yes) {
+    ctx.openFn(GITHUB_APP_URL);
+    w.write(
+      `  \x1b[38;2;255;179;71m✔\x1b[0m Opening ${GITHUB_APP_URL}\n` +
+      `  ${ctx.mode === "none" ? "" : "\x1b[2m"}Install account-wide (all repositories) to enable webhook triggers.\x1b[22m\n`,
+    );
+    return { opened: true };
+  }
+
+  w.write(`  ${ctx.mode === "none" ? "" : "\x1b[2m"}Skipped — install anytime: ${GITHUB_APP_URL}\x1b[22m\n`);
+  return { opened: false };
+}
+
 // ---------------------------------------------------------------------------
 // The full journey (Task 8)
 // ---------------------------------------------------------------------------
@@ -902,7 +971,8 @@ export async function runJourney(ctx) {
     const forged = await forge(ctx);
     const { draft, description } = await read(ctx);
     const reviewed = await review(ctx, draft, description);
-    celebrate(ctx, { ...reviewed, total: forged.total, hookStatus: forged.hookStatus });
+    const connected = await connect(ctx);
+    celebrate(ctx, { ...reviewed, ...connected, total: forged.total, hookStatus: forged.hookStatus });
     return reviewed.aborted ? 1 : 0;
   } finally {
     process.removeListener("SIGINT", onSigint);

package/commands/autopilot.md

@@ -387,12 +387,47 @@ while true; do
     break
   fi
 
-  # Step 1: Orchestrate all open fast-lane issues in parallel via /orchestrate
-  echo "=== Fast Lane Iteration $FAST_LANE_ITERATIONS: Orchestrating $OPEN_UNMILESTONED issues ==="
+  # Step 1: Drive all open fast-lane issues through the durable engine.
+  # Each issue is dispatched individually via `forgedock run-issue` so the engine's
+  # phase table (fail-closed review gate, deterministic resume, lease-based concurrency)
+  # enforces every transition — not the LLM interpreting work-on.md.
+  # Fallback: if forgedock CLI is unavailable, delegate to /orchestrate (markdown-spec path).
+  echo "=== Fast Lane Iteration $FAST_LANE_ITERATIONS: Dispatching $OPEN_UNMILESTONED issues via engine ==="
+
+  FORGEDOCK_AVAILABLE=$(command -v forgedock >/dev/null 2>&1 && echo "true" || echo "false")
+
   if [ "$DRY_RUN" = "false" ]; then
-    Skill("orchestrate", args="fast-lane")
+    if [ "$FORGEDOCK_AVAILABLE" = "true" ]; then
+      # Engine-first dispatch: enumerate issues and run each through the durable engine.
+      # Issues are dispatched concurrently — the engine holds per-issue leases.
+      FAST_LANE_ISSUE_NUMS=$(gh issue list $GH_FLAG \
+        --state open \
+        --limit 200 \
+        --json number,milestone,labels \
+        --jq '[.[] | select(
+          .milestone == null and
+          (.labels | map(.name) | any(. == "workflow:merged" or . == "workflow:invalid" or . == "workflow:decomposed" or . == "needs-human") | not)
+        )] | .[].number' \
+        2>/dev/null || echo '')
+
+      for ISSUE_NUM in $FAST_LANE_ISSUE_NUMS; do
+        echo "Dispatching #$ISSUE_NUM via forgedock run-issue --lane staging"
+        forgedock run-issue "$ISSUE_NUM" --lane staging &
+      done
+
+      # Wait for all engine workers to complete before proceeding to deploy step.
+      wait
+      echo "Engine dispatch complete for fast-lane iteration $FAST_LANE_ITERATIONS"
+    else
+      echo "INFO: Using agent dispatch mode (forgedock CLI not in PATH — run \`npm install -g forgedock\` for engine-mode dispatch)"
+      Skill("orchestrate", args="fast-lane")
+    fi
   else
-    echo "[DRY-RUN] Would invoke: Skill(orchestrate, fast-lane)"
+    if [ "$FORGEDOCK_AVAILABLE" = "true" ]; then
+      echo "[DRY-RUN] Would dispatch each fast-lane issue via: forgedock run-issue <issue> --lane staging"
+    else
+      echo "[DRY-RUN] Would invoke: Skill(orchestrate, fast-lane)"
+    fi
   fi
 
   # Step 2: Deploy staging→main if staging has new commits
@@ -481,12 +516,43 @@ echo "$MILESTONES" | jq -c '.[]' | while IFS= read -r milestone; do
 
   echo "=== Processing milestone: '$MS_TITLE' ($MS_PCT% complete, $MS_OPEN open) ==="
 
-  # Step 1: Orchestrate open issues in this milestone
+  # Step 1: Drive open issues in this milestone through the durable engine.
+  # Same engine-first dispatch as Phase 2 — fail-closed gates apply to milestone issues too.
+  # Fallback: if forgedock CLI is unavailable, delegate to /orchestrate.
   if [ "$MS_OPEN" -gt 0 ]; then
+    FORGEDOCK_AVAILABLE=$(command -v forgedock >/dev/null 2>&1 && echo "true" || echo "false")
+
     if [ "$DRY_RUN" = "false" ]; then
-      Skill("orchestrate", args="milestone $MS_SLUG")
+      if [ "$FORGEDOCK_AVAILABLE" = "true" ]; then
+        MS_ISSUE_NUMS=$(gh issue list $GH_FLAG \
+          --state open \
+          --limit 200 \
+          --json number,milestone,labels \
+          --jq --arg slug "$MS_SLUG" \
+          '[.[] | select(
+            .milestone != null and
+            (.milestone.title | ascii_downcase | gsub("[^a-z0-9]+"; "-") | ltrimstr("-") | rtrimstr("-")) == $slug and
+            (.labels | map(.name) | any(. == "workflow:merged" or . == "workflow:invalid" or . == "workflow:decomposed" or . == "needs-human") | not)
+          )] | .[].number' \
+          2>/dev/null || echo '')
+
+        for ISSUE_NUM in $MS_ISSUE_NUMS; do
+          echo "Dispatching #$ISSUE_NUM via forgedock run-issue --lane milestone/$MS_SLUG"
+          forgedock run-issue "$ISSUE_NUM" --lane "milestone/$MS_SLUG" &
+        done
+
+        wait
+        echo "Engine dispatch complete for milestone '$MS_TITLE'"
+      else
+        echo "INFO: Using agent dispatch mode (forgedock CLI not in PATH — run \`npm install -g forgedock\` for engine-mode dispatch)"
+        Skill("orchestrate", args="milestone $MS_SLUG")
+      fi
     else
-      echo "[DRY-RUN] Would invoke: Skill(orchestrate, milestone $MS_SLUG)"
+      if [ "$FORGEDOCK_AVAILABLE" = "true" ]; then
+        echo "[DRY-RUN] Would dispatch each milestone issue via: forgedock run-issue <issue> --lane milestone/$MS_SLUG"
+      else
+        echo "[DRY-RUN] Would invoke: Skill(orchestrate, milestone $MS_SLUG)"
+      fi
     fi
   else
     echo "Milestone '$MS_TITLE' has no open issues — checking if branch needs deploy"

package/commands/deploy-pr.md

@@ -392,8 +392,11 @@ while [ "$REVIEW_ITER" -lt "$MAX_REVIEW_ITER" ] && [ "$REVIEW_GATE_PASSED" = "fa
       # This loop's next iteration will re-read the latest PR state.
     fi
   else
-    echo "WARNING: Could not determine review verdict from FORGE:REVIEW comment. Assuming APPROVED."
-    REVIEW_GATE_PASSED=true
+    # Fail-closed: unknown verdict must block merge, not grant it.
+    # If FORGE:REVIEW comment is missing, malformed, or unparseable for any reason
+    # (race condition, context compaction, skill error, comment format mismatch),
+    # treat it as a failed review — REVIEW_GATE_PASSED remains false.
+    echo "ERROR: Could not determine review verdict from FORGE:REVIEW comment. Blocking merge — review verdict is required. (#1714)"
   fi
 done
 

package/commands/orchestrate/phase-3-dependency.md

@@ -443,15 +443,19 @@ Proceed? (yes / adjust / pick specific issues)
 
 ---
 
-## Engine mode (headless)
+## Engine mode (default)
 
-When running headless/CI, dispatch each issue via the durable execution engine instead of spawning prose agents:
+Dispatch each issue via the durable execution engine. This is the **default execution mode** for both interactive (`/autopilot`, `/orchestrate`) and headless/CI paths:
 
 ```bash
 forgedock run-issue <issue> --lane <staging|milestone/slug>
 ```
 
-The engine drives every phase transition deterministically, mirrors state to the `FORGE:STATE` block on the issue, and holds a lease. To recover stalls, scan in-flight issues' `FORGE:STATE`; any issue with an expired lease and a non-terminal state is re-dispatched with the same `forgedock run-issue <issue>` command — it resumes from the last committed phase (idempotent). This replaces the label-heuristic "already in progress" check and the resume-with-nagging loop.
+The engine drives every phase transition deterministically, mirrors state to the `FORGE:STATE` block on the issue, and holds a lease. Its **fail-closed review gate** (`phases.mjs → detectOutcome`) means the PR must be confirmed merged before the phase is committed — missing or unparseable review comments are treated as failures, not approvals. To recover stalls, scan in-flight issues' `FORGE:STATE`; any issue with an expired lease and a non-terminal state is re-dispatched with the same `forgedock run-issue <issue>` command — it resumes from the last committed phase (idempotent). This replaces the label-heuristic "already in progress" check and the resume-with-nagging loop.
+
+**Why engine-first**: The engine's phase table enforces gate semantics in code — not via LLM interpretation of markdown specs. This eliminates the class of bug where the LLM assumes a review approved when the FORGE:REVIEW comment is absent or unreadable (issue #1714). Interactive sessions that run `/work-on` via Skill invocations additionally bridge to the engine run-log via the SubagentStop hook (`bin/hooks/interactive-engine.mjs`) — state is durable across compaction and context resets.
+
+**Fallback (no forgedock CLI)**: If `forgedock` is not in PATH, fall back to spawning Agent sub-agents that run `Skill("work-on", ...)` per issue. The SubagentStop hook still bridges these runs to the engine run-log for state persistence.
 
 ### Concurrency model: in-process worker pool + worktree-per-issue
 

package/commands/orchestrate/phase-4-execution.md

@@ -171,7 +171,31 @@ Use `${ISSUE_LANE[$NUM]}` and `${ISSUE_PR_BASE[$NUM]}` to populate `{LANE}` and
 
 ### Step 4A: Dispatch ready issues
 
-**REMINDER: You MUST use the template below verbatim. Only fill in `{VARIABLES}`. Do NOT rewrite the agent prompt. Do NOT write custom implementation instructions. The agent MUST invoke `/work-on` via the Skill tool — this is the HARD RULE from the top of this file.**
+**Engine-first dispatch (default)**: When `forgedock` is in PATH, dispatch each ready issue via the durable engine rather than spawning prose Agent sub-agents. The engine's phase table enforces gate semantics in code — its fail-closed review gate and deterministic phase ordering are not subject to LLM interpretation.
+
+```bash
+# Engine-first dispatch: check CLI availability, then dispatch ready issues in parallel
+FORGEDOCK_AVAILABLE=$(command -v forgedock >/dev/null 2>&1 && echo "true" || echo "false")
+
+if [ "$FORGEDOCK_AVAILABLE" = "true" ]; then
+  for NUM in {ready_issue_numbers}; do
+    LANE="${ISSUE_LANE[$NUM]}"
+    PR_BASE="${ISSUE_PR_BASE[$NUM]}"
+    echo "Dispatching #$NUM via forgedock run-issue --lane $PR_BASE"
+    forgedock run-issue "$NUM" --lane "$PR_BASE" &
+  done
+  wait
+  echo "Engine dispatch complete — advancing to Step 4B (completion sweep)"
+else
+  echo "INFO: Using agent dispatch mode (forgedock CLI not in PATH — run \`npm install -g forgedock\` for engine-mode dispatch)"
+  # Fall through to Agent-spawn template below. The SubagentStop hook (bin/hooks/interactive-engine.mjs)
+  # bridges these runs to the engine run-log for state persistence even on the fallback path.
+fi
+```
+
+**Agent-spawn path (fallback when forgedock CLI unavailable)**: When `FORGEDOCK_AVAILABLE=false`, spawn Agent sub-agents per issue using the template below. This preserves engine state via the SubagentStop hook even without the CLI.
+
+**REMINDER: You MUST use the template below verbatim when on the Agent-spawn fallback path. Only fill in `{VARIABLES}`. Do NOT rewrite the agent prompt. Do NOT write custom implementation instructions. The agent MUST invoke `/work-on` via the Skill tool — this is the HARD RULE from the top of this file.**
 
 For each **ready** issue (all predecessors resolved or no predecessors), spawn an Agent sub-agent that runs the full `/work-on` pipeline. On the initial dispatch, this is every issue with an empty predecessor set. On subsequent dispatches (triggered by agent completions in Step 4B), this is every newly-unblocked issue.
 

package/docs/design/awesome-list-submissions.md

@@ -0,0 +1,105 @@
+# Awesome List Submission Drafts
+
+Important: Have a contributor or community member submit these, not the repo owner's account. Many lists reject self-submissions.
+
+---
+
+## 1. hesreallyhim/awesome-claude-code (36.8K stars) — TOP PRIORITY
+
+### PR Title
+```
+Add ForgeDock — autonomous pipeline commands for Claude Code
+```
+
+### Entry (add under "Workflow & Automation" or "Agent Frameworks" section)
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Structured autonomous development pipeline that adds investigate-build-review-merge workflow to Claude Code. Features 9-agent specialist PR review, 14-domain quality gate, and GitHub-native persistent memory via FORGE annotations. `npx forgedock`
+```
+
+### PR Description
+
+```markdown
+Adding ForgeDock, an open-source (AGPL) tool that adds structured pipeline commands to Claude Code.
+
+**What it does**: Turns Claude Code from a stateless chatbot into a multi-stage development pipeline. Each stage (investigate, build, review, merge) posts machine-readable annotations to GitHub issues/PRs, so agents reconstruct full context after compaction.
+
+**Key features**:
+- 20+ slash commands including `/work-on` (full pipeline), `/orchestrate` (parallel multi-issue), `/autopilot` (self-improvement cycle)
+- 9-agent specialist PR review (security, database, auth, concurrency, etc.)
+- 14-domain quality gate
+- GitHub labels as workflow state machine
+- `forge.yaml` per-repo configuration
+
+**Install**: `npx forgedock`
+
+**Why it belongs here**: It's the most comprehensive pipeline orchestration system in the Claude Code ecosystem — 35 command files totaling 800KB+ of structured prompt engineering.
+```
+
+---
+
+## 2. rohitg00/awesome-claude-code-toolkit
+
+### Entry
+
+```markdown
+### Pipeline Orchestration
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Full SDLC pipeline for Claude Code: investigate → build → review → merge. 9-agent review, quality gate, GitHub-native memory via FORGE annotations. `npx forgedock`
+```
+
+---
+
+## 3. travisvn/awesome-claude-skills
+
+### Entry
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - 20+ pipeline commands: `/work-on` (full pipeline), `/orchestrate` (parallel issues), `/review-pr` (9-agent review), `/autopilot` (self-improvement), `/quality-gate` (14-domain checks). Uses GitHub as persistent knowledge graph.
+```
+
+---
+
+## 4. ComposioHQ/awesome-claude-skills
+
+### Entry
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Autonomous development pipeline commands for Claude Code. Structured investigate-build-review-merge workflow with GitHub-native memory, multi-agent review, and quality gates.
+```
+
+---
+
+## 5. VoltAgent/awesome-agent-skills
+
+### Entry
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Structured autonomous dev pipeline for Claude Code agents. Uses GitHub Issues/PRs as a knowledge graph with machine-readable FORGE annotations for inter-agent context passing. 35 command specs covering the full SDLC.
+```
+
+---
+
+## 6. Broader awesome lists
+
+### awesome-ai-agents
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Open-source pipeline orchestrator for AI coding agents. Structures investigate → build → review → merge workflow using GitHub as a persistent knowledge graph. Currently supports Claude Code; multi-model planned.
+```
+
+### awesome-developer-tools
+
+```markdown
+- [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) - Autonomous development pipeline that adds structured workflow commands to Claude Code. 9-agent PR review, 14-domain quality gate, GitHub-native memory. `npx forgedock`
+```
+
+---
+
+## Submission Checklist
+
+- [ ] Check each list's CONTRIBUTING.md for formatting requirements
+- [ ] Ensure the entry follows the list's existing style (alphabetical? categorized?)
+- [ ] One PR per list
+- [ ] Submitter should have some GitHub activity (not a brand new account)
+- [ ] Don't submit all on the same day — space them out over 1-2 weeks
+- [ ] Priority order: awesome-claude-code first, then toolkit, then skills lists, then broader lists

package/docs/design/f5bot-monitoring-setup.md

@@ -0,0 +1,43 @@
+# F5Bot Mention Monitoring Setup
+
+F5Bot is a free service that sends email alerts when keywords appear on Reddit, Hacker News, or Lobsters.
+
+## Setup (5 minutes)
+
+1. Go to https://f5bot.com
+2. Create a free account (email only)
+3. Add these keyword alerts:
+
+| Keyword | Why |
+|---------|-----|
+| `forgedock` | Direct mentions |
+| `ForgeDock` | Case-sensitive variant |
+| `forge dock` | Common misspelling |
+| `"claude code commands"` | Users looking for what ForgeDock provides |
+| `"claude code workflow"` | High-intent search phrase |
+| `"autonomous development pipeline"` | Category-level interest |
+| `"FORGE annotation"` | Protocol mentions |
+
+4. Set email notifications to immediate (not digest)
+
+## Response Playbook
+
+When an alert fires:
+
+### Direct mention (someone talking about ForgeDock)
+- Read the full thread context
+- If positive: thank them, offer to help with any questions
+- If a question: answer thoroughly with code examples
+- If criticism: acknowledge, explain the reasoning, ask what they'd improve
+
+### Indirect mention (someone looking for what ForgeDock does)
+- Answer their question genuinely first
+- Mention ForgeDock naturally: "I've been using ForgeDock for this — it structures Claude Code into an investigate-build-review-merge pipeline"
+- Never just drop a link with no context
+
+### Rules
+- Always add genuine value to the conversation
+- Never post in threads where it would feel forced
+- On Reddit: post manually (never automate — ban risk)
+- On HN: only comment if you have genuine insight to add
+- Wait at least 10 minutes after the alert before responding (don't look like a bot)

package/docs/design/growth-strategy-2026.md

@@ -0,0 +1,579 @@
+# ForgeDock Growth Strategy — June 2026
+
+Comprehensive strategic research covering market positioning, growth flywheel, new features, automated marketing, and fundraising narrative.
+
+---
+
+## Table of Contents
+
+1. [The Opportunity](#1-the-opportunity)
+2. [Competitive Positioning](#2-competitive-positioning)
+3. [The Perpetual Growth Flywheel](#3-the-perpetual-growth-flywheel)
+4. [Free Automated Marketing Playbook](#4-free-automated-marketing-playbook)
+5. [New Features to Build](#5-new-features-to-build)
+6. [Further Automation Opportunities](#6-further-automation-opportunities)
+7. [Website Strategy (forgedock.io)](#7-website-strategy-forgedockio)
+8. [Fundraising Positioning](#8-fundraising-positioning)
+9. [Execution Timeline](#9-execution-timeline)
+
+---
+
+## 1. The Opportunity
+
+### Market Size
+- AI code tools market: **$9.5B in 2026**, growing at 26% CAGR to $30B+ by 2031
+- Enterprise AI coding agents specifically: **$9.8-11.0B annualized** (April 2026)
+- 85% of developers regularly use AI tools; 51% use them daily
+
+### The Core Problem Nobody Has Solved
+**Vibe coding is creating a crisis.** 84% of developers use AI to generate code, but:
+- **96% don't trust it** (only 3% "highly trust" AI output)
+- AI-coauthored code has **2.74x higher vulnerability rates**
+- **41% increase in bug rates** after Copilot adoption (Uplevel study, ~800 devs)
+- 63% spend MORE time debugging AI code than writing it manually would take
+- Refactoring dropped 60% (from 25% to 10% of changes)
+- Context loss is the **#1 pain point** — developers lose 12 min/morning re-explaining to AI
+
+**The market is screaming for structured AI development — not more code generation.**
+
+### ForgeDock's Unique Position
+ForgeDock is the **only tool** that:
+1. Uses **GitHub itself as a structured knowledge graph** (not an external DB)
+2. Provides a **multi-stage pipeline** (investigate > build > review > merge) with machine-readable contracts between stages
+3. Runs **locally with your own API key** (not a $500/month cloud service)
+4. Is **free and open-source** (AGPL)
+5. Survives context compaction — agents reconstruct full state from GitHub alone
+
+No competitor — not Devin ($26B valuation), not Copilot (4.7M subscribers), not Cursor ($4B ARR) — does structured pipeline orchestration with persistent GitHub-native memory.
+
+---
+
+## 2. Competitive Positioning
+
+### The Landscape
+
+| Tool | What It Is | Price | Stars | Gap ForgeDock Fills |
+|------|-----------|-------|-------|-------------------|
+| **Devin** | Autonomous cloud agent | $20-500+/mo | Private | Opaque, expensive, no structured pipeline |
+| **Cursor** | AI IDE | $20/mo | Private | Daily-driver IDE, not a pipeline orchestrator |
+| **GitHub Copilot** | AI assistant + Coding Agent | $10-19/mo | Private | Single-issue automation, no cross-issue memory |
+| **Kiro (AWS)** | Spec-driven IDE | TBD | Private | Specs before code, but no GitHub knowledge graph |
+| **OpenHands** | OSS autonomous agent | Free | 68K | Research-focused, no production pipeline |
+| **Aider** | Terminal AI agent | Free | 41K | Code generation only, no workflow orchestration |
+| **Claude Code (raw)** | CLI agent | API costs | N/A | Stateless, no pipeline, no persistence |
+
+### ForgeDock's Positioning Statement
+
+> **"ForgeDock turns Claude Code from a chatbot into a deterministic engineering pipeline."**
+
+Alternative framings by audience:
+- **For non-coders**: "Ship production software with AI — without knowing how to code"
+- **For developers**: "Structured autonomous development that doesn't create tech debt"
+- **For enterprises**: "Traceable, auditable AI development with GitHub-native compliance"
+- **For investors**: "The engineering process layer for the AI-native SDLC"
+
+### Category Creation: "Context Engineering for the SDLC"
+
+"Context engineering" is now a recognized discipline (Gartner published on it; Karpathy coined it). ForgeDock IS a context engineering tool — it structures what agents need to know at each pipeline stage via FORGE: annotations. Position ForgeDock as the **context engineering platform for software development**, not just "Claude Code commands."
+
+---
+
+## 3. The Perpetual Growth Flywheel
+
+The goal: mechanisms that compound automatically with zero ongoing effort.
+
+### Flywheel 1: FORGE Annotations as Passive Advertising
+
+Every ForgeDock run posts FORGE: annotations to GitHub issues/PRs. This is a **built-in viral loop** that scales with adoption.
+
+**Action**: Add a subtle footer to every FORGE: annotation:
+```
+> Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)
+```
+
+This is exactly how Dependabot, Renovate, and Codecov built massive organic reach — every PR they touched linked back. Make it opt-out via `forge.yaml`:
+```yaml
+branding:
+  show_attribution: true  # default
+```
+
+**Impact**: Every public repo using ForgeDock becomes a permanent billboard. Passive, perpetual, scales linearly with adoption.
+
+### Flywheel 2: Auto-Published Content Pipeline
+
+Set up a GitHub Actions workflow that:
+1. Watches for new markdown files in a `content/` directory
+2. Claude Code generates articles (tutorials, tips, comparisons)
+3. Auto-publishes to dev.to and Hashnode via their APIs
+4. Each article links back to the GitHub repo
+
+**Both platforms have REST APIs that support fully automated publishing:**
+- dev.to: `POST https://dev.to/api/articles` with `api-key` header
+- Hashnode: GraphQL API with Personal Access Token
+
+**Cadence**: 1-2 articles/week, auto-published. Topics that drive stars:
+- "How I built an autonomous PR pipeline with Claude Code"
+- "ForgeDock vs raw Claude Code: 9 review agents vs copy-paste"
+- "Why 96% of developers don't trust AI code (and how to fix it)"
+
+### Flywheel 3: Awesome List Presence
+
+**The single highest-leverage free action**: Get listed on `hesreallyhim/awesome-claude-code` (36.8K stars). Every follower of that repo is a direct target user.
+
+Other lists to target (20+ total):
+- `travisvn/awesome-claude-skills`
+- `rohitg00/awesome-claude-code-toolkit`
+- `ComposioHQ/awesome-claude-skills`
+- `VoltAgent/awesome-agent-skills`
+- `webfuse-com/awesome-claude`
+- `awesome-llm-tools`, `awesome-ai-agents`, `awesome-developer-tools`
+
+**Important**: Many lists reject self-submissions. Have a community member or contributor submit. Claude Code can draft the PR text.
+
+### Flywheel 4: Anthropic Official Plugin Marketplace
+
+Submit ForgeDock to `anthropics/claude-plugins-official`. Getting the **"Anthropic Verified" badge** drives organic installs via Claude Code's built-in `/plugin install` command.
+
+This requires packaging with a `.claude-plugin/plugin.json` structure. One-time effort, potentially very high long-term impact.
+
+### Flywheel 5: "Built with ForgeDock" Badges
+
+Create a shields.io badge users can add to their repos:
+```markdown
+[![Built with ForgeDock](https://img.shields.io/badge/pipeline-ForgeDock-blue)](https://github.com/RapierCraftStudios/ForgeDock)
+```
+
+Shields.io serves 1.6B images/month. Every badge is a backlink and exposure point.
+
+### Flywheel 6: GitHub SEO
+
+Immediate, zero-effort optimizations:
+- **GitHub Topics**: `claude-code`, `claude`, `ai-agents`, `developer-tools`, `autonomous-coding`, `cli`, `npm`, `pipeline`, `code-review`, `github-workflow`, `anthropic`, `slash-commands`, `agentic-ai`
+- **npm keywords**: Same list in `package.json`
+- **README**: One-line value prop at top, `npx forgedock` visible without scrolling, animated GIF demo, comparison table
+
+---
+
+## 4. Free Automated Marketing Playbook
+
+### What Claude Code Can Fully Automate (Zero Human Involvement)
+
+| Action | How | Frequency |
+|--------|-----|-----------|
+| dev.to article publishing | GitHub Actions + dev.to API | Weekly |
+| Hashnode cross-posting | GitHub Actions + Hashnode GraphQL API | Weekly |
+| GitHub Discussions tips | GitHub API | Weekly |
+| Comparison page generation | Static site generator + GitHub Pages | Monthly |
+| FORGE annotation branding | Built into command specs | Every run |
+| Release notes / changelog | Generate from git log, post to GitHub | Per release |
+| Badge/shield creation | One-time commit | Once |
+| GitHub Topics + npm keywords | One-time commit | Once |
+
+### What Claude Code Can Draft (Human Posts)
+
+| Action | Why Human Required | Frequency |
+|--------|-------------------|-----------|
+| Hacker News Show HN | HN requires karma/age; authenticity matters | 2-3x total |
+| Product Hunt launch | Requires coordinated community support | 1x |
+| Awesome list PRs | Self-submission rejected by many lists | 10-20x total |
+| Reddit answers | API crackdown; ban risk for automation | As opportunities arise |
+| Twitter/X posts | Free API tier is read-only; posting costs $100/mo | Weekly |
+| Plugin marketplace submission | Anthropic manual review | 1x |
+
+### The Show HN Strategy
+
+**This is the single highest-impact launch event.** Data:
+- Successful Show HN posts generate **5,000-50,000 visitors in 48 hours**
+- Conversion: ~**1.4 GitHub stars per upvote**
+- Optimal: Tuesday-Thursday, 9AM-12PM ET
+
+**Format**: `Show HN: ForgeDock -- Structured autonomous pipeline for Claude Code (open source)`
+
+**Rules**:
+- NO superlatives, NO marketing language
+- Post a maker comment immediately: what you built, why, technical decisions, one known limitation
+- Respond to every comment in the first 60 minutes
+- HN allows re-posts after significant updates — plan 2-3 over time
+
+### The Product Hunt Strategy
+
+- Wait until you have ~500 stars (credibility baseline)
+- Tuesday-Thursday launch, 12:01 AM PST
+- Prepare supporters in advance
+- "Product of the Day" badge is permanent social proof
+
+### Content That Drives Stars
+
+Based on research, these formats convert best:
+1. **Problem-first tutorials** ("How I stopped wasting tokens on AI re-discovery")
+2. **Comparison posts** ("ForgeDock vs raw Claude Code: structured pipeline vs YOLO")
+3. **"Show your work" demos** (terminal recordings, output examples)
+4. **Controversy/hot-take** ("Why vibe coding will bankrupt your startup")
+5. **Data-driven posts** ("We measured: 2,100 tokens saved per session with adaptive scripts")
+
+### Monitoring and Response
+
+- **F5Bot** (free, self-hostable): Email alerts when "ForgeDock", "Claude Code commands", or "autonomous development pipeline" appears on Reddit, HN, or Lobsters
+- Claude Code drafts replies; human reviews and posts
+- Estimated: 30 min/week human time
+
+### Channels to AVOID
+
+- **Reddit automated posting**: Nov 2025 crackdown banned ~70% of automated accounts. Manual only.
+- **r/programming**: Banned all LLM content since April 2026
+- **Medium**: No publishing API anymore. Not automatable.
+- **Thin SEO pages**: Google penalizes pages under 500 words with minimal unique content
+
+---
+
+## 5. New Features to Build
+
+Prioritized by impact on growth and differentiation.
+
+### P0: Features That Drive Adoption
+
+**1. FORGE Annotation Attribution Footer**
+- Add `> Pipeline powered by [ForgeDock](...)` to every annotation
+- Opt-out via `forge.yaml`
+- Impact: Passive viral loop scaling with every user
+- Effort: 1-2 hours
+
+**2. Claude Code Plugin Marketplace Packaging**
+- Package ForgeDock in `.claude-plugin/` format
+- Submit to `anthropics/claude-plugins-official`
+- Impact: In-product discovery for all Claude Code users
+- Effort: 1-2 days
+
+**3. `forgedock-init` Wizard Improvements**
+- Zero-config first run: detect stack, generate `forge.yaml`, run first issue
+- "Time to value under 60 seconds" is the 2026 standard
+- Impact: Reduces drop-off at install
+- Effort: 1-2 days
+
+**4. Shareable Pipeline Reports**
+- After each `/work-on` run, generate a shareable HTML/markdown report
+- Pipeline timeline, agent decisions, token usage, review findings
+- Users share these on Twitter/Discord = free marketing
+- Impact: Creates tweet-sized "wow moments"
+- Effort: 2-3 days
+
+### P1: Features That Deepen Retention
+
+**5. Scripts Layer (already planned, #651)**
+- Deterministic execution for routing, labels, branch names, PR targets
+- Eliminates the #1 reliability complaint (agent hallucination on deterministic ops)
+- Impact: Core reliability improvement; retention driver
+- Effort: In progress
+
+**6. Per-Repo Adaptive Scripts (already planned, #653)**
+- Cached operational knowledge per repo
+- 2,100 tokens/session saved; primary value is reliability
+- Impact: Projects that use ForgeDock for a week become locked in
+- Effort: In progress
+
+**7. Multi-Model Support**
+- Currently Claude Code only. Add support for Codex CLI, Cursor Agent, Aider
+- 62% of enterprises use 2-3 AI coding tools simultaneously
+- FORGE annotations are model-agnostic — the protocol works with any agent
+- Impact: Expands TAM dramatically
+- Effort: 1-2 weeks per integration
+
+**8. FORGE Annotation Protocol as Open Standard**
+- Publish a formal spec: `docs/forge-annotation-protocol.md`
+- Position as an open protocol any tool can adopt
+- If other tools emit/consume FORGE annotations, ForgeDock becomes the ecosystem hub
+- Impact: Category-creating move; attracts contributors
+- Effort: 1 week
+
+### P2: Features That Enable Monetization
+
+**9. Observability Dashboard (Platform L1)**
+- Read-only web dashboard rendering the GitHub knowledge graph
+- Pipeline runs, timelines, stall detection, throughput, cycle time, cost-per-issue
+- Host on forgedock.io (free tier: public repos; paid: private repos)
+- Impact: First commercial product; visual "proof" for stakeholders
+- Effort: 2-4 weeks
+
+**10. GitHub App / Webhook Bot (Platform L2)**
+- Always-on backend that triggers pipeline runs automatically
+- Assign an issue > pipeline runs > PR appears
+- BYO API key, multi-tenant credential isolation
+- Impact: "Always-on ForgeDock" — the thing enterprises will pay for
+- Effort: 4-8 weeks
+
+**11. Hosted Execution Sandboxes (Platform L3)**
+- Pipeline execution on isolated ephemeral compute (E2B or similar)
+- No local setup required
+- Impact: Opens the non-technical user market completely
+- Effort: 4-8 weeks
+
+---
+
+## 6. Further Automation Opportunities
+
+### Things ForgeDock Can Automate That Nobody Else Does
+
+**1. Autonomous Repo Health Monitoring**
+- `/autopilot` already does recon > triage > fix cycles
+- Extend to run on a cron via GitHub Actions: daily health checks, auto-create issues for regressions
+- Position: "Your repo gets better while you sleep"
+
+**2. Automated Dependency Upgrades with Full Pipeline**
+- Detect outdated deps > create issue > `/work-on` runs investigate > build > review > merge
+- Devin charges $20+/mo for this; ForgeDock can do it free with your own API key
+
+**3. Automated Documentation Generation**
+- After each merged PR, auto-update docs based on code changes
+- FORGE:TRAJECTORY annotations provide the "why" for every change
+
+**4. Automated Security Scanning Pipeline**
+- `/security-audit` already exists
+- Chain with `/work-on` to auto-fix findings
+- Enterprise compliance teams would pay for this
+
+**5. PR-as-CI: Review Pipeline Triggered by GitHub Actions**
+- GitHub Actions workflow that runs `/review-pr` on every opened PR
+- Like Copilot Coding Agent, but with ForgeDock's 9-agent review depth
+- This is exactly what Continue.dev pivoted toward ("Continuous AI")
+
+**6. Automated Onboarding for New Contributors**
+- When someone opens their first PR, ForgeDock auto-reviews with extra context
+- Posts a welcome comment with repo conventions extracted from `forge.yaml`
+- Builds community goodwill
+
+**7. Cross-Repo Orchestration**
+- `/orchestrate` already supports multi-repo via `forge.yaml > repos.satellites`
+- Extend: changes in repo A auto-trigger pipeline runs in dependent repos B, C
+- Monorepo alternative without the monorepo
+
+---
+
+## 7. Website Strategy (forgedock.io)
+
+### Hosting: Cloudflare Pages (Free)
+
+- Zero cost, unlimited bandwidth, global CDN
+- Auto-deploy from GitHub repo
+- Custom domain (forgedock.io) with free SSL
+- Alternative: GitHub Pages (also free, slightly less flexible)
+
+### Pages to Build
+
+All can be generated by Claude Code and auto-deployed:
+
+| Page | Purpose | Target Query |
+|------|---------|-------------|
+| `/` | Landing page with value prop + install command | "forgedock" |
+| `/docs` | Quick-start guide, command reference | "forgedock docs" |
+| `/vs/devin` | Comparison: free+local vs $500/mo+cloud | "devin alternative open source" |
+| `/vs/claude-code` | Before/after: raw Claude Code vs ForgeDock | "claude code workflow commands" |
+| `/vs/copilot-workspace` | Comparison with GitHub Copilot | "copilot workspace alternative" |
+| `/vs/cursor` | IDE vs pipeline positioning | "cursor alternative" |
+| `/blog` | Auto-published articles (same content as dev.to) | Long-tail SEO |
+| `/protocol` | FORGE Annotation Protocol spec | "AI agent context passing protocol" |
+
+### Landing Page Must-Haves
+
+1. One-sentence value prop above the fold
+2. `npx forgedock` install command (copyable)
+3. Animated terminal GIF showing a full `/work-on` run
+4. "How it works" 3-step diagram (Issue > Pipeline > Merged PR)
+5. Comparison table (ForgeDock vs Devin vs raw Claude Code)
+6. GitHub star count badge (social proof)
+7. Link to GitHub repo (drives stars)
+
+### SEO Strategy
+
+- Each comparison page targets a high-intent search query
+- Canonical URLs on the site; cross-post to dev.to/Hashnode with canonical pointing back
+- Expected timeline: indexed in 2-4 weeks, organic traffic in 3-6 months
+- All content generated by Claude Code, committed to repo, auto-deployed
+
+---
+
+## 8. Fundraising Positioning
+
+### The Narrative
+
+> **ForgeDock is the engineering process layer for the AI-native SDLC.**
+>
+> Every developer tool in the $9.5B AI coding market helps write code faster. None of them structure HOW that code gets from idea to production. ForgeDock is the missing layer: a deterministic pipeline that turns autonomous AI agents into reliable engineering teams.
+>
+> We use GitHub — where 180M developers already work — as the knowledge graph. No new infrastructure. No vendor lock-in. No $500/month cloud service. Just structured, traceable, auditable AI development.
+
+### Key Metrics to Build Toward
+
+Based on what investors look for in 2026:
+
+| Metric | Target | Why It Matters |
+|--------|--------|---------------|
+| GitHub stars | 1K, then 10K | Social proof; HN front page threshold |
+| npm weekly downloads | 1K+ | Usage signal |
+| Active repos using ForgeDock | 100+ | Adoption proof |
+| FORGE annotations posted | 10K+ | Pipeline execution volume |
+| Community size (Discord) | 500+ | Engagement signal |
+| dev.to/blog impressions | 50K/month | Awareness funnel |
+| Time to value | <60 seconds | PLG benchmark |
+
+### Investor-Ready Data Points
+
+From research, these are the metrics that move conversations:
+
+- **Market**: $9.5B and growing 26% CAGR
+- **Category gap**: No one does structured pipeline orchestration for AI agents
+- **Architectural moat**: FORGE annotation protocol + GitHub-as-knowledge-graph
+- **Open-core model**: Proven by GitLab ($759M revenue), PostHog ($57.5M ARR), Supabase ($170M ARR)
+- **Platform roadmap**: L1 observability > L2 GitHub App > L3 sandboxed execution
+- **Developer satisfaction**: Track NPS early. Claude Code has 91% CSAT — ForgeDock riding that wave.
+
+### Comparable Valuations (mid-2026)
+
+| Company | Stage | ARR | Valuation | Multiple |
+|---------|-------|-----|-----------|----------|
+| Cursor | Series D | $4B | $29.3B | ~7x |
+| Cognition (Devin) | Series D | $492M | $26B | ~53x |
+| Vercel | Series F | $340M | $9.3B | ~27x |
+| PostHog | Series E | $57.5M | $1.4B | ~24x |
+| Supabase | Series D | $170M | $2B | ~12x |
+
+Pre-seed/seed median pre-money: **$70M** (Q1 2026, up from $30M in Q4 2025).
+
+### Who to Target
+
+**Specialist funds (highest likelihood)**:
+- **Heavybit**: $180M+ across two new funds (July 2025). AI-native infrastructure + dev tools. Portfolio: PagerDuty, Netlify, Snyk.
+- **Craft Ventures**: Active in devtools. Backed PostHog, Sourcegraph.
+
+**Tier-1 generalists with devtools track record**:
+- Accel (Sentry, Snyk, Vercel)
+- Index Ventures (Vercel)
+- Kleiner Perkins (Neon)
+- Founders Fund (Cognition)
+- a16z, Sequoia, Khosla (all active in AI)
+
+### The Open-Core Commercial Pathway
+
+```
+Phase 1 (Now): Free CLI — build adoption, community, stars
+Phase 2 (Post-traction): Observability dashboard (forgedock.io) — freemium
+Phase 3 (Post-funding): GitHub App + hosted API — subscription
+Phase 4 (Scale): Hosted sandboxes + enterprise — usage-based
+```
+
+**Critical rule**: Never move free features to paid. The HashiCorp/OpenTofu disaster is now a reference point in every OSS evaluation. Public pledge: core pipeline commands will always be free and AGPL.
+
+---
+
+## 9. Execution Timeline
+
+### Week 1: Zero-Effort Optimizations (All Automatable)
+
+- [ ] Add GitHub Topics to repo (5 min)
+- [ ] Optimize `package.json` keywords and description (10 min)
+- [ ] Add FORGE annotation attribution footer to command specs (1-2 hours)
+- [ ] Create "Built with ForgeDock" shields.io badge in README (15 min)
+- [ ] Optimize README: one-liner at top, install command visible, comparison table (1 hour)
+
+### Week 2: Content Pipeline Setup
+
+- [ ] Set up GitHub Actions workflow for auto-publishing to dev.to + Hashnode
+- [ ] Generate and publish first 3 articles
+- [ ] Enable GitHub Discussions with seeded Q&A content
+- [ ] Set up F5Bot monitoring for "ForgeDock", "Claude Code commands", "autonomous pipeline"
+
+### Week 3: Ecosystem Submissions
+
+- [ ] Draft and submit PR to `hesreallyhim/awesome-claude-code` (via contributor)
+- [ ] Submit to 9 other awesome lists
+- [ ] Package as Claude Code plugin and submit to Anthropic marketplace
+- [ ] Submit to `claudemarketplaces.com`, `claudefa.st`, `ClaudeLog`
+
+### Week 4: Launch Events
+
+- [ ] Deploy forgedock.io on Cloudflare Pages (landing + comparison pages)
+- [ ] Post Show HN (human submits; Claude Code drafts everything)
+- [ ] Cross-post launch content to dev.to, Hashnode
+- [ ] Create Discord server (if 50+ active GitHub users exist)
+
+### Month 2-3: Feature Development
+
+- [ ] Shareable pipeline reports (viral content generation)
+- [ ] Scripts layer completion (#651)
+- [ ] FORGE Annotation Protocol published as open spec
+- [ ] PR-as-CI: GitHub Actions integration for auto-review
+
+### Month 4-6: Platform Foundation
+
+- [ ] Observability dashboard (Platform L1) on forgedock.io
+- [ ] Multi-model support investigation (Codex CLI, Aider)
+- [ ] Product Hunt launch (with star baseline)
+- [ ] Begin investor conversations with traction data
+
+### Ongoing (Automated, Perpetual)
+
+- Weekly dev.to/Hashnode articles via GitHub Actions
+- Weekly GitHub Discussion tips
+- FORGE annotations with attribution on every pipeline run
+- F5Bot monitoring + drafted replies
+- Monthly comparison page updates on forgedock.io
+
+---
+
+## Key Risks and Mitigations
+
+| Risk | Mitigation |
+|------|-----------|
+| Anthropic changes Claude Code plugin system | FORGE annotations are the moat, not the plugin format. Protocol-level lock-in survives surface changes |
+| Competitor copies the pipeline approach | Depth is the moat: 35 command files, 9 review agents, 14+ quality domains. Years of prompt engineering not easily replicated |
+| GitHub restricts API access for bots | FORGE annotations use standard `gh` CLI, not bot API. Same access as any developer |
+| Reddit/HN community backlash against "AI marketing" | All social posting is human-reviewed. Content is genuinely useful, not promotional |
+| Open-source users never convert to paid | Expected — 90%+ won't pay. The Platform sells to orgs, not individuals. GitLab model: free for ICs, paid for management features |
+| Claude Code itself loses market share | Multi-model support (P1 feature) reduces single-platform risk |
+
+---
+
+## Sources
+
+### Market Data
+- AI code tools market: Mordor Intelligence ($9.5B, 26% CAGR)
+- Cursor: $4B ARR (Sacra, May 2026), $29.3B valuation
+- Devin: $492M ARR run-rate, $26B valuation (CyberNewsCentre, May 2026)
+- Copilot: 4.7M paid subscribers (Panto, Jan 2026)
+- 85% AI adoption: Stack Overflow 2026 Survey
+- 96% don't trust AI code: Stack Overflow 2026 Survey
+- 2.74x vulnerability rate: Taskade/CodeRabbit analysis of 470+ OSS PRs
+- 41% bug increase: Uplevel study (~800 developers)
+
+### Competitor Intelligence
+- Devin pricing/capabilities: devin.ai, VentureBeat, TechTimes
+- Cursor stats: Panto, Sacra, Digital Applied
+- Kiro: kiro.dev, Computer Weekly, AWS Blog
+- OpenHands/Aider/Cline: GitHub repos, OpenSourceAIReview
+- GitHub Copilot Desktop: GitHub Blog (June 17, 2026)
+- GitHub Agentic Workflows: GitHub Blog (June 11, 2026)
+
+### Growth Patterns
+- Show HN star conversion: arxiv.org/html/2511.04453v1
+- Developer tool discovery: Catchyagency (202 OSS developers study)
+- OpenCode growth: abhs.in (160K stars analysis)
+- Zero-budget playbook: Indie Hackers, star-history.com, rzlt.io
+
+### Monetization
+- Open-core models: PostHog blog, GitLab IR, Sacra
+- Seat-based pricing decline: Monetizely, Outrunly
+- Docker pivot: Sacra (Docker PLG case study)
+- Vercel trajectory: Sacra, SaaSt, reo.dev
+
+### VC Landscape
+- Q1 2026 funding: Qubit Capital ($300B global, 61% AI)
+- Heavybit: $180M+ new funds (heavybit.com)
+- Valuation multiples: Qubit Capital, various Sacra reports
+
+### Automated Marketing
+- dev.to API: dev.to documentation
+- Hashnode API: Hashnode documentation
+- Awesome lists: hesreallyhim/awesome-claude-code (36.8K stars)
+- Anthropic plugin marketplace: anthropics/claude-plugins-official
+- FORGE annotation virality: Dependabot/Renovate growth pattern analysis
+- F5Bot monitoring: f5bot.com
+- Shields.io: 1.6B images/month (shields.io GitHub)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Autonomous dev pipeline for Claude Code. GitHub as institutional memory — every issue, PR, and annotation survives context resets and makes the next agent smarter.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/refresh-bot-token.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# scripts/refresh-bot-token.sh — refresh the rapiercraft-forgedock[bot] installation token.
+#
+# Generates a JWT from the app's private key, exchanges it for a 1-hour
+# installation token, and re-auths the gh CLI. Idempotent — safe to run
+# on every session start or from cron.
+#
+# Supports two installations:
+#   RapierCraftStudios (org)  — installation 144998831 (default)
+#   RapierCraft (personal)   — installation 140233364
+#
+# Usage:  scripts/refresh-bot-token.sh [--pem /path/to/key.pem] [--personal]
+#
+# Env:    FORGEDOCK_APP_PEM — path to private key (default: secrets/rapiercraft-forgedock.pem)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+FORGE_HOME="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+APP_ID="4051319"
+ORG_INSTALLATION_ID="144998831"
+PERSONAL_INSTALLATION_ID="140233364"
+DEFAULT_PEM="$FORGE_HOME/secrets/rapiercraft-forgedock.pem"
+
+# --- Parse args ---
+PEM_PATH="${FORGEDOCK_APP_PEM:-$DEFAULT_PEM}"
+INSTALLATION_ID="$ORG_INSTALLATION_ID"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --pem) PEM_PATH="$2"; shift 2 ;;
+    --personal) INSTALLATION_ID="$PERSONAL_INSTALLATION_ID"; shift ;;
+    *) echo "Unknown arg: $1" >&2; exit 1 ;;
+  esac
+done
+
+if [[ ! -f "$PEM_PATH" ]]; then
+  echo "ERROR: Private key not found at $PEM_PATH" >&2
+  echo "  Set FORGEDOCK_APP_PEM or pass --pem /path/to/key.pem" >&2
+  exit 1
+fi
+
+# --- Generate JWT and exchange for installation token ---
+INSTALL_TOKEN=$(node -e "
+var crypto = require('crypto');
+var fs = require('fs');
+var https = require('https');
+var pem = fs.readFileSync(process.argv[1], 'utf8');
+var now = Math.floor(Date.now() / 1000);
+var h = Buffer.from(JSON.stringify({alg:'RS256',typ:'JWT'})).toString('base64url');
+var p = Buffer.from(JSON.stringify({iat:now-60,exp:now+(9*60),iss:process.argv[2]})).toString('base64url');
+var s = crypto.createSign('RSA-SHA256');
+s.update(h+'.'+p);
+var jwt = h+'.'+p+'.'+s.sign(pem,'base64url');
+var opts = {
+  hostname: 'api.github.com',
+  path: '/app/installations/'+process.argv[3]+'/access_tokens',
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer '+jwt,
+    'Accept': 'application/vnd.github+json',
+    'User-Agent': 'forgedock-refresh'
+  }
+};
+var req = https.request(opts, function(res) {
+  var body = '';
+  res.on('data', function(c) { body += c; });
+  res.on('end', function() {
+    var t = JSON.parse(body).token;
+    if (!t) { process.stderr.write('API error: '+body); process.exit(1); }
+    process.stdout.write(t);
+  });
+});
+req.end();
+" "$PEM_PATH" "$APP_ID" "$INSTALLATION_ID")
+
+if [[ -z "$INSTALL_TOKEN" ]]; then
+  echo "ERROR: Failed to obtain installation token" >&2
+  exit 1
+fi
+
+# --- Auth gh CLI ---
+echo "$INSTALL_TOKEN" | gh auth login --with-token 2>/dev/null
+
+# --- Clean up stale old bot if present ---
+if gh auth status 2>&1 | grep -q "rapiercraft-forge\[bot\]"; then
+  gh auth logout -h github.com -u "rapiercraft-forge[bot]" 2>/dev/null || true
+fi
+
+if [[ "$INSTALLATION_ID" == "$ORG_INSTALLATION_ID" ]]; then
+  echo "rapiercraft-forgedock[bot] token refreshed — org (RapierCraftStudios) ~1h"
+else
+  echo "rapiercraft-forgedock[bot] token refreshed — personal (RapierCraft) ~1h"
+fi