# ContextKit
> Token-Efficient Context Engineering + Agentic AI Pipelines
ContextKit gives your AI assistants (Cursor, Claude, Copilot, Codex, OpenCode, Gemini, Aider, Continue, Windsurf) structured context through markdown files—and gives you a multi-role autonomous pipeline (PO → Architect → Dev → Test → Review → Doc) to execute work with those same agents. The context layer is what keeps the pipeline grounded: agents read your standards, so they never hallucinate your conventions.
ContextKit is a CLI tool with two capabilities: **context engineering** (`.contextkit/standards/` + platform bridge files so every AI tool reads your project conventions automatically) and **squad pipelines** (a six-role agentic workflow grounded by those same standards).
**[Read the full documentation](https://contextkit-docs.vercel.app/)** · **[How context works](https://contextkit-docs.vercel.app/docs/how-context-works)**
## Why ContextKit?
**The problem:** LLMs are good at syntax, not at _your_ conventions — and multi-agent pipelines amplify that. An autonomous dev agent that doesn't know your architecture, naming, or testing patterns will produce code you have to fully rewrite.
**The solution — two pillars that reinforce each other:**
**Pillar 1: Context engineering**
- **Glossary** — project terminology and domain-specific entity names
- **Standards** — code style, testing patterns, architecture rules
- **Templates** — canonical component shapes
- **Platform bridges** — auto-generated `CLAUDE.md`, `AGENTS.md`, `.windsurfrules`, etc. so every AI tool reads the same context without manual setup
- **Token-efficient by design** — tiered loading (core standards always on, the rest on-demand via skills), a `compress` skill to retrofit oversized docs, and a `response_style` config to tune chat/doc density per project
**Pillar 2: Agentic squad pipeline**
- A six-role pipeline (PO → Architect → Dev → Tester → Reviewer → Doc Writer) runs in a single AI session
- Each role reads the context layer before acting — no hallucinated conventions
- Run `/squad "add dark mode"` then `/squad-auto` and walk away
Update your `.md` standards as your project evolves; every agent that runs after picks up the change automatically.
## Multi-Platform Support
Works with: **Cursor** • **Claude Code** • **GitHub Copilot** • **Codex CLI** • **OpenCode** • **Gemini CLI** • **Aider** • **Continue** • **Windsurf**
Each platform gets auto-loaded bridge files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.windsurfrules`, etc.) so your AI tools read project standards automatically. Claude Code and Codex always-load `code-style.md` and `architecture.md` via `@` imports; testing, workflows, AI-behavior rules, terminology, decisions, and roadmap load on demand the first time a matching skill triggers, instead of every session. Other platforms still auto-load the full standards set.
---
## Quick Start (60s)
**1. Install the CLI**
```bash
npm i -g @nolrm/contextkit
```
**2. Set up your project**
```bash
cd your-project
contextkit install
```
Creates `.contextkit/` with skeleton standards files, a self-describing `README.md`, and an attribution block in `config.yml` (including a `response_style` toggle for chat terseness and doc diagrams) so any developer who encounters the folder knows what manages it.
**3. Generate your standards**
Run `/analyze` in your AI tool — it scans your codebase and fills the skeleton files with your project's conventions.
Done. Your AI tools now have project-specific context.
---
## Multi-Team Workflow
Perfect for teams where members use different AI tools:
```bash
# First team member - sets up the project with their tool
contextkit install claude # or: contextkit install (interactive picker)
# Each additional team member adds their platform
ck claude # creates CLAUDE.md + .claude/rules/ — skips if already up to date
ck cursor # creates .cursor/rules/ (scoped .mdc files) — skips if already up to date
ck copilot # creates .github/copilot-instructions.md
ck codex # creates AGENTS.md + .codex/skills/ (24 skills)
ck opencode # creates AGENTS.md
ck gemini # creates GEMINI.md + .gemini/settings.json
ck aider # creates CONVENTIONS.md + .aider/rules.md
ck continue # creates .continue/rules/ + config.yaml
ck windsurf # creates .windsurfrules + .windsurf/rules/
ck vscode # alias for copilot
```
Each platform generates bridge files that the AI tool auto-reads. If a bridge file already exists (e.g., you have a custom `CLAUDE.md`), ContextKit appends its section below your content instead of overwriting. Share your `.contextkit/standards/*.md` files with the team and everyone gets the same context.
---
## See the difference (before → after)
**Prompt**
```
"Add checkout flow for customer"
```
**What the AI does with ContextKit**
- Reads `glossary.md` → `checkout` = checkout process; `customer` = customer account
- Applies `code-style.md` → strict TS, functional components
- Follows `testing.md` → testing levels, change-driven test selection, numbered test cases
**Result (diff)**
```diff
- const Checkout = () =>
+ export function CheckoutFlow({ customer }: { customer: string }) {
+ // Uses customer from glossary context
+ return
Checkout for {customer}
+ }
```
---
## Use it in your tool
**Cursor** — rules auto-load from `.cursor/rules/`, slash commands in `.cursor/prompts/`
```
/analyze # scan codebase and generate standards
/review # code review with checklist
```
**Claude Code** — `CLAUDE.md` uses `@` imports to auto-load all standards into context every session (no manual reads needed, saves tokens). Skills in `.claude/skills/`.
```bash
/analyze # scan codebase and generate standards
/review # code review with checklist
claude "create checkout flow for customer"
```
**GitHub Copilot** — reads `.github/copilot-instructions.md` automatically
```
@.contextkit Create checkout flow for customer
```
**Codex CLI** — reads `AGENTS.md` automatically + skills in `.codex/skills/`
```bash
codex "create checkout flow for customer"
# Skills available: $spec, $squad, $squad-auto, $squad-spec, $analyze, $ck, and more
```
**OpenCode** — reads `AGENTS.md` automatically
```bash
opencode "create checkout flow for customer"
```
---
## Slash Commands
ContextKit installs reusable slash commands for supported platforms:
| Command | What it does |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `/analyze` | Scan codebase and generate standards content |
| `/doc-arch` | Generate architecture docs — stack-aware (Level 1). Output: `docs/.md`, or `docs/architecture.md` if no topic given. Pass a topic name, PR number, or leave blank to infer from branch. Proposes a split if the file grows too long. |
| `/doc-feature` | Generate feature-level docs (`docs/features/.md`) — stack-aware (Level 2). Proposes a split if the file grows too long. |
| `/doc-component` | Generate component-level docs colocated with the target file — stack-aware (Level 3). Proposes a split if the file grows too long. |
| `/compress` | Measure a file's size, rewrite it for information density, and report the before/after diff |
| `/spec` | Turn a product overview into a reference spec — data model, API contracts, UX flows, and squad-ready stories. Single CTO pass per scope. |
| `/spec-component` | Write a component spec (MD-first) before any code is created |
| `/squad` | Kick off a squad task — one task or many (auto-detects batch mode). Pushes back with clarifying questions if the task is vague. |
| `/squad-architect` | Design the technical plan from the PO spec |
| `/squad-dev` | Implement code following the architect plan |
| `/squad-test` | Classify test levels, write and run tests against acceptance criteria |
| `/squad-review` | Review the full pipeline and give a verdict |
| `/squad-doc` | Create companion `.md` files for new/modified code after review passes |
| `/squad-spec [scope]` | Run all stories in a spec scope through the full pipeline, retrying automatically on review failure before pausing for input. On Claude Code, each phase runs as its own isolated Task subagent — Review defaults to Haiku since it's checking already-written acceptance criteria, not designing anything. With a slug, runs that scope only. Without a slug, runs ALL completed scopes in sequence automatically. Claude Code: use with `/loop /clear /squad-spec` (context clearing matters — stories add up fast). Codex: use `/goal`, which clears context between turns natively. |
| `/squad-go` | Extract tasks from the current conversation and run the full pipeline immediately — no second command needed |
| `/squad-auto` | Auto-run the full pipeline after `/squad` kickoff (sequential) |
| `/ck` | Health check — verify setup, standards, and integrations |
| `/agent-push-checklist` | Pre-push quality checklist for agents to self-check before `git push` |
| `/context-budget` | Prioritized guide for which standards files to load for a given task |
| `/standards-aware` | Decide whether and how to add a newly discovered pattern to the project's standards files. Also checks `corrections.md` first and offers to self-run `ck update` when the install is stale. |
| `/product-context` | Load architecture decisions and roadmap context before proposing changes that might conflict with a prior decision or plan |
**Claude Code** — available as `/analyze`, `/squad`, etc. via `.claude/skills/`
**Cursor** — available as slash commands in Chat via `.cursor/prompts/`
Both platforms delegate to the universal command files in `.contextkit/commands/`, so you maintain one set of workflows.
---
## Squad Workflow
The squad workflow turns a single AI session into a structured multi-role pipeline. Each role has its own slash command that reads and writes to a shared handoff file (`.contextkit/squad/handoff.md`), simulating a team of specialists.
Because state lives in plain markdown on disk instead of an in-memory session, handoff files survive closing the terminal, context compaction, even switching tools mid-pipeline — start a task in Claude Code, pick it up in Codex or Cursor tomorrow.
> **Squad works standalone.** If `.contextkit/` isn't set up, `/squad` will offer to create just `.contextkit/squad/` so you can use the pipeline without a full `ck install`.
### Pipeline Roles
| Step | Role | Command | What it does |
| ---- | ------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Product Owner | `/squad` | Writes a user story, acceptance criteria, edge cases, and scope. If the task is ambiguous, asks up to 5 clarifying questions before writing the spec. Optionally captures screenshots/images as visual assets. |
| 2 | Architect | `/squad-architect` | Designs the technical approach, files to change, and implementation steps |
| 3 | Developer | `/squad-dev` | Implements the code following the architect's plan |
| 4 | Tester | `/squad-test` | Writes and runs tests against the PO's acceptance criteria |
| 5 | Reviewer | `/squad-review` | Reviews everything and gives a PASS or NEEDS-WORK verdict |
| 6 | Doc Writer | `/squad-doc` | Creates companion `.md` files for every new/modified code file |
### Conversation-First Flow
After a planning conversation, `/squad` extracts the agreed tasks automatically — no need to retype them:
```bash
/squad # scans the conversation, shows extracted tasks, confirms before writing specs
/squad "let's do this" # directive phrase — same behaviour, not treated as a task
/squad-go # same as above but immediately runs the full pipeline after specs — no second command needed
```
Phrases like "let's do it", "go ahead", "let's go" are recognised as directives and trigger conversation extraction. Quoted task descriptions bypass extraction and go straight to the PO spec.
### Single-Task Flow
```bash
/squad "add dark mode support" # PO writes the spec
/squad-auto # Auto-runs architect → dev → test → review → doc
# — or step through manually —
/squad-architect # Architect designs the plan
/squad-dev # Dev implements the code
/squad-test # Tester writes and runs tests
/squad-review # Reviewer gives the verdict
/squad-doc # Doc Writer creates companion .md files
```
### Batch Flow
Pass multiple tasks to `/squad` and it automatically runs in batch mode:
```bash
/squad "add dark mode" "fix login bug" "refactor checkout"
# PO writes specs for all three tasks
/squad-auto
# Runs Architect → Dev → Test → Review → Doc for each task sequentially
```
**Model routing (Claude Code only):** Set `model_routing: true` in `.contextkit/squad/config.md` to have `/squad-auto` automatically use Claude Haiku for Dev and Test phases. Architect and Review always run on your primary model. Saves ~35% tokens with no quality loss — the standards files and Review gate maintain quality.
Each task is committed individually right after its Doc phase, before `/squad-auto` moves on to the next one — staged from that task's own Changes Made/Tests Written/Doc Notes, Conventional Commits format, skipped cleanly if there's nothing to commit or no git repo.
```markdown
# .contextkit/squad/config.md
checkpoint: po
model_routing: true # dev + test → Haiku, architect + review → primary model
```
### Feedback Loop
Any downstream role can raise questions for an upstream role. When this happens, the pipeline pauses and directs you to the right command:
```
Reviewer has questions for Dev → run /squad-dev to clarify
Tester has questions for Architect → run /squad-architect to clarify
Architect has questions for PO → run /squad to clarify
```
After clarifications are added, re-run the asking role's command to continue. This prevents misunderstandings from compounding through the pipeline.
### Visual Assets (Optional)
If you have a screenshot, mockup, or design image relevant to the task, paste or attach it when running `/squad`. The PO agent will save it to `.contextkit/squad/assets/` and reference the path in the handoff. Architect and Dev agents automatically read any listed assets when they pick up the handoff.
---
## Spec Pipeline
The spec pipeline turns a high-level product overview into a full reference spec — data model, API contracts, UX flows, and squad-ready stories. It runs before the squad, one scope at a time.
```bash
/spec # Start or continue — picks up the next unchecked scope automatically
/spec OVERVIEW.md # Start a new spec from a specific file (prompts before archiving an existing spec)
/spec 02-jobs # Run a specific scope by name
/spec --redo 01-identity-auth # Re-run a completed scope from scratch
/spec --reset # Delete the entire .contextkit/spec/ folder and start over
/spec --add analytics # Append a new scope and run it immediately
/spec --extend 02-jobs # Add new stories to an existing scope's SPEC.md
```
### How It Works
Each `/spec` run is a single inline CTO pass — no sub-agents, no revision rounds. The CTO reads the overview and any prior scope specs (for consistency), then writes the full `SPEC.md` for that scope.
Each `SPEC.md` contains: data model (full schema + ERD), API contracts (all endpoints with request/response), UX flows (key journeys and edge cases), a story table with sizes and dependencies, and copy-paste `/squad` commands for every story.
### Output Structure
Each scope produces one `SPEC.md`. Progress and index files track the full project:
```
.contextkit/spec/
PROGRESS.md ← scope checklist, updated after each run
INDEX.md ← links to every completed SPEC.md
01-identity-auth/
SPEC.md ← full spec for this scope
02-jobs-scheduling/
SPEC.md
```
### First Run
On the first run, the CTO reads the entire overview and identifies all logical scopes — ordering them by dependency (identity before marketplace, invoicing before tax). This produces `.contextkit/spec/PROGRESS.md` which acts as the checklist for all subsequent runs.
You can also pass the overview file directly: `/spec MY_OVERVIEW.md`. If an existing spec is detected from a different file, you'll be prompted before anything is archived.
### From Spec to Squad
Each `SPEC.md`'s `## Stories` section has an `### Acceptance Criteria` block per story (EARS format — `WHEN [event], the system SHALL [response]`) followed by `### Squad Commands` — copy-paste `/squad` commands for every story. Run them one at a time, or use `/squad-spec` to implement scopes automatically:
```bash
# Option 1 — one story at a time
/squad "S1 — Workspace schema: create workspaces table with RLS policies"
/squad-auto
# Option 2 — single scope, context-safe
/loop /clear /squad-spec 01-identity-auth # Claude Code
/goal complete every story in scope 01-identity-auth via /squad-spec # Codex
# Option 3 — all scopes in sequence, fully automatic
/loop /clear /squad-spec # Claude Code
/goal complete every story in every scope via /squad-spec # Codex
```
Both drive `/squad-spec` repeatedly and clear context between stories, so a scope with many stories won't blow the context window. Claude's `/loop /clear` re-invokes on an interval; Codex's `/goal` keeps working autonomously until the stated condition holds, then stops on its own.
Within a story, Claude Code dispatches each phase (Architect/Dev/Test/Review/Doc) as its own isolated Task subagent — Review runs on Haiku by default, checking each EARS-format acceptance criterion individually against the diff. Codex runs phases inline in the current context; no subagent isolation there yet. At the end of each scope, the full-suite regression gate runs in the foreground with serial/low parallelism rather than backgrounded at max workers, so it doesn't saturate your machine while confirming the scope is clean before the next one starts.
Each story is committed individually right after its Doc phase passes, before moving to the next story — Conventional Commits format, staged from that story's own Changes Made/Tests Written/Doc Notes rather than a blanket `git add -A`, so history stays bisectable and revertable per story instead of landing as one scope-sized commit. If a story's spec lists open questions blocking it, Architect resolves them itself and records the assumption plus rationale under Open Question Resolutions in the handoff — squad-spec runs unattended, so there's no human mid-run to escalate to.
---
## Hooks & Quality Gates
ContextKit installs **Git hooks** (pre-push, commit-msg) that enforce quality at push time for the whole team.
ContextKit can optionally install Git hooks during `ck install`. Uses `git config core.hooksPath` to point Git at `.contextkit/hooks/` — no external dependencies like Husky required. Works in any git repo, not just Node.js projects.
If an existing hooks manager is detected (Husky, Lefthook, simple-git-hooks, an existing `core.hooksPath`, or scripts in `.git/hooks/`), `ck install` will suggest how to integrate rather than overriding your setup.
For **Node.js projects**, a `prepare` script is automatically added to `package.json` so hooks activate for all developers after `npm install` — no need for everyone to run `ck install`.
If you enable the pre-push hook on a Node.js project that has no `format` or `lint` scripts, `ck install` will offer to scaffold a minimal **prettier + eslint** setup for you (adds scripts, `.prettierrc`, `.prettierignore`, `eslint.config.js`, and installs the devDependencies). Answer No to skip and set it up manually later.
| Hook | What it does |
| -------------- | --------------------------------------------------------------------------------------- |
| **pre-push** | **Quality Gates** — auto-detects your project framework and runs the appropriate checks |
| **commit-msg** | Enforces [Conventional Commits](https://www.conventionalcommits.org/) format |
### Framework-Aware Quality Gates
The pre-push hook detects your project type and runs the right quality checks automatically. All gates are skipped silently when tools aren't installed.
| Framework | Checks |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Node.js** | TypeScript, ESLint, Prettier, `format` script, `lint` script, build, test, e2e — each only runs when present in `package.json` scripts or dependencies; auto-detects npm/yarn/pnpm/bun |
| **Python** | ruff/flake8, mypy, black/ruff format, pytest |
| **Rust** | cargo check, clippy, cargo test |
| **Go** | go vet, golangci-lint, go test |
| **PHP** | PHPStan, PHPUnit |
| **Ruby** | RuboCop, RSpec/rake test |
| **Java** | Maven verify / Gradle check |
| **Kotlin** | ktlint, Gradle test |
| **Swift** | SwiftLint, swift test |
| **.NET / C#** | dotnet build, dotnet test |
### Managing Gates
Use `ck gates` to inspect or toggle individual checks without editing config files manually:
```bash
ck gates # list all gates and their status
ck gates --disable prettier # disable a specific gate
ck gates --enable prettier # re-enable it
```
Gate state is saved to `.contextkit/quality-gates.yml`. Commit this file to share gate preferences with your team.
### Commit Message Format
When the `commit-msg` hook is enabled, all commits must follow this format:
```
():
```
**Types:** `feat`, `fix`, `improve`, `docs`, `refactor`, `test`, `chore`
**Examples:**
```bash
git commit -m "feat(auth): add login page"
git commit -m "fix: resolve null pointer in checkout"
git commit -m "docs: update API reference"
git commit -m "test(cart): add edge case coverage"
```
Hooks are optional and can be skipped with `ck install --no-hooks`.
---
## CI Squad — GitHub Issues → PR
ContextKit can automatically turn GitHub issues into pull requests — no local development required.
**How it works:**
1. Label any issue `squad-ready`
2. GitHub Actions runs the full squad pipeline (architect → dev → test → review) using Claude
3. A draft PR is opened, linked to the issue
**Setup:**
```bash
ck install # answer "yes" to the CI squad prompt
```
Then add your Anthropic API key as a repository secret:
> **Settings → Secrets and variables → Actions → New repository secret**
> Name: `ANTHROPIC_API_KEY`
**Tips:**
- Write issues with clear acceptance criteria for the best results
- If the issue is too vague, the workflow posts a comment asking for clarification instead of generating a bad PR
- PRs always open as **draft** — you review and merge manually
- Re-apply the `squad-ready` label after answering a clarification comment to re-trigger the pipeline
---
## Key Features
- 🧠 **Context Engineering** - Structured MD files your AI reads automatically
- 🔍 **Smart Analysis** - AI generates standards content based on your codebase
- 🌍 **Project Agnostic** - Works with React, Vue, Node.js, PHP, Python, Rust, monorepos—any project type
- 🤖 **Multi-Platform** - Works with Cursor, Claude Code, Copilot, Codex, OpenCode, Gemini, Aider, Continue, Windsurf
- 🛡️ **Safe Install** - Backs up existing files with rollback support
- ⚡ **Zero Config** - Auto-detects project type and package manager
- ✅ **Policy Enforcement** - Configurable validation with `ck check`
- 📝 **Corrections Tracking** - Track AI performance issues with corrections log
- ⚙️ **Configurable Output** - Tune chat terseness and doc diagrams per project via `config.yml`
## Commands
```bash
# Installation & Setup
ck install # set up .contextkit + pick AI tool interactively
ck install claude # set up .contextkit + Claude, or add Claude to an existing install
ck install --force # regenerate all files, including user-customized standards
ck claude # add or refresh Claude integration — skips if already up to date
ck cursor # add or refresh Cursor integration — skips if already up to date
ck copilot # add GitHub Copilot integration
ck codex # add Codex CLI integration (AGENTS.md + .codex/skills/)
ck opencode # add OpenCode integration (AGENTS.md)
ck gemini # add Gemini CLI integration (GEMINI.md)
ck aider # add Aider integration (CONVENTIONS.md)
ck continue # add Continue integration
ck windsurf # add Windsurf integration (.windsurfrules)
ck vscode # alias for copilot
# Analysis & Updates
/analyze # customize standards to your project (slash command in your AI tool)
ck update # pull latest commands/hooks — never bulk-overwrites your standards or glossary (may patch specific unedited sections, see CHANGELOG)
ck update --force # also regenerate user-owned files (standards, glossary)
# updates are also flagged automatically after each ck command (24h cache),
# on git push (pre-push hook nudge, 24h cache), and in-session via /standards-aware
# (which offers to run ck update itself when stale)
ck status # check install & integrations
# Global Skills — squad/spec skills shared across all your projects, no per-repo install
ck install --global # install all squad + spec skills to ~/.claude/skills/
ck install --global squad # install just the squad family
ck install --global spec # install spec + spec-component
ck update --global # regenerate/overwrite currently installed global skills
ck check --global # list installed global skills + flag version drift
ck uninstall --global squad # remove them (--all for everything; no name/--all lists instead of deleting)
# Validation & Compliance
ck check # validate installation & policy compliance
ck check --strict # treat warnings as errors
# Corrections Logging
ck note "message" # add note to corrections log
ck note "AI issue" --category "AI Behavior" --priority HIGH
# Squad — multi-role AI pipeline (slash commands in your AI tool)
/squad "add dark mode" # PO writes spec
/squad-auto # runs architect → dev → test → review → doc hands-free
/squad-reset # clear stuck or mixed squad state
```
## Links
• 🐛 [Issues](https://github.com/nolrm/contextkit/issues)
• 💬 [Discussions](https://github.com/nolrm/contextkit/discussions)
---
## License
MIT
## Author
**Marlon Maniti**
GitHub: [@nolrm](https://github.com/nolrm)