Agent context and repository readiness for Codex · Claude Code · Cursor · GitHub Copilot · Gemini · MCP
Validates agent instructions, scans repositories, optimizes context and enforces evidence-backed workflows.
Offline-first · Deterministic · No telemetry — ackit on Node ≥ 22
Try it in 30 seconds — no install:
```powershell npx --yes @cynrath/agent-context-kit@latest readiness ```One command scores your repository 0–100 with actionable findings.
- Detect conflicting agent instructions (`AGENTS.md` / `CLAUDE.md` / provider scopes) - Find unsafe repository context (secrets, connection strings, absolute paths) - Measure repository readiness across instructions, security and context efficiency - Reduce wasted agent context (duplicate guidance, oversized files, low-value includes) - Enforce evidence-backed task completion with independent verification - Generate provider-aware context packs (Codex / Claude / Copilot / Gemini / generic)Quickstart → · Getting Started · Changelog · Security · Discussions · Sponsors · GitHub Action
--- ### ✨ Demo (30 seconds) ```bash # 1 — onboard (dry-run, writes nothing) $ ackit init --dry-run ✔ plan: AGENTS.md shim + 4 built-in skills # 2 — score readiness (explainable, no LLM) $ ackit readiness Readiness 88/100 ██████████████████░░ (threshold 80 — pass) Instructions 90/100 Security 90/100 Context Efficiency 70/100 # 3 — graph + optimize $ ackit instructions --explain codex/AGENTS.md → claude/CLAUDE.md (provenance: frontmatter applyTo) $ ackit optimize --explain --json | jq .suggestions[0].tokenWasteEstimate 42 # 4 — provider-aware pack & dashboard $ ackit pack --profile codex --max-tokens 50000 | head -5 # ACKit Context Pack — 12 files, 34210 tokens $ ackit dashboard --port 0 --open # localhost-only, CSP, live polling → http://127.0.0.1:54321 ``` ### 🔐 Trust flow (60 seconds) ```bash $ ackit task complete TASK-0007 completion gate blocked: MISSING_VERIFIER_VERDICT: profile 'standard' requires an independent verdict (run 'ackit verification bundle' + record) $ ackit evidence verify TASK-0007 --criterion AC-001 --type test --ref "pnpm vitest run (green)" $ ackit verification bundle TASK-0007 --format json --out .ackit/reviews/bundle.json $ ackit verification record TASK-0007 --verdict .ackit/reviews/verdict.yaml --bundle .ackit/reviews/bundle.json TASK-0007: verdict VR-0001 registered (PASS) $ ackit status TASK-0007 blockers: (none — completion eligible) - verdict VR-0001 (PASS): fresh; independent $ ackit task complete TASK-0007 TASK-0007: completed $ ackit checkpoint export TASK-0007 --format json --out .ackit/reviews/handoff.json # ... second process, zero shared memory ... $ ackit checkpoint import .ackit/reviews/handoff.json TASK-0007: handoff CP-0001 fresh (bundle 9f2c…); resume context renders ``` Stale state blocks with `VERDICT-STATE-STALE` (naming what changed); a fresh bundle + verdict restores eligibility. The full flow runs as a test (`tests/e2e/trust-flow-demo.test.ts`) and is walked through in [`docs/guides/demo-trust-flow.md`](docs/guides/demo-trust-flow.md) — offline, no API key. --- ### 🧭 Table of Contents - [Why ACKit?](#-why) - [Features at a glance](#-features-at-a-glance) - [Install](#-install) - [Quickstart](#-quickstart) - [CLI Overview](#-cli-overview) - [Configuration](#-configuration) - [Architecture](#-architecture) - [GitHub Action](#-github-action) - [VS Code](#-vs-code) - [Docs](#-docs) - [Development](#-development) - [Versioning](#-versioning) --- ### ❓ Why | Before | With ACKit | |---|---| | Convention-based — nothing is verified | **Deterministic local analysis** with stable JSON/SARIF contracts | | Cloud-coupled — code leaves the machine | **Offline-by-construction** — zero network in product code | | Secrets leak into prompts/logs | **Redacted at construction** — evidence never contains plaintext secrets | | One `AGENTS.md` for all providers | **Provider-aware** — Codex/Claude/Copilot/Gemini/generic, `includeScopes`/`applyTo` | | “It worked on my machine” | **Machine-checkable gates** — `ackit scan --ci`, `ackit readiness --strict` | > This repository dogfoods itself: it was built by following the same `docs/tasks` task system it ships. **What ACKit is not:** an autonomous coding agent, a model runtime, a browser automation framework, an agent router, or a cloud orchestration service. ACKit is the deterministic, offline-first engineering layer those agents share — repository context, explicit intent, structured tasks, plan discipline, evidence-backed completion, resumability, independent verification, policy enforcement, drift detection, and provider interoperability. Model execution and autonomous coding stay with your chosen agent (Codex, Claude Code, OpenCode, Copilot, Gemini, Cursor, Cline, any MCP-capable agent). --- ### 🎁 Features at a glance| Capability | Command | What you get | |
|---|---|---|---|
| 📊 | Agent Readiness | ackit readiness | 0–100 across 6 categories (25/25/20/10/10/10), weighted renormalization, ackit.readiness.v1 JSON + terminal tree, --fail-below/--strict/--baseline/--compare |
| 🧩 | Instruction Graph v2 | ackit instructions --explain | Codex/Claude/Gemini/Copilot+shared, nesting, includeScopes/excludeScopes/providerApplicability/provenance/shadowedBy/duplicateOf, applyTo globs, conflict/duplicate/shadow/dead, depth→precedence→id |
| 🎭 | Provider Profiles + Surface Parity | ackit pack --profile codex | 5 built-ins (codex/claude/copilot/gemini/generic), CLI --profile > ackit.yml > auto-detect > generic, budget/includePriority; CLI ≡ SDK ≡ read-only MCP ≡ Action ≡ VS Code project the same canonical status snapshot (Codex/Claude/Gemini/Copilot distinctions in docs/reference/provider-surfaces.md) |
| 📜 | Rule/Policy Packs | ackit policy check | schemas/rule-pack.schema.json v1 (presence|pattern|config|dependency|instruction), glob/scope/match, overrides/composition, ReDoS/size guards |
| 🧹 | Optimize v2 | ackit optimize --explain | 8-class taxonomy, evidence[]/confidence/tokenWasteEstimate/provenance/plan, --fix --dry-run, terminal|json|markdown|sarif |
| 📦 | Context Packs | ackit pack --max-tokens 50000 | Weighted deterministic ranking, manifest hash/reason/tokens per file |
| 🔒 | Scanning + Containment Hardening | ackit scan --ci | Secrets/assignments/private keys/connection strings/entropy/absolute-path/CI pinning/drift, redacted evidence, SARIF 2.1.0; link-aware root-contained output guard (symlink/junction escape repair, T27), adversarial matrix, MCP stays read-only |
| ✅ | Tasks | ackit task | docs/tasks single-active, [ ]/[~]/[x]/[!], completion gate, task doctor |
| 🧭 | Workflows + Intent | ackit workflow set --profile standard | quick/standard/high-risk lifecycles with stage gates (ackit.workflow.v1), committed intent docs with fingerprints (ackit.intent.v1), artifact refs on tasks |
| 🧾 | Evidence + State-Bound Verification | ackit evidence verify … && ackit verification bundle … --format json && ackit verification record … --bundle … | criteria↔proof registry (ackit.evidence.v2), state-bound bundles (ackit.verification-bundle.v2 with stateDigest/bundleDigest), persisted bound verdicts (ackit.verdict.v2, v1-authored) with verifier independence (reviewedBundleDigest, VERDICT-INDEPENDENCE-UNPROVEN), replay rejection (VERDICT-REPLAY-REJECTED) + staleness refusal (VERDICT-STATE-STALE/VERDICT-BUNDLE-MISMATCH), completion gate enforcement |
| ⏸️ | Checkpoints + Portable Handoff v2 | ackit checkpoint create … && ackit checkpoint export … --format json && ackit checkpoint import … | ackit.checkpoint.v1 snapshots + verification-bound portable handoff (ackit.handoff.v2 with verification binding, status snapshot, redaction manifest), checkpoint import read-only resume with stale refusal (VERDICT-STATE-STALE/HANDOFF-V1-UNBOUND/HANDOFF-INVALID), deterministic resume context + task-aware packs |
| 🧭 | Canonical Status | ackit status [id] | read-only task/stage, verbatim blockers, verification + checkpoint freshness, derived next actions — human + stable ackit.status.v1 JSON; never mutates |
| 🛰️ | Drift + Policy v2 | ackit drift check --ci | 8 deterministic finding codes, risk-tiered autonomy (tier0-4 × allow/ask/deny, deny wins) + review policy, declarative lifecycle gates (no executable hooks), portable role contracts |
| 🔭 | Watch/Dashboard | ackit dashboard | scan --watch debounced 400ms + cache; dashboard localhost-only 127.0.0.1, CSP + nosniff, /api/* paginated, <50KB vanilla JS |
| 🩺 | Diagnostics | ackit diagnostics bundle | ackit.diagnostics.v1 + deterministic bundle-manifest.json (sha256 + redaction count), 5-secret [REDACTED] proof |
| ⚡ | Benchmarks | benchmarks/run.mjs | 7 deterministic fixtures, 8 metrics (coldScanMs/warmScanMs/incrementalMs/peakRssMb/filesPerSec/packMs/graphMs/cacheHitRatio), median-of-3 |
| 🔌 | SDK v1 | import { scanRepository } from "@cynrath/agent-context-kit" | sideEffects:false, type:module, exports {".","./mcp"}, AbortSignal <200ms, AckitError |
| 🧩 | VS Code | extensions/vscode | 0.5.4, Cynrath, lints Linters, onStartupFinished, readiness tree + Problems ACKITxxx + status-integrated Tasks view (canonical blockers/next actions, no mutation), <2MB VSIX — Marketplace: Cynrath.ackit-vscode |
| 🤖 | MCP | ackit mcp serve | Official SDK stdio, 16 read-only tools (incl. canonical ackit_status, workflow status, intent, checkpoint, verification bundle, drift, roles), 5 resources, 4 prompts, InMemoryTransport cancellation |
| 🔐 | Trust-Flow Demo | docs/guides/demo-trust-flow.md | reproducible offline proof: missing proof blocks → bound independent verdict enables → mutation stales → fresh re-verification restores → handoff exports → second process resumes (tests/e2e/trust-flow-demo.test.ts) |
| Command | Purpose | Key options / subcommands | |
|---|---|---|---|
| 🚀 | ackit init | Plan/write shims + skills | --dry-run --agents |
| 🔒 | ackit scan | Security / hygiene scan | --ci --changed --staged --since --range --baseline --watch --fail-below |
| 📊 | ackit readiness | 0–100 readiness scoring | --fail-below --strict --baseline / --compare --json |
| 🧹 | ackit optimize | Hygiene advisor v2 | --fix --dry-run --profile --explain --category --min-severity --format |
| 🩺 | ackit diagnostics | Environment / config / cache / policy / task diagnostics | --json bundle --out --redact-check |
| 🔭 | ackit dashboard | Local dashboard (localhost-only by default) | --host --port --allow-nonlocal --open |
| 🧩 | ackit instructions | Instruction graph v2 | --provider --profile --for --explain --json |
| 📦 | ackit pack | Provider-aware context pack | --max-tokens --profile --include --changed |
| 🛠️ | ackit skills / task / policy / config | Skills, task workflow, policy and configuration | skills list/validate/install/export · task create/list/start/complete/resume · policy check · config check |
| 🧭 | ackit workflow / intent / checkpoint / status | Workflow lifecycles, intent docs, resume + canonical status | workflow set/show/advance/verify · intent new/list/show/validate/fingerprint · checkpoint create/show/validate/export [--format json]/import · status [id] (read-only ackit.status.v1) |
| 🧾 | ackit evidence / verification / drift / role / journal | Evidence registry, state-bound verifier bundles, drift, roles, journal | evidence sync/show/verify/validate · verification bundle [--format json] / record --bundle … / show (v2 state binding + independence) · drift check [--ci] · role list/show/validate · journal show/validate |
| 🔧 | ackit cache / workspaces / hooks / report / mcp | Utility commands | cache clean · workspaces · hooks · report serve · mcp serve |