convez.ai
Agente
tonmoy007

forge-plugins

tonmoy007/forge-plugins

Ver no GitHub
BomPluginScore · de 0 a 100

12-stage gated SDLC orchestrator for Claude Code — deterministic gates, REQ-ID traceability, cost-capped background agents, brownfield adoption

Instalação

$npx convez-ai tonmoy007/forge-plugins

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
3
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 1 mês
Versão
v0.8.0
Issues abertas
0
Contribuidores
2

README

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

Forge — SDLC Orchestrator for Claude Code

Forge turns Claude Code from a smart coding assistant into a disciplined engineering partner. Memory isn't the problem Claude Code solves poorly — sequencing is. Forge enforces it: gated stages, REQ-ID traceability, and structured lesson capture across projects.

Tests Python Claude Code License: MIT


What Forge Does

Claude Code already has memory — CLAUDE.md, persistent project context, subagents, Agent Teams. Forge does not try to out-remember it. What Claude Code does not enforce is process: that requirements come before design, design before code, and that nothing advances until the previous stage actually passed. That is the gap Forge fills.

Forge imposes a structured 12-stage pipeline — from requirements through release — where every stage has a gate that must pass before the next begins, and every line of work traces back to a numbered requirement (REQ-NNN → gate → code → test).

Without Forge: a capable assistant with no enforced sequencing — requirements drift, design is skipped under deadline pressure, and "done" means whatever the last prompt asked for.

With Forge: work proceeds only through gates you can inspect and, when justified, explicitly override (/forge:force-advance records why). Nothing advances silently, nothing is untraceable.

What is genuinely Forge's, not Anthropic's:

  • Gated sequencing — stages block until their criteria pass; overrides are explicit and audited, not silent.
  • REQ-ID traceability — every artifact, gate, and test links back to a requirement ID, end to end.
  • Structured cross-project lessons — not free-text memory: tagged, filterable, tied to project profiles, and promoted across repos.
  • Automatic skill mining — repeated workflows are detected and proposed as new /forge:* commands.

Traceability in practice — each artifact references the requirement it satisfies:

SRS            REQ-GATE-003  "force-advance override records a lesson"
  └─ Gate      G7-001        eval asserts the requirement is met
       └─ Code  scripts/force-advance.py
            └─ Test  tests/unit/test_force_advance.py  (17 cases)

See docs/gate-philosophy.md for when a gate should be resolved versus overridden.


Prerequisites

  • Claude Code ≥ 2.1.0
  • Python ≥ 3.11 (on PATH)
  • pyyaml: pip install pyyaml

Install

In Claude Code, run these two commands:

/plugin marketplace add tonmoy007/forge-plugins
/plugin install forge@forge-plugins

That's it. Forge activates automatically in any project where you've run /forge:init.


Quickstart (< 5 minutes)

1. Initialize Forge in your project

/forge:init

Forge detects your project type (API, full-stack, ML pipeline, CLI, library), scaffolds pipeline/ in your project root, and writes pipeline/state.md — the single source of truth for where you are in the pipeline.

2. Describe your project to get requirements

/forge:srs

Claude interviews you about your project and produces a requirements document (pipeline/01-srs/srs.md) with REQ-IDs you'll trace through every subsequent stage.

3. Continue through the pipeline

Each /forge:* command runs the next stage. You never need to remember where you are — Forge tells you at every session start.


The 12-Stage Pipeline

CommandStageOutput
/forge:srs1 — RequirementsSRS with REQ-IDs
/forge:product2 — Product & UXPRD, design system, user flows
/forge:arch3 — ArchitectureArchitecture doc, ADRs, data model
/forge:spec4 — Technical SpecTech spec, interface spec, test strategy
/forge:plan5 — PlanningTask DAG, milestones, risk register
/forge:build6 — ImplementationCode, decisions log, progress tracker
/forge:eval7 — EvaluationTest results, security review, eval report
/forge:deploy8 — DeploymentDeploy plan, deploy log
/forge:monitor9 — MonitoringObservability config, incident log
/forge:feedback10 — FeedbackFeedback log, triage
/forge:resolve11 — ResolutionHotfixes, backlog updates
/forge:release12 — ReleaseRelease notes, release checklist

Utility Commands

CommandWhat it does
/forge:statusShow current stage, task, blockers, and recent history
/forge:resumeRestore context after a session restart
/forge:retroRun a cycle-completion retrospective after Stage 12

Gate Enforcement

Every stage has exit criteria. Forge will not let you advance until gates pass:

  • Stage 1 requires REQ-IDs in the SRS and an "Open Questions" section
  • Stage 2 requires design tokens (--color-, --font-, --space- CSS variables) and WCAG accessibility notes
  • Stage 3 requires at least one ADR in pipeline/03-architecture/adr/
  • Stage 6 checks that all tasks are done before calling the build complete
  • ...and so on through Stage 12

Gates are defined in references/gate-criteria.md and enforced by scripts/check-gate.py. Blockers stop advancement; warnings are surfaced but don't block.


Adaptive Project Profiles

Forge detects your project type at init and customizes the pipeline:

TypeHow it adapts
apiAdds OpenAPI spec step; emphasizes auth and rate-limiting gates
fullstackAdds design system enforcement; CSS token gate in Stage 2
ml-pipelineAdds data contract step; GPU memory and drift detection lessons
cliSkips UX flows; emphasizes help text and exit-code documentation
libraryEmphasizes API stability and semver constraints
monorepoCross-package architecture + build orchestration; acyclic dependency-graph gate
mobileUI-heavy (Flutter/RN/iOS/Android); platform UX + app-store readiness gate
data-contractSchema-first (Protobuf/Avro/GraphQL/dbt); schema-hygiene + compatibility gate

Run /forge:init — Forge detects the type automatically, or you can override it.


Memory and Lessons

Forge maintains three tiers of memory:

  1. Session context — injected at every SessionStart via the hook; current stage, active task, blockers, relevant lessons
  2. Project memory — pipeline/ files accumulate decisions, reflections, and stage history across sessions
  3. Cross-project lessons — ~/.forge/global-lessons.yaml promotes high-frequency patterns across all your Forge projects

Lessons are extracted automatically after each stage completion. When a pattern appears 3+ times, Forge proposes a new skill you can approve, modify, or reject.


How Hooks Work

Forge installs 7 lifecycle hooks that run silently alongside your Claude Code session:

HookFiresWhat it does
session-start.pyEvery session openInjects current stage, task, blockers, top lessons (≤ 2 000 tokens)
prompt-submit.pyEvery user messageDetects stage intent; flags corrections for lesson extraction
pre-tool-write.pyBefore Write/EditChecks design token compliance, traceability, naming conventions
post-tool-use.pyAfter Write/Edit/BashLogs tool use; appends to patterns.jsonl for skill mining
stop-reflect.pyEnd of Claude turnEvaluates output against gate criteria; surfaces skill proposals
subagent-stop.pyEnd of subagent turnCaptures subagent reflections
session-end.pySession closeWrites session summary to .forge/sessions/; syncs lessons

Hooks never block your work unless a blocker gate fires (exit code 2).


If something looks wrong

  1. Run /forge:doctor — it reports environment, plugin, and current-stage gate health (healthy / wedged / broken) and usually names the exact fix.
  2. Seeing a cryptic PreToolUse / Stop hook error that doesn't mention a Forge path? It's probably from another plugin's hook, not Forge — see Troubleshooting third-party plugin hooks. (Forge's only PreToolUse hook is hooks/pre-tool-write.py.)
  3. Found a real Forge bug? File it with the feedback issue template.

Project Structure (After Init)

your-project/
├── pipeline/
│   ├── state.md              ← single source of truth (stage, task, blockers)
│   ├── 01-srs/               ← requirements
│   ├── 02-product-ux/        ← PRD, design system
│   ├── 03-architecture/      ← architecture docs, ADRs
│   ├── 04-spec/              ← technical and interface specs
│   ├── 05-plan/              ← task DAG, milestones
│   ├── 06-implementation/    ← progress tracker, decisions log
│   ├── 07-evaluation/        ← test results, eval report
│   ├── 08-deploy/            ← deploy plan and log
│   ├── 09-monitor/           ← observability config, incident log
│   ├── 10-feedback/          ← feedback log, triage
│   ├── 11-resolve/           ← hotfixes, backlog updates
│   └── 12-release/           ← release notes, checklist, retrospective
└── .forge/
    └── lessons.yaml          ← project-local lessons

Configuration

No config file needed for basic use. Advanced options via environment variables:

VariableDefaultDescription
FORGE_PROJECT_TYPEauto-detectedOverride project type detection
FORGE_MAX_LESSON_TOKENS500Max tokens for lesson injection
FORGE_LESSON_CAP5Max lessons shown at session start

Testing Forge

The integration test runs the full pipeline against a sample Todo API project:

bash tests/integration/full-pipeline.sh
# PASS: full-pipeline integration test
#   29 artifacts present
#   12/12 stage gate checks passed
#   traceability chain intact (REQ → spec, FEAT → arch, T-IDs in plan)

Unit tests:

python3 -m pytest tests/ -q
# 532 passed

Contributing

See CONTRIBUTING.md for the development workflow and docs/agent-authoring.md for step-by-step guides on:

  • Adding a new agent persona
  • Adding a pipeline stage
  • Adding a project-type profile override

License

MIT

Author

Saddam · built with Claude Code

Ver o original no GitHub

Bom para

Relacionados