CCF — Claude Context First

English · Tiếng Việt · 简体中文

A workflow plugin for Claude Code that enforces a context-first, spec-driven, strictly sequential way of working. CCF turns the loose "vibe coding" loop into a disciplined pipeline where the spec is always fresh, every decision is grounded in real docs, and work happens one verifiable slice at a time.

• Context-first — the spec lives in CLAUDE.md + .claude/, kept continuously fresh so every session starts already knowing the project.
• Grounding — every design decision references best practices from Context7 and Microsoft Learn (two MCP servers bundled with the plugin), not from memory.
• Strictly sequential — one task at a time (waterfall of vertical slices), no parallel feature development, to maximize quality.
• Adapts to your codebase — bootstrap a fresh project as a monorepo (git init at the root; fullstack splits into be/ + fe/ with nested specs) or onboard an existing one, where /ccf:init analyzes the real structure (5 read-only agents) and writes a spec that mirrors it — no layout forced on you.

Why CCF — the problems it solves

Pain in plain Claude Code	What CCF does about it
Context "rots" over a long session; the model drifts from the rules	A SessionStart hook re-injects the context-first reminder every start/clear/compact, and re-loads your in-progress task after a compact.
The spec silently falls behind the code	Two freshness hooks compare the spec's vs the code's last git commit time and nudge /ccf:updatespec — at session start and when you stop.
Planning slips straight into editing files	A UserPromptSubmit hook hard-blocks /ccf:plan unless you're in plan mode — planning stays read-only and reviewable.
Design decisions made from stale memory	Bundled Context7 + Microsoft Learn MCP servers; CCF prompts cite official docs before writing.
Mistakes repeat across sessions	/ccf:updatespec writes two tiers — project rules to the spec, anti-mistake feedback to system memory (loaded at higher weight).
Big-bang features that are hard to review	Plans are a sequential waterfall of vertical slices, each a thin tracer-bullet (DB→service→UI) with its own test gate.
Tests written loosely (or skipped) under time pressure	An opt-in test discipline — when on, ccf-implementer designs a contract-level matrix (Equivalence Partitioning + Boundary Value Analysis + decision table) and writes the tests failing-first as part of implement, and a generated Stop-hook gate blocks stopping until the tests actually pass. Ship-fast flows simply don't opt in.

Install

Via marketplace (recommended)

/plugin marketplace add naniiluja/ccf
/plugin install ccf@ccf

Via npx

npx @naniiluja/ccf

(runs claude plugin marketplace add + install for you)

Local (for development)

claude plugin marketplace add D:/projects/ccf
claude plugin install ccf@ccf

After installing, open Claude Code in your project folder and run /ccf:init.

The 6 commands

Command	What it does
/ccf:init	Bootstrap a new project (interview → generate CLAUDE.md + .claude + plan) or onboard an existing one (5 read-only analyzer agents map the real structure).
/ccf:plan	Create a sequential plan for one feature, grounded in best practices. Requires plan mode (Shift+Tab) — enforced by a hook. After planning, execute each task with an agent.
/ccf:check	Verify the implementation against the spec (conformance, conventions, SOLID/OOP, BE↔FE cross-check). Read-only.
/ccf:fix	Disciplined debugging: reproduce → trace logs/DB step by step → root cause → failing test → minimal fix. No guessing.
/ccf:updatespec	Update the spec and system memory with this session's lessons (incl. new tools with "when to use").
/ccf:cook	Run the whole todo/in-progress backlog in one go: sequential ccf-implementer loop (stop on any red gate), then a batch-verify pass (review + /code-review in parallel, /simplify, re-gate, /ccf:updatespec). Mutually exclusive with auto-verify.mjs --auto-verify.

Typical flow: /ccf:init → (plan mode) /ccf:plan → implement (per task, or the whole backlog via /ccf:cook) → /ccf:check → /code-review → /ccf:updatespec. When the test discipline is ON, ccf-implementer writes the contract-level matrix tests during implement and the verify chain runs them.

The 6 agents

Specialized subagents that inherit the host project's tools, MCP servers and skills — so they can use whatever MCP your project provides (Supabase, Oracle, chrome-devtools, …) and call its skills, with no per-agent allowlist to maintain. Every CCF agent is a leaf — it carries disallowedTools: Agent, Task so it cannot spawn nested subagents (nested spawning is allowed by default, but the limit is version-dependent: 3 levels by default, 5 in v2.1.172 through v2.1.216, and 1 — effectively disabled — in v2.1.217 and v2.1.218; configurable via the CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH env var — set to 1 to disable NESTED spawning only, i.e. a spawned subagent can no longer spawn a subagent of its own; the harness still spawns a level-1 subagent normally. CCF blocks nested spawning deterministically regardless of that default). The read-only agents (everyone except ccf-implementer) also list Write, Edit, NotebookEdit, so they get the same MCP/skill reach but cannot write files. Parallelism is read-only research only — file-writing agents never run in parallel on the same feature.

Agent	Role	Mode
ccf-codebase-analyzer	Analyzes one slice of an existing codebase and reports what exists, proposing no solutions. Fanned out 5-in-parallel by /ccf:init (onboarding slices, whole project) and /ccf:plan (planning slices, scoped to the requested change). CCF commands discover code through this, never the built-in Explore.	read-only
ccf-best-practice-researcher	Fetches cited best practices from Context7 / MS Learn in an isolated context.	read-only
ccf-implementer	Implements exactly one plan task: failing test first, then code to meet acceptance criteria.	writes
ccf-spec-writer	Drafts CLAUDE.md / rules content from a decisions summary, for /ccf:init and /ccf:updatespec; the main thread writes the files.	drafts
ccf-spec-checker	Fresh-context reviewer — checks an implementation or critiques a plan, including a premortem / prospective-failure lens.	read-only
ccf-debugger	Investigates one root-cause hypothesis, follows the correlation ID, verifies against the DB.	read-only

Hooks — the deterministic layer

Commands and agents are prompts (a model can choose to ignore a prompt). Hooks are the only deterministic part of CCF — .mjs scripts run by node at lifecycle events, so they fire every time regardless of what the model decides. They are no-build, no-dependency, Windows-clean (Node ≥ 18, built-ins only).

Hook	Event	What it guarantees
plan-mode-guard	UserPromptSubmit	If a prompt contains /ccf:plan but the session is not in plan mode, it blocks (exit 2) and tells you to enter plan mode. Every other prompt passes through untouched. This is the enforced half of "planning is read-only and reviewed before execution".
plan-review-gate	PreToolUse (ExitPlanMode)	In a /ccf:plan session, denies ExitPlanMode (so the plan can't be presented for approval) until the transcript shows a ccf-spec-checker plan review ran. Best-effort on the undocumented transcript shape: any read failure or a non-CCF session passes through, so it never blocks wrongly — strong enforcement backed by /ccf:plan's step-6 prompt. (The review now includes a premortem lens; the gate mechanism is unchanged.)
session-start	SessionStart (startup|clear|compact)	Injects the context-first reminder so the model wakes up already in CCF mode. If CCF-managed, it adds a freshness signal when the code looks newer than the spec, and after a compact/clear it re-loads the in-progress task from .claude/plan/PLAN.md so you resume exactly where you left off.
updatespec-nudge	Stop	Purely advisory, never blocks. Four independent clauses: (A) if you edited code this session but ran no tests, it reminds you to verify your work (run the tests / type-check); (B) if the code changed but the spec didn't, it nudges /ccf:check then /ccf:updatespec; (C) if you ran git commit this session but PLAN.md still has tasks not done, it nudges you to mark each done (only after its /ccf:check + /code-review) or fix its status; (D) if an iteration in PLAN.md has every task row closed, it prints the exact scripts/archive-plan.mjs command to retire it. Guards against re-trigger loops via . Default path is single-channel ( only). (default off): add to the command in to also emit the same nudge as (model-facing) alongside (user-facing) — on a real harness payload, so this stays off in the shipped .

Freshness heuristic (shared, single source of truth in hooks/lib/freshness.mjs): both freshness-aware hooks compare the last git commit time (git log -1 --format=%ct) of code files against that of spec files (.md under .claude/rules + CLAUDE.md) — committer time, so it reflects real content change and is immune to mtime churn from checkout/pull/clone. When git can't answer (not a git repo, or a path with no commits yet — e.g. a freshly /ccf:init-ed project) it falls back to a depth-limited mtime walk that works for any layout (src/, server/, packages/x/src, plugin-style plugins/x/hooks, or code at the root). It is a lightweight nudge, never a hard conclusion — a content-level "is the spec still accurate?" judgment is left to /ccf:updatespec.

Why hooks are auto-loaded, not declared: like commands/agents/MCP, hooks load automatically from the standard hooks/hooks.json location — current Claude Code (v2.1.x) auto-discovers it. Do not add a "hooks" field to plugin.json pointing back at the standard path: that loads the file twice and fails with Duplicate hooks file detected. The manifest.hooks field is only for additional hook files at a non-standard path.

Bundled MCP servers

The plugin bundles 2 MCP servers (plugin scope, auto started/stopped by Claude Code):

• microsoft-learn — https://learn.microsoft.com/api/mcp (remote HTTP, no auth required).
• context7 — https://mcp.context7.com/mcp (remote HTTP, works out of the box without a key).

Context7 rate limit: the plugin runs Context7 without an API key (free rate limit). If you hit a rate limit, get a free key at context7.com/dashboard, set the CONTEXT7_API_KEY env var, and restart Claude Code.

Spec vs Memory (two context tiers)

/ccf:updatespec records lessons in two places with different purposes:

• Spec (CLAUDE.md + .claude/rules/) — loaded as a user message, lower weight. Holds project rules: conventions, architecture, tech-stack, tooling.
• Memory (~/.claude/projects/<path>/memory/) — loaded into the system prompt, not down-weighted, so Claude follows it more strongly. Holds anti-mistake feedback + user preferences across sessions → helps Claude repeat fewer mistakes.
• MEMORY.md is a pure index — only its first 200 lines or 25KB load each session, so keep it lean; the strongest tier is feedback (always with its Why).

Principle: no duplication. A rule in CLAUDE.md that keeps getting forgotten → write a feedback memory that reinforces it (with the "why"), rather than copying its content.

Compact-aware mechanism

A proactive /compact <hint> beats letting auto-compact fire (when context has "rotted" the model is at its least sharp). After you compact, CCF's session-start hook (matcher compact) auto re-loads the in-progress task from .claude/plan/PLAN.md, restoring the right work context so you don't have to paste it back.

Plan = sequential waterfall of vertical slices

/ccf:init and /ccf:plan produce one plan in .claude/plan/ (a PLAN.md index + task-NNN-*.md files). Each task is a thin vertical slice — a tracer-bullet crossing the layers it touches (DB + service + UI), ordered thinnest → richest, each as spec → failing test → implement. Every task has exactly one predecessor and names the test gate that must be green before the next slice starts. This is what makes "strictly sequential" concrete and reviewable.

PLAN.md stays scoped to the current iteration. When every task in an iteration is done, it is retired into ARCHIVE.md (its task files into .claude/plan/archive/). This cuts both ways on purpose: a closed row left in PLAN.md is counted as live work by the session-start and Stop hooks, while deleting the history would strip ccf-spec-checker's premortem of the real past failures it anchors its predictions to. So the rule is archive, never delete.

Retirement is detected automatically, applied deliberately. The Stop hook notices a fully-closed iteration and prints the exact command; node "<plugin-root>/scripts/archive-plan.mjs" previews it (writing nothing, and naming any row still holding an iteration open) and --apply performs it — rewriting both files and git mv-ing the task files, staged but never committed. The mutation is not automated on purpose: a hook fires with no human in the loop, and a wrong detection there would silently rewrite your plan and your history.

Architecture

• Commands = 6 markdown prompts that drive Claude in-session (not scripts): init, plan, check, fix, updatespec, cook.
• Agents = 6 specialized subagents (analyzer, researcher, implementer, spec-writer, spec-checker, debugger).
• Skills = 1 internal skill (grill-me) — the shared requirements-interview engine the commands invoke via the Skill tool; hidden from the / menu (user-invocable: false).
• Hooks = 9 .mjs run directly with node — no build step, no dependency, Windows-clean; shared helpers (freshness, plan parsing, context-usage, review-trace, git-trace, verify-trace, verify-chain, output-style, explore-guide, implementer-verify) live in hooks/lib/.
• Scripts = 1 human-run CLI (scripts/archive-plan.mjs) — same no-build/no-dependency rules as a hook, but nothing invokes it automatically. This is where an action that mutates your files belongs, so its blast radius stays bounded by you choosing to run it.
• Templates = {{...}}-placeholder files (root/ always, backend/ + frontend/ when fullstack) that /ccf:init instantiates.

See plugins/ccf/ for details. Requires Node ≥ 18 for the hooks.

License

MIT

Acknowledgements

This project was first released in the LINUX DO community — thanks to the community members for their support and feedback.