agentic-bootstrap

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.

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)

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)

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):

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):

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

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 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.

.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

• --profile defaults to all, which materializes the full surface set: per-agent generated surfaces (.claude/skills, .claude/commands, .github/prompts, .codex/skills), shared overlay symlinks, and the lifecycle hoist (Makefile.d/lifecycle.mk plus the sentinel-bracketed -include block in the consumer Makefile). Pass --profile minimal for a clone-only install with no surfaces, or --profile lifecycle for just the lifecycle runner and Makefile fragment. The active profile is recorded in .agentic-bootstrap.json under "profile".
• --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:

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