Skip to content

README.md

Latest commit

 

History

History
129 lines (101 loc) · 8.43 KB

README.md

File metadata and controls

129 lines (101 loc) · 8.43 KB
Raw

Documentation Index

English · Русский

Production documentation for the Forgeplan project.

Local notes (research, planning, sessions, raw source materials) live in .local/ (gitignored) — not part of this tree.

Structure

docs/
├── README.md          ← this file — navigation index
├── ROADMAP.md         ← gap analysis + priority matrix (Architecture, UX, Distribution, Docs)
├── methodology/       ← how the Forgeplan methodology works (for humans)
├── operations/        ← agent hooks, enforcement, repo protection (devops)
└── schemas/           ← formal artifact schemas (contracts for the validator)

Artifacts (PRDs, RFCs, ADRs, Epics, Specs, Evidence, Problems, Notes) live in the Forgeplan workspace at .forgeplan/ — see Artifacts below.

Methodology — start here

Full methodology reference. Canonical source for humans learning to use Forgeplan.

Document Purpose
FORGEPLAN-GUIDE.md Start here — full guide: methodology + CLI + evidence + lifecycle
HOW-TO-USE.md 10 methodology rules with practical examples
ARTIFACT-MODEL.md Artifact hierarchy: Epic → PRD → Spec → RFC → ADR + lifecycle
PRD-RFC-ADR-FLOW.md Decision tree: which artifact type to create
DEPTH-CALIBRATION.md Tactical → Standard → Deep → Critical, with auto-escalation
QUALITY-GATES.md Verification Gate + Adversarial Review + R_eff scoring
UNIFIED-WORKFLOW.md Forgeplan × Orchestra × Hindsight integration
USAGE-BY-ROLE.md How to use Forgeplan based on your role
METHODOLOGY-COURSE.md Full learning path (course format)
GLOSSARY.md 31 terms + lifecycle reference table
LESSONS.ru.md Lessons learned — dependent sprint base verification, audit incidents, process improvements
agent-protocol.md Hint contract (PRD-071) — 5 markers (Next/Or/Wait/Done/Fix), good/bad examples, agent reading protocol
release-workflow.md End-to-end release recipe — dependabot triage gate, version bump, release/* PR strategy, post-release sync (CLAUDE.md red lines #9 + #10), hotfix flow, anti-patterns

Operations

Setup, hooks, and repository protection.

Document Purpose
AGENT-ENFORCEMENT.md Rules and guardrails for AI agents working in this project
AGENT-HOOKS.md PreToolUse / PostToolUse hooks (safety, formatting, tests)
LLM-PROVIDERS.md v0.33.0+ LLM provider config (openai/claude/gemini/ollama/claude-code) — keyless claude-code reuses local claude login (personal/local only, ADR-017 disclosure)
MULTI-AGENT.md v0.24.0+ multi-agent dispatch — forgeplan_dispatch/claim/release/claims MCP tools, file-overlap detection, skill routing
REPO-PROTECTION-GUIDE.md Branch protection, PR rules, destructive-action prevention
GIT-WORKFLOW.ru.md Full Git rules — branching lifecycle, PR pipeline, release process, worktrees
RELEASE-PROTOCOL.md (ru) Canonical release procedure — the 10 steps for any release/vX.Y.Z cut, pre-conditions, and the mandatory post-merge sync-PR (RED LINE #9)
dependabot-triage-YYYY-MM-DD.md Per-release dependency-alert triage (RED LINE #10) — every open alert labelled addressed / scheduled / accepted-with-justification. One file per release window
SOURCE-PORTING.ru.md Reference Code map — what was ported from sources/{quint-code,git-adr,BMAD,OpenSpec,ccpm} to our crates
PLAYBOOK-AUTHORING.ru.md v0.26.0+ playbook authoring — declarative YAML workflows, 5 delegation types, fallback hints, DAG ordering. v0.27.0+ Subprocess lifecycle section (real dispatchers, kill_on_drop, timeout policy, security model) per ADR-010/PRD-072
INGEST-MAPPINGS.ru.md v0.26.0+ ingest mapping authoring — translate plugin output to forge artifacts with hallucination-proof ## Sources invariant (PRD-066/SPEC-004)
QUALITY-GATES.ru.md v0.28.0+ CI quality gates — all CI gates (fmt, clippy, test, health, validate, drift detector) with local run commands and fix guides. Note: docs/methodology/QUALITY-GATES.md covers methodology gates (R_eff, Verification Gate).

Schemas

Formal specifications that the validator enforces.

Document Purpose
PRD-SCHEMA.md PRD: MUST sections, depth calibration, validation rules
EPIC-SCHEMA.md Epic: aggregated progress, children rules
SPEC-SCHEMA.md Spec: API contracts, data models, versioning

Artifacts

Location: .forgeplan/ in the repository root.

Storage model (per ADR-003):

  • Markdown files in .forgeplan/{adrs,rfcs,prds,epics,specs,evidence,problems,solutions,notes,refresh,memory}/ = source of truth (git-tracked)
  • LanceDB in .forgeplan/lance/ = derived index layer (git-ignored, rebuildable)
  • Config .forgeplan/config.yaml = local LLM keys (git-ignored)

Directories:

Directory Contents
.forgeplan/epics/ Epics — strategic groupings
.forgeplan/prds/ Product Requirements Documents
.forgeplan/rfcs/ RFCs — architectural proposals with implementation phases
.forgeplan/adrs/ Architecture Decision Records
.forgeplan/specs/ Formal specifications (API contracts, data models)
.forgeplan/evidence/ EvidencePacks — tests, benchmarks, measurements
.forgeplan/problems/ ProblemCards — problem framing with anti-Goodhart indicators
.forgeplan/solutions/ SolutionPortfolios — 2-3+ variants with weakest-link scoring
.forgeplan/notes/ Micro-decisions (auto-expire 90 days)
.forgeplan/refresh/ RefreshReports — re-evaluation of stale artifacts
.forgeplan/memory/ Decision memory

Managing artifacts: always use forgeplan CLI — do not hand-edit YAML frontmatter.

forgeplan new prd "Title"        # create new artifact
forgeplan list -t adr            # list all ADRs
forgeplan get ADR-003            # read one
forgeplan validate PRD-024       # check quality
forgeplan score PRD-024          # compute R_eff
forgeplan reindex                # rebuild LanceDB index from markdown

Fresh clone workflow:

git clone <repo> && cd forgeplan
forgeplan init -y                # creates .forgeplan/lance/ locally (empty)
forgeplan reindex                # syncs tracked markdown into LanceDB
forgeplan list                   # verify — should see all artifacts

See also

  • CLAUDE.md — project instructions for Claude Code
  • AGENTS.md — standard instructions for other AI agents (Aider, Cursor, etc.)
  • README.md — project README for humans
  • templates/ — markdown templates for each artifact kind
  • .local/ (gitignored) — local research, planning, sessions, raw source materials

Conventions

  • All paths in documents are relative to repository root.
  • Artifact files in .forgeplan/ are managed by the forgeplan CLI — hand-editing works but may cause drift with the LanceDB index until reindex runs.
  • Methodology docs here are authoritative — if a tutorial and a schema disagree, the schema wins.
  • Activated artifacts are immutable — supersede via forgeplan supersede, do not rewrite history.