Persistent project intelligence that converts conversation into structured decisions, constraints, and artifacts. A builder talks. The product thinks. The system evolves. Every conversational turn flows through a pipeline: 1. Classify — Is this a decision, constraint, rejection, exploration, goal, correction, or noise? 2. Extract — Pull structured data: statement, rationale, category, certainty, a
Add this skill
npx mdskills install gzoonet/forgeSophisticated project intelligence system that extracts and persists decisions from conversation with robust architecture
1# GZOO Forge2345Persistent project intelligence that converts conversation into structured decisions, constraints, and artifacts.67> conversation → structured meaning → decision → artifact → system change89A builder talks. The product thinks. The system evolves.1011---1213## How It Works1415Every conversational turn flows through a pipeline:16171. **Classify** — Is this a decision, constraint, rejection, exploration, goal, correction, or noise?182. **Extract** — Pull structured data: statement, rationale, category, certainty, alternatives193. **Model** — Write to the project model (event-sourced, append-only)204. **Propagate** — Check for constraint conflicts and tensions between decisions215. **Surface** — Trust-calibrated notifications (flow state detection, interruption budgets)226. **Execute** — Hook into external systems (GitHub issues, repo creation, spec commits)2324The project model persists across sessions. When you come back tomorrow, Forge knows what was decided, what was rejected, and what's still open.2526---2728## Quick Start (Claude Code)2930The primary integration. Add Forge as an MCP server and Claude Code automatically remembers everything.3132Add to your Claude Code MCP config (`.mcp.json` in your project root):3334```json35{36 "mcpServers": {37 "forge": {38 "command": "npx",39 "args": ["@gzoo/forge-mcp"],40 "env": {41 "ANTHROPIC_API_KEY": "sk-ant-..."42 }43 }44 }45}46```4748Start Claude Code. That's it. See [packages/mcp/README.md](packages/mcp/README.md) for details.4950---5152## Quick Start (CLI)5354For manual testing and inspection.5556```bash57# Initialize a project58forge init "My SaaS App"5960# Process conversational turns61forge turn "We're building an analytics dashboard for SMBs"62forge turn "Let's use TypeScript and Next.js"63forge turn "No PHP. Ever."64forge turn "I'm torn between Stripe and Paddle for payments"6566# View the model67forge model # Full project model68forge brief # Session brief (what's decided, what's pending)69forge tensions # Active constraint conflicts70forge trust # Trust calibration metrics7172# Cross-project memory73forge memory "database choice"7475# Execution hooks (GitHub)76forge actions # Propose actions based on decisions77forge execute <action-id> # Approve and run78```7980---8182## Architecture8384Monorepo with npm workspaces. 6 packages:8586```87packages/88 core/ Types, IDs, provenance — zero dependencies89 store/ Event sourcing + SQLite (better-sqlite3)90 extract/ Two-stage LLM pipeline (classify → extract) + Cortex bridge91 execute/ Execution hooks (GitHub integration)92 cli/ CLI test surface (forge command)93 mcp/ MCP server for Claude Code integration94```9596**Dependency flow:**9798```99core ← store ← extract ← execute100 ↑ ↑101 cli mcp102```103104---105106## Configuration107108Copy `.env.example` to `.env` and set your provider:109110| Variable | Description | Default |111|----------|-------------|---------|112| `FORGE_LLM_PROVIDER` | `anthropic`, `openai`, or `openai-compatible` | `anthropic` |113| `ANTHROPIC_API_KEY` | Anthropic API key | — |114| `OPENAI_API_KEY` | OpenAI (or compatible) API key | — |115| `OPENAI_BASE_URL` | Base URL for OpenAI-compatible providers | — |116| `FORGE_FAST_MODEL` | Override the fast/classifier model | Provider default |117| `FORGE_QUALITY_MODEL` | Override the quality/extractor model | Provider default |118| `GITHUB_TOKEN` | GitHub PAT for execution hooks | — |119| `GITHUB_OWNER` | GitHub username for execution hooks | — |120121**Supported providers:** Anthropic (Claude), OpenAI, Groq, Together, Ollama, or any OpenAI-compatible API.122123---124125## CLI Reference126127| Command | Description |128|---------|-------------|129| `forge init "name"` | Initialize a new project |130| `forge turn "text"` | Process a conversational turn |131| `forge model` | Display the full project model |132| `forge events` | Show the event log |133| `forge brief` | Generate a session brief |134| `forge artifacts` | Show generated spec artifacts |135| `forge tensions` | Show constraint tensions (active/resolved) |136| `forge actions` | Propose execution actions from decisions |137| `forge execute <id>` | Approve and execute an action |138| `forge trust` | Show trust calibration metrics |139| `forge workspace` | Show workspace values and risk profile |140| `forge memory "query"` | Search cross-project memory |141142---143144## Project Model145146Forge builds a structured model from conversation with 5 layers:147148**Intent** — Primary goal, success criteria, scope (in/out), quality bar, anti-goals.149150**Decisions** — Statements with commitment levels:151- `exploring` — Mentioned, not committed152- `leaning` — Showing preference (auto-promoted from exploring)153- `decided` — Explicitly committed (**never automatic**)154- `locked` — Structural dependency, costly to reverse155156**Constraints** — Hard or soft boundaries: technical, financial, timeline, ethical, etc.157158**Rejections** — What was explicitly rejected, with type (categorical/conditional/deferred) and revealed preferences.159160**Explorations** — Open questions and investigations with status tracking.161162Cross-cutting: **Tensions** (conflicts between decisions/constraints) and **Artifacts** (generated specs from committed decisions).163164### Cardinal Rule165166> `leaning → decided` is **never** automatic. No exceptions.167168A decision moves from leaning to decided only through explicit user commitment. Tests enforce this invariant.169170---171172## Phase Status173174| Phase | Description | Status |175|-------|-------------|--------|176| 1 | Core model, event sourcing, extraction pipeline | Complete |177| 2 | Artifact generation engine | Complete |178| 3 | Constraint propagation + semantic conflict detection | Complete |179| 4 | Execution hooks (GitHub integration) | Complete |180| 5 | Trust calibration engine | Complete |181| 6 | Cross-project memory + workspace intelligence | Complete |182| MCP | MCP server for Claude Code | Complete |183| Cortex | Cortex Bridge for codebase-aware decisions | Complete |184185**Test count:** 176 tests across 14 test files.186187---188189## Development190191```bash192# Install dependencies193npm install194195# Build all packages196npx tsc -b197198# Run all tests199npx vitest run200201# Run tests for a specific package202npx vitest run packages/extract203204# Build and run the MCP server205npx tsc -b packages/mcp206node packages/mcp/dist/index.js207```208209**Stack:** TypeScript (strict), SQLite via better-sqlite3, nanoid@3 (CJS-compatible).210211---212213## Requirements214215| Dependency | Minimum Version | Notes |216|------------|----------------|-------|217| Node.js | 20+ | Required for all packages |218| npm | 9+ | Workspace support required |219| Claude Code | Latest | For MCP integration |220| LLM API key | — | Anthropic, OpenAI, or any OpenAI-compatible provider |221| Cortex | Latest | Optional — enables codebase-aware decisions |222223The MCP server requires **one** LLM API key to process conversational turns. Without an API key, resources (like `forge://brief`) still work but `forge_process_turn` will fail.224225---226227## Your Project's .gitignore228229When you install Forge in your project, add this to your `.gitignore`:230231```gitignore232# Forge local state (decisions are stored locally, not in version control)233.forge/234```235236The `.forge/` directory contains `state.json` (session tracking) and `forge.db` (SQLite database with all decisions). This is local per-developer state — it should not be committed.237238---239240## FAQ241242**Do I need to pay for an API key?**243Yes. Forge uses LLM calls to classify and extract decisions from conversation. Each `forge_process_turn` call makes 1-2 API calls (classifier + extractor). Costs are minimal — a typical session uses a few cents of API credits.244245**Can I use a local model (free)?**246Yes. Set `FORGE_LLM_PROVIDER=openai-compatible` and point `OPENAI_BASE_URL` at your local server (e.g., Ollama at `http://localhost:11434/v1`). Quality depends on the model — larger models extract decisions more reliably.247248**Does Forge send my code to an API?**249No. Forge only sends conversational text (what you say) to the LLM for classification and extraction. Your source code, files, and project contents are never sent. All extracted decisions are stored locally in `.forge/forge.db`.250251**Can I use this with Cursor, Windsurf, or other IDEs?**252Forge uses the MCP (Model Context Protocol) standard. Any IDE or tool that supports MCP stdio servers can use Forge. Claude Code has the most mature MCP support. Check your IDE's documentation for MCP server configuration.253254**How do I reset and start fresh?**255Delete the `.forge/` directory in your project root. Next time Claude Code starts, Forge will prompt for a new `forge_init`.256257**Where are my decisions stored?**258In `.forge/forge.db` (SQLite) in your project directory. The database is event-sourced — decisions are append-only events. You can inspect it with any SQLite viewer.259260**Can multiple developers share decisions?**261Not yet. The `.forge/` directory is local state. Cross-developer synchronization is a potential future feature. For now, each developer has their own decision history.262263---264265## Cortex Integration266267Forge integrates with [GZOO Cortex](https://github.com/gzoonet/cortex) to enrich decisions with codebase context. The two tools are complementary:268269- **Forge** knows *why* — decisions, constraints, intent, rejections270- **Cortex** knows *what* — code entities, patterns, dependencies, architecture271272When both are installed, Forge automatically queries Cortex's knowledge graph during decision extraction. If a developer says "Let's switch to PostgreSQL," Forge checks Cortex for existing database references, related services, and migration patterns — giving decisions real codebase awareness.273274### How it works2752761. On startup, Forge checks if `cortex` CLI is available2772. If found, it spawns `cortex mcp start` and connects via MCP (stdio JSON-RPC)2783. When new decisions or explorations are extracted, Forge queries Cortex in parallel with its own cross-project memory2794. Cortex matches appear in the extraction output alongside decisions280281### Setup282283Install both tools as MCP servers in your project:284285```json286{287 "mcpServers": {288 "forge": {289 "command": "npx",290 "args": ["@gzoo/forge-mcp"],291 "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }292 },293 "cortex": {294 "command": "npx",295 "args": ["@gzoo/cortex-mcp"]296 }297 }298}299```300301Each tool works independently. Cortex works without Forge, Forge works without Cortex. When both are present, Forge queries Cortex automatically — no additional configuration needed.302303---304305## Contributing306307See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.308309---310311## License312313MIT — see [LICENSE](LICENSE)314315---316317## About318319Built by [GZOO](https://gzoo.ai) — an AI-powered business automation platform.320321Forge started as an internal tool to preserve project decisions across sessions. We open-sourced it because every AI-assisted project loses context — decisions get forgotten, constraints get violated, rejected ideas resurface. We think this approach — structured extraction + event sourcing + persistent memory — is the right way to solve it.322
Full transparency — inspect the skill content before installing.