Skip to content

README.md

Latest commit

 

History

History
95 lines (72 loc) · 3.62 KB

README.md

File metadata and controls

95 lines (72 loc) · 3.62 KB

basemap

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

What it does

basemap 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

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

Getting started

# 1. Clone basemap as your workspace
git clone git@github.com:nicolasse/basemap.git my-workspace
cd my-workspace

# 2. Set up your project context
cd features
git init  # or clone an existing features repo
cd ..

# 3. Clone your repos
cd repositories
git clone git@github.com:your-org/repo-a.git
git clone git@github.com:your-org/repo-b.git
cd ..

# 4. Open Claude Code
claude

Three layers of git

basemap separates the framework from the project context from the code:

my-workspace/                ← basemap git (the framework)
  .claude/
    commands/                ← bm- prefixed commands
    agents/                  ← worker agents
  features/                  ← project context git (your team's knowledge)
    CLAUDE.md                ← part of basemap
    _template/               ← part of basemap
    follow-up/               ← your project context
    payments/                ← your project context
  repositories/              ← each repo has its own git
    repo-a/
    repo-b/
Layer What it is Who shares it
basemap (root git) Framework: commands, agents, templates Everyone using basemap
features/ (its own git) Project context: product, engineering, implementation docs Your team working on this project
repositories/ (each its own git) The actual code Depends on the repo

This means you can:

  • Update basemap independently (pull new commands/agents)
  • Share project context with your team without coupling it to basemap
  • Use the same basemap setup for completely different projects

Commands

Command What it does
/bm-add-feature Design and implement a new feature from scratch
/bm-add-use-case Add a use case to an existing feature with contract validation
/bm-map-feature-product Explores repos + talks to you → generates product.md
/bm-map-feature-engineering Explores repos → extracts technical contracts into engineering.md
/bm-map-feature-implementation Explores repos → maps current implementation into implementation.md

Agents

Agent Color What it does
feature-implementer 🔵 blue Writes code scoped to a feature, respecting its contracts
contract-reviewer 🟡 yellow Validates code against product and engineering contracts (read-only)

Workflow

New feature (doesn't exist in code):

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

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

  1. /bm-map-feature-product → generates product.md
  2. /bm-map-feature-engineering → generates engineering.md
  3. /bm-map-feature-implementation → generates implementation.md

Adding behavior to an existing feature:

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