ctx

A context layer for multi-repo workspaces. Maps features across repositories with product definitions, engineering contracts, and implementation docs — designed for AI-assisted development.

What it does

ctx sits on top of your repos and gives AI agents (and humans) a structured way to understand features that span multiple services. Each feature gets three files:

• product.md — what the feature does, use cases, business rules
• engineering.md — technical contracts, key interfaces, constraints
• implementation.md — how it's actually built today, key files, flows

Skills use these files to implement new use cases, review contracts, and map existing code — all without losing context across repos.

Install

This is a Claude Code plugin. Add the marketplace and install:

claude plugin marketplace add nicolasse/ctx
claude plugin install ctx

To test locally during development:

claude --plugin-dir ./ctx

Getting started

# 1. Create a workspace directory
mkdir my-project && cd my-project

# 2. Clone your repos at the root level
git clone git@github.com:your-org/repo-a.git
git clone git@github.com:your-org/repo-b.git

# 3. Open Claude Code and init
claude
# then: /ctx:init

/ctx:init asks for your project name, sets up the workspace structure, explores all repos, and generates a workspace map.

Skills

Skill	What it does
/ctx:init	Name the project, set up workspace, explore repos, generate workspace map
/ctx:add-index	Deep scan all repos and generate _ctx/index.md — the big-picture project map
/ctx:export	Scan repos and export _ctx/config.json with repo list and context link
/ctx:pull-repos	Clone repos from config.json into the workspace root
/ctx:add-feature	Design and implement a new feature from scratch
/ctx:add-use-case	Add a use case to an existing feature with contract validation
/ctx:modify-feature	Modify an existing feature — loads context, implements changes, validates, updates docs
/ctx:map-product	Explores repos + talks to you → generates product.md
/ctx:map-engineering	Explores repos → extracts technical contracts into engineering.md
/ctx:map-implementation	Explores repos → maps current implementation into implementation.md
/ctx:update	Update workspace scaffolding files (CLAUDE.md, templates) to latest plugin version

Workspace structure

my-project/
  _ctx/                      ← project context (its own git)
    WORKSPACE.md             ← generated by ctx-init
    index.md                 ← generated by ctx-add-index
    config.json              ← repo list for ctx-pull-repos
    follow-up/               ← feature context
      product.md
      engineering.md
      implementation.md
  repo-a/                    ← repos live at the root
  repo-b/

Automatic Routing

Users don't need to remember slash commands. When a user asks to work on a feature, route automatically:

1. Resolve: list directories under _ctx/ (skip _template/), match the request semantically.
2. Route:

Situation	Skill
Feature exists in _ctx/, user wants to change it	ctx:modify-feature
Feature does not exist, user wants to build something new	ctx:add-feature
Feature exists, user wants to add a new use case	ctx:add-use-case
User asks to map/document a feature	Ask: "All three files (product, engineering, implementation) or a specific one?" Then run the matching ctx:map-* skill(s)
No _ctx/WORKSPACE.md	ctx:init
Need project index	ctx:add-index
Need to export/share	ctx:export
Need to clone repos	ctx:pull-repos

Workflow

First time:

1. /ctx:init — names project, explores repos, generates WORKSPACE.md
2. /ctx:add-index — deep scans all repos, generates _ctx/index.md
3. /ctx:export — scans repos and generates _ctx/config.json

Existing feature (already in code, needs context files):

1. /ctx:map-product → generates product.md
2. /ctx:map-engineering → generates engineering.md
3. /ctx:map-implementation → generates implementation.md

New feature (doesn't exist in code):

1. /ctx:add-feature — designs product + engineering, implements, validates, documents

Adding behavior to an existing feature:

1. /ctx:add-use-case — implements, validates contracts, updates context files

Modifying an existing feature:

1. /ctx:modify-feature — describe the change, implements it, validates, updates context files

Sharing the workspace:

1. /ctx:export — generates _ctx/config.json with all repo URLs
2. Push the _ctx/ repo to GitHub
3. Others clone it and run /ctx:pull-repos to get all repos

Updating

To update the plugin:

claude plugin marketplace update nicolasse-ctx && claude plugin update ctx@nicolasse-ctx

To create a shell alias for quick updates, add this to your ~/.zshrc (or ~/.bashrc):

alias ctx-update="claude plugin marketplace update nicolasse-ctx && claude plugin update ctx@nicolasse-ctx"

Then reload your shell (source ~/.zshrc) and run ctx-update anytime.