Metadata-Version: 2.4
Name: agentic-bootstrap
Version: 0.4.2
Summary: Bootstrap CLI that hoists the shared agentic-system surface into consumer repos.
Project-URL: Homepage, https://github.com/darce/agentic-protocol-monorepo
Project-URL: Source, https://github.com/darce/agentic-protocol-monorepo/tree/main/packages/agentic-bootstrap
Project-URL: Documentation, https://github.com/darce/agentic-protocol-monorepo/blob/main/docs/CONSUMER.md
Project-URL: Issues, https://github.com/darce/agentic-protocol-monorepo/issues
Author: darce
License: Proprietary
Requires-Python: >=3.11
Requires-Dist: agentic-protocol<0.2.0,>=0.1.4
Requires-Dist: pyyaml>=6
Requires-Dist: tomlkit>=0.13
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# agentic-bootstrap

Pip-installable CLI that hoists the shared agentic-system surface
(typed protocol, two MCP servers, hooks, skills, generated agent
workflows) into consumer repositories. Lives inside
[`darce/agentic-protocol-monorepo`](https://github.com/darce/agentic-protocol-monorepo).

Consumers run `agentic-bootstrap install --target <path>` once; it
clones the monorepo, materializes the overlay, and registers both
managed MCP servers (`mcp-agent-handoff`, `mcp-agent-orchestrator`)
across `.mcp.json`, `.vscode/mcp.json`, and `.codex/config.toml`. No
hand-edits required.

## Install

### From PyPI (recommended)

```bash
uvx --from agentic-bootstrap agentic-bootstrap install --target /path/to/your/repo
# or, persistent:
uv tool install agentic-bootstrap
```

### From the monorepo source tree (development)

```bash
cd packages/agentic-bootstrap
python -m pip install -e ".[dev]"
```

### Direct from git (private-repo phase, before PyPI release)

One-shot (no install — fetches each invocation):

```bash
uvx --from "git+ssh://git@github.com/darce/agentic-protocol-monorepo@agentic-bootstrap-v0.2.1#subdirectory=packages/agentic-bootstrap" \
    agentic-bootstrap install \
    --target /path/to/your/repo
```

Persistent (recommended once you start running `status` / `doctor`
regularly — installs `agentic-bootstrap` onto `$PATH`):

```bash
uv tool install "git+ssh://git@github.com/darce/agentic-protocol-monorepo@agentic-bootstrap-v0.2.1#subdirectory=packages/agentic-bootstrap"
# then:
agentic-bootstrap status --target /path/to/your/repo
agentic-bootstrap doctor --target /path/to/your/repo
# upgrade later:
uv tool upgrade agentic-bootstrap
```

> **Hardlink warning on first install?** If you see
> `Failed to hardlink files; falling back to full copy`, your `uv`
> cache and tool dir live on different filesystems. The install still
> succeeds; silence the warning with `export UV_LINK_MODE=copy` in
> your shell profile.

## Subcommands

```text
agentic-bootstrap install --target <path> [--remote-ref <tag>] [--mcp-servers <default|path>] [--no-mcp-servers]
agentic-bootstrap update  --target <path> --remote-ref <tag>
agentic-bootstrap status  --target <path>
agentic-bootstrap doctor  --target <path> [--mcp-servers <default|path>]
agentic-bootstrap repair  --target <path> [--force-dirty] [--mcp-servers <default|path>]
```

- `install`: Clone the monorepo, materialize SHARED + GENERATED
  surfaces, write the three MCP-config files, run `init-state` to
  provision `<target>/.task-state/handoff.db` (skipped under
  `--no-mcp-servers`), set `core.hooksPath`, and write the overlay
  manifest.
- `update`: Re-run install at a new `--remote-ref`; refresh GENERATED
  surfaces and, optionally, configs.
- `status`: Print a summary of the installed overlay manifest. When
  the install registered MCP servers, also reports the resolved
  `state_dir` / `db_path` / `exports_dir` / `schema_version` via
  `init-state --check`.
- `doctor`: Detect drift in SHARED, GENERATED, config, and
  initialized-state surfaces. Flags missing `.task-state/handoff.db`
  as `state_drift` only when the manifest recorded `.mcp.json`. Exit
  `1` when drift exists.
- `repair`: Restore drifted surfaces flagged by `doctor`.

See [`docs/CONSUMER.md`](https://github.com/darce/agentic-protocol-monorepo/blob/main/docs/CONSUMER.md)
for the consumer-facing walkthrough (upgrade, drift handling, skill
overrides, the `current_task_auto_regen` migration note).

## Surfaces written by `install`

The canonical source of truth for bootstrap-managed surfaces is the
installer implementation in
`src/agentic_bootstrap/install.py` (`SHARED_SURFACES` and
`GENERATED_SURFACES`). Keep this table aligned with those constants.

| Surface                              | Source     | Layer       |
| ------------------------------------ | ---------- | ----------- |
| `scripts/hooks/`                     | shared     | symlink     |
| `.github/hooks/`                     | shared     | symlink     |
| `docs/agentic/contracts/`            | shared     | symlink     |
| `.claude/skills/`                    | generated  | real dir    |
| `.claude/commands/`                  | generated  | real dir    |
| `.github/prompts/`                   | generated  | real dir    |
| `.codex/skills/`                     | generated  | real dir    |
| `.mcp.json`                          | generated  | real file   |
| `.vscode/mcp.json`                   | generated  | real file   |
| `.codex/config.toml`                 | generated  | real file   |
| `core.hooksPath` git config          | generated  | git config  |
| `.task-state/handoff.db`             | runtime    | sqlite      |
| `.task-state/exports/`               | runtime    | dir         |
| `.agentic/remote/`                   | bootstrap  | git clone   |
| `.agentic-bootstrap.json`              | bootstrap  | manifest    |

`.task-state/` is provisioned by the handoff server's `init-state`
subcommand at install time and is gitignored — each fresh checkout
regenerates it through `agentic-bootstrap install`.

## Defaults

- `--remote-url` defaults to `git@github.com:darce/agentic-protocol-monorepo.git`.
- `--remote-ref` defaults to `main` (override with a release tag like `v0.1.0`).
- `--mcp-servers` defaults to the built-in managed map registering
  `mcp-agent-handoff` and `mcp-agent-orchestrator` via `uvx` with
  `--workspace-root . serve-stdio`, so Codex, VS Code, and Claude
  clients start real MCP stdio servers from the generated config.
  Pass a JSON file path to override; pass `--no-mcp-servers` to skip
  the three config writers entirely.

## Development

Tests live under `tests/`. From the monorepo root:

```bash
cd packages/agentic-bootstrap
PYTHONPATH=.:src:../agentic-protocol/src pytest tests -q
```
