Metadata-Version: 2.4
Name: cobild
Version: 0.1.0
Summary: Collaborative Brainstorming and LLM Development — spec-driven development with a brainstorming phase and agent-managed state documents
Keywords: spec-driven-development,mcp,agents,llm,ai
Author: Scott Purdy
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Dist: mcp>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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

```python
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:

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

## Development

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