# Context protocol (v1)

A shared contract for how agents create, validate, render, persist, and share context.

## artifact locations
- JSON-first artifacts: write to `.claude/context/artifacts/<artifact>.json`.
- Rendered Markdown: write to `.claude/context/artifacts/<artifact>.md`.
- Reasoning logs (shallow, auditable): `.claude/context/history/reasoning/<workflow>/<step>-<agent>.json`.
- Gate records: `.claude/context/history/gates/<workflow>/<artifact-or-step>.json`.

## validation and rendering
- Validate every artifact against its schema using the gate tool:
  - `node .claude/tools/gates/gate.mjs --schema <schema> --input <json> --gate <gatefile> --autofix 1`
- Only after a pass, render Markdown for humans using the renderer:
  - `node .claude/tools/renderers/bmad-render.mjs <type> <json> > <md>`
- Before a PR, run the sweep:
  - `node .claude/tools/ci/validate-all.mjs`

## session updates
- Orchestrator owns `.claude/context/session.json`.
- Persist `route_decision`, `project.workflow`, and `current_context.current_step`.
- Append generated artifact filenames into `artifacts.generated` and list schemas into `artifacts.schemas_used`.

## naming conventions
- Use kebab-case for filenames; keep consistent artifact names per schema:
  - project-brief.json, prd.json, ux-spec.json, system-architecture.json, test-plan.json, review-notes.json
- Prefer one canonical JSON name per schema; keep legacy aliases only where workflows require.

## directory creation
- Create parent directories before writing; tools already mkdir recursively.

## handoff and escalation
- Handoffs use workflow `depends_on` and `escalate_to`.
- On failure after auto-fix, escalate per workflow and record in gate file.

## context reading
- Agents read previous artifacts from `.claude/context/artifacts/` and do not re-ask for information already present.

## reasoning logs (shallow)
- keys: `assumptions`, `decision_criteria`, `tradeoffs`, `open_questions`, `final_decision`.
- Do not include chain-of-thought in main artifacts.