forgedock 1.0.19 → 1.0.21

package/docs/design/messaging-angles-research.md

@@ -0,0 +1,179 @@
+# Messaging Angles Research: Codebase LLM Wiki
+
+**Issue**: #1092
+**Date**: 2026-06-25
+**Method**: Cross-platform engagement analysis (HN, Product Hunt, GitHub, developer surveys, blogs)
+
+---
+
+## Summary
+
+Five candidate messaging angles were evaluated for the "GitHub as a Codebase LLM Wiki" concept. Research covered Hacker News engagement patterns, Karpathy's LLM Wiki viral moment, Stack Overflow 2025 Developer Survey data, Product Hunt launches, and GitHub stars across competing tools.
+
+**Verdict**: Candidate #4 ("Agent Memory that Lives in GitHub") has the strongest backing. Candidate #1 ("Codebase Wiki for AI Agents") has the strongest direct vocabulary alignment with Karpathy's viral LLM Wiki gist.
+
+---
+
+## Key Event: Karpathy's LLM Wiki (April 4, 2026)
+
+Andrej Karpathy published a GitHub Gist titled **"LLM Wiki"** on April 4, 2026. Results within days:
+
+- **17 million views**
+- **5,000+ GitHub stars**
+- **4,282 forks**
+- Dozens of independent implementations (agentmemory 20K+ stars, llm-wiki repo, LLM Wiki v2 gist)
+- VentureBeat coverage, commercial SaaS products launched off the pattern
+
+**Karpathy's exact framing**: *"incrementally builds and maintains a persistent wiki"*, *"compiled knowledge layer"*, *"the human curates; the LLM maintains"*, *"stop re-deriving, start compiling"*
+
+This is the largest single organic engagement signal in this exact vocabulary space in 2025–2026. The term "LLM Wiki" now has category-level developer awareness.
+
+---
+
+## Key Event: "Context Engineering" Goes Viral (June 25, 2025)
+
+Karpathy posted endorsing "context engineering" over "prompt engineering" — *"the delicate art and science of filling the context window with just the right information for the next step."* Shopify CEO Tobi Lütke amplified. Gartner declared 2026 "the year of context."
+
+Within months: conference talks, job titles, blog posts, a GitHub Awesome-Context-Engineering repo.
+
+**Implication for ForgeDock**: "Context Layer" (candidate #2) deploys this already-activated vocabulary. Developers now have a crystallized pain around *filling context with the right information*. ForgeDock directly solves this.
+
+---
+
+## Developer Pain: Quantified
+
+From the Stack Overflow 2025 Developer Survey (84% of devs using AI tools):
+
+- **66%** cite "AI solutions that are almost right, but not quite" as primary frustration — directly caused by missing codebase context
+- **54%** report AI misses relevance even when context is manually selected
+- Context pain scales with seniority: **41% junior → 52% senior** developers
+- Only **29%** trust AI outputs (down from 40% in 2024) — credibility gap driven by context failures
+
+From Augment Code/Cerbos research: *"The bottleneck is not model quality — it's what context you feed the model."*
+
+From "The Goldfish Effect" (viral Medium, Jan 2026): agents forget constraints set minutes earlier. This exact pain is already named and circulating in developer communities.
+
+---
+
+## Engagement Data: Competing Tools (GitHub Stars)
+
+| Tool | Framing | Stars |
+|------|---------|-------|
+| Mem0 | "agent memory" | ~48,000 |
+| agentmemory | "LLM Wiki pattern" | ~20,000 |
+| Cognee | "knowledge graph" | ~12,000 |
+| codebase-memory-mcp | "persistent knowledge graph" | growing |
+
+**Memory dominates raw adoption. Context Engineering dominates cultural vocabulary.**
+
+---
+
+## Candidate Angle Rankings
+
+### 1. Candidate #4: "Agent Memory that Lives in GitHub" — STRONGEST
+
+**Evidence**:
+- "Memory" is the dominant vocabulary: Mem0 at 48K stars, agentmemory at 20K stars
+- Stack Overflow: 66% of devs cite context-missing as #1 frustration
+- Goldfish Effect framing: directly names the felt pain developers articulate
+- GitHub-native framing adds open-source/no-vendor-lock-in signal (HN community rewards this)
+
+**Suggested headline**: *"Your AI agents forget everything. ForgeDock gives them memory that lives in GitHub."*
+
+**Suggested subhead**: *"Issues, PRs, and labels become a queryable knowledge graph your agents read and write across every session. No proprietary database. No vendor lock-in."*
+
+**Why it works**: Names the pain directly ("forget"), names the solution directly ("memory"), names the platform ("GitHub"), and adds the differentiator ("no vendor lock-in"). Zero explanation required.
+
+---
+
+### 2. Candidate #1: "Codebase Wiki for AI Agents" — VERY STRONG
+
+**Evidence**:
+- Karpathy's "LLM Wiki" gist: 17M views, 5K stars, 4K forks
+- Direct vocabulary alignment — developers are actively searching "LLM wiki" and "codebase wiki" post-Karpathy
+- agentmemory (20K stars) explicitly positions as "Karpathy's LLM Wiki pattern — implemented and shipped"
+
+**Best use**: HN Show HN title and README hero headline — maps directly to the activated cultural artifact.
+
+**Suggested Show HN title**: *"Show HN: ForgeDock — Codebase LLM Wiki for AI agents, built on GitHub Issues"*
+
+**Suggested subhead**: *"Every investigation, decision, and review becomes structured context your agent reads back after compaction. No external memory layer — just GitHub."*
+
+**Why it works**: The term "LLM Wiki" has 17M views of cultural priming. Developers who saw the Karpathy post immediately understand "codebase LLM Wiki" as a specific, desirable thing.
+
+---
+
+### 3. Candidate #2: "Context Layer" — STRONG
+
+**Evidence**:
+- "Context engineering" went viral via Karpathy (June 2025); Gartner baked it into 2026 briefings
+- Atlan markets itself as "the Context Layer for AI"
+- Weavable (Product Hunt) used "persistent work context" framing successfully
+
+**Best use**: Technical subtitle, developer documentation, and LinkedIn/technical-blog positioning.
+
+**Suggested technical positioning**: *"The context engineering layer for autonomous AI pipelines."*
+
+**Caution**: "Context Layer" is accurate and vocabulary-correct but abstract. Works better as a subtitle after the emotional hook of "memory" or "wiki."
+
+---
+
+### 4. Candidate #3: "Knowledge Graph on GitHub" — MODERATE
+
+**Evidence**:
+- Harness.io blog *"Your Repo Is a Knowledge Graph. You Just Don't Query It Yet"* got organic traction with the negation-pattern headline
+- codebase-memory-mcp (arxiv 2603.27277, March 2026): 83% answer quality at 120x fewer tokens using graph framing
+- Cognee (12K stars), Graphiti both use knowledge graph vocabulary for technical credibility
+
+**Best use**: Technical documentation, README architecture section, developer-to-developer credibility. Not a hero headline — requires explanation.
+
+**Caution**: Knowledge graph vocabulary signals technical depth but triggers "sounds complex" reactions in non-graph-native developers. Use as a credibility signal after the hook, not as the hook.
+
+---
+
+### 5. Candidate #5: "Self-Documenting Codebase" — WEAKEST
+
+**Evidence**:
+- Dev.to/GitHub Blog posts on auto-doc-gen get organic traffic but no breakout engagement
+- divar-ir/ai-doc-gen and similar tools use this framing without notable viral moments
+- GitHub Octoverse 2025: 4.3M AI repos, 178% YoY growth — the space is crowded with this framing
+
+**Why it ranks last**: Passive/descriptive rather than pain-naming. Developers don't search for "a system that documents my code" — they search for something that stops their agent from losing context. "Self-documenting" solves an imagined problem; "agent memory" solves the felt one. Also: documentation tools are a crowded category with no differentiation angle.
+
+---
+
+## Open Source / No Vendor Lock-in Amplifier
+
+OpenCode (open-source Claude Code alternative): 162K+ GitHub stars. The HN community is explicitly hostile to vendor lock-in. The following sub-messages consistently add lift to any primary angle:
+
+- "No proprietary database"
+- "Your data stays in GitHub"
+- "Works with your own API key"
+- "AGPL — always free for the pipeline"
+
+These amplify candidates #4 and #1 most strongly because those angles already imply GitHub as the storage layer.
+
+---
+
+## Recommended Messaging Stack
+
+| Layer | Copy |
+|-------|------|
+| Hero Headline | "Your AI agents forget everything. ForgeDock gives them memory that lives in GitHub." |
+| Subhead | "Issues, PRs, and labels become a queryable knowledge graph your agents read and write across every session. No proprietary database. No vendor lock-in." |
+| Show HN Title | "Show HN: ForgeDock — Codebase LLM Wiki for AI agents, built on GitHub Issues" |
+| Technical Subtitle | "The context engineering layer for autonomous AI pipelines." |
+| One-liner | "GitHub as structured agent memory. Every decision survives context reset." |
+
+---
+
+## Sources and Evidence Links
+
+- Karpathy LLM Wiki gist: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
+- Karpathy "context engineering" tweet: https://x.com/karpathy/status/1937902205765607626
+- Stack Overflow 2025 Developer Survey (AI section): https://survey.stackoverflow.co/2025/ai/
+- Mem0 State of AI Agent Memory 2026: https://mem0.ai/blog/state-of-ai-agent-memory-2026
+- Harness.io "Your Repo Is a Knowledge Graph": https://www.harness.io/blog/your-repo-is-a-knowledge-graph-you-just-dont-query-it-yet
+- codebase-memory-mcp arxiv paper: https://arxiv.org/abs/2603.27277
+- Developer context pain (Augment Code): https://www.augmentcode.com/guides/why-ai-agents-repeat-questions
+- Context Engineering from tweet to infrastructure: https://thecontextgraph.co/memos/context-engineering-2026-from-tweet-to-infrastructure

package/docs/design/show-hn-draft.md

@@ -0,0 +1,86 @@
+# Show HN Draft
+
+<!-- Updated by #1092: messaging angles research (2026-06-25) -->
+<!-- Updated by #1099: context-rot pain framing (2026-06-27) -->
+<!-- Research: "LLM Wiki" vocabulary = 17M views / 5K stars (Karpathy gist, April 2026).
+     "Context rot" is now mainstream community vocabulary (MindStudio, Augment Code, Stack Overflow, 2025-2026).
+     Lead with context rot pain; use LLM Wiki vocabulary as the HN title hook. Full research: docs/design/messaging-angles-research.md -->
+
+## Title (choose one)
+
+**Option D** (research-backed — RECOMMENDED for HN):
+```
+Show HN: ForgeDock — Codebase LLM Wiki for AI agents, built on GitHub Issues
+```
+*Rationale: "LLM Wiki" has 17M views of cultural priming from Karpathy's April 2026 gist. Developers
+searching for the pattern recognize it immediately. Direct vocabulary alignment with the activated term.*
+
+**Option E** (pain-first — RECOMMENDED for product pages and README hero):
+```
+Show HN: ForgeDock — AI agents forget everything. This gives them memory that lives in GitHub.
+```
+*Rationale: "Memory" is the #1 vocabulary by adoption (Mem0 48K stars). Names the felt pain ("forget")
+directly. No explanation required.*
+
+**Option A** (technical):
+```
+Show HN: ForgeDock – Open-source pipeline that turns Claude Code into a deterministic dev team
+```
+
+**Option B** (problem-first):
+```
+Show HN: ForgeDock – GitHub as institutional memory for AI coding agents
+```
+
+**Option C** (concise):
+```
+Show HN: ForgeDock – Autonomous investigate-build-review-merge pipeline for Claude Code
+```
+
+---
+
+## URL
+
+https://github.com/RapierCraftStudios/ForgeDock
+
+---
+
+## Maker Comment (post immediately after submission)
+
+Hi HN. AI coding agents suffer from context rot: the gradual degradation of output quality as context fills with noise, stale file contents, and conventions re-explained from scratch every session. Every context reset, the agent forgets what it investigated, what decisions it made, what it already tried. You end up re-explaining your codebase every time.
+
+Most teams try to fight context rot with config files — CLAUDE.md, AGENTS.md, .cursorrules, Copilot instructions, Kiro steering. Five files, five formats, five things to keep in sync, and the agent still can't reconstruct what happened in the last PR.
+
+ForgeDock takes a different approach: it turns GitHub itself into the agent's persistent memory. When the pipeline runs on an issue, each stage (investigate, build, review, merge) posts a machine-readable FORGE: annotation to the issue/PR. Downstream stages read what upstream stages wrote. When context compacts, the agent runs `gh issue view` and reconstructs full state from GitHub alone — no external memory layer, no proprietary database, no vendor lock-in.
+
+Unlike DeepWiki (which generates a documentation snapshot of your codebase once), ForgeDock writes structured annotations during each pipeline execution — so context reflects the current state of every open issue and in-flight decision, not a snapshot that goes stale.
+
+It's the LLM Wiki pattern (Karpathy's April 2026 gist), but applied to your entire development pipeline: issues are the wiki entries, FORGE: annotations are the structured knowledge, and GitHub's API is the query interface.
+
+The pipeline has 9 phases, a 9-agent specialist review system (security, database, auth, concurrency, etc.), and a 14-domain quality gate — all running as Claude Code slash commands. It's not a wrapper or thin CLI; the command specs are 50KB+ prompt engineering documents that constrain agent behavior at every step.
+
+Some technical details:
+- Zero runtime code — just markdown command specs symlinked into Claude Code
+- Install: `npx forgedock`
+- Uses `gh` CLI and `yq` as only dependencies
+- AGPL licensed, free forever for the core pipeline
+- Currently Claude Code only, investigating multi-model support
+
+Known limitations:
+- Claude Code only (no Cursor/Codex/Aider support yet)
+- Token-heavy on first run before adaptive scripts cache project patterns
+- The pipeline is opinionated — it enforces a specific workflow that may not fit every team
+
+I'm a solo developer building this to solve my own problems. Happy to answer questions about the architecture, the FORGE annotation protocol, or the prompt engineering behind the command specs.
+
+---
+
+## Posting Guidelines
+
+- **When**: Tuesday–Thursday, 9AM–12PM ET
+- **First 60 minutes**: Respond to every comment
+- **Tone**: Technical, honest, no marketing language
+- **If asked about monetization**: "Open-core model — the pipeline is AGPL and always free. Planning a commercial dashboard for pipeline observability."
+- **If compared to Devin**: "Devin is a cloud service; ForgeDock runs locally with your own API key. Different trade-offs — Devin is turnkey, ForgeDock gives you full control and traceability."
+- **If compared to DeepWiki**: "DeepWiki generates a documentation snapshot of your repo. ForgeDock writes structured annotations during each pipeline run — context stays current with your actual work, not a snapshot."
+- **If asked about scale**: Be honest about current adoption. Don't inflate numbers.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "forgedock",
-  "version": "1.0.19",
-  "description": "GitHub as a knowledge graph for AI agents. Autonomous dev pipeline for Claude Code.",
+  "version": "1.0.21",
+  "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"
   },