ForgePlan

From raw idea to proven decision

An engineering decision framework for teams that want their ideas to leave a paper trail. Structured artifacts (PRD, RFC, ADR, Epic, Spec), quality scoring, evidence, and native AI-agent integration.

Website · Documentation · Methodology · Releases · Marketplace

English · Русский

---

    ┌─────────┐    ┌────────┐    ┌────────┐    ┌───────┐    ┌────────┐    ┌──────┐
    │ OBSERVE │ ─▶ │ ROUTE  │ ─▶ │ SHAPE  │ ─▶ │ BUILD │ ─▶ │ PROVE  │ ─▶ │ SHIP │
    └─────────┘    └────────┘    └────────┘    └───────┘    └────────┘    └──────┘
     health        depth          PRD/RFC       code+test    evidence      activate

Every decision leaves a trail. Every trail has proof. Every proof decays honestly.

---

Why ForgePlan

Before Decisions scattered in Slack, Linear, email "Why did we pick X?" — silence six months later AI agents produce plausible-but-shallow work ADRs exist in theory, never get written Research never reaches the implementation

After Every decision is a git-tracked artifact Full Problem → Decision → Consequence trail Depth calibration forces appropriate rigor forgeplan new adr — one command, done ADI reasoning demands 3+ hypotheses

Install

# Homebrew (macOS, Linux)
brew install ForgePlan/tap/forgeplan
# Homebrew 6.0+: if install is refused with "untrusted tap",
# run `brew trust ForgePlan/tap` once, then re-run the line above.

# Install script
curl -fsSL https://raw.githubusercontent.com/ForgePlan/forgeplan/main/install.sh | sh

# From source
git clone https://github.com/ForgePlan/forgeplan.git && cd forgeplan
cargo install --path crates/forgeplan-cli

60-Second Demo

$ forgeplan init -y
  ✓ Workspace initialized at .forgeplan/

$ forgeplan route "Add OAuth2 authentication"
  Depth:      Standard
  Pipeline:   PRD → RFC
  Confidence: 92%

$ forgeplan new prd "OAuth2 Authentication"
  ID:    PRD-001
  Next:  fill Problem, Goals, Non-Goals, Target Users, FR

$ forgeplan validate PRD-001
  Result: PASS (0 errors, 0 warnings)

$ forgeplan reason PRD-001
  Hypothesis 1: Session-based flow   (confidence: 0.6)
  Hypothesis 2: JWT with refresh     (confidence: 0.8)  ← best supported
  Hypothesis 3: OAuth proxy service  (confidence: 0.4)

$ forgeplan new evidence "15 tests pass, 180ms p95 on benchmark"
$ forgeplan link EVID-001 PRD-001 --relation informs
$ forgeplan score PRD-001
  R_eff: 1.00  (Adequate)

$ forgeplan activate PRD-001
  ✓ PRD-001 (draft → active)

The seven things that matter

📝 Markdown-first	All artifacts are plain markdown in git. LanceDB is a derived index — you can rebuild it from the files.
🎯 Quality scoring	R_eff (weakest-link evidence trust) and F-G-R (formality, granularity, reliability), automatic.
🧭 Smart routing	Analyzes your task, picks the right depth and artifact pipeline. No over-documenting typo fixes.
🧠 ADI reasoning	Abduction → Deduction → Induction. Forces 3+ hypotheses before every decision.
🤖 MCP-native	73 tools for Claude Code, Cursor, Aider, Continue. Agents speak the methodology natively.
🔍 Local semantic search	fastembed (BGE-M3, 1024 dims). No network, no API keys, no egress.
⏰ Evidence decay	Expired valid_until → artifact goes stale. Trust decays honestly, nothing rots in the dark.

Artifacts at a glance

Artifact	Answers	When
PRD	What are we building and why?	New feature, product decision
RFC	How will we build it?	Architecture, API design
ADR	Why did we choose this way?	Irreversible technical decisions
Spec	What are the exact contracts?	API contracts, data models
Epic	What is the bigger picture?	Cross-cutting, multi-PRD initiatives
Evidence	Does it actually work?	After implementation, before activation

See docs/methodology/PRD-RFC-ADR-FLOW.md for the full decision tree.

Documentation

Three entry points — pick the one that matches what you need right now.

I want to...	Start here
Learn the methodology	docs/methodology/FORGEPLAN-GUIDE.md
Browse all docs	docs/README.md
Work with AI agents	CLAUDE.md · AGENTS.md

Dogfood

394 tracked artifacts

3243 tests passing

81 CLI commands

73 MCP tools

This repository uses ForgePlan to manage itself. Every PRD, RFC, ADR, and Evidence lives in .forgeplan/ — browse them or run forgeplan list locally.

Contributing

See CLAUDE.md for the full guide. Short version:

# Branch from dev
git checkout dev && git pull
git checkout -b feat/my-feature

# Work the cycle: Route → Shape → Validate → Build → Evidence → Activate
# cargo fmt + cargo test before every commit
# PR → dev (main is touched only via release branches)

Cargo features

Feature	Default	Purpose
semantic-search	off	BGE-M3 vector search via fastembed (~150 MB model on first run)
test-helpers	off	Test fixtures only — exposes *_for_test escape hatches on LanceStore that bypass the projection pipeline. MUST NOT be enabled in production binaries. Internally gated on cfg(debug_assertions) so release builds with the feature accidentally enabled still keep the ADR-003 lockdown. Downstream test crates that need direct DB seeding should enable it under [dev-dependencies] only (see forgeplan-mcp/Cargo.toml for the canonical example).

License

MIT — see LICENSE.

Structure. Evidence. Trust.

→ Install now and run forgeplan route "your next task".

Built on top of Quint-code · BMAD · OpenSpec · FPF · LanceDB · fastembed

_{Made with care by @ForgePlan · Русская версия}