Skip to content

Design Notes

Status

Placeholder for initial design notes on context retention.

Purpose

This document is the working note for how workspace-mcp should retain stable context that helps agents and maintainers recover architecture, tooling, and operational intent without broad repo scanning.

It complements:

  • docs/architecture.md for the high-level model
  • WORKSPACE_MCP_ARCHITECTURE.md for the fuller architecture note
  • docs/context/contracts.md for boundaries and rules
  • docs/context/workflows.md for stable operating paths

ADR Review Notes

Current state in this repo:

  • no dedicated docs/adr/ directory exists yet
  • ADRs are treated as part of the expected repo contract
  • architecture guidance currently lives in docs/architecture.md and WORKSPACE_MCP_ARCHITECTURE.md

Implication:

  • the repo already assumes ADR-style authority, but still needs an explicit ADR index and decision-record location if decisions are to be retained systematically

Initial Context Retention Policy

Retain only stable, reusable context in versioned documents. Prefer small indexes and routing documents over large narrative dumps.

Recommended retained context categories:

  1. Architecture
  2. system model
  3. authority order
  4. major components

  5. boundary decisions

  6. Tools

  7. MCP resources and tools
  8. registry generation scripts
  9. server entrypoints

  10. local operating commands

  11. Contracts

  12. manifest schema expectations
  13. repo participation requirements

  14. compatibility and migration rules

  15. Workflows

  16. discovery flow
  17. provisioning flow

  18. update and validation flow

  19. Decisions

  20. ADR index
  21. individual decision records for changes that affect authority, routing, schema, or compatibility

Proposed Document Set

Suggested baseline set for context retention in this repo:

  • docs/architecture.md
  • docs/context/design-notes.md
  • docs/context/contracts.md
  • docs/context/workflows.md
  • docs/context/capabilities.md
  • docs/adr/index.md
  • docs/adr/ADR-0001-context-retention-policy.md

Initial Design Questions

  • What qualifies as durable context versus session-only working notes?
  • Which decisions require a formal ADR instead of a design-note update?
  • Should tool descriptions live in one consolidated catalog or next to each implementation area?
  • How should generated registry artifacts be documented versus regenerated?

Next Notes To Author

  • ADR index placeholder
  • first ADR for context retention and authority precedence
  • tool catalog for server, scripts, and generated registry flows
  • ownership note for who can change schemas, manifests, and routing behavior