Validate adopt-chio-developer-base playbook with a second-adopter team

[bb-connor]

Goal

Validate vault/playbooks/adopt-chio-developer-base.md by inviting a real adopter team to walk through it cold and find the gaps that only surface when a non-author tries it.

This is also the test of ADR-0001's graduation criteria — "second adopter committed" requires working code, not a verbal commit.

Audience

One of: platform, opus, alpha team. Anyone in Backbay-labs / clusters/* who has a Rust+docs codebase that benefits from a graph + retrieval layer.

What to expect (v0.1.x readiness)

The "Current readiness" table at the top of the playbook has the honest state. TL;DR:

Ready (use confidently):

• The 4-hook plugin contract (SourceIngester, GraphProjector, ToolRegistrar, FrontmatterHandler)
• `Registry.load_entry_points()` autoloading via pyproject.toml
• Engine ↔ pack boundary (CI-enforced; you can't accidentally leak chio_*)
• `chio-dev` CLI (10 subcommands: status / up / down / ingest / sync / query / migrate-seeds / eval / dogfood / session)
• Phase 0 fixture set (38 fixtures, runners scaffolded)

Rough — pin your expectations here:

• Real Postgres+Neo4j ingest works against the docker stack but isn't exercised in CI; `chio-dev ingest --no-postgres --no-neo4j` is the safest way to dry-run
• Vault-sync daemon's GraphitiHttpRouter doesn't ship yet (only NullRouter + JsonlRouter)
• The actual MCP gateway (the 10 `kb_*` tools) is a /health stub; full Phase 1.3+
• ADR-0002 outcome-eval baselines pending — runners return `blocked-input`
• Cross-pack federation is explicitly out of v1 scope

The validation walkthrough

Take the playbook end-to-end as written. We're looking for friction points, not finished output.

1. Step 1: choose path. Read the "Current readiness" table. Decide: `-pack` (1B) is the right path for almost anyone whose domain isn't already covered by chio-pack's labels.
2. Step 2B: copy chio-pack as a template. `cp -R chio-pack platform-pack`. Note every place the playbook says "update X" — flag any you couldn't update without reading source.
3. Step 3: implement at least 2 of 4 plugin hooks. Suggested minimum: `SourceIngester` (recognize your repo's file types) + `GraphProjector` (emit one node per file). Skip `ToolRegistrar` (Phase 1.3+ anyway).
4. Step 4: declare entry point. Add `[project.entry-points."kb_engine.plugins"]` to your pyproject.toml.
5. Step 5: run `chio-dev ingest /path/to/your-repo --no-postgres --no-neo4j`. Verify your Source/Projector hooks fire by reading the JSON output.
6. Step 6: outcome evals. Decide if your domain wants its own outcome eval categories. Document your targets in your pack's `eval/PHASE-0.md` (copy chio-pack's as a starting point).

What we want from you

A short report, written as a GitHub comment on this issue, covering:

• What worked: which playbook steps you completed without asking a question.
• Where you got stuck: every place you had to fall back to reading source code or asking.
• What you actually built: link your pack repo (or fork). At minimum: the SourceIngester + GraphProjector implementations.
• What's missing from the playbook: features / surfaces / docs you needed but didn't find.

Stakeholders

• Maintainer: @bb-connor — answers questions and updates the playbook in real time.
• Validator: TBD — the person taking up this issue. Comment to claim it.

Out of scope

• We are NOT asking for production-grade integration. Stub implementations of the four hooks are enough.
• We are NOT asking for an outcome-eval baseline. PHASE-0.md's bar is for chio-pack alone today.
• We are NOT promising perfect docs. The point is to find the bad parts.

Related

• ADR-0001 — graduation review at Phase 4 explicitly weighs second-adopter signal.
• ADR-0003 — vault-root convention you'll inherit.
• PLAN.md — the full phased delivery; relevant context for what's done vs. planned.