Context Engineering for AI Development
Give your AI assistants (Cursor, Claude, Copilot, Codex, OpenCode, Gemini, Aider, Continue, Windsurf) structured context through markdown files. ContextKit creates a knowledge base that ensures AI generates code matching your exact patterns, style, and architecture—no more hallucinated code or mismatched conventions.
ContextKit is a CLI tool that provides context-engineering capabilities by creating .contextkit/ directories with project standards, guidelines, and patterns that AI assistants read automatically.
Read the full documentation · How context works
The problem: LLMs are great at syntax, not at your conventions. Generic AI output requires manual fixes for style, structure, and architecture.
The solution: ContextKit provides your AI with:
- Glossary of project terminology and domain-specific terms (e.g., your entity, feature, and module names)
- Standards for code style, testing patterns, and architecture
- Templates with canonical component shapes
Update .md files as your project evolves; the AI follows.
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 uses @ imports in CLAUDE.md to load standards content directly into context — no extra token cost from manual file reads.
1. Install the CLI
npm i -g @nolrm/contextkit2. Set up your project
cd your-project
contextkit installCreates .contextkit/ with skeleton standards files, a self-describing README.md, and an attribution block in config.yml 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.
Perfect for teams where members use different AI tools:
# 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
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 copilotEach 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.
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)
- const Checkout = () => <button>Buy</button>
+ export function CheckoutFlow({ customer }: { customer: string }) {
+ // Uses customer from glossary context
+ return <div>Checkout for {customer}</div>
+ }Cursor — rules auto-load from .cursor/rules/, slash commands in .cursor/prompts/
/analyze # scan codebase and generate standards
/review # code review with checklist
/fix # diagnose and fix bugs
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/. Also writes a PostToolUse hook to .claude/settings.json that runs format+lint after every file edit — auto-detected for Node.js (npm/pnpm/yarn/bun), Go, and Python.
/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
codex "create checkout flow for customer"OpenCode — reads AGENTS.md automatically
opencode "create checkout flow for customer"ContextKit installs reusable slash commands for supported platforms:
| Command | What it does |
|---|---|
/analyze |
Scan codebase and generate standards content |
/review |
Code review with checklist |
/fix |
Diagnose and fix bugs |
/refactor |
Refactor code with safety checks |
/test |
Generate comprehensive tests |
/doc |
Add documentation |
/doc-arch |
Generate architecture docs — stack-aware (Level 1). Output: docs/<topic>.md, or docs/architecture.md if no topic given. Pass a topic name, PR number, or leave blank to infer from branch. |
/doc-feature |
Generate feature-level docs (docs/features/<name>.md) — stack-aware (Level 2) |
/doc-component |
Generate component-level docs colocated with the target file — stack-aware (Level 3) |
/spec |
Turn a product overview into an implementation-ready spec — UX flows, DB schema, API contracts, and phased build plan |
/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-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) |
/squad-auto-parallel |
Auto-run the pipeline in parallel using Claude Code agents (Claude Code only) |
/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 |
Claude Code — available as /analyze, /review, 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.
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.
Squad works standalone. If
.contextkit/isn't set up,/squadwill offer to create just.contextkit/squad/so you can use the pipeline without a fullck install.
| 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 |
After discussing a feature or fix with your AI tool, run a single command to go hands-free:
/squad-go
# Reads tasks from the current conversation, confirms the list, writes specs,
# and immediately runs architect → dev → test → review → doc — no second command needed/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 filesPass multiple tasks to /squad and it automatically runs in batch mode:
/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 sequentiallyParallel mode (Claude Code only): Use /squad-auto-parallel instead of /squad-auto to spawn parallel subagents — one per task per phase — so all tasks progress simultaneously rather than one at a time.
/squad "add dark mode" "fix login bug" "refactor checkout"
/squad-auto-parallel
# Phase 1: architect agents for all 3 tasks run in parallel
# Phase 2: dev→test→review pipeline runs in parallel per task; Phase 3: doc runs sequentiallyModel 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.
# .contextkit/squad/config.md
checkpoint: po
model_routing: true # dev + test → Haiku, architect + review → primary modelAny 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.
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.
The spec pipeline turns a high-level product overview into an implementation-ready spec. It runs before the squad — producing the UX flows, DB schema, API contracts, and phased build plan that make stories possible.
/spec # Start or continue — picks up the next unchecked scope automatically
/spec 02-jobs # Run a specific scope by name
/spec --redo 01-identity-auth # Re-run a completed scope from scratch/spec reads a product overview file (PROJECT_OVERVIEW.md, OVERVIEW.md, BRIEF.md, or any .md file you point it to) and runs a multi-round pipeline for each scope:
| Round | Who runs | What happens |
|---|---|---|
| 0 — Brief | CTO | Reads the overview, defines scope boundaries, writes a brief all agents share |
| 1 — Domain experts | UX, Data, Systems, Planner (parallel) | Each produces their section independently from the brief |
| 2 — Challenges | CTO | Reads all four sections, writes challenges — gaps, contradictions, missing decisions |
| 3 — Revisions | UX, Data, Systems, Planner (parallel) | Each addresses the CTO's challenges, flags unresolvable items as OPEN DECISIONs |
| Final — Author | CTO | Resolves open decisions, writes the unified SPEC.md |
Each scope produces a folder with all working artifacts and a final SPEC.md:
spec/
PROGRESS.md ← scope checklist, updated after each run
INDEX.md ← master TOC linking all SPEC.md files
01-identity-auth/
00-brief.md ← CTO's scoping brief
01-ux.md ← UX flows and screens
02-data.md ← DB schema and relationships
03-systems.md ← API contracts and services
04-plan.md ← build phases and stories
05-challenges.md ← CTO's Round 2 challenges
SPEC.md ← final unified spec for this scope
Run /spec once per scope. Each run appends to spec/INDEX.md. When all scopes are done, feed individual SPEC.md files into /squad as implementation tasks.
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 spec/PROGRESS.md which acts as the checklist for all subsequent runs.
If no standard overview file is found, /spec lists all .md files in the directory and asks you to pick.
ContextKit installs two kinds of hooks. Git hooks (pre-push, commit-msg) enforce quality at push time for the whole team. For Claude Code installs, a PostToolUse hook is also written to .claude/settings.json — it runs format+lint after every file edit in a Claude Code session, catching failures immediately rather than at push time.
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 format |
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 |
Use ck gates to inspect or toggle individual checks without editing config files manually:
ck gates # list all gates and their status
ck gates --disable prettier # disable a specific gate
ck gates --enable prettier # re-enable itGate state is saved to .contextkit/quality-gates.yml. Commit this file to share gate preferences with your team.
When the commit-msg hook is enabled, all commits must follow this format:
<type>(<scope>): <description>
Types: feat, fix, improve, docs, refactor, test, chore
Examples:
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.
ContextKit can automatically turn GitHub issues into pull requests — no local development required.
How it works:
- Label any issue
squad-ready - GitHub Actions runs the full squad pipeline (architect → dev → test → review) using Claude
- A draft PR is opened, linked to the issue
Setup:
ck install # answer "yes" to the CI squad promptThen 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-readylabel after answering a clarification comment to re-trigger the pipeline
- 🧠 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
# 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)
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 overwrites your standards or glossary
ck update --force # also regenerate user-owned files (standards, glossary)
# updates are also flagged automatically after each ck command (24h cache)
ck status # check install & integrations
# 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
• 🐛 Issues • 💬 Discussions
MIT
Marlon Maniti
GitHub: @nolrm