cobild 0.1.0

Collaborative Brainstorming and LLM Development — spec-driven development with a brainstorming phase and agent-managed state documents

CoBILD — Collaborative Brainstorming and LLM Development

CoBILD is a form of spec-driven development with two additions:

1. Brainstorming mode. Before any implementation, the user and the agent collaborate on the spec — clarifying questions, alternatives, trade-offs — and capture the converged result in SPEC.md.
2. An agent-managed state document. Each spec scope has a .state.yaml recording how the actual implementation relates to the spec: which components are implemented, partial, missing, or drifted. It is analogous to React's virtual DOM: just as the virtual DOM makes a declarative UI interface efficient, the state document makes a declarative interface to agentic coding efficient — the agent reads the state document instead of re-deriving the codebase's relationship to the spec, and reconciles only when files have actually changed.

Scopes

Any directory containing a SPEC.md is a scope. A repo typically has a top-level SPEC.md; subdirectories may add their own for more detail. A scope owns its subtree minus nested scopes, and each scope has its own .state.yaml next to its spec.

How reconciliation works

A scope is stale when its .state.yaml is missing, older than the most recent file change in the scope, or its recorded spec digest no longer matches SPEC.md. Reconciliation takes the changed files, the spec, and the previous state, and produces an updated state document. The mechanical parts (staleness detection, context bundling, validation, writing) live in this library; the judgment (comparing code to spec) is done by the agent.

Python API

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

scopes = find_scopes("path/to/repo")        # every dir with a SPEC.md
reports = check_repo("path/to/repo")        # staleness report per scope

scope = scopes[0]
if check_staleness(scope).stale:
    bundle = prepare_reconciliation(scope)  # spec text, prior state, changed files
    # ... agent compares bundle["spec_text"] against the changed files ...
    apply_reconciliation(scope, {
        "summary": "Auth and routing implemented; rate limiting pending.",
        "components": [
            {"name": "auth", "status": "implemented", "files": ["auth.py"]},
            {"name": "rate-limiting", "status": "missing"},
        ],
        "drift": [
            {"kind": "missing", "description": "spec requires rate limiting"},
        ],
    })

state = load_state(scope)
state.in_sync  # False — drift recorded

apply_reconciliation validates the document (component statuses: implemented | partial | missing | drifted | extra; drift kinds: missing | incomplete | divergent | undocumented | stale-spec) and stamps the spec digest and timestamp automatically.

MCP server

The cobild-mcp stdio server helps agents follow the process:

Tool	Purpose
cobild_process	The full process guide: brainstorm → SPEC.md → implement → reconcile
cobild_list_scopes	All scopes under a root, with state-file presence
cobild_check_repo / cobild_check_staleness	Is .state.yaml older than the latest changes?
cobild_prepare_reconciliation	Spec text + previous state + changed files for a stale scope
cobild_apply_reconciliation	Validate and write the updated state document
cobild_init_scope	Capture a brainstormed spec as a new SPEC.md

It also exposes a brainstorm prompt that puts the agent into brainstorming mode (questions and trade-offs only, no code) until the user signs off on the spec.

Register with Claude Code:

claude mcp add cobild -- uv run --directory /path/to/cobild cobild-mcp

Development

uv sync          # install dependencies
uv run pytest    # run the test suite