@nolrm/contextkit

ContextKit

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

Why ContextKit?

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.

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 uses @ imports in CLAUDE.md to load standards content directly into context — no extra token cost from manual file reads.

Quick Start (60s)

1. Install the CLI

npm i -g @nolrm/contextkit

2. Set up your project

cd your-project
contextkit install

Creates .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.

Multi-Team Workflow

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 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)

- const Checkout = () => <button>Buy</button>
+ export function CheckoutFlow({ customer }: { customer: string }) {
+   // Uses customer from glossary context
+   return <div>Checkout for {customer}</div>
+ }

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
/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"

Slash Commands

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.

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.

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

Express Flow (conversation-first)

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

Single-Task Flow

/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:

/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

Parallel 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 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.

# .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 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

How It Works

/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

Output Structure

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.

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 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.

Hooks & Quality Gates

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

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:

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:

<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.

CI Squad — GitHub Issues → PR

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 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

Commands

# 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

Links

• 🐛 Issues • 💬 Discussions

License

MIT

Author

Marlon Maniti
GitHub: @nolrm