BowThruster

Architecture memory, focused code lookup, and pre-commit verification for AI coding agents. The board itself is the spec, eliminating manual spec writing and keeping design and code in sync automatically.

Built for AI Coding Agents — Not Manual Human Bookkeeping
BowThruster (bowthruster-mcp) is a tool for your AI coding agent to operate directly, not another spec format for you to maintain by hand. Anyone (or any AI agent) can clone the repo and run it immediately with stock python3. Connect bowthruster-mcp to your agent and your AI builds the architecture map, pulls focused code slices, and verifies its own commits automatically.

Why BowThruster

When you use an AI coding agent on a growing project, three things start going wrong:

1. It burns time and tokens hunting through files: To make a 15-line change, the agent greps across the repo and reads dozens of files—filling its context window with noise before it writes a single line of code.

2. Fixing one thing breaks another: It forgets a rule you explained earlier, or changes a function in one file without realizing three downstream modules depend on it.

3. Architecture docs rot immediately: Nobody has time to keep markdown specs in sync with code by hand.

BowThruster (bowthruster-mcp) fixes all three. It is a fast, deterministic MCP server (zero LLMs, zero API keys) that your AI operates directly to keep your codebase's architecture, rules, and Git history in lockstep:

• 1-Shot Code Slicing Instead of Repo Grepping: Instead of reading whole files, your agent queries BowThruster for a function or feature and gets back a < 2 KB slice containing the exact #L<start>-L<end> source code, the private helpers it calls, and its upstream/downstream contracts in a single call.

• Rules That Can't Be Silently Dropped: Important invariants and module contracts are registered on the board instead of buried in chat history. Before a commit lands, BowThruster checks your code's AST and formal invariants—blocking the commit if an invariant was bypassed or an unrelated module was edited by mistake.

• Automatic Blast-Radius Tracking: When your agent changes an upstream data structure or interface, BowThruster automatically marks the affected downstream modules STALE so the agent knows exactly what else needs updating and which tests to run.

• Works Across Languages & Repos: Built-in AST/symbol extractors support Python, TypeScript/JavaScript, Go, Rust, C/C++, Java, Kotlin, C#, Swift, and Ruby—and bowthruster-mcp automatically discovers the right board across multiple repositories from a single global MCP config.

Related MCP server: Hokmah MCP Server

Quick Start

• Standard MCP JSON Config

  {
    "mcpServers": {
      "bowthruster": {
        "command": "python3",
        "args": ["-m", "bowthruster.mcp_server"],
        "env": {
          "PYTHONPATH": "/ABSOLUTE/PATH/TO/bowthruster"
        }
      }
    }
  }

• Once connected, open any new or existing repository and tell your agent:

1. Map the codebase:

   "Call readme(section='readme') on bowthruster and map this repository onto a board with its Charter, component Roles/Why, Flows, Interfaces, and Laws."

2. Run an architectural audit:

   "With the insight you now have from the board and AST slices, what would you change about this project's architecture (e.g., monoliths doing another component's job, hidden state mutations across flows, duplicated logic, or missing seams)?"

Agent Reference: Tools, Workflows & Pipe-Table Schema

The 8 MCP Tools (bowthruster server)

Daily Agent Workflows

More Examples: See docs/examples.md for walkthroughs of multi-agent parallel STALE dispatch, targeted QA & producer $\rightarrow$ consumer seam testing, architectural audits, and living spec generation.

Workflow A — Internal Fix (0 Contract Changes, 3 Tool Calls)

When fixing an internal bug, helper function, or threshold where no # SCHEMA, $ INTERFACE, > FLOW, or % LAW signature changes:

1. Pull Code & Mark STALE in One Shot:

   • Call slice(board="my_board", query="verify_token", include_code=True, mark_stale=True)

   • Returns the < 2 KB component contract slice, the exact #L<start>-L<end> code block, and transitions the owning component (auth_service) to STALE in one call. (If exploring first without knowing whether you will edit, omit mark_stale=True until you pull the target function to edit.)

2. Edit the Code:

   • Call edit_file directly using the returned #L<start>-L<end> lines.

3. Pre-Commit Gate + Auto-Verify in One Shot:

   • Call git_sync(board="my_board", mode="pre", mark_verified=True) (and run delta tests on the changed component).

   • Verifies AST signatures, % LAW call-graph reachability, > FLOW schemas, and Bend 2 proofs. When allowed: true, it automatically transitions STALE components back to VERIFIED and refreshes file hashes and #L<start>-L<end> AST anchors.

Workflow B — Architectural / Contract Change (4 Tool Calls)

When adding or modifying a @ COMPONENT, > FLOW, $ INTERFACE, # SCHEMA, % LAW, or Rule:

1. Explore & Slice (atlas / slice): Inspect the component slice and existing contracts.

2. Mutate the Board First (turn): Submit the updated Markdown pipe table(s), which transitions the modified component and any impacted downstream > FLOW consumers from VERIFIED to STALE. (Optional for greenfield/new laws: call packets(status="STALE") for laws_skeleton and python_skeleton.)

3. Edit the Code (edit_file): Implement the updated contract and % LAW wiring.

4. Pre-Commit Gate + Auto-Verify (git_sync): Call git_sync(board="my_board", mode="pre", mark_verified=True), run delta + producer $\rightarrow$ consumer seam tests, commit, and stamp git_sync(board="my_board", mode="post").

Canonical Pipe-Table Schema (turn)

Pass canonical Markdown pipe tables (Charter, Component, Flow, Interface, Law, plus optional Schema and Rule tables) to turn. atlas(board="my_board", spec=True) renders the complete human-readable specification directly from the board at any time:

| Charter | Summary | Principles |
| :--- | :--- | :--- |
| my_board | Edge API gateway and stateless JWT authentication service for client requests. | Stateless token validation; zero shared mutable state between gateway workers; explicit typed contracts on all internal flows. |

| Component | Role | Why | Owner | Stage | Depends_On | Files |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| auth_service | JWT token validator | Isolates cryptographic signature and expiration checks so downstream handlers only receive verified AuthTokens. | backend | 1 | none | src/auth.py:L1-L120 |
| api_gateway | HTTP request router | Terminates external HTTP requests and enforces auth_check before dispatching to internal services. | backend | 1 | auth_service | src/gateway.py:L1-L150 |

| Flow | Source | Target | Payload | Condition |
| :--- | :--- | :--- | :--- | :--- |
| auth_check | api_gateway | auth_service | AuthToken | on incoming HTTP request |

| Interface | Component | Inputs | Outputs | Owner | Stage | File | Spec |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| verify_token | auth_service | raw_token: str | AuthToken | backend | 1 | src/auth.py:L20-L60 | Spec 1 |
| route_request | api_gateway | request: dict | HttpResponse | backend | 1 | src/gateway.py:L30-L90 | Spec 1 |

| Law | Component | Owner | Stage | Bend_Dir | Args | LHS | RHS | Spec |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| token_valid_law | auth_service | backend | 1 | laws | has_sig: Bool, not_expired: Bool | MOD.is_token_valid(has_sig, not_expired) | Bool.and(has_sig, not_expired) | Spec 1 |
| route_allow_law | api_gateway | backend | 1 | laws | token_ok: Bool, route_exists: Bool | MOD.can_route(token_ok, route_exists) | Bool.and(token_ok, route_exists) | Spec 1 |

| Schema | Component | Fields | Owner | Stage | File | Spec |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| AuthToken | auth_service | user_id: str, expires_at: int | backend | 1 | src/auth.py:L10-L18 | Spec 1 |

| Rule | Component | Type | Property | Op | Value | Condition |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| max_lines_rule | auth_service | BOUND | max_file_lines | <= | 500 | always |
| retry_cap_rule | api_gateway | BOUND | MAX_RETRIES | <= | 3 | always |
| no_requests_lib | api_gateway | PROHIBITION | requests | == | false | always |

• When to use Rule (*) vs. Law (%):

  • Rule (BOUND / PROHIBITION / OBLIGATION): Use for file line caps (BOUND on max_file_lines), module constant bounds (BOUND on an AST constant like MAX_RETRIES <= 3), banned imports (PROHIBITION on a module name like requests or torch, checked against AST import statements on git_sync), or component obligations (OBLIGATION, mounted in slice). Re-submitting the same (Component, Property) overwrites the old rule in place (MARKOVIAN_OVERWRITE), or attaches a conditional exception when Condition differs.

  • Law (% LAW): Reserve for multi-variable boolean state machines, routing tables, or conservation invariants ($k \ge 2$ boolean inputs, or a Theorem column LHS == RHS) that are proven in Bend 2 and called by the component's $ INTERFACE in the AST call graph. Never invent a 1-boolean identity law (MOD.is_ok(x) == x) just to mark a component STALE—use slice(..., mark_stale=True) or update the $ INTERFACE, # SCHEMA, or Rule row instead.

Onboarding an Existing Repository & Installing the AI Skill / Git Hooks

1. Compile & Verify the Baseline: Submit the initial pipe tables via turn, mark existing files VERIFIED via git_sync(board="my_board", mode="pre", mark_verified=True), and stamp the initial Git SHA via git_sync(board="my_board", mode="post").

2. Install the Unified bowthruster Skill: Call readme(section="skills") to retrieve docs/skills/bowthruster/SKILL.md and write it to .agents/skills/bowthruster/SKILL.md (or .claude/skills/bowthruster/SKILL.md), replacing <BOARD_NAME> and <TEST_CMD>.

3. Optional Git Hooks (.git/hooks/pre-commit & post-commit):

   # .git/hooks/pre-commit (chmod +x .git/hooks/pre-commit)
   #!/usr/bin/env bash
   set -euo pipefail
   LATTICE_PROJECT_ROOT="$(git rev-parse --show-toplevel)" \
     python3 -m bowthruster.cli --board <BOARD_NAME> git-sync --pre-commit
   
   # .git/hooks/post-commit (chmod +x .git/hooks/post-commit)
   #!/usr/bin/env bash
   set -euo pipefail
   LATTICE_PROJECT_ROOT="$(git rev-parse --show-toplevel)" \
     python3 -m bowthruster.cli --board <BOARD_NAME> git-sync --post-commit

How It Works Under the Hood

BowThruster is organized into six packages under bowthruster/:

flowchart LR
    User(["Developer / AI Agent"]) -- "Markdown Pipe Tables" --> Reg["1. bowthruster.regiment\n(Pipe-Table Compiler)"]
    Reg -- "IntakePacket (Tables + MCUs)" --> Exec["2. bowthruster.the_executive\n(Pre-Flight & Git Gate)"]
    Exec -- "Seed Cues" --> Mem["4. bowthruster.ai_memory\n(Directed Spreading Activation & URIs)"]
    Mem -- "Activated Nodes (LOD_1)" --> Table["5. bowthruster.the_table\n(Bounded Context Desk & Atlas)"]
    WB["3. bowthruster.whiteboard\n(Constraint Graph & Skeletons)"] -- "ContextView" --> Table
    Table -- "TableView (LOD_0 / LOD_1 / LOD_2)" --> Exec
    Exec -- "COMMIT_TO_WHITEBOARD" --> WB
    Exec -- "SEND_BACK_TO_USER (Conflict / Gap)" --> User
    WB -- "Committed Rules" --> Mem
    GC["6. bowthruster.graph_core\n(SQLite Store & Activation)"] -. "Storage" .-> WB
    GC -. "Storage" .-> Mem
    GC -. "Storage" .-> Table

1. The 4-Layer Verification Stack

Behavioral unit tests alone leave internal program structure underdetermined (Skeleton Coding, arXiv:2610.38214): an LLM can pass a unit test with a hardcoded workaround while ignoring your architecture. BowThruster verifies both the architecture graph and the implementation across four layers:

1. Graph Completeness & Interval Satisfiability (whiteboard/frustration.py): A board only reaches PROVEN_COMPLETE when every @ COMPONENT has an owner, file path or typed $ INTERFACE / # SCHEMA contract, and connected > FLOW edge, with 0 open structural gaps and 0 contradictory BOUND/PROHIBITION intervals.

2. Formal Dependent-Type Proofs in Bend 2 (LATTICE_PROOF.bend & LAWS.bend): Both the board-level completeness theorem (lattice_proof_proven_iff_complete_and_conflict_free in LATTICE_PROOF.bend) and optional component % LAW invariants (Args, LHS, RHS) are compiled into formal equality theorems (LHS == RHS proven via inductive case analysis) and checked by the Bend 2 proof checker (bend).

3. AST Signature, Call-Graph & Python-to-Bend Law Gate (the_executive/gate.py & nlp.py): Before every commit (git_sync(mode="pre")), BowThruster parses staged files to verify that every declared # SCHEMA class and $ INTERFACE function exists with its required fields/parameters, every $ INTERFACE invokes any declared % LAW helper in the static call graph, every staged Python % LAW helper's AST transpiles to Bend 2 and satisfies LHS == RHS, and no VERIFIED file was modified without marking its component STALE.

4. Finite-State Algebraic & Mutation Parity (bend_gate.py): For multi-datatype state machines in laws/*/main.bend, compiles Bend 2 theorems to .mjs, exhaustively evaluates truth-table parity against Python, and runs incremental law-mutation checks (--only-law).

2. Directed Spreading Activation vs. Naive GraphRAG (bowthruster.ai_memory)

If you put a codebase into a naive dependency graph and walk 2 undirected hops from auth_service, hop 1 hits a shared utility (types.py or graph_core), and hop 2 bounces out to every module in the repository that imports types.py (94.7% hub noise). Conversely, restricting retrieval to 1 hop misses multi-stage data pipelines (gateway -> router -> auth -> token_store).

bowthruster.ai_memory (hippocampal_index.py and uri_resolver.py) solves this with three mechanisms:

1. Pointer-Only Storage & Git-Synchronized URIs: ai_memory never copies raw source files into a vector database. It stores concept nodes holding uri://file/<path>#L<start>-L<end> pointers and local _helper#L<start>-L<end> call trees. When files are renamed (git mv) or line ranges shift on commit, sync_git_diff_uris automatically heals the pointers and refreshes AST line anchors.

2. Causal Edge-Type Separation (Data Flows vs. Shared Utilities):

   • Data-Flow Edges (> FLOW) & Scope Hierarchy: Propagate activation both forward and backward along the pipeline (up to 6 hops) so multi-step data paths stay connected.

   • Shared Utility Dependencies (depends_on): Pulled 1 hop forward (caller -> utility) into a terminal contract sink. You get the utility's interface contract without ever bouncing backward into unrelated callers (0% hub noise).

3. Two-Ended Pipeline Bridge Recall: When a task mentions two components at opposite ends of a pipeline (e.g., api_gateway and token_store), recall_concepts propagates a forward wave from the upstream component and a backward wave from the downstream component. Intermediate pipeline stages where both waves meet automatically get boosted into the active context slice—surfacing the full connecting path across up to 5 hops without pulling in unrelated branches.

3. Bounded Working Context (bowthruster.the_table) & Markovian Board Updates (bowthruster.whiteboard)

• Three Levels of Detail (LOD_0 / LOD_1 / LOD_2): bowthruster.the_table bounds active working memory (max_table_slots = 16, max_table_tokens = 1200), mounting LOD_0 (atlas) for global topology/spec queries, LOD_1 (50-word synopses) for neighboring components, and LOD_2 (full contracts + #L<start>-L<end> code slices) for active targets.

• Markovian Overwrite & Scope Mitosis: Re-submitting a rule on (Component, Property) or a flow on (Source, Target, Payload) updates the existing entry in place (MARKOVIAN_OVERWRITE) so superseded rules and duplicate edges never accumulate. When any component exceeds k_cap rules (default 7), it automatically splits along metadata axes into child sub-scopes (comp::subscope).

Configuration (config.json) & Limitations

All gate policies and working-memory budgets live in config.json:

Known Limitations (What BowThruster Does Not Replace)

1. Static AST & Boolean Law Proofs Complement Behavioral Tests:

   • The pre-commit gate (evaluate_git_commit_gate + verify_ast_call_graph_skeleton) and Bend 2 (bend check) prove that no VERIFIED component was edited without marking it STALE, declared # SCHEMA classes/fields and $ INTERFACE functions/parameters exist in the AST, every $ INTERFACE calls its governing % LAW helper without discarding the return value, and every % LAW formula (LHS == RHS) is mathematically sound.

   • However, static checks cannot prove that an algorithm computes the right intermediate values before passing booleans to a % LAW helper, or that SQL queries, I/O, or runtime state mutations behave correctly. Component-scoped unit and producer $\rightarrow$ consumer seam tests (pytest on changed_scopes | stale_dependents) remain essential.

2. Enforcement Is Bounded by What Is Declared on the Board:

   • evaluate_git_commit_gate verifies schemas, interfaces, laws, bounds, and import prohibitions registered on the board (and flags unregistered_public_symbols on modified files). If an internal helper introduces an undeclared side effect not governed by a board rule, promote a new Rule, # SCHEMA, or % LAW onto the board via turn.

License

Licensed under the Functional Source License, Version 1.1, Apache 2.0 Future License (FSL-1.1-Apache-2.0). See LICENSE for full terms.