convez.ai
AgenteAutomaçãoAvançado
RapierCraftStudios

ForgeDock

RapierCraftStudios/ForgeDock

GitHub como memória estruturada para agentes Claude Code

Ver no GitHub
BomPluginScore · de 0 a 100

Agent autônomo que transforma GitHub em grafo de conhecimento estruturado para pipelines de desenvolvimento. Investigação, construção, revisão e merge totalmente automáticos — saindo de issue para PR pronto com contexto completo da história do código.

Instalação

$npx convez-ai RapierCraftStudios/ForgeDock

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
119
Forks
16
Acompanhando
0
Saúde
62%
Último commit
há 2 dias
Versão
v1.61.2
Issues abertas
46
Contribuidores
4

Casos de uso

  • Automação completa de fluxo de issues para PRs com contexto histórico
  • Redução de erros repetitivos mantendo memória de decisões passadas
  • Revisão especializada com 9 agentes validadores (segurança, billing, DB, concorrência)
  • Recuperação instantânea de contexto entre sessões do agente

Veredito

Solução robusta que resolve o problema crítico de amnesia em agentes IA — memória estruturada via GitHub reduz taxa de falsos positivos de 44% para <10%. Exige setup maduro e integração GitHub nativa, mas entrega automação de ponta-a-ponta genuína.

README

A tradução para o português deste README ainda está na fila.

Your AI coding agent forgets everything after every session. ForgeDock fixes that.

  • Uses GitHub as structured memory — every pipeline stage writes findings agents can read later
  • Runs the full issue lifecycle autonomously: investigate → build → review → merge
  • False positive rate dropped from 44% to under 10% through a self-improving review loop
npx forgedock    # install in 10 seconds

⭐ If ForgeDock saves you time, star this repo — it helps more developers find it.


Without ForgeDock vs. With ForgeDock

Without ForgeDockWith ForgeDock
Agent starts every session blind — no context from prior workAgent reads structured investigation findings, root cause, and history from GitHub
Same bugs get introduced repeatedly across PRsReview agents surface known pitfalls from past PRs before you commit
Investigation gets repeated after every compactionGitHub is the memory — a new session picks up exactly where the last one left off
Manual: you write the issue, plan the fix, open the PR, review itAutonomous: /work-on #42 → investigated, built, reviewed, merged
Review depends on whoever has capacity9 domain-specialist agents (security, billing, DB, concurrency, etc.) review every PR

You:        /work-on #42
ForgeDock:  Investigates → Architects → Builds → Quality gates → Reviews → Opens PR
You:        *click merge*

The Problem

AI coding agents have no lookback. They don't know why the code they're touching was written. They can't tell that a function was shaped by a bug fix in issue #347, that a similar approach was tried and reverted in PR #891, or that three other files use the same pattern and need the same fix. They start every task blind — even within a single session.

Context window isn't the bottleneck. Memory is. When an agent compacts or a conversation ends, everything it learned is gone. The next agent starts from scratch. The investigation gets repeated. The same mistakes get made. There's no institutional knowledge.

The Insight

GitHub already stores everything an agent needs to know — commits, PRs, issues, blame, cross-references. It's a knowledge graph. But AI agents don't use it that way.

ForgeDock changes that. Every pipeline stage writes structured, machine-readable annotations to GitHub issues and PRs. Every downstream agent reads what came before. The gh CLI becomes the query interface to institutional memory.

┌─────────────────────────────────────────────────────────────────────┐
│                     GITHUB (Knowledge Graph)                        │
│                                                                     │
│  Issues:  FORGE:INVESTIGATOR → FORGE:CONTRACT → FORGE:ARCHITECT     │
│  PRs:     FORGE:BUILDER → FORGE:REVIEW → FORGE:TRAJECTORY           │
│  Links:   git blame → commit → PR → issue → related issues          │
│                                                                     │
│  Every agent reads this. Every agent writes to it.                  │
│  Nothing is lost between conversations.                             │
└─────────────────────────────────────────────────────────────────────┘

When the builder agent starts, it doesn't explore the codebase from scratch. It reads the investigation comment that already traced the root cause, identified affected files, and referenced the commit that introduced the bug. When the architect agent plans the implementation, it reads historical findings from related PRs so it doesn't repeat known mistakes. When a review agent flags a finding, that finding becomes a new issue that enters the same pipeline — investigated, built, reviewed, and merged.

The result: agents that are deterministic, not guessing. They follow structured data, not vibes.


See It Working

Generate the demo GIF: Install VHS and run vhs docs/demo.tape — it outputs docs/demo.gif from the tape script in this repo.

Here's what a real pipeline run looks like. A user reports that an API endpoint is returning 500 errors — the pipeline takes it from there.

Example 1: Bug fix with full context chain

A user opens issue #42: "POST /api/payments returns 500 for free-tier users."

FORGE:INVESTIGATOR  →  Traced bug to commit e8f21a3 (PR #38). The payment validation
                        gate assumed all users have a billing profile — free-tier users don't.
                        Quantified impact: 12 affected users, 94 failed requests in the last 24h.

FORGE:CONTRACT      →  2-file fix: add nil-check in payment validator,
                        add free-tier guard in the API router

FORGE:CONTEXT       →  Surfaced 2 historical bugs in the same module:
                        #29 (missing nil-check on subscription lookup) and
                        #34 (billing profile race condition on signup).
                        Known pitfall: don't skip the audit log write on early returns.

FORGE:ARCHITECT     →  Ordered implementation plan with exact file/function/line table

FORGE:BUILDER       →  Branch fix/payment-validation-free-tier-42, 2 files changed

FORGE:REVIEW        →  4 review agents, 0 findings, auto-merged to staging

The context phase knew about the audit log pitfall from issue #34 — a completely different bug, months earlier, in the same module. That's institutional memory.

Example 2: Cross-issue knowledge graph

The fix for #42 only covered the /payments endpoint. But the same nil-check bug exists in /invoices and /subscriptions. The pipeline spawns issue #43.

The context phase reads the structured data from #42 and says: "Billing profile nil-check was already fixed in payment_validator.py (#42) — same pattern must be applied consistently." It doesn't re-investigate. It reads the knowledge graph and applies the known fix to the remaining endpoints. 7 minutes, start to merge.

Example 3: Review agents catch bugs across service boundaries

A staging-to-main deploy PR gets reviewed by four specialized agents:

  • Concurrency agent — verified idempotency keys through PostgreSQL advisory locks
  • Security agent — flagged a force_https default change with broad blast radius
  • API agent — verified route registration consistency across all endpoints
  • Billing Integrity agent — found that the /invoices query still referenced an old column name that was renamed in a recent migration

That billing finding becomes a new issue — enters the same pipeline, gets investigated, built, reviewed, and merged. Bug caught before it hits production.

Example 4: The pipeline catches its own false positives

A review agent flags "no input size cap on the system key path." The investigation phase traces the full call chain and finds the cap already exists in a downstream quality gate module. Closed as workflow:invalid with an explanation of why the review agent missed it (it only inspected the text-building logic, not the downstream gate). The trajectory recorded: "Investigation revealed fix already present."

The pipeline self-corrects. No wasted work. Full audit trail.


How It Works

The Pipeline

Issue → Investigate → Architect → Build → Quality Gate → Review → Merge
                ↓           ↓         ↓          ↓            ↓
          writes to    reads from  reads from  reads from   writes to
           GitHub       GitHub      GitHub      GitHub       GitHub

Each stage reads the structured output of previous stages and writes its own findings back:

StageReadsWrites
InvestigateIssue body, git blame, related issues/PRsFORGE:INVESTIGATOR — verdict, root cause, affected files, severity
ContextHistorical findings from related PRs, known pitfallsFORGE:CONTEXT — institutional memory for this module
ArchitectInvestigation + context findingsFORGE:ARCHITECT — ordered implementation plan, code paths, risks
BuildInvestigation + context + architect planFORGE:BUILDER — branch, commits, files changed, checklist
Quality GateBuilder output, 14+ domain-specific checksFORGE:QUALITY_GATE — findings by domain (security, auth, DB, etc.)
ReviewPR diff, builder contract, quality gate resultsFORGE:REVIEW — per-agent findings with evidence and confidence
CloseAll of the aboveFORGE:TRAJECTORY — full audit trail of the entire run

GitHub as Database

Every annotation is wrapped in an HTML comment tag (<!-- FORGE:INVESTIGATOR -->, <!-- FORGE:CONTRACT -->, etc.) that makes it machine-parseable. When an agent starts — even in a brand new conversation after compaction — it queries the issue via gh and reconstructs full context from these tags. Nothing depends on conversation history.

Labels track workflow state (workflow:investigating, workflow:building, workflow:in-review, workflow:merged, workflow:invalid). The pipeline resumes from whatever state GitHub says it's in.

The annotation format is an open standard. See FORGE Annotation Protocol for the full specification — annotation types, schemas, context-passing chain, and conformance tests.

Review Agents

PRs are reviewed by domain-specific agents, each with deep expertise:

AgentFocus
Billing IntegrityPayment flows, credit debit paths, column renames
Auth & Access ControlEndpoint auth dependencies, resource ownership
DatabaseMigrations, unbounded queries, NOT NULL without DEFAULT
SecuritySQL injection, SSRF, XSS, hardcoded secrets
ConcurrencyIdempotency, advisory locks, race conditions
FrontenduseEffect cleanup, error states, hook dependencies
APIRoute registration, proxy paths, response contracts
PerformanceN+1 queries, unbounded loops, missing indexes
InfrastructureDockerfile changes, volume permissions, CI/CD

Each agent posts structured findings with confidence levels — CONFIRMED (traced full code path), LIKELY (pattern match), or POSSIBLE (needs verification). Findings above a severity threshold become new GitHub issues that enter the same pipeline.

The Self-Improvement Loop

Review findings from real PRs feed back into the pipeline:

  1. Review agents flag patterns (e.g., "async code keeps missing cleanup")
  2. /pipeline-health correlates findings with prompt changes and build failures
  3. The quality gate evolves — new domain checks get added from recurring patterns
  4. False positive rate dropped from 44% to under 10% through this loop

/autopilot takes this further: it pulls production signals (errors, CI failures, stale issues, analytics), creates issues from findings, and optionally runs /work-on on the top issues. Each cycle's fixes compound into the next.


Commands

CommandWhat it does
/work-onFull issue lifecycle: investigate → build → quality gate → review → merge
/issueCreates pipeline-ready GitHub issues
/orchestrateParallel execution: decomposes milestones into waves, runs /work-on on each
/review-prContext-aware PR review with 9 specialized agents
/quality-gatePre-commit checks across 14+ domains
/milestoneCreate, manage, and ship milestones
/deploy-infoStaging vs main diff with risk assessment
/review-pr-stagingComprehensive staging-to-main review gate
/rollbackAutomated revert PR for production incidents
/incident-responseP0 coordination: hotfix, timeline, postmortem
/pipeline-healthSelf-analysis: measures performance, proposes improvements
/autopilotAutonomous improvement cycle: recon → triage → fix
/security-audit4-phase security posture audit
/cleanupSweeps stale issues, branches, worktrees
/analyticsPull metrics from GSC, Clarity, Umami, Stripe, and more
/qa-sweepFull platform QA via browser automation

Vision

ForgeDock today uses GitHub as its knowledge graph. It works — 20,000+ issues processed, real production codebases shipping autonomously. But GitHub wasn't designed for this. Issue comments are append-only text blobs. Labels are flat strings. Cross-references are implicit links, not queryable edges. Every annotation costs tokens to parse because it's wrapped in markdown meant for humans, not machines.

The end state is a purpose-built knowledge graph — a structured, token-efficient store designed from the ground up for AI agents to read and write. Not a GitHub overlay. Not a vector database bolted on the side. A first-class system where:

In-house knowledge layer. Replace GitHub comments with a native graph store where relationships are edges, not hyperlinks. An agent asking "what bugs has this module had in the last 30 days?" should be a graph query returning structured data — not parsing 50 issue comment bodies hoping to find <!-- FORGE:INVESTIGATOR --> tags. Annotations become nodes with typed relationships (caused-by, fixed-in, blocks, related-to) instead of flat text.

Token-efficient by design. Today, an agent reads a 3,000-character investigation comment to extract 5 fields. A purpose-built store returns those 5 fields directly — 50 tokens instead of 800. At pipeline scale (investigation + context + architect + builder + review), this compresses the context budget dramatically. Agents get more lookback within the same window.

Self-improving feedback loops, closed tighter. Right now, the improvement loop runs through /pipeline-health — a command a human invokes. In the end state, the pipeline continuously measures its own accuracy (false positive rates, investigation-to-build time, review-finding recurrence), identifies degrading patterns, and adjusts its own prompts, quality gate checks, and review focus areas without human intervention. Not "suggest improvements" — actually ship them, validate them, and roll back if metrics regress.

Fully autonomous development cycles. Today, /autopilot runs recon and creates issues, but a human gates every fix. The vision is a pipeline that can run continuously — detecting production issues, creating issues, investigating, building, reviewing, deploying to staging, validating, and promoting to production — with human oversight moving from "approve every action" to "set policy and review outcomes." The human becomes the architect, not the operator.

Provider-agnostic agent runtime. ForgeDock currently runs on Claude Code. The pipeline logic — the state machine, the annotation protocol, the review agent catalog — is model-agnostic. The goal is an agent runtime that can orchestrate any LLM (Claude, GPT, Gemini, open-source models) as specialized workers, choosing the right model for each task based on capability, cost, and latency.

The path from here to there is incremental. Each piece — the knowledge store, the tighter feedback loop, the autonomous deploy gate — can ship independently and compound with the others.


Install

Option A: npx (recommended)

Step 1: Install commands

npx forgedock

This symlinks all pipeline commands into your Claude Code environment (~/.claude/commands/).

Note: If you run npx forgedock from inside the ForgeDock repository, it uses the local working-tree binary rather than the published package. Run from your own project directory, or use npx forgedock@latest to pin to the published release.

Step 2: Generate config

npx forgedock init         # Auto-detects your repo, owner, and branches

Creates forge.yaml in your project root — the config file that makes ForgeDock work with your repo instead of a hardcoded one. It also injects a concise ForgeDock usage block into your project's CLAUDE.md so every Claude Code session in the repo automatically knows that ForgeDock drives development here and which commands to use.

To regenerate the block later (e.g. after a ForgeDock update):

npx forgedock integrate

Step 3: AI-powered setup (optional)

/forgedock-init            # Inside Claude Code — guided full config walkthrough

Requires Claude Code and GitHub CLI.

Other commands:

npx forgedock update      # Pull latest commands
npx forgedock uninstall   # Remove all commands
npx forgedock help        # Show all commands

Option B: Claude Code Plugin Marketplace

If you're running Claude Code v2.1.143 or later, you can install ForgeDock directly through the plugin marketplace:

/plugin marketplace add RapierCraftStudios/ForgeDock
/plugin install forgedock@forgedock

After install, commands are available as /forgedock:work-on, /forgedock:review-pr, etc. You still need to run npx forgedock init (or /forgedock-init inside Claude Code) to generate your forge.yaml config.


Show Your Support

If you're using ForgeDock to power your development pipeline, add a badge to your README to let the community know:

[![Built with ForgeDock](https://img.shields.io/badge/Built_with-ForgeDock-blue?logo=github)](https://github.com/RapierCraftStudios/ForgeDock)

Rendered: Built with ForgeDock

This creates a discovery channel — each badge is a backlink and a signal to other developers that the project is AI-pipeline driven.

Star History


Documentation


Contributing

PRs welcome. Every change goes through a PR, tested against 3+ scenarios, using conventional commits (fix(command):, feat(command):, refactor(command):).

License

AGPL-3.0 — free to use, modify, and distribute. If you modify ForgeDock and offer it as a service (including over a network), you must open-source your modifications under the same license.


Ver o original no GitHub

Bom para

Relacionados