Metadata-Version: 2.4
Name: cobild
Version: 0.3.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
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
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: 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`:

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

```sh
uvx --from cobild cobild-mcp
```

For Claude Code:

```sh
claude mcp add cobild -- uvx --from cobild cobild-mcp
```

For Codex:

```sh
codex mcp add cobild -- uvx --from cobild cobild-mcp
```

For Hermes Agent:

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

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

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

Generic MCP JSON configuration:

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

## Agent Workflow

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

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

```text
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](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

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

```text
implemented | partial | missing | drifted | extra
```

Drift kinds:

```text
missing | incomplete | divergent | undocumented | stale-spec
```

## Development

```sh
uv sync
uv run pytest
uv build
```

To run the MCP server from a local checkout:

```sh
uv run cobild-mcp
```

To register a local checkout with an agent:

```sh
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](LICENSE).
