# devcontract

Evidence-backed **Team Engineering Contract** + guided AI workflows (Understand, Build), served over **MCP stdio** so Grok, Claude Code, Codex, Kiro, and Cursor share the same tools.

```bash
npx -y devcontract
```

Requires **Node.js 22+** and `git` on PATH. Build plans need `XAI_API_KEY` (xAI / SpaceXAI). Understand is deterministic and works without a key.

## First onboarding

In the git repo you want the agent to learn (not in this package unless you are dogfooding):

```bash
npm install -g devcontract
cd your-service
devcontract init
```

That compiles the Team Engineering Contract, writes `.devcontract/` (gitignored except README), and prints MCP snippets.

Then hook Codex once per machine:

```bash
codex mcp add devcontract -- devcontract
codex mcp list
codex
```

In Codex: `/mcp` should show `devcontract`. Ask: *Why does `<file>` exist? Use dev.understand.*

Optional: `devcontract init --write` drops `.codex/config.toml` / `.mcp.json` into the repo (Codex project config only applies after the directory is trusted).

## Status

v0.1.1. Working now:

- `devcontract init` — first-run onboarding
- `devcontract` (no args) — MCP stdio with `dev.understand`
- `devcontract contract compile` — Team Engineering Contract from git artifacts
- `devcontract understand <path-or-ticket>` — cited git history (no API key)

Still stubbed: `build`, `approve`, `run`.

Product overview: [docs/PRODUCT.md](docs/PRODUCT.md)  
Design: [docs/DESIGN.md](docs/DESIGN.md)

## MCP clients

**Claude Code / Cursor** — `.mcp.json` or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "devcontract": {
      "command": "npx",
      "args": ["-y", "devcontract"]
    }
  }
}
```

**Codex / Grok** — project MCP config, `command = "npx"`, `args = ["-y", "devcontract"]`, `startup_timeout_sec = 60`.

**Kiro** — best-effort `.kiro/settings/mcp.json` (same JSON shape).

Put `XAI_API_KEY` in the host environment. Do not commit it.

## CLI

```text
npx -y devcontract              # MCP stdio (default)
npx -y devcontract --help
npx -y devcontract init
npx -y devcontract contract compile
npx -y devcontract understand <path-or-ticket>
npx -y devcontract build <ticket>
npx -y devcontract approve <runId>    # TTY only; not an MCP tool
npx -y devcontract run <runId> [--resume]
```

## Develop

```bash
npm install
npm test
npm run build
```

License: Apache-2.0