diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..28710eb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing to Fable Mode + +Issues and pull requests are welcome. This project is MIT licensed and +dependency-free at runtime; please keep it that way. + +## Development setup + +```bash +git clone https://github.com/REX-codebase/fable-mode.git +cd fable-mode +python -m venv .venv && source .venv/bin/activate +pip install -e . pytest +``` + +## Running the tests + +```bash +python -m pytest -q +``` + +The suite currently holds 473 tests and should stay green on Linux, macOS, +and Windows (see `.github/workflows/test.yml`). A change that breaks a test +is not ready, and a new behavior without a test is not done. + +## What makes a good contribution + +- **Small, explained diffs.** Say what changes and why, in the PR body. +- **Evidence, not vibes.** Fable Mode is about verifiable claims; include + test output, a receipt, or a repro for behavior changes. +- **Adversarial mindset.** If you touch the proof engine, time-lock, or + red-team logic, describe how the change could be gamed and why it cannot. +- **No new runtime dependencies** without a discussion issue first. + +## Good first issues + +Look for issues labeled `good first issue`. Documentation fixes, new test +cases for the verifier modules, and MCP client setup notes for other editors +are all great first contributions. + +## Reporting security issues + +Please open a private security advisory (Security tab) instead of a public +issue for anything that weakens the time-lock, proof validation, or red-team +guarantees. diff --git a/README.md b/README.md index a440d86..f1bd838 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,15 @@
-Python 3.10+ +Python 3.10+   -MIT +MIT   -MCP +MCP   -Zero Dependencies +Zero Dependencies +  +473 tests passing

@@ -26,12 +28,11 @@
-Fable Mode is a control plane for AI coding agents. - -It forces structured deliberation, evidence, and adversarial review -**before** any code is written to your workspace. +Fable Mode is an open-source control plane for AI coding agents. -No complexity. No hype. Just a mechanical lock that keeps agents honest. +It makes an agent deliberate, produce evidence, and survive adversarial review +**before** it earns permission to write to your workspace. The gates are +mechanical, not prompt advice: no timer, no proof, no write access.
@@ -39,6 +40,52 @@ No complexity. No hype. Just a mechanical lock that keeps agents honest. Think → Prove → Attack → Write + + +
+ +### See it work + +A session starts locked. Confidence does not unlock it. + +```text +>>> session = create_session('demo-refactor', budget='2 min') + state=INIT execution_locked=True can_execute_code=False + +>>> session.unlock_execution('the plan looks fine, let me write code now') + PermissionError: HARD TIME-LOCK VIOLATION: Execution unlock rejected! + The immutable 2.0m authority budget has not elapsed yet + (Remaining: 1m 59s / 120.0s). +``` + +The same gates guard every phase: evidence receipts for claims, a five-vector +red-team swarm for code, and a sealed record of what was verified. + +
+ +### Install + +```bash +pip install git+https://github.com/REX-codebase/fable-mode.git +``` + +Point your agent at the MCP server: + +```jsonc +// Claude Code: claude mcp add fable-engine -- python -m fable_engine.server +// Cursor: ~/.cursor/mcp.json +{ + "mcpServers": { + "fable-engine": { + "command": "python", + "args": ["-m", "fable_engine.server"] + } + } +} +``` + +Python 3.10+, zero runtime dependencies. PyPI package publishing is in progress. +
### How it works @@ -50,26 +97,25 @@ No complexity. No hype. Just a mechanical lock that keeps agents honest.
-### Install +### What it is not -```bash -# Clone -git clone https://github.com/REX-codebase/fable-mode.git -cd fable-mode +- Not a claim of flawless code. It is a checkable workflow, not a guarantee. +- Not a bigger prompt. The locks are enforced by the engine, not by wording. +- Not a framework lock-in. It speaks MCP and runs beside your current agent. -# Run the MCP server -python -m fable_engine.server -``` +
+ +### Docs -Point your agent (Claude Code, Cursor, Codex, etc.) at the MCP server. -That’s it. +- [V1 → V2 migration](./docs/fable-v1-v2-migration.md) +- [V2 architecture](./docs/fable-v2-architecture.md) +- [System 3 (experimental)](./docs/system3-architecture.md)
-### Why +### Contributing -Most agents jump straight to editing files. -Fable Mode makes them earn the right to touch your code. +Issues and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
diff --git a/SKILL.md b/SKILL.md index b08f05b..ceed5da 100644 --- a/SKILL.md +++ b/SKILL.md @@ -3,14 +3,13 @@ name: fable-mode description: Fable-Mode Cognitive Reasoning, System 2 Deliberation, and Swarm Architecture Protocols for Non-Frontier AI Models. --- -# Fable-Mode Strict Architecture & Role Separation Directive +# Fable-Mode Architecture & Role Separation -> ⚠️ **MANDATORY EXECUTION LAW & NON-COMPLIANCE PENALTY (NON-FRONTIER AI MODELS)**: -> Any failure by non-frontier AI models to strictly adhere to Fable Mode guidelines—including bypassing Red-Team Swarm review, substituting plain unit tests for adversarial stress testing, ignoring Fable zero-cost research scrapers, or skipping Cortical Evolution—results in **IMMEDIATE TASK INVALIDATION, SESSION REJECT, AND COGNITIVE PENALTY**. Non-frontier AI models MUST NOT deviate from this control plane under any circumstances. Standard tests have zero counterfactual reasoning ability; passing tests alone is NEVER proof of correctness. +> **Operating protocol for non-frontier AI models.** Fable Mode works because its gates are applied consistently, not because of wording. Follow the workflow below: ground research with the Fable scrapers, run the adversarial Red-Team Swarm instead of relying on unit tests alone, and finish with Cortical Evolution. Standard tests have limited counterfactual reasoning ability; passing tests alone is not proof of correctness. -## 0. Non-Frontier AI Mandatory Step-by-Step Execution Protocol +## 0. Step-by-Step Execution Protocol (Non-Frontier AI Models) -Non-frontier AI models executing under Fable-Mode MUST execute tasks through this strict sequential checklist without skipping steps: +Non-frontier AI models executing under Fable-Mode execute tasks through this sequential checklist: ``` ┌──────────────────────────────────────────────────────────────────────────┐ @@ -55,7 +54,7 @@ Non-frontier AI models executing under Fable-Mode MUST execute tasks through thi - If the initial 8-Pass System 2 thinking completes before the timer expires, the AI is **strictly forbidden from idling**. - The AI is **strictly required to continue rethinking and refining** (`rethink, refine, rethink, refine`). - Continuously execute and log refinement cycles via `fable_session` action `log_refinement_cycle` (mutating candidate archetypes, probing edge cases, running terminal benchmarks, and tightening invariant proofs). -- **Ungameable Deterministic Proof Standards**: +- **Deterministic Proof Standards**: - Ground all formal invariants in AST symbol coordinates, SHA-256 file checksum chains, and cryptographically bound `ToolReceipt` execution attestations. - Anti-tautology and circularity filters eliminate vacuous assertions ($P \implies P$); formal constructive proof terms and Kripke model checking ($AG(\text{safe})$) verify state dynamics. - **Visual Mockup-First Workflow ("Visualize Before You Build")**: diff --git a/marketing/launch-kit.md b/marketing/launch-kit.md index a97fdb2..fe7533a 100644 --- a/marketing/launch-kit.md +++ b/marketing/launch-kit.md @@ -100,3 +100,44 @@ Hey — I’m working on Fable Mode, an open-source MCP control plane for coding ## Conversion improvements to measure Track stars, forks, release downloads, README clicks into installation, issue quality, and the number of contributors who successfully run the canonical test suite. The most important near-term signal is not raw impressions; it is whether a technically serious visitor can understand the product, install it, and reproduce one evidence-gated workflow in under ten minutes. + +## Show HN post + +**Title:** Show HN: Fable Mode – an MCP control plane that makes coding agents earn write access + +I built Fable Mode because my coding agent kept doing the same thing: it would start editing files within seconds, produce a plausible patch, and only afterwards would I find out what it never checked. + +Prompting it to "think harder" changed nothing. So I made deliberation a mechanical constraint instead of a request. + +Fable Mode is an open-source (MIT) MCP server that puts four gates in front of the workspace: + +1. **Think** – a hard time-lock. The agent literally cannot write code until the deliberation budget elapses. Trying to unlock early raises a PermissionError, not a warning. +2. **Prove** – claims must carry evidence: tool receipts, SHA-256 checksum chains, AST-grounded invariants. Tautologies are filtered out. +3. **Attack** – a five-vector red-team swarm (chaos environment, Byzantine payloads, concurrency races, resource exhaustion, state invariants) tries to break the change. Unresolved breakages reject the milestone. +4. **Write** – only then is the workspace unlocked, with a sealed record of what was verified. + +Python 3.10+, zero runtime dependencies, works with Claude Code, Cursor, or anything that speaks MCP. 473 tests, CI on Linux/macOS/Windows. + +What it is not: a claim of flawless code. It is a way to make "be careful" machine-checkable instead of advisory. + +## r/ClaudeCode post + +**Title:** I got tired of my agent editing before thinking, so I built a mechanical lock for it (open source, MCP) + +Body: same narrative as Show HN, trimmed, leading with the Claude Code setup line (`claude mcp add fable-engine -- python -m fable_engine.server`) and ending with a request for feedback on the proof engine design. + +## r/mcp post + +**Title:** Fable Mode: an open-source MCP server that gates agent writes behind time-locks, evidence, and red-team review + +Body: the tool-oriented version: create_session + set_timer, the evidence ledger ([HYPOTHESIS]/[PROVEN] with receipts), red_team_code_review with the five attack vectors, and the sealed session record. Ends asking the community which other attack vectors the red team should cover. + +## Launch checklist + +- [ ] Embed the 30-second film at the top of the README (placeholder comment is in place) +- [ ] Publish `fable-engine` to PyPI, then switch the README install line to `pip install fable-engine` +- [ ] Submit server.json to the official MCP registry (`mcp-publisher publish`) +- [ ] PR to punkpeye/awesome-mcp-servers and modelcontextprotocol/servers (draft lines ready) +- [ ] Post Show HN (Tuesday-Thursday, morning US Eastern) +- [ ] Post r/ClaudeCode and r/mcp with the demo leading +- [ ] X post with the film attached, then the 3-post thread diff --git a/pyproject.toml b/pyproject.toml index 0f4d8c1..d434392 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -9,6 +9,7 @@ description = "Independent deterministic System 2 cognitive engine and mechanica readme = "README.md" authors = [{ name = "REX-codebase" }] license = { file = "LICENSE" } +keywords = ["mcp", "ai-agents", "coding-agents", "verification", "red-team", "llm-tools"] requires-python = ">=3.10" dependencies = [] classifiers = [ @@ -35,3 +36,8 @@ fable_engine = ["fable_session.json"] py-modules = ["fable_mode_entry", "fable_compressor"] + +[project.urls] +Homepage = "https://github.com/REX-codebase/fable-mode" +Repository = "https://github.com/REX-codebase/fable-mode" +Issues = "https://github.com/REX-codebase/fable-mode/issues" diff --git a/skills/fable-mode/SKILL.md b/skills/fable-mode/SKILL.md index b08f05b..ceed5da 100644 --- a/skills/fable-mode/SKILL.md +++ b/skills/fable-mode/SKILL.md @@ -3,14 +3,13 @@ name: fable-mode description: Fable-Mode Cognitive Reasoning, System 2 Deliberation, and Swarm Architecture Protocols for Non-Frontier AI Models. --- -# Fable-Mode Strict Architecture & Role Separation Directive +# Fable-Mode Architecture & Role Separation -> ⚠️ **MANDATORY EXECUTION LAW & NON-COMPLIANCE PENALTY (NON-FRONTIER AI MODELS)**: -> Any failure by non-frontier AI models to strictly adhere to Fable Mode guidelines—including bypassing Red-Team Swarm review, substituting plain unit tests for adversarial stress testing, ignoring Fable zero-cost research scrapers, or skipping Cortical Evolution—results in **IMMEDIATE TASK INVALIDATION, SESSION REJECT, AND COGNITIVE PENALTY**. Non-frontier AI models MUST NOT deviate from this control plane under any circumstances. Standard tests have zero counterfactual reasoning ability; passing tests alone is NEVER proof of correctness. +> **Operating protocol for non-frontier AI models.** Fable Mode works because its gates are applied consistently, not because of wording. Follow the workflow below: ground research with the Fable scrapers, run the adversarial Red-Team Swarm instead of relying on unit tests alone, and finish with Cortical Evolution. Standard tests have limited counterfactual reasoning ability; passing tests alone is not proof of correctness. -## 0. Non-Frontier AI Mandatory Step-by-Step Execution Protocol +## 0. Step-by-Step Execution Protocol (Non-Frontier AI Models) -Non-frontier AI models executing under Fable-Mode MUST execute tasks through this strict sequential checklist without skipping steps: +Non-frontier AI models executing under Fable-Mode execute tasks through this sequential checklist: ``` ┌──────────────────────────────────────────────────────────────────────────┐ @@ -55,7 +54,7 @@ Non-frontier AI models executing under Fable-Mode MUST execute tasks through thi - If the initial 8-Pass System 2 thinking completes before the timer expires, the AI is **strictly forbidden from idling**. - The AI is **strictly required to continue rethinking and refining** (`rethink, refine, rethink, refine`). - Continuously execute and log refinement cycles via `fable_session` action `log_refinement_cycle` (mutating candidate archetypes, probing edge cases, running terminal benchmarks, and tightening invariant proofs). -- **Ungameable Deterministic Proof Standards**: +- **Deterministic Proof Standards**: - Ground all formal invariants in AST symbol coordinates, SHA-256 file checksum chains, and cryptographically bound `ToolReceipt` execution attestations. - Anti-tautology and circularity filters eliminate vacuous assertions ($P \implies P$); formal constructive proof terms and Kripke model checking ($AG(\text{safe})$) verify state dynamics. - **Visual Mockup-First Workflow ("Visualize Before You Build")**: