Agent Context Kit

ACKit — AgentContextKit

✨ 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

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

📦 Install

Requires Node ≥ 22.

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

# one-shot, pinned
npx --yes @cynrath/[email protected] --version
npx --yes @cynrath/[email protected] --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

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

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

• 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]

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/[email protected] (SHA-pinned for high-assurance):

permissions:
  contents: read
jobs:
  ackit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@f548e57e544e1ff5a4c46bf1e1b8685f8e4a348a
      - uses: Cynrath/[email protected]
        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

Context7 / Docs7: Maintained indexing settings live in context7.json; Docs7 navigation uses docs/docs.json. See the Context7, Docs7 and verification guide for owner claiming, badge requests and optional Docs7 Free hosting. Existing documentation hosting remains unchanged.

🔗 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