# Setup Toolbox Context

> Scaffolds the CONTEXT.md glossary and docs/adr/ directory that grill-with-docs and improve-codebase-architecture expect. Single-context or multi-context layout based on the repo. Use when starting a new project, adopting the CONTEXT.md convention, or invoking /setup-toolbox-context.

- Skill: `orakitine/setup-toolbox-context` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add orakitine/setup-toolbox-context`
- Raw SKILL.md: https://api.skillmd.com/api/skills/orakitine/setup-toolbox-context/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: orakitine (https://skillmd.com/u/orakitine)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/orakitine/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.