ccf

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.
• Codes directly, fast — no coding subagent to wait on. Implementation happens right in the main session, with the plan and codebase already loaded; CCF's subagents exist only for discovery, review and best-practice grounding.

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, a contract-level matrix (Equivalence Partitioning + Boundary Value Analysis + decision table) is designed and the tests are written failing-first directly during 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 5 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, implement each task directly in the session, one at a time.
/ccf:check	Verify the implementation against the spec (conformance, conventions, SOLID/OOP, BE↔FE cross-check). Read-only — this is the single mandatory verify step before a task is marked done.
/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, implementing each task directly in the session (stop on any red gate), then a single /ccf:check and /ccf:updatespec. Mutually exclusive with auto-verify.mjs --auto-verify.

Typical flow: /ccf:init → (plan mode) /ccf:plan → implement directly (per task, or the whole backlog via /ccf:cook) → /ccf:check → /ccf:updatespec. When the test discipline is ON, the contract-level matrix tests are written during implement and /ccf:check confirms they pass. /code-review remains a good optional extra, never a required step.

The 4 agents — all read-only

There is no coding subagent: every task is implemented directly in the main session. Spawning a coding subagent means waiting on a separate context to boot, read the task, and hand a result back, which is measurably slower than writing the code yourself with the plan already loaded — so CCF's subagents exist only for discovery, review and best-practice grounding.

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: Write, Edit, NotebookEdit, Agent, Task, so it cannot write files or spawn nested subagents (nested spawning is allowed by default, but the limit is version-dependent: 5 in v2.1.172 through v2.1.216, 1 — effectively disabled — in v2.1.217 and v2.1.218, and back to 3 from v2.1.219 onward, which is the current default; 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). Parallelism is read-only research only, and since none of these agents write files, there is no separate writer-parallelism concern to track.

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-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 against the spec (conformance, conventions, SOLID/OOP, drift).	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".
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 passes) 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 stop_hook_active. Default path is single-channel (systemMessage only). Opt-in (default off): add --dual-channel-stop to the updatespec-nudge.mjs command in hooks.json to also emit the same nudge as additionalContext (model-facing) alongside systemMessage (user-facing) — not yet observed on a real harness Stop payload, so this stays off in the shipped hooks.json.
auto-verify	Stop	Opt-in (default off) and the only CCF Stop hook that can block. Enable by adding --auto-verify to the auto-verify.mjs command in hooks.json. When a task is in-review, this session changed code, and no ccf-spec-checker review has run yet, it returns decision: "block" (the "ralph loop") with a reason that drives a single verify step — /ccf:check, then /ccf:updatespec once it comes back clean. Guards against loops via stop_hook_active; best-effort, any error exits silently.
context-guard	UserPromptSubmit	When the session transcript shows context has crossed ~40% of the model window — capped at an absolute ~300k tokens, since 40% of a 1M-native window (Opus/Sonnet 4.x) would be unreachable before auto-compact — i.e. the "dumb zone", it surfaces a proactive /compact warning (with a ready-made hint pre-filled from your active task). Default = warn, non-blocking: the advice reaches both you (systemMessage) and the model (additionalContext) every turn. Opt into hard-block by adding --hard-block to the context-guard.mjs command in hooks.json — it then blocks (exit 2) any over-threshold prompt until you compact, with an escape hatch (prefix the prompt with /compact, or include ccf:override). Best-effort: if it can't read the transcript it stays silent.
explore-guide-inject	SubagentStart (Explore)	CCF doesn't own the built-in Explore subagent's prompt, so at spawn this hook injects (via additionalContext) a short, language-agnostic, LSP-conditional exploration directive: prefer semantic navigation (the LSP tool — workspaceSymbol/goToDefinition/findReferences/documentSymbol, falling back when no server exists) plus ripgrep-backed Grep and Glob, and read whole files only after locating the region. Best-effort, never blocks the spawn. This is now the ONLY SubagentStart hook — CCF has no writer subagent left to inject coding rules into.