Context Management

Your project depends on external services, APIs, and libraries. Context management gives agents structured knowledge about these dependencies so they make decisions based on real documentation, not training data.

Why this matters

When an Executor writes code that integrates with Stripe, or a Reviewer checks that your Auth0 flow follows best practices, they need current documentation. Without it, agents fall back on training data — which may be outdated, incomplete, or wrong for your specific version.

The context/ directory is a structured knowledge base that sits at your project root. Agents read it automatically during planning and execution.

The context directory

Each external system gets its own subdirectory with a consistent layout:

context/
├── README.md                     # Index of all external systems
├── stripe/
│   ├── docs/                     # API docs, webhook guides, specs
│   │   ├── api-reference.md
│   │   └── webhook-guide.md
│   └── code/                     # Git submodules, SDKs, samples
│       └── stripe-node/          # (git submodule)
├── auth0/
│   ├── docs/
│   │   └── oidc-flow.md
│   └── code/
└── internal-api/
    ├── docs/
    │   └── api-spec.md
    └── code/

Adding external systems

/uc:context-management add stripe

This creates the directory structure and asks what information to add — API docs, SDK submodule, configuration guides, or all of the above.

Documentation from URLs

When you provide a URL, the skill fetches key content via Ref.tools and saves it as structured markdown. No raw HTML dumps — it extracts and organizes the facts that matter.

/uc:context-management add auth0 OIDC flow documentation

Code references and SDKs

Add git submodules for SDKs and libraries your project depends on:

/uc:context-management add submodule https://github.com/stripe/stripe-node

Submodules land in context/{system}/code/ and can be updated later with /uc:context-management update submodules.

How agents use context

During planning — Feature mode and debug mode read context/ to understand what external services your system integrates with and how
During execution — Executors read context docs to write correct integration code. Reviewers check that integrations follow the documented patterns.
/uc:research skill — when the Lead or any planning mode invokes research, it consults context/ for project-specific system details and Ref.tools for external library docs, caching results under documentation/technology/research/

Context is not documentation. The context/ directory lives at the project root, separate from documentation/. It contains reference material about external systems — not your own specs, architecture, or standards. Think of it as "things we depend on" vs "things we build."

What to add

Good candidates for the context directory:

System type	What to include	Example
Payment provider	API reference, webhook events, SDK	Stripe, PayPal
Auth provider	OIDC/OAuth flows, token handling, SDK	Auth0, Clerk, Supabase Auth
Database	Query patterns, migration guides, ORM docs	Prisma, Drizzle, Supabase
Internal API	OpenAPI spec, endpoint docs, auth scheme	Your own microservices
Cloud services	SDK docs, config patterns, IAM setup	AWS, GCP, Cloudflare
Third-party APIs	Rate limits, response formats, error codes	SendGrid, Twilio, OpenAI

File naming conventions

API references: api-reference.md, api-v2.md
Guides: {topic}-guide.md (e.g., webhook-guide.md)
Specs: {topic}-spec.md (e.g., openapi-spec.md)
Config: configuration.md, {topic}-config.md
Migration: migration-{from}-to-{to}.md

Keep files focused — one topic per file, under 200 lines. Include the source URL at the top of each file so agents know where the information came from.

Managing git submodules

Git submodules let you include external code repositories as references:

# Add a submodule
/uc:context-management add submodule https://github.com/stripe/stripe-node

# Update all submodules to latest
/uc:context-management update submodules

Submodules are added with your confirmation (they modify .gitmodules). They're useful for having SDK source code available locally so agents can read actual implementations, not just API docs.

Generating an overview

/uc:context-management summarize context

Scans all systems and regenerates context/README.md with a comprehensive index — what each system provides, what documentation is available, and what code references exist.