setup-toolbox-context

# Purpose Scaffolds the domain-documentation convention that `grill-with-docs` and `improve-codebase-architecture` rely on: a `CONTEXT.md` glossary at the repo root (or per bounded context) and a `docs/adr/` directory for architecture decision records. Detects existing state, asks only when the layout is genuinely ambiguous, and creates stubs lazily so the repo never carries empty placeholder files. ## Workflow 1. **Explore Current State** - Check the repo for existing context and ADR scaffolding before writing anything - Files to detect: `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/`, and any `src/*/CONTEXT.md` (signals a multi-context repo) - Example: `ls CONTEXT*.md docs/adr/ 2>/dev/null; find src -maxdepth 3 -name "CONTEXT.md" 2>/dev/null` - Report findings concisely to the user before touching anything 2. **Determine Layout** - IF: `CONTEXT-MAP.md` exists OR multiple `src/*/CONTEXT.md` files exist → multi-context layout, skip to step 4 - IF: `CONTEXT.md` exists at root → single-context layout, skip to step 4 - IF: neither exists AND user passed `--single` or `--multi` → use that - IF: neither exists AND no flag → ask user once: "Single context (one CONTEXT.md at root) or multi-context (CONTEXT-MAP.md + per-module CONTEXT.md, typically a monorepo)?" Default to single-context — most repos are. - Example: monorepo with `src/ordering/`, `src/billing/`, `src/fulfillment/` directories → recommend multi-context 3. **Create Stubs Lazily** - Do NOT create empty files. Only create scaffolding when there is real content to put in it. - IF: single-context AND no `CONTEXT.md` exists → ask user for the first 1-3 domain terms they want to define, then create `CONTEXT.md` with those terms following the format in `../grill-with-docs/references/CONTEXT-FORMAT.md` - IF: multi-context AND no `CONTEXT-MAP.md` exists → ask user for the names and one-line descriptions of their bounded contexts, then create `CONTEXT-MAP.md` pointing at where each lives - IF: `docs/adr/` does not exist → create the directory with a single `docs/adr/README.md` stub that explains the convention and links to `../grill-with-docs/references/ADR-FORMAT.md`. Do NOT create `0000-template.md` or empty placeholder ADRs. - Example: user gives "Order, Invoice, Customer" → write `CONTEXT.md` with those three terms, each with a one-line description and `_Avoid_:` aliases the user provides 4. **Update CLAUDE.md or AGENTS.md (Optional)** - IF: a `CLAUDE.md` or `AGENTS.md` exists at the repo root AND does not already mention CONTEXT.md - THEN: ask user whether to add a short "Domain Documentation" section pointing at `CONTEXT.md` and `docs/adr/`. Default: yes. - Example: append a section like "## Domain Documentation\n- `CONTEXT.md` is the project glossary; reach for it before introducing new terms.\n- `docs/adr/` records architectural decisions. See `setup-toolbox-context` and `grill-with-docs` for the conventions." - Skip silently if no agent-instructions file exists — don't create one just for this. 5. **Report and Hand Off** - List the files created or modified, with absolute paths - Suggest the next move: invoke `/grill-with-docs` to start populating the glossary and recording ADRs from real conversations - Example: "Created `/path/to/CONTEXT.md` with 3 seed terms. Created `/path/to/docs/adr/` with README stub. Next: run `/grill-with-docs` on your current design conversation to grow the glossary and capture ADRs inline." ## References ### CONTEXT.md format and rules - IF: writing the initial `CONTEXT.md` or `CONTEXT-MAP.md`, or deciding what belongs in the glossary - THEN: Read `../grill-with-docs/references/CONTEXT-FORMAT.md` - EXAMPLES: - "what does a CONTEXT.md entry look like?" - "how do I structure a multi-context repo?" - "should this go in CONTEXT.md or an ADR?" ### ADR format and when to record - IF: writing the `docs/adr/README.md` stub or explaining the ADR convention - THEN: Read `../grill-with-docs/references/ADR-FORMAT.md` - EXAMPLES: - "what does an ADR look like?" - "when is something ADR-worthy?" - "how should ADRs be numbered?" ## Works well with This skill is the substrate the methodology family reads. Run it once; the rest degrade gracefully without it (falling back to plain language). - **`grill-with-docs`** — reads and writes the `CONTEXT.md` and `docs/adr/` this scaffolds. - **`living-plan`**, **`tdd`**, **`improve-codebase-architecture`**, **`zoom-out`** — all consume the `CONTEXT.md` glossary and/or `docs/adr/` decisions it creates.