CoBILD

Collaborative Brainstorming and LLM Development: a small MCP server and Python library for running spec-driven development with coding agents.

CoBILD adds two habits to normal spec-driven development:

1. Brainstorm before implementation. The user and agent clarify goals, trade-offs, constraints, and edge cases before code changes begin.
2. Keep agent-readable state. Each spec scope has a paired state file that records how the current implementation relates to its spec.

The result is a workflow where the spec remains the durable source of intent, and the state file gives agents a fast, explicit place to see what is already implemented, what is missing, and where reality has drifted.

Install

Run the MCP server directly from PyPI with uvx:

uvx --from cobild cobild-mcp

Register With An Agent

CoBILD is exposed as a stdio MCP server. Any MCP-compatible coding agent can run it with this command:

uvx --from cobild cobild-mcp

For Claude Code:

claude mcp add cobild -- uvx --from cobild cobild-mcp

For Codex:

codex mcp add cobild -- uvx --from cobild cobild-mcp

For Hermes Agent:

hermes mcp add cobild --command uvx --args --from cobild cobild-mcp

Or add the server directly to ~/.hermes/config.yaml:

mcp_servers:
  cobild:
    command: "uvx"
    args: ["--from", "cobild", "cobild-mcp"]

Generic MCP JSON configuration:

{
  "mcpServers": {
    "cobild": {
      "command": "uvx",
      "args": ["--from", "cobild", "cobild-mcp"]
    }
  }
}

Agent Workflow

Tell your coding agent to use CoBILD before it starts a feature:

Use the cobild MCP server for this work. Start with cobild_process, brainstorm
the spec with me first, write or update SPEC.md or a focused *.spec.md when
we agree, implement only after that, then reconcile the paired state file
before you finish.

The intended loop is:

1. Call cobild_process to load the workflow.
2. Brainstorm with the user until the spec is clear.
3. Create or update SPEC.md or a focused *.spec.md.
4. Implement against the spec.
5. Run cobild_check_repo or cobild_check_staleness.
6. For stale scopes, run cobild_prepare_reconciliation.
7. Compare the changed files to the spec.
8. Finish with cobild_apply_reconciliation.

Scopes

Any SPEC.md or *.spec.md file is a scope. The scope root is the spec file's containing directory. A scope owns its subtree except for nested directories that have their own specs. If SPEC.md and one or more *.spec.md files exist in the same directory, they are separate scopes.

Legacy SPEC.md scopes use STATE.yaml. Arbitrary *.spec.md scopes use the same basename with .state.yaml: auth.spec.md pairs with auth.state.yaml, and cad.intent.spec.md pairs with cad.intent.state.yaml.

Example:

my-app/
  SPEC.md              # top-level product/system spec
  STATE.yaml           # top-level implementation state
  auth.spec.md         # focused auth spec
  auth.state.yaml      # focused auth implementation state
  api/
    SPEC.md            # deeper API-specific spec
    STATE.yaml         # API-specific implementation state

Each state file records:

• the digest of the spec it was reconciled against
• when reconciliation happened
• implementation status for spec components
• concrete drift between the spec and code

This repository is itself a CoBILD scope; see SPEC.md and the adjacent STATE.yaml for a small self-hosted example.

MCP Tools

Tool	Purpose
cobild_process	Return the full CoBILD workflow for agents.
cobild_version	Return the installed package version served by the MCP server.
cobild_list_scopes	List spec scopes under a root.
cobild_check_repo	Check every scope for stale state.
cobild_check_staleness	Check one scope for stale state.
cobild_prepare_reconciliation	Return spec text, previous state, staleness info, and changed file contents.
cobild_apply_reconciliation	Validate and write an updated paired state file.
cobild_init_scope	Create a new scope by writing SPEC.md.

The server also exposes a brainstorm prompt that puts an agent into questions-and-trade-offs mode before implementation.

Python API

from cobild import (
    Scope,
    apply_reconciliation,
    check_staleness,
    find_scopes,
    load_state,
    prepare_reconciliation,
)

scopes = find_scopes("path/to/repo")
scope = scopes[0]

if check_staleness(scope).stale:
    bundle = prepare_reconciliation(scope)
    # The agent compares bundle["spec_text"] with bundle["changed_file_contents"].
    apply_reconciliation(
        scope,
        {
            "summary": "Auth is implemented; rate limiting is still missing.",
            "components": [
                {"name": "auth", "status": "implemented", "files": ["auth.py"]},
                {"name": "rate-limiting", "status": "missing"},
            ],
            "drift": [
                {
                    "kind": "missing",
                    "description": "The spec requires rate limiting.",
                }
            ],
        },
    )

state = load_state(scope)
assert not state.in_sync

Component statuses:

implemented | partial | missing | drifted | extra

Drift kinds:

missing | incomplete | divergent | undocumented | stale-spec

Development

uv sync
uv run pytest
uv build

To run the MCP server from a local checkout:

uv run cobild-mcp

To register a local checkout with an agent:

claude mcp add cobild -- uv run --directory /path/to/cobild cobild-mcp
codex mcp add cobild -- uv run --directory /path/to/cobild cobild-mcp
hermes mcp add cobild --command uv --args run --directory /path/to/cobild cobild-mcp

License

MIT. See LICENSE.