# contextkit/ — ContextDevKit platform

This folder is the AI-assisted development platform installed by
[ContextDevKit](https://github.com/reiTavares/ContextDevKit). It is a **bounded
context** separate from your product code — everything here exists to make
Claude Code sessions reliable, self-documenting, and consistent across time.

## Layout

| Path | What |
| --- | --- |
| `runtime/hooks/` | Claude Code hooks (boot context, edit ledger, drift nudge, L5 gate) |
| `runtime/config/` | Zero-dep config loader, defaults, paths, settings composer, optional zod schema |
| `runtime/git-hooks/` | `pre-commit` (reindex), `commit-msg` (Conventional Commits), `pre-push` (block real conflicts) |
| `runtime/providers/review/` | PR/review CLI adapters (`gh` ships) — see ADR-0021 |
| `runtime/providers/media/` | Media generation adapters — `nano-banana` (Imagen 3) + `veo` (Veo 3); see ADR-0024 |
| `runtime/state/` | Canonical `state.json` substrate for tasks + pipeline runs (ADR-0015) |
| `tools/scripts/` | 50+ helpers (reindex, dashboard, sync-check, audits, media-gen, …) |
| `memory/decisions/` | ADRs — generated/validated by the canonical Decision CLI; see `memory/decisions/README.md` |
| `memory/sessions/` | One markdown file per work session — the *what* |
| `memory/SESSIONS.md` | Auto-generated index (do not hand-edit) |
| `memory/WORKSPACE.md` | Auto-generated active-claims index (do not hand-edit) |
| `memory/GLOSSARY.md` | Domain term ↔ code identifier |
| `memory/preferences/personalization.md` | User-owned, explicit project instructions; seeded once and never overwritten |
| `memory/preferences/owner-preferences.json` | Existing structured, recommendation-only owner preference store |
| `memory/workflows/` | Workflow spec packs: PRD/PDR, SPEC, ADR/task indexes, handoffs, reports |
| `pipeline/` | DevPipeline lanes: `backlog/ → working/ → testing/ → conclusion/` |
| `workflows/playbooks/` | Reusable procedures (tanstack, landing-page, seo-aiso, tech-debt-sweep, …) |
| `squads/agent-forge/` | The L6+ "agent that builds agents" (Agent Package pipeline) |
| `config.json` | Level + ledger path lists + L5 params (edit via `/context-config`) |
| `.env.example` | Optional credentials template (`/media-gen` Google AI Studio keys) |

## The 7 levels

The active level is `config.json` → `level`. See `/context-level` to inspect or
change it. Higher levels add capability — earlier ones stay active.

1. **Memory** — boot context, session log, ADRs, changelog.
2. **Ledger** — drift detection (tracks edits, nudges you to `/log-session`).
3. **Multi-session** — claims, worktrees, derived indices, git hooks.
4. **Squads** — 28 specialized sub-agents organised into 7 squads (devteam,
   qa-team, design-team with `seo-specialist` + `landing-architect`,
   security-team, compliance-team, ops-team, agent-forge).
5. **Proactive** — `/simulate-impact` gate on high-risk paths, tech-debt sweep,
   distill-detect nudge, contract drift.
6. **Autonomy & Insight** — `/ship`, `/retro`, `/context-stats`, agent-forge squad.
7. **Ecosystem** — `/fleet` multi-repo control plane, `/tune-agents`,
   visual tests, playbook runner.

## Requirements

- **Node.js ≥ 18** (the hooks/scripts — Levels 1–3 need zero npm packages).
  **Node 20.6+** unlocks `--env-file` for the media-gen credentials flow.
- **git** (for divergence detection and Level 3 git hooks).
- `zod` is optional, only for strict `/context-config` validation at Level 5.
- *Optional:* `gh` (GitHub CLI) for sync-check PR awareness;
  `GOOGLE_AI_API_KEY` for `/media-gen`.

## Updating the engine

Re-run the kit installer over the project to pull engine updates. It never
modifies user-authored memory (ADRs, executed workflows, sessions, roadmap,
business rules, project docs), your config overrides, pipeline tasks, or either
file under `memory/preferences/`. In `CLAUDE.md`, `AGENTS.md`, and
`INSTRUCTIONS.md`, only the dedicated ContextDevKit personalization-reference
block may be refreshed atomically; all owner prose outside that block remains
byte-preserved. Derived artifacts such as the project-map may be generated or
refreshed transactionally when safe (deferred if active sessions or a
self-update are detected):

```bash
npx contextdevkit@latest --target . --update
# or, offline / from GitHub:
npx github:reiTavares/ContextDevKit --target . --update
```

Use `--allow-active-sessions` to proceed with active sessions detected (a
snapshot is taken to `~/.contextdevkit/projects/<id>/backups/` first).
Use `--allow-self-update` when updating the kit's own source repo. Both flags
are required when both risks apply.

`--update` also refreshes the installed kit README through the conflict-safe
manifest path and regenerates `docs/README.md`. Your product's root `README.md`
stays yours.

## CompozyOS and Graphify interoperability

ContextDevKit passively detects `.compozy/config.toml` and
`graphify-out/graph.json`. It does not execute either tool, install their
dependencies, or rewrite their hooks/instructions. ContextDevKit remains the
sole authority for workflow state, governance gates, approvals, claims, tests,
QA, and durable evidence; CompozyOS coexistence is passive until an explicit
governed execution adapter is implemented.

File discovery uses `graphify -> native -> project-map-find`. Graphify is a
bounded read-only optimization; unsafe, malformed, stale, partial, or empty
evidence releases the next provider automatically. `/context-doctor` reports
detected tools and host-surface overlap without activating them.

## Project personalization

Put durable project instructions in `memory/preferences/personalization.md`.
Keep bounded structured preferences in the existing
`memory/preferences/owner-preferences.json`; that JSON is recommendation-only
and never authorizes work. Both files are user-owned, created only when absent,
and preserved across normal updates and `--force`. Native host roots point to
them instead of copying personalized content into generated base instructions.
Current system, developer, and user instructions plus platform safety
boundaries always take precedence.

## Workflow spec packs

Use `/workflow new <slug>` for large features and architecture changes. It
creates `memory/workflows/<slug>/` with PRD/PDR, SPEC, ADR/task indexes,
handoff memory, and dated daily reports.

```text
intake -> prd -> spec -> adr -> roadmap(if feature) -> pipeline -> ship -> testing -> conclusion
```

The pack is not a second board. ADRs stay in `memory/decisions/`, roadmap stays
in `memory/roadmap.md`, and execution stays in `pipeline/`. Link cards back with
`pipeline.mjs add --workflow <slug> --spec contextkit/memory/workflows/<slug>/spec.md`.

## Quick references

- **Slash commands** — see `.claude/commands/README.md` for the taxonomy.
- **Provider adapters** — `runtime/providers/{review,media}/_adapter.mjs`
  document the contract.
- **Playbooks** — `workflows/playbooks/` for reusable procedures.
- **Setup credentials for `/media-gen`** — copy `.env.example` to `.env`, fill
  in `GOOGLE_AI_API_KEY`, run with `node --env-file=contextkit/.env ...`.