fuzzy — autonomous engineering skills

Fuzzy is a multi-host Agent Skills suite for Codex, Claude Code, oh-my-pi, and Kimi Code. Its flagship workflow, Archon, improves a codebase without pausing for human decisions: consequential judgments are gated by two independent oracle agents with opposing mandates, and every verdict is recorded.

The canonical skill tree is skills/. Each supported host discovers or packages that same tree, so host integration does not fork the workflows.

Inspired by mattpocock/skills and obra/superpowers, Fuzzy pushes the pattern toward fully autonomous engineering with recorded, two-agent decision gates.

Archon — the autonomous enhancement suite

Named for the Greek magistrate who ruled the city but consulted the oracles. A full Archon run is a three-track campaign in deliberate order:

1. Cleanup — dead code, duplication, needless indirection, and AI slop.
2. Architecture — evidence-first surveys, oracle-approved designs, pinned seams, and reversible migrations.
3. Bug hunt — adversarial verification, a failing regression test, then a minimal fix.

Skill	Role
archon	Orchestrates the complete autonomous campaign and leaves a merge-ready branch plus evidence-backed handoff
oracle-consensus	Runs blind two-agent decisions, debate, constraint checks, consensus or safe no-consensus, and decision records
surveying-architecture	Maps modules, dependencies, churn, cycles, width, locality, and test seams before design begins
designing-deep-modules	Supplies the shared rubric for boundaries, interfaces, dependency direction, depth, locality, and migration risk
pinning-behavior-with-tests	Writes characterization tests that preserve current observable behavior before structural change
executing-architecture-changes	Lands an approved design through green-to-green, reversible micro-steps
simplifying-code	Removes proven-unnecessary complexity without changing behavior
hunting-bugs	Finds, refutes, reproduces, diagnoses, and minimally fixes real bugs test-first
reviewing-the-diff	Gives the completed branch an independent, blind, adversarial pre-handoff review
auditing-agent-skills	Audits and ports skill catalogs across hosts, including trigger boundaries, metadata, references, packaging, and checks

The skills compose rather than duplicate one another. A focused request such as “clean up this module,” “design this boundary,” or “find bugs” routes to the dedicated skill; archon is reserved for the complete multi-track campaign.

What an Archon run leaves in the target repository

• docs/architecture/<RUN>-run.md — branch, baseline commands, scanner flags, checkpoints, step ledger, bug ledger, and recovery state.
• docs/architecture/<RUN>-survey.md — evidence, metrics, and ranked candidates.
• docs/architecture/<RUN>-plan-<candidate>.md — exact behavior-preserving migration steps.
• docs/architecture/<RUN>-archscan-before.json and -after.json — comparable metric snapshots.
• docs/architecture/<RUN>-report.md — measured outcomes, known issues, deferrals, decision index, and integration handoff.
• docs/decisions/D-NNN-<slug>.md — complete oracle records, including NO-CONSENSUS and DISPATCH-FAILED outcomes.

Proof of life — an executed campaign

examples/demo-campaign/ is a complete, genuinely executed Archon run against a fixture package: two blind two-oracle decisions (both unanimous, with independently gathered evidence beyond the briefs), pins including a known-wrong boundary, gated execution, a test-first bug fix, a blind review that caught the run's own staging mistake, a completeness audit that caught three bookkeeping gaps, and a measured cycle BROKEN verification.

Use with Codex

Fuzzy has native Codex discovery, metadata, plugin packaging, marketplace support, repository guidance, and subagent instructions. See CODEX.md for the full guide.

From a checkout

Open Codex anywhere inside this repository. .agents/skills -> ../skills exposes all skills at repository scope. Invoke explicitly with $<skill-name> or inspect them with /skills:

$archon Run an autonomous improvement campaign on this repository.
$hunting-bugs Find and fix reproducible bugs in the payment subsystem.
$auditing-agent-skills Audit this catalog for Codex compatibility.

Descriptions are intentionally concise and boundary-aware so Codex can also choose a matching skill implicitly without stealing near-neighbor tasks.

As a plugin marketplace

After this support is merged to the repository's default branch:

codex plugin marketplace add aj2666/fuzzy
codex plugin marketplace list

To test a branch or tag before merge:

codex plugin marketplace add aj2666/fuzzy --ref <branch-or-tag>

The CLI adds the marketplace source. Browse, install, enable, and smoke-test the plugin through the ChatGPT desktop app's Plugins Directory. The native files are .codex-plugin/plugin.json and .agents/plugins/marketplace.json.

Use with Claude Code

In the target repository's Claude Code session:

/plugin marketplace add aj2666/fuzzy
/plugin install fuzzy-skills@fuzzy

Then say Run archon on this codebase. A manual install can copy all ten skill directories into .claude/skills/; copy the whole catalog because the workflows call one another by stable skill name.

Use with oh-my-pi

Fuzzy ships the native catalog at .omp-plugin/marketplace.json and keeps it identical to the Claude Code marketplace catalog:

/marketplace add aj2666/fuzzy
/marketplace install fuzzy-skills@fuzzy

A copy into .claude/skills/ also works through oh-my-pi's inherited skill discovery. The shared subagent adapter maps independent dispatch to task without embedding that host-specific name throughout the catalog.

Use with Kimi Code

Open Kimi Code anywhere inside this repository. Kimi Code scans .agents/skills at project level, so the shared symlink exposes all ten skills with no setup; invoke explicitly with /skill:<skill-name> or let the model select a skill from its description.

As a plugin (installed per-user, applies to all projects):

/plugins install https://github.com/aj2666/fuzzy

Pin a branch, tag, or commit with the /tree/<ref> or /releases/tag/<tag> URL forms. The native manifest is .kimi-plugin/plugin.json, which points at the canonical skills/ tree. Run /reload or start a new session after installing.

Other Agent Skills hosts

The core workflows require:

1. discovery of standard SKILL.md directories; and
2. for oracle, survey, bug-hunt, and review workflows, genuinely independent agent threads.

The subagent-dispatch adapter defines capability-first semantics and host mappings. When independent dispatch is unavailable, oracle decisions fail safely as DISPATCH-FAILED; one model must never simulate two agreeing agents.

Tooling and validation

• skills/surveying-architecture/scripts/archscan.py — zero-dependency scanner for dependency graphs, cycles, fan-in/out, approximate interface width, churn, and co-change. Its regression suite is python3 skills/surveying-architecture/scripts/tests/run_tests.py.
• scripts/lint-skills.py — validates frontmatter, names, descriptions, announce lines, references, README coverage, and existing-host manifest parity.
• scripts/check-codex-compat.py — validates Codex discovery, plugin and marketplace shape, synchronized versions, per-skill agents/openai.yaml, concise trigger boundaries, and trigger-corpus coverage.
• tests/skill-triggers.json — positive and near-neighbor negative prompts for every skill. It is a review/evaluation corpus, not a claim that static checks can prove model selection.

Run before committing:

python3 scripts/lint-skills.py
python3 scripts/check-codex-compat.py
python3 skills/surveying-architecture/scripts/tests/run_tests.py
python3 -m py_compile scripts/lint-skills.py scripts/check-codex-compat.py
git diff --check

CI runs the skill linter, Codex compatibility checker, and archscan regression suite on pushes and pull requests.

Layout

skills/<skill-name>/SKILL.md          canonical workflow instructions
skills/<skill-name>/agents/openai.yaml
                                      Codex/ChatGPT display and invocation metadata
skills/<skill-name>/references/*     long schemas, adapters, and reference material
skills/<skill-name>/scripts/*        deterministic tooling and tests
.agents/skills -> ../skills          Codex repository discovery
.claude/skills -> ../skills          Claude-compatible repository discovery
.codex-plugin/plugin.json            native Codex plugin manifest
.agents/plugins/marketplace.json     native Codex repository marketplace
.claude-plugin/plugin.json           Claude Code plugin manifest
.claude-plugin/marketplace.json      Claude Code marketplace catalog
.omp-plugin/marketplace.json         oh-my-pi catalog, identical to Claude's
.kimi-plugin/plugin.json            Kimi Code plugin manifest
AGENTS.md                             repository-wide Codex authoring guidance
CODEX.md                              install, invocation, and smoke-test guide
scripts/lint-skills.py               cross-catalog skill linter
scripts/check-codex-compat.py        native Codex contract checker
tests/skill-triggers.json            representative selection cases

Design rules

1. Focused selection surface. A description starts with Use when, front-loads the task and recognizable symptoms, and names a real non-trigger boundary. Workflow details stay in the body.
2. Stable names. Skill directory names are public invocation interfaces and do not change for one host.
3. One canonical tree. Host discovery paths and plugins expose skills/; they do not carry copied skill forks.
4. Autonomy with safe failure. Skills never ask a human mid-run. Ambiguity goes to oracle-consensus; failed dispatch, no consensus, or exhausted gates records and defers the action.
5. Evidence before claims. Codebase claims carry file references; metric claims carry comparable scanner snapshots; bug fixes carry a failing regression test.
6. Capability-first portability. Generic instructions describe required behavior, then link to shared host adapters. They do not assume one vendor's tool name.
7. Progressive disclosure. Selection metadata stays small; reusable details move to linked references; deterministic rules become tested scripts when useful.
8. Independent review. Agents that judge a diff or decision do not author it and do not receive reasoning that would bias the blind round.
9. Every decision leaves a record. Unrecorded decisions do not exist.
10. Validation before release. Structural checks, trigger cases, affected tooling tests, and an end-to-end host smoke test each cover different failure modes.