forgedock 1.0.10 → 1.0.11

package/docs/launch/reddit-r-claudeai.md

@@ -0,0 +1,83 @@
+# Reddit Post — r/ClaudeAI
+
+## Subreddit Profile
+
+- **Community**: ~200k members, Claude power users, prompt engineers, tool builders
+- **Culture**: Hands-on and practical. People share what they've built, configurations that work, tricks they've found. Receptive to Claude Code content — many are active Claude Code users.
+- **Best post styles**: Show & Tell, tool releases, workflows that improved their setup
+- **Avoid**: Pure self-promotion without substance, vague capability claims, anything that sounds like an ad
+
+---
+
+## Post Title
+
+```
+I built a slash command system that gives Claude Code permanent memory across sessions — open source
+```
+
+---
+
+## Post Body
+
+> **Target length**: ~800–1200 characters (Reddit has a higher threshold but shorter is better)
+> **Tone**: Personal, practical, showing specific mechanisms. Show & Tell format.
+> **URL**: https://github.com/RapierCraftStudios/ForgeDock
+
+---
+
+```
+Claude Code is great. But it forgets everything between sessions. Every new conversation starts blind — even if you've investigated the same codebase a hundred times.
+
+I got tired of re-explaining context, so I built ForgeDock: 25 slash commands that use GitHub as Claude's persistent memory layer.
+
+The way it works: every pipeline stage writes machine-readable HTML annotations to your GitHub issues and PRs. FORGE:INVESTIGATOR traces the root cause and affected files. FORGE:CONTEXT surfaces known pitfalls from closed issues in the same module. FORGE:ARCHITECT produces a typed implementation plan. When Claude Code picks up the task — even days later, even after compaction — it reads these annotations via `gh` CLI and knows everything the previous session learned.
+
+Typical session:
+/work-on #42 → Claude investigates (reads git blame + closed issues) → writes context to GitHub → plans implementation → builds → quality gate → 9-agent PR review → opens PR
+
+No conversation history required. GitHub is the knowledge graph.
+
+install: npx forgedock
+
+I've processed 20,000+ issues across production codebases this way. Happy to answer questions about how the memory protocol works.
+
+[demo GIF — see repo]
+```
+
+---
+
+## Launch Timing
+
+- **Post 1–2 days after the HN Show HN post** to ride HN momentum (HN discussion often spills into Reddit)
+- **Best windows**: Tuesday–Thursday, 10am–2pm PT (r/ClaudeAI peaks mid-morning Pacific)
+- **Pair with**: r/SideProject on the same day or next day (different audience, no overlap)
+
+---
+
+## Engagement Strategy
+
+- Respond to every comment in the first 2 hours
+- Expect: "How is this different from CLAUDE.md?" and "Does it work with [other AI tool]?"
+- Share specific examples when asked — walk through the payment nil-check flow from the README
+- If asked for demo: link to demo GIF from #542 and offer to do a live walkthrough in comments
+- Be specific about limitations: works with Claude Code today, provider-agnostic runtime on roadmap
+
+---
+
+## Pre-Drafted Comment Responses
+
+### "How is this different from CLAUDE.md?"
+
+> CLAUDE.md is static — describes your repo once, globally. FORGE annotations are dynamic and issue-specific. The FORGE:INVESTIGATOR comment on issue #42 contains the exact commit that introduced a specific bug, the affected file list, root cause, and related issues. A future session working on #47 reads that and skips the entire investigation. CLAUDE.md can't accumulate per-issue knowledge that compounds across hundreds of tasks.
+
+### "Does this work with Cursor / Windsurf / other tools?"
+
+> The annotation protocol is model-agnostic — it's just structured content in GitHub comments that any tool reading `gh` output can consume. Claude Code is the supported runtime today (the `/work-on` slash commands are Claude Code primitives). Porting to other runtimes is architecturally straightforward; Claude Code just has the richest slash command support right now.
+
+### "Is this just a bunch of prompts?"
+
+> Yes — 25 markdown files with carefully engineered prompt specs, installed via `npx forgedock`. There's no runtime server, no embeddings, no vector DB. The 'intelligence' is the structured protocol for passing context between stages, not a model. The model is Claude. ForgeDock is the memory and workflow layer.
+
+### "What happens if Claude makes a mistake?"
+
+> Review findings don't block merges — they become new GitHub issues that enter the same pipeline. The 9-agent review step catches most mistakes before they reach the PR stage. Over time, those review findings accumulate as closed issues; the FORGE:CONTEXT phase mines them before the next related build so the same mistake is flagged proactively. The loop is: mistake → finding → issue → fix → future prevention.

package/docs/launch/reddit-r-devops.md

@@ -0,0 +1,80 @@
+# Reddit Post — r/devops
+
+## Subreddit Profile
+
+- **Community**: ~1.5M members, DevOps engineers, SREs, platform engineers
+- **Culture**: Pragmatic and skeptical. Values reliability, observability, and automation that actually works in production. Allergic to "revolutionary" claims. Wants to know: does it work at scale, what breaks it, what's the blast radius?
+- **Best post styles**: Automation walkthroughs, pipeline architecture, real-world reliability stories, honest post-mortems
+- **Avoid**: Startup marketing language, vague AI capability claims, anything that glosses over failure modes
+
+---
+
+## Post Title
+
+```
+AI agents that read your GitHub issues and autonomously open PRs — the pipeline architecture behind it
+```
+
+---
+
+## Post Body
+
+> **Target length**: ~1000–1400 characters (r/devops wants the mechanism and the reliability story)
+> **Tone**: Engineering-first, pragmatic. Lead with the pipeline architecture. Acknowledge failure modes.
+> **URL**: https://github.com/RapierCraftStudios/ForgeDock
+
+---
+
+```
+Here's the pipeline we built: GitHub issue → AI agent investigates → builds fix → runs quality checks → 9-agent PR review → opens PR. Human reviews and merges.
+
+The reliability problem was agent amnesia. Every new session the agent re-investigated root causes it had already traced, re-made decisions it had already documented, missed context that prior sessions had surfaced. Without persistent memory, "autonomous" meant "needs constant supervision to not repeat mistakes."
+
+The architecture: every pipeline stage writes machine-readable HTML annotations to the GitHub issue. FORGE:INVESTIGATOR records root cause with file:line references. FORGE:CONTEXT surfaces known failure patterns for the affected module, mined from closed issues in the same domain. FORGE:ARCHITECT produces a typed implementation plan with all call sites traced before any code is written. The next agent session reads these annotations via `gh` CLI before doing anything.
+
+GitHub is the state store. `gh` is the query interface. No external memory service, no vector DB, no embedding pipeline. The annotations are structured content in GitHub comments — append-only, auditable, queryable.
+
+Quality gate runs 14+ check domains before the PR opens: security, auth, SQL safety, migration safety, env var consistency, frontend proxy paths, database config. Review phase uses 9 domain-specific agents (concurrency, billing integrity, auth, database migrations, infrastructure). Review findings become new GitHub issues — they don't block the merge.
+
+After 20,000+ issues on production codebases, the main reliability improvement: false positive rate in review agents dropped from 44% to <10% as closed-issue history accumulated. The pipeline learns.
+
+install: npx forgedock (25 markdown command specs, no runtime server)
+```
+
+---
+
+## Launch Timing
+
+- **Post 3–4 days after HN** — r/devops audience appreciates substance over recency; let the HN discussion build
+- **Best windows**: Tuesday–Thursday, 9am–1pm ET
+- **Good pairing**: r/programming on the same day (complementary audiences)
+
+---
+
+## Engagement Strategy
+
+- r/devops culture rewards honest failure-mode discussion — don't oversell reliability
+- Lead with the quality gate and review agent architecture — these are the parts DevOps engineers care about most
+- Be specific about what the pipeline does and doesn't handle (it doesn't deploy, it doesn't manage infrastructure — it's the PR creation pipeline, not the CD pipeline)
+- If asked about integration with existing CI/CD: the pipeline produces a PR, the existing CI/CD handles the rest. It's complementary, not replacement.
+- Have concrete answers about blast radius and rollback
+
+---
+
+## Pre-Drafted Comment Responses
+
+### "How does this interact with existing CI/CD pipelines?"
+
+> ForgeDock produces a PR — your existing CI/CD pipeline takes it from there. The quality gate and review agents run before the PR is opened; once the PR exists, it goes through whatever CI checks you have (tests, linting, build verification). ForgeDock is the "issue to reviewed PR" pipeline; CD from PR to production is your existing workflow. They're complementary. The only touchpoint is the PR creation — same interface as a human developer opening a PR.
+
+### "What happens when the AI makes a bad deployment change?"
+
+> The quality gate explicitly checks for high-risk infrastructure changes: Dockerfile modifications, env var additions, service restarts, volume permission changes. Each flagged change gets annotated in the commit with `[restart: service]` markers and a hard-blocker item in the testing checklist. The 9-agent review includes an infrastructure agent specifically for deployment-related changes. Nothing auto-merges; a human reviews every PR. If something still gets through, the review finding becomes a new issue that gets fixed in the next cycle.
+
+### "What's the blast radius if the agent writes broken code?"
+
+> The PR is the blast radius boundary. The agent can't deploy, can't push to main directly, can't merge its own PRs. The worst case is a PR that fails CI checks — which your existing CI will catch. The review agents catch most logic errors before CI even runs. If a bad PR gets merged by a human who approved it, that's the same blast radius as any PR merge. The audit trail (FORGE annotations on the issue) makes root cause analysis fast: you can see exactly why the agent made the change it made.
+
+### "Does this work with monorepos or multi-service architectures?"
+
+> The pipeline operates at the issue level — it reads the affected files listed in the issue and the investigation report, traces callers within those files, and scopes the change accordingly. For multi-service architectures, the `forge.yaml` config supports a multi-repo setup with satellite repos and per-repo staging branches. Each service/repo gets its own pipeline configuration. The quality gate does cross-service checks for env var consistency and proxy path alignment, but the build scope stays scoped to the issue.

package/docs/launch/reddit-r-localllama.md

@@ -0,0 +1,86 @@
+# Reddit Post — r/LocalLLaMA
+
+## Subreddit Profile
+
+- **Community**: ~400k members, AI/LLM researchers, engineers, enthusiasts
+- **Culture**: Highly technical, skeptical of hype, rewards architectural depth. People here read papers, benchmark models, and build infrastructure. They want the mechanism, not the pitch.
+- **Best post styles**: Technical deep-dives, architecture posts, novel approaches with clear trade-offs
+- **Avoid**: Marketing language, vague claims ("intelligent agents"), self-promotion without substance, anything that sounds like a product announcement
+
+---
+
+## Post Title
+
+```
+Using GitHub's existing graph structure as persistent memory for AI coding agents — architecture deep-dive
+```
+
+---
+
+## Post Body
+
+> **Target length**: ~1500–2000 characters (r/LocalLLaMA tolerates longer technical posts)
+> **Tone**: Technical, architectural, honest about trade-offs. Describe the mechanism, not the outcome.
+> **URL**: https://github.com/RapierCraftStudios/ForgeDock
+
+---
+
+```
+AI coding agents have a memory problem that bigger context windows don't fully solve. Even within a 200k token window, agents exploring a codebase from scratch on every task re-discover the same root causes, miss the same historical mistakes, and make the same implementation errors that prior sessions already identified. The bottleneck isn't token capacity — it's structured lookback.
+
+The key insight: GitHub already stores everything an agent needs as structured relationships. Issues reference PRs. PRs reference commits. Commits point to files. git blame traces when and why code was written. The relationships are there; agents just don't use them systematically.
+
+ForgeDock is a protocol that makes these relationships machine-readable. Every pipeline stage writes HTML annotations directly to GitHub issues and PRs using a consistent schema:
+
+- FORGE:INVESTIGATOR — verdict, root cause with file:line references, affected files, severity
+- FORGE:CONTEXT — historical findings from related issues, known pitfalls in the same module
+- FORGE:ARCHITECT — ordered implementation plan with full dependency graph of affected code paths
+- FORGE:BUILDER — branch, commits, acceptance criteria status
+
+When a new agent session starts — even after compaction, even days later — it queries GitHub via `gh` CLI and reconstructs full context from these annotations. No conversation history dependency. No vector store. No embedding lookup. The storage layer is GitHub itself.
+
+The pipeline: investigate (git blame + closed issue mining) → context (surface historical module failures) → architect (trace all call sites before writing code) → build → quality gate (14+ check domains) → 9-agent review → PR. Each stage reads what came before and writes what it found. Agents don't explore; they follow structured data.
+
+Trade-offs worth knowing: (1) annotation parsing costs tokens — you're spending ~800 tokens to read a FORGE:INVESTIGATOR comment that could be 50 tokens in a purpose-built store; (2) GitHub is append-only, so corrections require new comments, not edits; (3) quality depends heavily on the quality of the command specs.
+
+After 20,000+ issues on production codebases, the main observation: false positive rate in review agents dropped from 44% to <10% through the accumulated findings loop. The knowledge graph compounds.
+
+install: npx forgedock (25 markdown command specs, no runtime)
+```
+
+---
+
+## Launch Timing
+
+- **Post 2–3 days after HN** — r/LocalLLaMA audience overlaps with HN; wait for HN discussion to settle
+- **Best windows**: Weekday mornings, 9am–12pm ET (community peaks weekday mornings)
+- **Pair with**: r/programming on the same or next day (different tone, some audience overlap)
+
+---
+
+## Engagement Strategy
+
+- This community will probe the architecture hard — welcome it
+- If asked about token costs: acknowledge the parsing overhead and link to the Vision section of the README (purpose-built graph store as the roadmap end state)
+- If compared to RAG/vector approaches: explain that structured relationships in GitHub are qualitatively different from semantic similarity search — git blame tells you *why* code exists, not just that it's similar
+- Be precise about what "memory" means: it's not fine-tuning, not RAG, not in-context learning — it's structured state written to an external store that persists across conversation boundaries
+
+---
+
+## Pre-Drafted Comment Responses
+
+### "Why not just use a vector database?"
+
+> Vector stores give you semantic similarity — "this code looks like that code." GitHub's graph gives you causal relationships — "this code was written to fix issue #347, which was caused by the same nil-check pattern that broke issue #291." Those are different. For a coding agent, the causal chain (what changed, why, what broke after) is more useful than semantic proximity. GitHub already has the causal chain as structured relationships. We're just reading it systematically.
+
+### "This seems like it would be expensive in tokens"
+
+> It is — parsing a full FORGE:INVESTIGATOR comment costs ~800 tokens for what could be 50 tokens in a purpose-built store. That's a known trade-off we're accepting in v1 to validate the protocol before building a custom storage layer. The Vision section of the README describes the end state: a purpose-built graph store where those 5 fields come back as structured data, not markdown. The current GitHub-as-database approach is the proof-of-concept.
+
+### "How does this handle model context limits in long-running pipelines?"
+
+> Each pipeline stage reads only the annotations relevant to it — FORGE:INVESTIGATOR is ~800 tokens, FORGE:CONTEXT is ~600, FORGE:ARCHITECT is ~1000. Total context load per stage is well under 3k tokens for a typical task. Each stage also writes its findings, so downstream stages don't need to re-read upstream raw data. The annotation protocol is explicitly designed to be token-efficient per stage, not session-efficient overall.
+
+### "Isn't this just prompt chaining?"
+
+> The annotations are structured state that outlives any conversation. Prompt chaining typically means passing output from one LLM call directly to the next within a session. ForgeDock annotations persist on GitHub indefinitely — a session six months from now can read the FORGE:INVESTIGATOR from today and not re-investigate. That's closer to a write-ahead log than a prompt chain.

package/docs/launch/reddit-r-programming.md

@@ -0,0 +1,81 @@
+# Reddit Post — r/programming
+
+## Subreddit Profile
+
+- **Community**: ~6M members, general software developers
+- **Culture**: High bar for substance. Values problem/solution framing, architectural insights, honest tradeoffs. Dislikes obvious marketing and "here's my product" posts. Loves posts that teach something or present a genuinely novel approach.
+- **Best post styles**: Architecture discussions, "here's a problem I solved and how", technical essays with a clear thesis
+- **Avoid**: Pure announcements, product marketing, vague claims without mechanisms
+
+---
+
+## Post Title
+
+```
+How we solved the AI agent amnesia problem: using GitHub as a structured knowledge graph
+```
+
+---
+
+## Post Body
+
+> **Target length**: ~1000–1400 characters (r/programming readers skim — lead with the insight)
+> **Tone**: Third-person / conceptual. Frame as architectural insight, not product launch.
+> **URL**: https://github.com/RapierCraftStudios/ForgeDock
+
+---
+
+```
+AI coding agents forget everything between sessions. Doesn't matter how capable the model is — when the conversation ends, every investigation, every root cause trace, every historical pattern the agent discovered is gone. The next agent starts blind.
+
+Context window size doesn't fix this. The problem is that learned context doesn't persist to where future agents can find it.
+
+The approach we settled on: treat GitHub as a knowledge graph, not a ticket tracker. GitHub already stores everything an agent needs — issues reference PRs, PRs reference commits, commits track file history, git blame traces the "why" behind every line. It's a causal graph. We just needed to make it machine-readable.
+
+ForgeDock is a protocol for writing structured annotations directly to GitHub issues and PRs — machine-readable HTML comments that survive conversation resets. Every stage of the development pipeline reads the annotations from prior stages and writes its own findings back.
+
+The result: a new session reading GitHub for issue #42 knows the root cause traced to commit e8f21a3, knows the three files that need to change, knows that a similar nil-check bug was already fixed in issue #34, and knows the historical pitfall to avoid in the audit log path. Not because it explored the codebase — because a prior agent left structured breadcrumbs.
+
+After 20,000+ issues processed across production codebases: false positive rate in automated review dropped from 44% to <10% as the knowledge graph accumulated. The memory compounds.
+
+https://github.com/RapierCraftStudios/ForgeDock — 25 markdown command specs, install via npx forgedock
+
+[demo GIF — see repo]
+```
+
+---
+
+## Launch Timing
+
+- **Post 2–3 days after HN** — r/programming audience regularly cross-posts from HN; being second is fine
+- **Best windows**: Tuesday–Thursday, 8am–11am ET (highest engagement window for r/programming)
+- **Avoid**: Weekends (lower engagement), Monday mornings (buried in new posts)
+
+---
+
+## Engagement Strategy
+
+- Frame responses around the architectural problem, not the tool
+- r/programming readers often engage with "what's the alternative?" — acknowledge vector stores, CLAUDE.md, and agent frameworks, explain the specific tradeoff each makes
+- If the post gains traction, expand in comments with concrete examples (the payment nil-check example from the README is good)
+- Welcome critical responses — r/programming culture rewards "that's a fair criticism, here's the tradeoff"
+
+---
+
+## Pre-Drafted Comment Responses
+
+### "Why not just keep a local notes file or wiki?"
+
+> The agent needs to find the relevant context automatically, not search a wiki. When Claude starts on issue #42 (payment validation bug), it needs to know — without human guidance — that the same nil-check pattern broke issue #34 six months ago. That relationship lives in git history, linked issues, and PR cross-references. A static notes file doesn't have queryable causal structure. GitHub does.
+
+### "This is just structured logging / a write-ahead log"
+
+> That's a fair description of the mechanism. The annotations are append-only structured records on GitHub that any agent can read in a fresh session. The key property is that they're stored in the same system where the code lives — issue #42's annotation is linked to commit e8f21a3, which is linked to the PR that introduced the bug, which is linked to the issue that PR closed. The causal chain is traversable. A write-ahead log detached from the codebase doesn't have those edges.
+
+### "How do you handle hallucinations in the annotations?"
+
+> Downstream agents read annotations as input, not ground truth. FORGE:INVESTIGATOR says "root cause: nil-check missing at payments/validator.py:84" — the architect agent actually reads that file before writing code. The annotation guides where to look, not what to build. Hallucinated annotations produce wrong investigations that get flagged in review. Over time those failures are tracked as closed issues and FORGE:CONTEXT surfaces them as pitfalls before the same path is touched again.
+
+### "Wouldn't this fail on large codebases where history is noisy?"
+
+> We scope the history mining intentionally — the context phase reads last 30 commits on the affected files, not the full repo history. The signal-to-noise improves as the FORGE annotations accumulate: after N issues processed in a module, the annotation history for that module is richer than git history alone. For brand-new codebases, the first few issues run without historical context; it builds from there.

package/docs/launch/reddit-r-sideproject.md

@@ -0,0 +1,84 @@
+# Reddit Post — r/SideProject
+
+## Subreddit Profile
+
+- **Community**: ~300k members, indie builders, solo developers, weekend hackers
+- **Culture**: Personal, story-driven. People share what they shipped, what they learned, what failed. Celebrates the journey. Wants to know: what problem did you solve, how long did it take, what's the install path?
+- **Best post styles**: Launch stories, "I built X in N weeks", personal journey + demo
+- **Avoid**: Corporate tone, excessive technical depth without narrative, anything that doesn't have a clear "you can try it right now" CTA
+
+---
+
+## Post Title
+
+```
+Shipped: an autonomous dev pipeline where you open a GitHub issue and an AI agent investigates, builds, and opens the PR — open source
+```
+
+---
+
+## Post Body
+
+> **Target length**: ~800–1100 characters (r/SideProject readers want the story + CTA, not architecture)
+> **Tone**: First-person, story-driven, authentic. Share what it does in concrete terms, not abstract claims.
+> **URL**: https://github.com/RapierCraftStudios/ForgeDock
+
+---
+
+```
+The workflow I wanted: open a GitHub issue, walk away, come back to a PR.
+
+The problem: AI coding agents forget everything between sessions. Every task starts from zero — re-reading the codebase, re-investigating root causes, making the same mistakes that prior sessions already caught. Without persistent memory, "autonomous" means "needs constant hand-holding."
+
+The solution I built: ForgeDock. It uses GitHub itself as the agent's memory layer. Every pipeline stage writes structured annotations to the issue — root cause, implementation plan, known pitfalls, historical bugs in the same module. The next session reads those annotations and picks up where the last one left off. No external server, no embeddings — just structured content in GitHub comments.
+
+The actual workflow now:
+/work-on #42 → AI investigates (reads git blame, traces root cause, checks related issues) → plans implementation → builds → runs quality checks → 9-agent PR review → opens PR
+
+Start to PR: ~15 minutes for a focused bug fix.
+
+Built it because I was tired of babysitting Claude through the same investigations over and over. Turned out to be generally useful.
+
+install: npx forgedock
+repo: https://github.com/RapierCraftStudios/ForgeDock
+
+[demo GIF — see repo]
+```
+
+---
+
+## Launch Timing
+
+- **Post Day 1 after HN** — r/SideProject is perfect for the launch day personal story wave
+- **Best windows**: Any weekday, 10am–4pm ET (r/SideProject is active throughout the day)
+- **Good pairing**: Post r/ClaudeAI on the same day (different audience, non-overlapping)
+
+---
+
+## Engagement Strategy
+
+- r/SideProject community is warm and encouraging — engage genuinely
+- Share the backstory when asked: what problem prompted this, how long it took, what you'd do differently
+- Have a clear answer for "what's the hardest part?" — the answer is the quality of the command specs; the agent is only as good as the investigation prompt
+- If people ask about monetization/pricing: AGPL, free, open-source. Sponsors welcome.
+- Don't oversell the autonomy — be honest that it works well for scoped tasks and less well for massive architectural changes
+
+---
+
+## Pre-Drafted Comment Responses
+
+### "What kinds of tasks does it handle well?"
+
+> Best for: bug fixes with clear reproduction steps, feature additions to existing modules, refactors with a defined scope, maintenance tasks (dependency updates, config changes). Less reliable for: greenfield architecture decisions, tasks requiring external API knowledge it doesn't have, anything where the spec is genuinely ambiguous. It's strongest when GitHub has history in the affected area — the more closed issues and PRs, the richer the context it can pull.
+
+### "How long did it take to build?"
+
+> The core pipeline (investigate → build → review) took about 3 months of evenings. The quality gate and review agent system took another 2 months of iterating on actual production runs. The false positive rate in review was ~44% in the early builds; it's now under 10% from accumulated findings. Most of the time went into the command specs — the prompt engineering, not the orchestration.
+
+### "Does it replace developers or just help them?"
+
+> Helps, not replaces — at least today. It handles the mechanical parts: investigation, implementation of scoped changes, review findings. A developer still decides what to build, reviews the PR, and merges. The goal is to make the gap between "I have an idea" and "I have a reviewed PR" as short as possible, not to remove humans from the loop entirely. The autopilot mode exists but humans gate every merge.
+
+### "What if the AI makes a bad change?"
+
+> Every change goes through a 9-agent PR review before it's mergeable. Review findings become new GitHub issues. Nothing auto-merges to production without a human looking at the PR. The annotation trail also makes it easy to see exactly why the agent did what it did — every decision is documented in the issue comments (FORGE:INVESTIGATOR, FORGE:ARCHITECT, etc.). If something's wrong, you can trace it back to the exact annotation that led the agent astray.

package/docs/launch/show-hn.md

@@ -0,0 +1,84 @@
+# Hacker News 'Show HN' Launch Post
+
+## Post Title
+
+```
+Show HN: ForgeDock – GitHub as a knowledge graph for AI coding agents (issue in, PR out)
+```
+
+---
+
+## Post Body
+
+> **Target length**: ~1200–1500 characters (well within HN's ~4000 limit)
+> **Tone**: Technical, first-person, specific. No marketing fluff.
+> **URL**: https://github.com/RapierCraftStudios/ForgeDock
+
+---
+
+```
+Show HN: ForgeDock – GitHub as a knowledge graph for AI coding agents (issue in, PR out)
+
+AI coding agents have no lookback. They don't know why the code they're touching was written, that a similar approach was tried and reverted in PR #891, or that three other files share the same bug and need the same fix. Each task starts blind.
+
+The fix isn't a bigger context window. It's structured memory that survives conversation resets.
+
+ForgeDock treats GitHub as that memory layer. Every pipeline stage writes machine-readable HTML annotations to issues and PRs — FORGE:INVESTIGATOR traces root cause to a specific commit, FORGE:ARCHITECT produces a typed implementation plan, FORGE:CONTEXT surfaces known pitfalls from closed issues in the same module. The next agent reads these before doing anything. The gh CLI is the query interface; no external store, no embeddings.
+
+The pipeline: /work-on #42 → investigate (reads git blame, closed issues, review findings) → architect (traces all call sites, orders changes by dependency) → build → quality gate (14+ check domains) → 9-agent review → PR. Each stage writes what it found so the next stage doesn't repeat the work. After 20,000+ issues processed across real production codebases, patterns accumulate: the context phase now flags known pitfalls in a module before the builder touches it.
+
+It's 25 markdown command specs installed via npx forgedock, no runtime server. Would love to hear what the HN community thinks about using GitHub's existing graph structure — commits, blame, cross-references — as agent memory.
+```
+
+**Character count**: ~1,380 characters (well within 4,000 limit)
+
+---
+
+## Launch Timing
+
+- **Best windows**: Tuesday–Thursday, 9–10am ET
+- **Hard dependencies**: #542 (demo GIF), #543 (social preview), #544 (README restructure) must be complete first
+- **Day-of commitment**: Stay online 12+ hours, respond to every comment within 30 minutes in the first 2 hours (HN front-page velocity is comment-response-weighted)
+- **Avoid**: Mondays (post-weekend backlog), Fridays (low engagement), holiday weeks
+
+---
+
+## Pre-Drafted FAQ Responses
+
+### "How is this different from GitHub Actions?"
+
+> ForgeDock isn't CI/CD. GitHub Actions runs code on events. ForgeDock is a protocol for AI agents to pass structured context to each other through GitHub — investigations, implementation plans, known pitfalls. The `gh` CLI is the read/write interface, not a runner. Nothing executes in your repo; it's a set of prompt specs your Claude Code agent follows.
+
+### "Why not just use CLAUDE.md?"
+
+> CLAUDE.md is static — it describes your repo once, globally. FORGE annotations are dynamic and issue-specific: the FORGE:INVESTIGATOR comment on issue #42 contains the exact commit that introduced the bug, the affected file list, and the root cause. A future agent working on a related issue reads that comment and doesn't re-investigate from scratch. CLAUDE.md can't accumulate per-issue knowledge across sessions.
+
+### "Does this work with other AI tools beyond Claude Code?"
+
+> The pipeline logic and annotation protocol are model-agnostic. Claude Code is the supported runtime today because slash commands (`/work-on`, `/review-pr`) are a Claude Code primitive. The architecture is designed to be portable — any agent that can run `gh` CLI commands and write structured comments can participate. Provider-agnostic runtime is on the roadmap.
+
+### "Why AGPL?"
+
+> The network clause ensures that if someone forks ForgeDock and offers it as a service — even internally at a company — they must open-source their modifications. Developer tooling built on open protocols should stay open. AGPL lets individuals and companies use it freely as long as modifications flow back.
+
+### "How is this different from LangChain / AutoGen / CrewAI agent frameworks?"
+
+> Those frameworks orchestrate agents at runtime — chains, memory stores, tool calls. ForgeDock doesn't run at runtime at all. It's a protocol: structured annotations written to GitHub that survive conversation resets and work across completely separate agent sessions. The 'memory' is GitHub itself. Any agent that knows the annotation schema can pick up where the last one left off — no shared process, no running server, no embedding database.
+
+### "What happens when the agent gets it wrong?"
+
+> Review findings don't block merges — they become new issues that enter the same pipeline. The 9-agent review step flags problems, each finding is created as a tracked issue, and the pipeline processes them in a future run. Over time, review findings accumulate as closed issues; the context phase mines them before the next related build so the same mistake doesn't recur. The loop is: mistake → review finding → issue → fix → closed issue → future context.
+
+### "Why HTML comments for annotations?"
+
+> GitHub renders HTML comments invisibly to humans — the issue stays readable without noise. Agents grep for `<!-- FORGE:INVESTIGATOR -->` to find structured context fast. It's a zero-dependency protocol: no API, no schema registry, no additional auth. Any tool with `gh` CLI access can read and write annotations. The downside is parsing cost (tokens to extract fields from markdown); the [Vision section of the README](https://github.com/RapierCraftStudios/ForgeDock#vision) describes replacing this with a purpose-built graph store once the protocol is proven.
+
+---
+
+## Response Strategy
+
+- **Lead technical**: HN rewards specificity. Every response should name a mechanism, not a benefit.
+- **Engage skeptics directly**: "That's a fair concern — here's the exact failure mode and why the design handles it." Do not defend, explain.
+- **Convert questions into examples**: If someone asks how it works, walk through the payment nil-check example from the README (issue #42 → FORGE:CONTEXT surfaces audit log pitfall from issue #34 → builder avoids the mistake).
+- **Acknowledge limitations honestly**: The pipeline is only as good as the command specs. False positives in review agents were ~44% early on; the README cites improvement to <10% through accumulated findings. Be honest about this tradeoff.
+- **On "why not X"**: Never dismiss alternatives. Acknowledge what X is good at, explain the specific gap ForgeDock fills.