ACKit — AgentContextKit

Turn any repository into an agent-ready repository.

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:

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)

# 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)

$ 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 — offline, no API key.

---

🧭 Table of Contents

• Why ACKit?
• Features at a glance
• Install
• Quickstart
• CLI Overview
• Configuration
• Architecture
• GitHub Action
• VS Code
• Docs
• Development
• 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)

---

📦 Install

Requires Node ≥ 22.

# global (recommended)
npm install --global @cynrath/agent-context-kit
ackit --version  # 0.5.4

# one-shot, pinned
npx --yes @cynrath/agent-context-kit@0.5.4 --version
npx --yes @cynrath/agent-context-kit@0.5.4 --help

# from source
pnpm install --frozen-lockfile && pnpm build
node dist/cli/index.js --help

---

🚀 Quickstart

ackit init --dry-run        # plan shims + 4 built-in skills (writes nothing)
ackit scan --ci             # gate: exit 1 at/over threshold (medium)
ackit readiness             # 0–100, N/A renormalization, --strict/--fail-below
ackit instructions --explain # graph v2 with provenance
ackit optimize --explain    # 8-class advisor, waste estimates
ackit pack --profile codex --max-tokens 50000  # provider-aware, budgeted
ackit diagnostics --json | jq .profile
ackit dashboard --port 0 --open  # localhost-only

Every command supports --json and --help. Full tour → docs/guides/getting-started.md

---

🖥️ CLI Overview

	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

Details: docs/reference/cli.md · Exit codes: docs/reference/exit-codes.md · Schemas: docs/reference/schemas.md

Exit codes

0 ok · 1 threshold/new-findings · 2 usage/config · 3 environment · 4 security boundary · 5 internal. See docs/reference/exit-codes.md.

---

⚙️ Configuration

Optional root ackit.yml (strict, additive — v1 still valid):

schemaVersion: 1
scan:
  severityThreshold: medium
limits:
  maxFiles: 50000
context:
  maxTokens: 80000
policy:
  extends: []
  rulePacks: []               # declarative packs (local or node_modules)
readiness:
  weights: { instructions: 25, security: 25, contextEfficiency: 20, taskHygiene: 10, skills: 10, policy: 10 }
  strictThreshold: 80
profile: codex                # codex|claude|copilot|gemini|generic
profiles:
  extend: []                  # repo-relative custom profiles

Validate: ackit config check · Schema: schemas/ackit.schema.json · Reference: docs/reference/config.md

---

🏗️ Architecture

flowchart LR
    A[Repository] --> B[Filesystem Engine<br/>realpath containment]
    B --> C[Instruction Graph v2<br/>scope → precedence]
    B --> D[Scanner<br/>redacted findings]
    B --> E[Context Pack<br/>budgeted ranking]
    C --> F[Readiness 0–100<br/>6 categories]
    D --> F
    E --> F
    C --> G[Optimize v2<br/>8-class + waste]
    D --> G
    F --> H{CLI / SDK / MCP / Action / Dashboard / VS Code}
    G --> H

Loading

• Single door to filesystem — one containment engine
• Redaction before reporters — findings constructed already-safe
• Determinism — same repo+config → byte-identical JSON/fingerprints
• Offline-by-construction — no network in product code

Trust chain (v0.5)

flowchart LR
    T[Task / Intent / Workflow] --> E[Evidence]
    E --> V[Bound Verification<br/>bundle v2 + verdict v2]
    V --> I[Verdict Independence + Freshness<br/>reviewed bundle + replay/stale refusal]
    I --> S[Canonical Status<br/>ackit.status.v1, read-only]
    S --> H[Portable Handoff v2<br/>export / import / resume]
    H --> P[CLI / SDK / MCP / Action / VS Code]

Loading

Task/intent/workflow → evidence → bound verification → verdict independence/freshness → status → handoff/resume → CLI/SDK/MCP/Action/VS Code. Details: docs/guides/demo-trust-flow.md · docs/concepts/evidence-verification.md · docs/concepts/checkpoints.md.

More: docs/architecture/overview.md

---

🤖 GitHub Action

Official Cynrath/agent-context-kit@v0.5.4 (SHA-pinned for high-assurance):

permissions:
  contents: read
jobs:
  ackit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@f548e57e544e1ff5a4c46bf1e1b8685f8e4a348a
      - uses: Cynrath/agent-context-kit@v0.5.4
        with:
          command: scan
          args: "--json"
          fail-threshold: high
          upload-sarif: "false"
      # optional: upload SARIF via github/codeql-action/upload-sarif@v3
      # optional: upload findings via actions/upload-artifact@v4

Inputs command/args/fail-threshold/upload-sarif, outputs findings-json/sarif-path, annotations/SARIF 2.1.0/job summary, least-privilege. Shareable local output: ackit scan --format markdown (copyable summary) or --format sarif for code scanning. Guide: docs/guides/ci.md · Action: action.yml

---

👀 Watch / Dashboard & Diagnostics

ackit scan --watch          # debounced 400ms, incremental cache, SIGINT → exit 0
ackit dashboard --port 0 --open  # localhost-only, CSP, XSS-escaped, live polling
ackit report serve ./report.html --port 0

ackit diagnostics --json | jq .profile
ackit diagnostics bundle --out ./ackit-diag.zip --redact-check

Guides: docs/guides/watch-dashboard.md · Reference: docs/reference/diagnostics.md

---

🔌 SDK

import { scanRepository, scoreRepository, buildInstructionGraph } from "@cynrath/agent-context-kit";

const result = await scanRepository({ canonicalPath: process.cwd() });
console.log(result.findings.length);

// cancellable
const ac = new AbortController();
setTimeout(() => ac.abort(), 10);
await scanRepository({ canonicalPath: "." }, { signal: ac.signal });

ESM-only, sideEffects:false, AbortSignal cancellable, no process.exit. Reference: docs/reference/sdk.md · Example: examples/sdk-consumer.mjs

---

🧩 VS Code

ACKit is available on the VS Code Marketplace as Cynrath.ackit-vscode.

From source:

pnpm --filter vscode build
vsce package # → ackit-vscode-0.5.4.vsix

Features: readiness tree, Problems ACKITxxx, graph “instructions for current file”, tasks/policy/optimize, palette Refresh/Show Graph/Optimize/Diagnostics, file watcher debounced, no telemetry.

Guide: docs/guides/vscode.md

---

📚 Docs

Area	Link
Architecture	docs/architecture/overview.md
Concepts	instruction-graph · context-budget · provider-profiles · readiness · workflows · intent · checkpoints · evidence-verification
Guides	getting-started · readiness · optimize · provider-profiles · instruction-graph · rule-packs · ci · watch-dashboard · diagnostics · sdk · vscode · monorepo · workflow-adoption · workflow-example · demo-trust-flow · spec-kit-bridge
Reference	cli · config · rules · readiness · profile · rule-pack · instruction-graph · diagnostics · sdk · exit-codes · mcp · schemas · drift · policy · status · provider-surfaces
Decisions	docs/decisions/ · v0.2.0: docs/v0.2.0/ · ADR-0025..0028: workflow/evidence/checkpoint/policy-v2
Tasks	docs/tasks/active
Ecosystem	Spec Kit bridge — community integration (@cynrath/ackit-spec-kit-bridge) connecting Spec Kit intent artifacts to ACKit tasks, evidence, verification gates, and handoffs

---

🔗 Ecosystem

Community integration for ACKit and GitHub Spec Kit: Spec Kit bridge (@cynrath/ackit-spec-kit-bridge) connects Spec Kit's intent-driven development artifacts to ACKit's deterministic repository context, task lifecycle, evidence, verification, and completion gates. Offline-first, no telemetry.

---

🔌 MCP Setup

{ "mcpServers": { "ackit": { "command": "ackit", "args": ["mcp", "serve"] } } }

Reference: docs/reference/mcp.md

---

🛠️ Requirements & Development

Requirements: Node ≥ 22 · pnpm 11 (development) · git optional (incremental features)

Development:

pnpm install --frozen-lockfile
pnpm lint && pnpm format:check && pnpm typecheck
pnpm build && pnpm test && pnpm smoke:cli
pnpm run smoke:package   # pack → temp install → CLI smoke

See CONTRIBUTING.md for the docs-first workflow.

---

🔖 Versioning

Development: 0.5.4 on master · Latest stable: 0.5.4 · Changelog · Releases · latest → 0.5.4 via OIDC Trusted Publishing with provenance. Stable pointer: release-state.json. Legacy .NET/NuGet 1.0.0-rc.1 at 258918b is frozen.

---

📄 License

MIT — LICENSE

⭐ Star this repo if it makes your agents happier!