ContextKit

Better project context for your AI coding tools

ContextKit gives your AI assistants (Claude Code, Codex, Cursor, Copilot, Gemini, OpenCode, Aider, Continue, Windsurf) your project's conventions through plain markdown files: one canonical AGENTS.md, a short always-loaded index, topic standards that load only where they apply, quality-gate git hooks, and five small skills.

Read the full documentation · How context works

Why ContextKit?

The problem: LLMs are good at syntax, not at your conventions. An agent that doesn't know your architecture, naming, or testing patterns writes code you have to rewrite — and loading every rule into every session wastes the context it needs for the task.

The solution: give the agent the right context, in the right place, and nothing more.

• One main file — AGENTS.md is canonical and written by every integration. CLAUDE.md, GEMINI.md, and the other tool files import or mirror it, so every tool reads the same context.
• Short always-loaded index — .contextkit/standards/index.md (≤ 50 lines): what the project is, must/must-not rules, exact commands, and a "when you touch X → read Y" table.
• Path-scoped topic standards — testing, code style, and other topic files load only when the agent works on matching paths (context_rules).
• Quality gates — pre-push and commit-msg hooks that check the code before it leaves your machine.
• Five skills — /ck, /doc, /learn, plus the /goal and /headline add-ons.

Update your .md standards as your project evolves; every session after picks up the change.

Multi-Platform Support

Works with: Claude Code • Codex CLI • Cursor • GitHub Copilot • Gemini CLI • OpenCode • Aider • Continue • Windsurf

Every integration writes AGENTS.md. Tools that don't read it natively get a bridge file: CLAUDE.md and GEMINI.md import it with @AGENTS.md; .github/copilot-instructions.md, .windsurfrules, and CONVENTIONS.md carry the same body.

---

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 config.yml, plus AGENTS.md and the bridge files for the tools you pick.

3. Generate your standards

Run /ck setup in your AI tool — it scans your codebase and writes the standards, index.md, and context_rules for your project.

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 (imports AGENTS.md) + .claude/skills/ + .claude/rules/
ck cursor      # creates .cursor/rules/ (scoped .mdc files) + .cursor/prompts/
ck copilot     # creates .github/copilot-instructions.md + .github/instructions/
ck codex       # creates AGENTS.md + .codex/skills/ + .agents/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

If a bridge file already exists (e.g., you have a custom CLAUDE.md), ContextKit writes its section inside <!-- Generated by ContextKit --> markers below your content instead of overwriting. Share your .contextkit/standards/*.md files with the team and everyone gets the same context.

AGENTS.md is the canonical context file. It tells the agent what to read first (index.md, any active goal, corrections.md), lists the topic standards to read when relevant, and lists the skills.

---

See the difference (before → after)

Prompt

"Add checkout flow for customer"

What the AI does with ContextKit

• Reads index.md → sees "touching src/checkout/ → read glossary.md"
• Reads glossary.md → checkout = checkout process; customer = customer account
• Applies code-style.md → strict TS, functional components

Result (diff)

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

---

Context Rules

Topic standards load only for the paths they apply to. Map them in .contextkit/config.yml (/ck setup writes this for you):

context_rules:
  - file: standards/testing.md
    paths: ["**/*.test.*", "**/*.spec.*", "**/__tests__/**"]
  - file: standards/code-style.md
    paths: ["src/**", "lib/**", "app/**", "packages/**"]

ck update --force (or ck <platform>) renders each rule in the tool's own format:

Tool	File	Scope field
Claude Code	.claude/rules/contextkit-<name>.md	paths:
Cursor	.cursor/rules/contextkit-<name>.mdc	globs:
GitHub Copilot	.github/instructions/contextkit-<name>.instructions.md	applyTo:

Stale contextkit-* rule files are removed; your own rule files are left alone.

---

Slash Commands

ContextKit installs five skills — /name in Claude Code and Cursor, $name in Codex:

Skill	Usage	What it does
/ck	/ck, /ck setup, /ck update, /ck tidy	Status. setup analyzes the codebase and writes standards, index.md, and context_rules. update finishes an upgrade after ck update, asking before each change. tidy shrinks always-loaded context, prunes generic or linter-enforced rules, wires orphan guides into context_rules, and promotes repeated corrections.
/doc	/doc, /doc arch, /doc feature [name], /doc component <path>	No argument: finds docs and standards that reference code changed on this branch and updates the stale ones. With a level: writes architecture, feature, or component docs.
/learn	/learn "rule" or /learn	Turns a correction into one rule in the right .contextkit/standards/ file and logs it via ck note.
/goal (add-on)	/goal "idea", /goal, /goal status, /goal done	Runs a long task against a one-page goal file. See Long-running tasks.
/headline (add-on)	/headline, /headline off, /headline pause	Short, result-first replies, always on. See Add-ons.

All platforms delegate to the same command files, so you maintain one set of workflows.

---

Long-running tasks (/goal)

/goal "idea" creates a one-page goal file at .contextkit/goals/<slug>.md (frontmatter status: active|paused|done):

Section	Owner	Content
Goal	—	2–3 sentences
Outcomes	You	3–7 checkable, user-side outcomes
Checks	Agent	How each outcome is verified; refined while building
Constraints / Non-goals	—	Boundaries
Open Decisions	—	Multiple-choice questions
Changes	—	Dated log of every change to Outcomes or Checks, with the reason
Progress	Agent	Done / next / blocked

Flow

1. Kickoff drafts the outcomes and asks up to 4 multiple-choice questions per round. You approve the outcomes.
2. The agent builds in its own loop — plan, edit, test, fix — and re-reads the goal file every session and after compaction.
3. Internal check changes are logged; user-visible changes (scope, UX, dropping an outcome) are asked first.
4. Each outcome gets tests plus a fresh-context review subagent on the same model that sees only the goal file, the outcome ID, and the diff. Max 3 review rounds, then it asks you.
5. One commit per outcome, then status: done and a summary.

Strong models plan, build, and test best in their own loop. What they still need is a durable goal, checkable done criteria, and an independent check.

Goal docs

---

Add-ons

/goal and /headline don't need the rest of ContextKit. Share them on their own:

ck install --global goal       # writes ~/.claude/skills/goal/
ck install --global headline   # writes ~/.claude/skills/headline/

Both also ship in the Claude Code plugin.

/headline

Faster-to-read replies. ck install writes this block into AGENTS.md (and the Copilot, Windsurf, and Aider mirror files) between <!-- headline:start --> and <!-- headline:end -->:

• Lead with the result or answer.
• Don't narrate reasoning or recap what you did.
• Plain sentences; tables only when comparing.
• Ask with options, not open-ended questions.
• Say plainly when something failed or was skipped.
• Code, commands, and paths stay complete — only prose gets shorter.

Grammar stays normal. Skip it with ck install --no-headline, or set headline: false in .contextkit/config.yml and run ck update.

Headline docs

---

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 format

When ck is on your PATH, the pre-push hook also runs ck check --context as a non-blocking warning.

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

ck install writes .contextkit/quality-gates.yml with every gate enabled and commented out under disabled:. Uncomment a gate's key to turn it off for the whole team:

disabled:
  # - prettier        # skip Prettier (direct, not via script)
  # - test            # skip npm test

Commit this file to share gate preferences with your team.

Already-verified code skips the gates. When every gate passes on a clean working tree, the hook records a fingerprint of that exact code (the commit's tree plus your gate config). Pushing the same code again skips the gates instead of re-running the full suite — e.g. a re-push after a rejected push, or an agent that already verified by running .contextkit/hooks/pre-push < /dev/null before pushing. Any file change or gate-config change forces a full run. CK_FORCE_GATES=1 git push always runs them.

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.

---

Key Features

• 🧠 Context Engineering - One canonical AGENTS.md, a short index, and path-scoped standards
• 🔍 Smart Analysis - /ck setup writes standards content based on your codebase
• 🌍 Project Agnostic - Node.js (React, Vue, etc.), Python, Rust, Go, PHP, Ruby, Java, Kotlin, Swift, .NET/C#, monorepos—any project type
• 🤖 Multi-Platform - Works with Claude Code, Codex, Cursor, Copilot, Gemini, OpenCode, Aider, Continue, Windsurf
• 🛡️ Safe Install - Backs up existing files with rollback support
• ⚡ Zero Config - Auto-detects project type and package manager
• ✅ Stale-Context Checks - ck check flags instructions pointing at missing files or removed skills, and oversized always-loaded context
• 📝 Corrections Tracking - /learn and ck note turn AI mistakes into rules

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 install --no-headline  # skip the always-on headline block
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
/ck setup      # customize standards to your project (skill in your AI tool)
ck analyze     # detects framework/monorepo scope, prints the setup prompt + codebase context
               # to paste into an AI tool with no skill support for /ck setup
ck update             # pull latest commands/hooks — never bulk-overwrites your standards or glossary
ck update --force     # also regenerate user-owned files (standards, glossary)
ck status      # check install & integrations
ck usage       # which skills get used, from local Claude Code + Codex session logs
               # (--days 90, --all for every project, --json; local only)

# Global Skills — the /goal and /headline add-ons, shared across all your projects
ck install --global           # install both to ~/.claude/skills/
ck install --global goal      # install just /goal (or: headline)
ck update --global            # regenerate installed global skills; removes retired ones
ck check --global             # list installed global skills + flag version drift
ck uninstall --global squad   # remove old pre-2.0 global skills (or: spec, a retired skill name, --all)

# Claude Code Plugin — /ck, /doc, /learn, /goal, /headline, updated the native Claude Code way
claude plugin marketplace add nolrm/contextkit
claude plugin install contextkit@contextkit-marketplace

# Validation & Compliance
ck check           # validate installation, policy compliance, and stale context
ck check --strict  # treat warnings as errors
ck check --context # only the stale-context check (--quiet, --strict)

# Corrections Logging
ck note "message"  # add note to corrections log
ck note "AI issue" --category "AI Behavior" --priority HIGH

---

Upgrading to 2.0

2.0 drops the multi-role workflows in favor of better context. Steps:

1. npm i -g @nolrm/contextkit@latest
2. Commit or stash your work.
3. ck update — changes only what's inside ContextKit markers: rewrites the AGENTS.md block, shrinks the CLAUDE.md block to the import, removes retired skills and command files, converts response_style to headline / diagrams_in_docs, creates index.md, and writes the headline block. It never moves your own content or deletes work in progress.
4. If it prints "N item(s) need a decision", run /ck update in Claude Code or Codex. It walks through .contextkit/pending-cleanup.md (custom CLAUDE.md content, unfinished squad/spec state, the squad CI workflow file, stale references), asks before each change, then makes one commit.
5. Optional: /ck setup (or /ck tidy) to write the index and context rules for your project.
6. Global skills: ck update --global or ck uninstall --global squad.

Claude Code plugin users: update the plugin.

What was removed → what replaces it

Removed	Replacement
/squad*, /spec, /spec-component, CI Squad (squad-issue.yml)	/goal
/doc-arch, /doc-feature, /doc-component	/doc arch|feature|component
/analyze, /compress skills	/ck setup, /ck tidy (the ck analyze CLI stays)
/standards-aware, /product-context	AGENTS.md + path-scoped rules
/context-budget	your tool's built-in context command
/agent-push-checklist	pre-push gates
response_style (chat_minimal_words, diagrams_in_docs)	headline: true|false + top-level diagrams_in_docs

Upgrade guide

---

Links

• 🐛 Issues • 💬 Discussions

---

License

MIT

Author

Marlon Maniti
GitHub: @nolrm