coding-kit

coding-kit

One operating contract, on-demand skills and cross-session memory for coding agents.

The kit gives an agent a short contract (OPS.md: authority, completion, evidence, memory), 27 skills that load only when their domain question is open, and a Python standard-library memory engine with evaluation tools. It is not an agent runtime, a sandbox, or a guarantee of better answers.

Get started · Daily use · Skills · Evidence and limitations · Upgrading · Contributing

What you can use it for

• Carry decisions across sessions. Save findings in your private memory store and search them from a fresh agent session instead of reconstructing project history from chat.
• Give coding work a consistent method. The contract defines acceptance, verification and reporting; skills add domain detail for planning, debugging, testing, review, security, money paths and UI.
• Evaluate behavior rather than trust promises. Run policy scenarios, skill-routing checks, and small coding tasks with deterministic verifiers. These answer different questions; none alone proves overall coding quality.

Developed and tested with Claude Code and Oh My Pi (OMP). Other agents that read instruction files and SKILL.md skills can be configured manually; this project does not claim to have tested their behavior. Instructions are in English; the kit asks the agent to answer in your language.

Get started

Installation has two separate steps: create the memory store, then connect your agent. The first step does not install agent instructions.

1. Create your memory store

Requirements: Git and Python 3.12. CI runs on Windows and Ubuntu with Python 3.12; other Python versions are untested. Runtime scripts use the standard library. Only contributors running the test suite need pytest.

Run these commands in PowerShell or Bash:

git clone https://github.com/oleg494/coding-kit.git coding-kit
cd coding-kit
python scripts/install.py

The installer creates your user-level ~/.memory/ directory, including fixtures and indexes, and links its engine to this clone. Keep the clone in place. Re-running the installer is supported. Look for search smoke: OK. It does not configure your agent's rules or skills.

Set MEMORY_ROOT before installation and in sessions that use the kit.

PowerShell:

$env:MEMORY_ROOT = "$HOME/coding-memory"
python scripts/install.py

Bash:

export MEMORY_ROOT="$HOME/coding-memory"
python scripts/install.py

Examples below call the engine from the clone, so they do not depend on shell expansion of ~ in script arguments.

2. Connect your agent

Merge a pointer to this clone's OPS.md into your agent's rules file. Use an absolute path so the contract remains reachable from other projects. Load it once; AGENTS.md is only a repository router. Preserve existing instructions rather than replacing them wholesale.

Copy or link only the 27 skills declared in profile.yml into the agent's skill directory, preserving unrelated skills. Skill bodies load on demand; no full method chain or memory warmup is required at startup. These user-level changes can affect every project opened with that agent.

Agent	Rules file	Skills
Claude Code	~/.claude/CLAUDE.md	~/.claude/skills/
Oh My Pi (OMP)	~/.omp/agent/AGENTS.md	~/.agents/skills/ with user-agent skill discovery enabled
Antigravity	~/AGENTS.md	~/.agents/skills/
ZCode	~/.zcode/AGENTS.md	~/.zcode/skills/
Hermes	Delimited block in SOUL.md	Generated owned-skill projection via Hermes adapter

The OMP paths above match the kit's deployment targets. See the Antigravity and ZCode guides for their environment-specific setup.

3. Verify the connection

From the clone, enter the tools directory, save a note, and retrieve it:

cd memory/db-tools
python findings.py add "first-note" --text "hello" --project coding-kit
python findings.py search "first-note" --project coding-kit
cd ../..

Then start a fresh agent session and ask:

Search my coding-kit memory for "first-note" using the memory tools. Show the command you ran and the stored finding.

The agent should invoke findings.py search or search_all.py against your memory store and retrieve the note, not merely repeat this example. If it does not, check that the rules and skill paths are loaded by your agent.

python scripts/doctor.py checks repository and memory consistency. A green result is not proof that an agent loaded or followed the kit.

Daily use

Run the memory tools from the clone, or use their absolute paths elsewhere:

python memory/db-tools/search_all.py "deployment decision"
python memory/db-tools/search_all.py "deployment decision" --project coding-kit
python memory/db-tools/search_all.py "deployment decision" --importance high
python memory/db-tools/findings.py projects

--mode lexical remains the default. Optional semantic retrieval uses a local multilingual MiniLM ONNX model, never a hosted inference API. It needs numpy, onnxruntime, and tokenizers only for semantic commands; ordinary FTS5 search and installation do not require those packages. Prepare the model and build the disposable index explicitly:

python memory/db-tools/vector_search.py prepare-model --model-dir ~/.local/share/coding-kit/models/paraphrase-multilingual-MiniLM-L12-v2
python memory/db-tools/vector_search.py build --model-dir ~/.local/share/coding-kit/models/paraphrase-multilingual-MiniLM-L12-v2
python memory/db-tools/search_all.py "resume interrupted work" --mode vector --model-dir ~/.local/share/coding-kit/models/paraphrase-multilingual-MiniLM-L12-v2
python memory/db-tools/search_all.py "resume interrupted work" --mode hybrid --model-dir ~/.local/share/coding-kit/models/paraphrase-multilingual-MiniLM-L12-v2

The pinned public model is Xenova/paraphrase-multilingual-MiniLM-L12-v2 at revision 2c4055b12046f11709e9df2c122e59ffbdc2f900; preparation downloads only its quantized ONNX graph and tokenizer, verifies their fingerprints, and never executes remote code. MEMORY_EMBEDDING_MODEL_DIR may replace repeated --model-dir flags. Semantic reads do not repair stale indexes: rebuild after memory changes. Index writes are temporary and atomic; source databases are authoritative. Semantic index files are disposable, not personal data backups. findings.py search also accepts --mode, --model-dir, and --index; both CLIs expose --state all|current|superseded and --verification all|verified|unverified before result limits.

How the agent retrieves and saves memory, and how it resumes "continue work on X", is defined once in OPS.md §§2 and 5: relevant memory is searched without a reminder, durable verified results are saved without a confirmation prompt, and read-only scope, "do not save" or stop switch saving off. These are instruction contracts, not runtime enforcement.

Skills at a glance

Ordinary implementation needs no skill; the contract is the method. Each skill owns one kind of open question, and its description names the neighbor to use instead. Cross-references are pointers, not a load order.

Open question	Skill
What to build: unclear idea, requirements, spec, design choice	brainstorming
How to execute coupled or multi-slice work	writing-plans
Independent slices to run in parallel	dispatching-parallel-agents
Workspace isolation for concurrent work	using-git-worktrees
Commits, branches, conflicts, releases, integrating a branch	git-workflow-and-versioning
Test-first work, test design, reproducing a bug as a test	testing-discipline
About to claim done, fixed or passing	verification-before-completion
Unknown failure cause, hung or broken runtime	systematic-debugging
Performing or requesting a code review	code-review-and-quality
Handling review feedback received	receiving-code-review
Blast radius of an N-file change or rename	code-graph-review
Independent audit of someone's completion claim	fable-judge
Speculative abstraction, new dependency, over-engineering	ponytail
Module boundaries, god files, schema evolution	architecture-simplicity
Consequential library, tool or platform choice	production-first-decisions
Payments, balances, quotas, refunds	money-path-safety
Untrusted input, auth, secrets, personal data	security-and-hardening
Logging, metrics, tracing, alerts	observability-and-instrumentation
Release, rollout, rollback	shipping-and-launch
UI components, tokens, themes	design-system
Dashboards and data visualization	dashboard-design
Web research with primary sources	web-research
Saving or retrieving cross-session knowledge	dev-wiki
Windows encoding, CRLF/BOM, cmd/PowerShell quirks	windows-encoding-fixes
Creating or editing a skill	skill-authoring
/fable-method, or a non-code plan/audit/report	fable-method
Explicitly granted open-ended mission	autonomous-work

profile.yml declares these kit-owned skills. Third-party skills beside them (for example Firecrawl) are not kit release assets; kit validation and synchronization leave them untouched.

Ownership and lightweight navigation

The kit owns its contract, declared skills, memory scripts and generated routers. Approval mode, sandboxing, model/provider routing, compaction and third-party tools belong to the host/user setup; kit releases do not change those settings.

Use targeted source search and LSP for ordinary code navigation. For an existing indexed project, python memory/db-tools/repomap.py project --db <project.db> --tokens 1500 gives a bounded map without installing a graph stack. Confirm indexed relationships against current source; an index may be stale.

Memory availability is an explicit check: python memory/scripts/memory-warmup.py; add --full only for diagnostic feeds and integrity inspection. Nothing runs automatically at session start.

Your knowledge lives in ~/.memory/ (or MEMORY_ROOT), outside the kit repository. The clone contains methodology and tooling, not your personal project history. Do not commit your memory store or assume it is a sandbox for untrusted data. See the security policy.

The store is the one asset this repository cannot rebuild (db/*.db are gitignored by design). Back it up, then prove the snapshot is usable:

python scripts/tools/backup_memory.py
python scripts/tools/backup_memory.py --list
python scripts/tools/backup_memory.py --restore-drill <backup directory>

Backups land in <memory root>/backups/<timestamp>/. A snapshot whose database was skipped is tagged DEGRADED and refused as a restore point. --restore-drill restores into a temporary root, runs PRAGMA integrity_check on every restored database, verifies the findings store and searches a token taken from the restored rows; it prints JSON and exits 0 only when that verification passes. --restore <dir> performs a live restore (pre-restore snapshot first; asks unless --yes).

Projects are discovered from the memory root's db/*.db files and optional projects.json. Project slugs use [a-z0-9][a-z0-9_-]{0,63}. Use portable for reusable cross-project knowledge and unknown for unclassified notes.

Importance levels:

• high: critical boundaries, invariants, and durable release contracts.
• normal: actionable findings, runbooks, and feature setups.
• low: temporary checkpoints and scratch notes.
• unreviewed: findings not yet qualitatively reviewed.

Use findings.py edit --help to update a finding using its returned ID; IDs are not guaranteed to start at 1. For batch classification, findings.py classify mapping.json --dry-run validates a mapping before mutation. Classification is transactional and preserves user-curated records unless --force is supplied. See findings.py.

Evidence and limitations

The kit is not a demonstrated universal coding-quality improvement. It adds instructions and can add work. Whether that helps depends on the model, task, and integration.

A historical external DeepSWE A/B run compared the same agent with and without the kit using deepseek-v4-pro, pier + mini-swe-agent in Docker, and a 10-task seed-0 subset:

Observation	Reported result
Solved tasks in the reported nine-task comparison	6/9 in both arms
Steps across five mutually solved tasks	+21% with the kit
Prompt tokens across those five tasks	+41%: 99.5M vs 70.4M
Task-level differences	One kit win and one kit loss

This was a small historical sample using a 36-skill manifest, not a benchmark of the current release. Version 6.0 cuts the inventory and the always-loaded contract partly because of this result; that cut has not been re-measured. Raw artifacts are retained outside this repository; the repo does not ship a reproduction script for these numbers. The results are descriptive, not a causal explanation or a general reliability claim. Prompt-token counts are not a measured monetary bill.

The 4.5.1 release notes separately document policy-calibration observations and their limits. They are stated-next-action evidence, not an end-to-end coding-quality win rate.

Every public claim the kit makes — including its unverified ones — is tracked in the claims ledger, which lists the runnable verification command, the evidence artifact, or an explicit unverified status for each claim, plus the release acceptance gates and rollback procedures that must hold before a version tag.

Run the kit's checks

python -m pip install pytest
python scripts/doctor.py
python -m pytest tests -q
python scripts/tools/check_file_sizes.py --ci

CI runs the kit gates on Windows and Ubuntu. Structural validation can run without a model or paid API calls:

python eval/runner.py --inline-skills
python eval/task_runner.py --dry-run
python eval/trigger_eval.py --queries eval/trigger_queries.json

These commands validate evaluation inputs; they do not measure a live model's behavior. Trap dry-runs record DRY_RUN rows with passed: 0; exit zero means the inputs are valid, not that the model passed.

Report input validation, stated-next-action text probes, executed tool tasks and controlled comparisons separately. Record the resolved model and reasoning level when observed; otherwise label them unknown. A self-assessed text probe is not a tool-loop success rate, a speedup, or a model comparison.

Trap and trigger results carry comparison_id: a digest of executed prompts, expectations, selected cases, scorer code and execution settings. trend.py compares only matching IDs within a model. Unknown IDs stay visible without deltas and cannot seed baselines; existing run files are never rewritten. On --update-baselines, new trap/trigger baselines use {model: {comparison_id: rate}}; old numeric baselines are not reused. Matching IDs do not control mutable images, ambient skills or provider aliases, and do not prove that an instruction change caused an improvement.

Tool	Purpose and boundary
Trap-suite	Adversarial policy scenarios. The judge defaults to the executor; use a distinct judge to reduce self-judging bias. Answers over 8000 characters fail evaluation without a model verdict, rather than judging an incomplete prefix. Policy adherence is not task superiority.
Task smoke	Six coding tasks, including two impossible canaries, with deterministic verify.py oracles. A smoke check, not a statistical benchmark.
Trigger evals	Skill activation routing: use --queries auto for current co-located cases; an 80-query central corpus provides fallback coverage.
Results store and trend	Structured results, explicit live/dry-run modes, failure categories, and comparisons of recorded runs.
Telemetry	Measures duration. Optional usage totals are user-reported, not independently measured token cost.
Ablation	Compares prompts with and without an inlined skill. Ambient skills remain uncontrolled; results are descriptive, not causal.
Rigor A/B	Policy experiments with isolation probes and an acceptance gate that can reject a candidate.

Live evaluations require an executor and may incur provider charges. Prompt evaluations require docker:<image> <argv...>; bare host commands are refused. The image must contain the executor. Only explicitly declared read-only mounts are visible alongside a disposable writable task directory; host credentials are not inherited. Network is off by default. @net enables unrestricted bridge networking, not endpoint allowlisting; live-model acceptance of this isolation stays open until credential and network restrictions are verified.

Autonomous work (opt-in)

Requests such as “do useful work” or “keep going without asking” activate autonomous-work: evidence-backed work selection, verified progress, and immediate stop/revocation. Ordinary bounded requests do not become autonomous missions. Outward, destructive and spending actions still need authorization (OPS §1); memory follows OPS §5.

An optional foreground Python supervisor supports continuation across process boundaries:

python scripts/tools/autonomous.py --help

It accepts an executor and independent verifier, records resumable state, and reports completion only after verification succeeds. A STOP file prevents further spawning and interrupts a live child. Read the supervisor contract before configuring commands; a workspace is not a security sandbox.

Carry unfinished work into a fresh session

Capture a task brief with scripts/tools/handoff.py. The brief is JSON with goal, acceptance, constraints, pending, and observations. Each observation has a claim and a nonempty paths list of workspace-relative regular files that support it. List only files you intend to fingerprint.

python scripts/tools/handoff.py capture --workspace /path/to/repo --brief brief.json --output handoff.json
python scripts/tools/handoff.py resume --workspace /path/to/repo --handoff handoff.json

Capture stores hashes, not file contents, and refuses to overwrite an existing handoff. Resume is read-only: it returns the complete task context and marks observations stale when their supporting files changed, disappeared, or became unsafe to read. Exit codes: 0 unchanged, 1 drift, 2 invalid input. Use --json on resume for structured output. Unchanged bytes are not proof that a claim is true, that tests passed, or that an action is authorized.

Give the fresh agent the resume output and the workspace, not the previous chat. It must inspect stale evidence and preserve current user edits before continuing. For automatic worker launches, add --handoff /path/to/handoff.json to the supervisor invocation. The supervisor refreshes this context before each worker; the configured independent verifier remains the completion gate. Neither tool executes commands embedded in a handoff, snapshots the whole repository, or replaces the host's permission and sandbox controls.

Upgrading

6.0: one contract, fewer overlapping skills

6.0 is a text release; the memory format and tools are unchanged. Skills whose triggers collided were merged, and three skills that restated the contract were folded into it:

Retired skill	Now lives in
superpowers, reasoning-engine, engineering-persona	OPS.md
yagni	ponytail
spec-driven-development	brainstorming
incremental-implementation	writing-plans
test-driven-development	testing-discipline
debug-incident-protocol	systematic-debugging
requesting-code-review	code-review-and-quality
finishing-a-development-branch	git-workflow-and-versioning

Each rule now lives in one place, descriptions name their neighbor skill, emphatic wording was replaced by stated reasons, and universal checklists got applicability conditions. Motivation: context files raised agent cost about 20% without raising solve rates (arXiv:2602.11988); skill routing errors concentrate inside clusters of similar skills and overly general skills capture routing (arXiv:2605.16508); focused skills beat exhaustive bundles (arXiv:2602.12670). Redeploying removes the retired skills from kit-managed skill directories; scripts/tools/deploy.py only deletes skills its manifest owns. Details: CHANGELOG.

5.x

• 5.1 added optional --mode vector|hybrid memory search on top of the unchanged lexical default; semantic modes need a local model and index. Searches are strictly read-only: an absent or desynced findings store is reported, not repaired; run findings.py list or the doctor to heal it.
• 5.0 replaced contract_drift.needs_contract_update(paths) with needs_contract_review(paths), which flags high-materiality paths for review and exits zero for valid input; callers that used the old boolean or exit code as an approval gate must change. The CLI accepts one JSON array of path strings (or nothing for an empty diff); invalid input exits 2.

Inside the repository

Component	Entry point
Operating contract	OPS.md
Repository router	AGENTS.md
Host integration notes	SKILL_RUNTIME.md
Paths and skill manifest	profile.yml
Skills	skills/
Memory engine	memory/db-tools/
Evaluation tools	eval/
Changes and contribution guide	Changelog · Contributing

Windows-first development; CI also runs on Ubuntu. The memory engine link is a junction on Windows and a symlink elsewhere.

Credits and license

MIT. Planning, debugging, verification and review skills are derived from obra/superpowers by Jesse Vincent, reworked for coding-kit; see the superpowers license. The ponytail skill is adapted from DietrichGebert/ponytail; see its license.