ContextKit

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

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

- 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

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 + skills in .codex/skills/

codex "create checkout flow for customer"
# Skills available: $spec, $squad, $squad-auto, $squad-spec, $analyze, $ck, and more

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
/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 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. With a slug, runs that scope only. Without a slug, runs ALL completed scopes in sequence automatically. Use with /loop /clear /squad-spec.
/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

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

Conversation-First Flow

After a planning conversation, /squad extracts the agreed tasks automatically — no need to retype them:

/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

/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

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 a full reference spec — data model, API contracts, UX flows, and squad-ready stories. It runs before the squad, one scope at a time.

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

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 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 ends with a ### Squad Commands section — copy-paste /squad commands for every story. Run them one at a time, or use /squad-spec to implement scopes automatically:

# 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

# Option 3 — all scopes in sequence, fully automatic
/loop /clear /squad-spec

---

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:

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:

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