/context-bootstrap

Generate the initial context graph from the current codebase. This is the most important command — it creates the foundation that all other context-graph commands build on.

Workflow

Step 1: Check for Existing Graph

Check if .claude/context-graph/ already exists.

• If it exists: Warn the user that a graph already exists. Ask whether to rebuild from scratch (destructive) or incrementally add new entities. If rebuilding, back up the existing index.md as index.md.bak before proceeding.
• If it does not exist: Create the directory structure:

  .claude/context-graph/
    index.md
    schema.md
    entities/
  

Step 2: Load References

Read the following files for entity format and conventions:

• ${CLAUDE_PLUGIN_ROOT}/skills/knowledge-management/references/entity_schema.md
• ${CLAUDE_PLUGIN_ROOT}/skills/knowledge-management/references/graph_conventions.md

Step 3: Discover Project Structure

Use Glob and Read to scan the codebase. Start broad, then narrow down:

1. Project metadata: Read package.json, Cargo.toml, pyproject.toml, go.mod, Gemfile, build.gradle, pom.xml, or equivalent — whichever exists. Extract project name, dependencies, and scripts.

2. Documentation: Read README.md, CLAUDE.md, ARCHITECTURE.md, docs/ directory — extract high-level architecture, conventions, and design decisions.

3. Source structure: Glob for top-level source directories (src/, lib/, app/, pkg/, internal/, cmd/). Identify major modules/components by directory structure.

4. Configuration: Glob for config files (.env.example, docker-compose.yml, k8s/, terraform/, Dockerfile, CI configs). Identify infrastructure and deployment patterns.

5. Database/Data models: Glob for schema files (migrations/, prisma/schema.prisma, models/, schemas/, *.graphql, *.proto). Identify data models.

6. External integrations: Grep for API client configurations, SDK imports, webhook handlers. Identify third-party integrations.

7. Tests: Glob for test directories to understand test coverage and test strategy.

If $ARGUMENTS contains --depth shallow, scan only project metadata, documentation, and top-level source directories. If --depth deep (default), perform the full scan.

If $ARGUMENTS contains --focus "area", prioritize files and directories related to that area.

Step 4: Identify Entities

From the discovered information, identify entities to create. Aim for 5-20 entities depending on project size.

Priority order:

1. project-context — One entity for the project overview (always created)
2. component — One per major module, service, or subsystem
3. data-model — One per significant data structure or database table
4. infrastructure — One per deployment target, database, cache, or queue
5. integration — One per external service or API
6. decision — One per significant architectural decision found in docs or code comments

Naming rules:

• Use kebab-case: auth-service, not AuthService or auth_service
• Be specific: postgres-primary, not database
• Decision entities use verb phrases: adopt-typescript, use-monorepo

Step 5: Create Entity Files

For each identified entity, create a file in .claude/context-graph/entities/ following the entity schema:

# {Entity Name}
**Type:** {type}
**Created:** {today's date YYYY-MM-DD}
**Last Updated:** {today's date YYYY-MM-DD}
**Tags:** {relevant tags}

## Summary
{2-5 sentences about this entity}

## Properties
- **Owner:** {team or "unassigned"}
- **Status:** {active|planned|in-progress}
- **Files:** {list of relevant file paths}
- **Dependencies:** {list of other entity names}

## Relations
{typed relations to other entities using [[link]] syntax}

## Notes
{gotchas, historical context, non-obvious info}

Ensure relations are bidirectional: if A depends-on B, then B should have consumed-by A.

Step 6: Create Schema File

Write .claude/context-graph/schema.md documenting the entity types and relation types used:

# Context Graph Schema

## Entity Types
- **component** — A module, service, or subsystem
- **data-model** — A database table, schema, or data structure
- **decision** — An architectural or design decision
- **infrastructure** — A deployment, hosting, or ops resource
- **integration** — An external service or API integration
- **project-context** — High-level project information

## Relation Types
- **depends-on** — Requires this entity to function
- **consumed-by** — Used by this entity
- **decided-by** — Governed by this decision
- **replaces** — Supersedes this deprecated entity
- **implements** — Realizes this specification
- **tested-by** — Has test coverage from this entity

Step 7: Build Index

Write .claude/context-graph/index.md listing all entities grouped by type:

# Context Graph Index

> Auto-generated by /context-bootstrap on {date}. {N} entities.

## Project Context
- [[project-overview]] — High-level project summary and conventions

## Components
- [[auth-service]] — Handles authentication and authorization
- [[api-gateway]] — Routes and rate-limits API traffic

## Data Models
- [[user-model]] — User account and profile data

## Infrastructure
- [[postgres-primary]] — Primary PostgreSQL database

## Integrations
- [[stripe-integration]] — Payment processing via Stripe API

## Decisions
- [[adopt-jwt-tokens]] — JWT tokens for API authentication

Entities within each section are sorted alphabetically.

Step 8: Report

Tell the user:

• How many entities were created, broken down by type
• Any areas of the codebase that were ambiguous or need manual entity creation
• Suggest running /context-map to generate the visual dependency graph
• Suggest reviewing entities and adding any missing relations or context