ctx
A context layer for multi-repo workspaces. Maps features across repositories with product definitions, engineering contracts, and implementa
Open source Open in the app JSON README (API)
About
A context layer for multi-repo workspaces. Maps features across repositories with product definitions, engineering contracts, and implementation docs — designed for AI-assisted development.
Details
- Kind
- Plugins
- Topic
- Maps, weather & travel
- Publisher
- nicolasse
- Origin
- marketplace
- Category
- ferramentas
- Last push
- 2026-04-08T01:40:48Z
- Repository state
- ativo
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
nicolasse/ctx/ctx
README
# 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](https://docs.anthropic.com/en/docs/claude-code/plugins). Add the marketplace and install:
```bash
claude plugin marketplace add nicolasse/ctx
claude plugin install ctx
```
To test locally during development:
```bash
claude --plugin-dir ./ctx
```
## Getting started
```bash
# 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:
```bash
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`):
```bash
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.