A knowledge base that stays in sync with your code.
freya-devkit is a suite of ten composable skills. Each keeps
one kind of artifact — your dependency graph, docs, feature specs, intended behaviors, and
security findings — coherent with the code as it changes. They cooperate through one shared,
version-controlled knowledge-base/ folder, and one command runs the whole team.
It began as a Claude Code plugin; it now runs on any agent that loads the Agent Skills
standard. Claude Code and GitHub Copilot are both validated live.
That is the only number on this page, because it is the only one that is measured
rather than asserted. bin/check_skill_conformance.py enforces fourteen rules with
zero exemptions and exits clean on the tree today — so "the port is finished" is a claim you
can check in one command rather than take on trust. (Thirteen of the fourteen are the
portability rules; R14 rides on the same gate and is about redacting secrets.)
The problem it solves
As code changes, the things around the code rot: docs go stale, design intent is forgotten, security findings drift, and tests quietly start mirroring what the code does instead of what it should do. Doing that upkeep by hand, in the right order, every time — nobody does.
Artifacts drift from code
A README written in March describes March. Docs, specs and security reports fall out of date the moment code changes, and nobody remembers to update all of them, in order. Each skill re-syncs its own artifact incrementally, from the commit it last processed.
Change-impact blindness
You edit a file and nothing tells you what else that touches. Updating only the files you literally changed misses the blast radius — the dependent files the change actually reaches. A dependency graph turns "changed" into "affected".
Intentional design gets "fixed"
A scanner flags the missing password fallback on your login route. A human removed it on purpose, as a phishing vector. Nothing recorded that, so the finding comes back every scan and someone eventually "fixes" it. Specs record the decision so the scan leaves it alone.
AI output is treated as certain
Generated content arrives with the same confident tone whether it was read off the code or inferred from a filename. Without a confidence signal you cannot tell which to trust and which to review. Inferred specs carry a 0–100 certainty, out loud.
Tooling is locked to one host
Write your workflow for one agent and it is worthless on the next. This toolkit had that problem itself: on Copilot the suite did not install, and the parts that did install would not run. Everything deterministic was already portable Python — it was the layer telling an agent how to use those scripts that had been written for one host.
Your tests prove what your code does. Nothing proves what it's supposed to do.
Behavior can drift while a green, high-coverage suite stays green. The behavior layer makes intended behavior a first-class, executable, gated artifact — so a change that alters it has to be classified rather than merged quietly.
A green suite at high coverage is perfectly consistent with the system doing the wrong thing. Ordinary tests are written from the code, so they mirror the implementation rather than the intent — and a test that mirrors the implementation cannot notice the implementation being wrong. Coverage measures how much code you executed, never whether the code was supposed to do that.
There is a seventh problem — the monolithic prompt that bloats context and cannot be mixed and matched — argued at length in knowledge-base/philosophy.md, so it is not repeated here.
The one idea
Derive one shared source of truth from the code — a dependency graph — then let single-purpose skills each keep one artifact coherent by reasoning about blast radius instead of just changed files, scoring their own confidence, and degrading gracefully when a sibling skill is absent.
wrap-up runs them
in dependency order; status is its read-only mirror, the same census with no
mutation, which is what makes "where do I stand?" a safe question to ask at any time.One command that finds itself
Instead of instructions containing a path only one vendor defines, everything runs through a single launcher. It works out where it lives from its own location on disk, looks the requested job up in a registry, and runs it with the interpreter already running. That is the piece every other decision assumes.
Instruction files that name no assistant
The skills describe commands, not filesystem paths, and mention no vendor. A checker runs over them in CI and fails the build if a host-specific construct reappears. Every one of its rules was added because something real had violated it — none speculatively.
An installer built on symlinks
One command installs the toolkit for whichever agents you have, by linking their skills directory at your checkout rather than copying into it. Because they are links, updating is close to just pulling: there is one copy of each file, and it is the one you edited.
And where prose was not enough, code
Asking an agent to fan work out is a request it may decline while reporting success. So the security scan drives its own worker processes. Nothing is delegated, so nothing can be quietly declined — the difference between hoping and knowing.
The ten skills
Five ship a real, stdlib-only Python engine that does deterministic work. Three are pure prose the agent follows, with no binary at all. One sits between — prose for the report, a Python driver for the fan-out — and one is prose with a single detection helper. Which kind a skill is changes what you can expect of it.
knowledge-base/reference/.behavior.json; answers both blast-radius directions.The exact command surface of every skill — each subcommand, its arguments, and what it writes — is reference material and lives in the repo, where an agent can read it. Reach for these when you need the precise invocation rather than the idea behind it.
What it is not — and what is not proven
The patterns and conventions are guidelines, not rules. Skills adapt them where they fit; nothing is forced. The toolkit is not prescriptive, not complete, and not perfect — and its certainty scores say so out loud rather than rounding to confident.
There are exactly two exceptions, and both are deliberate. The behavior and governance layer is one: deterministic facts — a broken test link, a regressed accepted behavior — hard-block a change, and model judgment ("does this violate a stated principle?") must be resolved before you can proceed. The agent-neutrality gate in CI is the other: it has no exemptions and fails the build on a single leftover host-specific reference, because that class of mistake is invisible where it is made and only surfaces on someone else's agent.
What has never been proven
Listed as risk, not reassurance.
No agent CLI has ever run on Windows
CI installs the toolkit on Windows and runs its tests there, and they pass. It does not drive an agent: no agent CLI is installed on that runner, so nobody has watched a real scan happen on the platform — only the toolkit around it.
Two install modes, one platform each
CI exercises symlink mode on Linux and --copy mode on Windows,
which mirrors how each is actually used — and therefore leaves the opposite diagonal
untested on both.
Whether Copilot delegates at scale
Every measurement was taken on a small fixture, and Copilot's own policy against splitting work up is itself conditioned on small scope. What it does on a large codebase has not been tried.
The ~7× token-cost figure
A roughly sevenfold token cost for parallel work appears in the documentation. It came from landscape research, not from measuring this toolkit, and nothing here has confirmed it.
This list is a snapshot. The live version — re-verified against shipped code, and the file that actually gets updated — is knowledge-base/roadmap.md.
Don't take this on trust
Five things, in increasing order of effort, none of which requires you to believe a page.
| To check… | Do this |
|---|---|
| That the tests really pass, and really are free | Run the suite. Every agent call in it is an injected callable, so nothing reaches the network and nothing costs money. |
| That no host-specific construct survives | Run bin/check_skill_conformance.py. It scans every skill file and exits
clean only if all fourteen rules pass — thirteen portability rules and one about
redacting secrets. |
| What actually happened during live testing | Read the validation record, including the runs whose results had to be thrown away and why. How it evolved → |
| That it really is checked on both platforms | The CI runs are public. Every push runs tests and a real install on Linux and Windows, and the results are attached to the change. The workflow runs → |
| That the reasoning holds up | Every load-bearing decision is written down as an ADR with the alternative it beat, and the places the plan turned out to be wrong are recorded rather than quietly dropped. The decisions → · The reversals → |
# no network, no agent, no cost — every agent call is an injected callable
python -m pytest bin/ skills/ -q
# fourteen rules, zero exemptions; a non-zero exit is a host-specific leak (or, for R14, a missing redaction rule)
python bin/check_skill_conformance.pyThe very first CI run is no longer retrievable. It failed twenty-nine times — nothing had broken, it was simply the first time the tests had ever executed on Windows, and the problems had been sitting there the whole time. Two were faults in the toolkit rather than in the tests, and one of those returned an empty answer with no error at all, which is the worst way for something to be wrong. All of that is written down rather than linkable, and that is worth knowing before you weigh anything else on this page.