CK
GitHub

Upgrading to 2.0

ContextKit 2.0 is about project context: one canonical AGENTS.md, a short always-loaded index, topic standards that load only where they apply, and five small skills. The squad and spec pipelines are gone. Upgrading is ck update, then /ck update if anything needs a decision.

What Changed

AGENTS.md is the canonical context file

Every integration writes the same AGENTS.md block. CLAUDE.md shrinks to @AGENTS.md + @.contextkit/standards/index.md plus one Claude-only line. Claude Code reads AGENTS.md on its own only when there's no CLAUDE.md, hence the import. See How Context Works.

A short always-loaded index

.contextkit/standards/index.md (50 lines or fewer): what the project is, must/must-not rules, exact commands, and a "when you touch X, read Y" table.

Topic standards load where they apply

context_rules in config.yml maps each topic file to paths, rendered per tool (paths: for Claude, globs: for Cursor, applyTo: for Copilot). This also fixes a 1.x bug: Claude rule files used globs:, which Claude Code ignores, so they loaded in every session.

Five skills

/ck, /doc, /learn, and the add-ons /goal and /headline. See Slash Commands.

New CLI options

ck usage, ck check --context (also a non-blocking pre-push warning), ck install --no-headline, and ck install --global goal|headline. New config keys: headline, diagrams_in_docs, context_rules, context_budget_lines, and format_version: 2. See Commands.

Removed and Replaced

RemovedUse instead
/squad, /squad-architect, /squad-dev, /squad-test, /squad-review, /squad-auto, /squad-reset, /squad-doc, /squad-go, /squad-spec/goal
CI Squad (GitHub issue → PR workflow, squad-issue.yml, squad_ci_workflow)/goal; /ck update asks whether to delete the workflow file
/spec, /spec-component/goal
/doc-arch, /doc-feature, /doc-component/doc arch, /doc feature, /doc component
/analyze (skill)/ck setup (the ck analyze CLI command still exists)
/compress/ck tidy
/standards-aware, /product-contextAGENTS.md "Read When Relevant" table + path-scoped rules; /ck update reconciles pending standards updates
/agent-push-checklistPre-push quality gates
/context-budgetYour tool's built-in context command
response_style config block (chat_minimal_words, diagrams_in_docs)headline: true|false and top-level diagrams_in_docs

Why /goal replaced squad: 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. More on /goal.

Upgrade Step by Step

1. Update the CLI

npm i -g @nolrm/contextkit@latest

2. Commit or stash your work

Start from a clean tree so the upgrade is one reviewable diff.

3. Run ck update

ck update

Does the mechanical part, only inside ContextKit markers. See the table below.

4. Run /ck update if asked

If ck update prints N item(s) need a decision, open Claude Code or Codex and run:

In Claude Code (or $ck update in Codex)
/ck update

It works through .contextkit/pending-cleanup.md, asks before each change, runs ck check --context, deletes the file, and makes one commit: chore(contextkit): upgrade to <version>.

5. Optional: write the index and context rules

Run /ck setup (or /ck tidy if your standards are already filled in) to write index.md and context_rules for your project. Then render the rule files with ck update --force or ck <platform>. Plain ck update exits early when there's no new version.

6. Clean up global skills

ck update --globalck uninstall --global squad

See Global Skills & Plugin.

What the CLI Changes vs. Asks

ck update does automatically

  • Rewrites the ContextKit block in AGENTS.md
  • Shrinks the CLAUDE.md block to the import
  • Removes retired skills from .claude/skills, .codex/skills, .agents/skills, .cursor/prompts, and retired command files
  • Converts the old response-style config to headline / diagrams_in_docs and drops the CI squad flag
  • Creates .contextkit/standards/index.md
  • Applies safe standards fixes
  • Writes the headline block

/ck update asks about

  • Your own content in CLAUDE.md: Move to AGENTS.md / Keep in CLAUDE.md / Delete
  • Unfinished squad handoffs: convert to a goal / archive / keep
  • An old spec folder: convert open stories to goals / archive / keep
  • The squad CI workflow file (it can no longer run): delete / keep
  • Pending standards updates for files you customised
  • Stale references found by ck check --context

Your content is safe

ck update never moves your own content or deletes work in progress. Anything that needs judgment goes to .contextkit/pending-cleanup.md for /ck update.

Global Skills & Plugin

If you installed squad or spec skills globally in 1.x, they live in ~/.claude/skills/. Remove them:

ck update --global            # removes retired managed global skills automatically
ck uninstall --global squad   # or: spec, or any retired skill name

Only skills ContextKit installed are removed, never a same-named skill you wrote. To add the 2.0 add-ons globally: ck install --global goal and ck install --global headline.

Claude Code plugin users: update the plugin. It now ships /ck, /doc, /learn, /goal, and /headline.

Unchanged

  • Quality gates: pre-push, commit-msg, .contextkit/quality-gates.yml, and the already-verified skip
  • The .contextkit/standards/ folder and product context
  • The corrections log (ck note)
  • Multi-platform installs (ck claude, ck codex, …) and monorepo support
  • ck status, ck run, and the ck analyze CLI
Previous
Project Structure
Next
How Context Works

Was this helpful?

Help us improve the documentation by sharing your feedback.