{
  "markdown": "# Fornax\n\n**Skills that plan before they touch your code** — portable, single-purpose skills that orient,\nunderstand, design, plan, restructure, and review, but never edit behind your back.\n\nFornax is a portable, multi-agent **skills registry**. Each skill is a small\noperation you apply to a codebase or a conversation to get one well-defined result — a plan, a map,\na review, a decision, or a clarified intent. Skills **read / plan / report** rather than edit, so an\nagent can reason with them safely *before* it changes anything.\n\nWorks across Claude Code, Codex, Cursor, Antigravity, and generic LLM agents. Installed as a Claude\nCode plugin, skills are namespaced under the brand: `/fornax:<skill>`.\n\nEach skill refines the **context** an agent holds — it separates and reorganizes what is there and\nnever fabricates what is not, which is why it reports rather than edits. See\n[docs/identity.md](docs/identity.md) for the full thesis and naming rationale;\n[PROJECT.md](PROJECT.md) for standing decisions and non-goals; and [AGENTS.md](AGENTS.md) for\nauthoring, versioning, and review rules.\n\n## The pipeline\n\nThe codebase skills form one continuous arc — each stage hands off to the next:\n\n```text\nexplore-intent → orient-repo → map-codebase → design-boundaries → plan-implementation → plan-split / plan-repo-extract → static-review\n   explore          orient       understand         design               plan                    restructure               review\n  (what/why)     (governance)   (how it works)    (boundaries)         (the work)               (split/extract)          (quality)\n```\n\n`static-review`'s findings return to the arc through [`triage-findings`](skills/triage-findings/),\nwhich groups them into causes, lists the repairs each cause admits with what each one touches, and\nroutes the accepted work back into the arc — the arc's one feedback edge.\n\nThe slugs are task-descriptive and say what each skill does.\n\n## Skills\n\nGrouped by `family` (see [docs/identity.md](docs/identity.md) and the skill maps below).\n\n**Implementation** — codebase work; produce a plan or report, do not edit code\n\n- [`explore-intent`](skills/explore-intent/) — explore intent and options through dialogue before building (a stance).\n- [`orient-repo`](skills/orient-repo/) — orient in an unfamiliar repo before acting, as a working brief.\n- [`map-codebase`](skills/map-codebase/) — map how an unfamiliar codebase or subsystem works.\n- [`design-boundaries`](skills/design-boundaries/) — design component boundaries before the code exists.\n- [`diagnose-issue`](skills/diagnose-issue/) — statically trace control and data flow to infer the root cause.\n- [`plan-implementation`](skills/plan-implementation/) — turn a goal into an ordered, verifiable implementation plan.\n- [`plan-testing`](skills/plan-testing/) — design a comprehensive test strategy for a feature or refactor.\n- [`plan-migration`](skills/plan-migration/) — plan a safe data migration or database schema change.\n- [`plan-split`](skills/plan-split/) — plan splitting a large or tangled code unit in place.\n- [`plan-repo-extract`](skills/plan-repo-extract/) — assess extracting a component into its own repository.\n- [`static-review`](skills/static-review/) — local, gate-based static code review.\n- [`triage-findings`](skills/triage-findings/) — decide which review findings to accept, and what each cause's repair would touch.\n- [`handle-feedback`](skills/handle-feedback/) — handle code-review feedback with rigor, not performative agreement (a stance).\n\n**Knowledge** — capture and shape conversation knowledge\n\n- [`assess-knowledge`](skills/assess-knowledge/) — assess a conversation for knowledge worth extracting.\n- [`write-learning-report`](skills/write-learning-report/) — turn mature conversation content into a learning report.\n- [`save-knowledge`](skills/save-knowledge/) — persist conversation knowledge into durable project, agent, or team sources.\n\n**Decisions & governance** — project-level judgment calls\n\n- [`assess-dependency`](skills/assess-dependency/) — decide whether to adopt a structural dependency.\n- [`assess-threats`](skills/assess-threats/) — identify trust boundaries and potential security vulnerabilities.\n- [`audit-governance`](skills/audit-governance/) — test governance prose against what the project actually enforces.\n- [`resolve-deadlock`](skills/resolve-deadlock/) — resolve conflicting requirements or a governance deadlock.\n\n**Meta** — skills about the toolkit itself\n\n- [`scope-new-skill`](skills/scope-new-skill/) — explore whether a workflow should become a skill.\n- [`harden-skill`](skills/harden-skill/) — harden a skill's instructions so the wording reliably changes behavior.\n\n## Skill maps\n\nPer-domain handoff graphs, generated from each skill's `family` and its `SKILL.md` handoffs by\n[scripts/skill_graph.py](scripts/skill_graph.py) — regenerate with `--write` after changing handoffs,\nand CI fails on a stale block. An edge that crosses into another domain is a hand-off to that\ndomain's skills.\n\n<!-- SKILL-MAPS:START (generated by scripts/skill_graph.py — do not edit by hand) -->\n\n### Implementation\n\n```mermaid\nflowchart LR\n    design-boundaries\n    diagnose-issue\n    explore-intent\n    handle-feedback\n    map-codebase\n    orient-repo\n    plan-implementation\n    plan-migration\n    plan-repo-extract\n    plan-split\n    plan-testing\n    static-review\n    triage-findings\n    design-boundaries --> assess-dependency\n    design-boundaries --> plan-implementation\n    design-boundaries --> plan-repo-extract\n    design-boundaries --> plan-split\n    diagnose-issue --> map-codebase\n    explore-intent --> design-boundaries\n    explore-intent --> map-codebase\n    explore-intent --> plan-implementation\n    explore-intent --> scope-new-skill\n    handle-feedback --> design-boundaries\n    handle-feedback --> map-codebase\n    handle-feedback --> plan-implementation\n    handle-feedback --> triage-findings\n    map-codebase --> design-boundaries\n    map-codebase --> diagnose-issue\n    map-codebase --> orient-repo\n    map-codebase --> plan-split\n    map-codebase --> static-review\n    orient-repo --> audit-governance\n    orient-repo --> map-codebase\n    orient-repo --> plan-split\n    orient-repo --> save-knowledge\n    plan-implementation --> design-boundaries\n    plan-implementation --> map-codebase\n    plan-implementation --> plan-split\n    plan-implementation --> static-review\n    plan-repo-extract --> design-boundaries\n    plan-repo-extract --> plan-split\n    plan-split --> design-boundaries\n    plan-split --> plan-repo-extract\n    plan-split --> static-review\n    static-review --> assess-threats\n    static-review --> diagnose-issue\n    static-review --> plan-testing\n    static-review --> triage-findings\n    triage-findings --> design-boundaries\n    triage-findings --> diagnose-issue\n    triage-findings --> plan-implementation\n    triage-findings --> plan-split\n    triage-findings --> plan-testing\n    triage-findings --> static-review\n```\n\n### Knowledge\n\n```mermaid\nflowchart LR\n    assess-knowledge\n    save-knowledge\n    write-learning-report\n    save-knowledge --> write-learning-report\n```\n\n### Decisions & governance\n\n```mermaid\nflowchart LR\n    assess-dependency\n    assess-threats\n    audit-governance\n    resolve-deadlock\n    audit-governance --> assess-knowledge\n    audit-governance --> plan-split\n    audit-governance --> resolve-deadlock\n    audit-governance --> save-knowledge\n    resolve-deadlock --> audit-governance\n    resolve-deadlock --> plan-split\n    resolve-deadlock --> save-knowledge\n```\n\n### Meta (skills about the toolkit)\n\n```mermaid\nflowchart LR\n    harden-skill\n    scope-new-skill\n    harden-skill --> audit-governance\n    harden-skill --> scope-new-skill\n    scope-new-skill --> harden-skill\n```\n\n<!-- SKILL-MAPS:END -->\n\n## Design principles\n\n- **Portable first.** Stable workflow in `SKILL.md`, vendor-neutral manifest in `skill.yaml`. Skills\n  are host-neutral; host-specific discovery and install live at the packaging layer (root plugin\n  manifests), not per skill. Copy or vendor a skill folder without rewriting paths.\n- **Read / plan / report.** Skills produce plans, maps, and reviews and hand off execution — they do\n  not edit code or change state behind the user's back.\n- **Task-descriptive names.** Slugs say what the skill does; triggering rides the `description`, and\n  the `/fornax:` prefix adds a second layer of collision safety against built-ins.\n\n## Layout\n\n```text\ndistribution.json       # canonical distribution identity and release version\nskills/<skill-name>/\n  skill.yaml            # portable discovery manifest\n  SKILL.md              # portable workflow (entrypoint)\n  skill-interface.yaml  # optional record handoff declaration\n  references/           # detail loaded on demand\n.claude-plugin/         # Claude Code plugin manifest (drives the /fornax: prefix)\ntemplates/skill/        # starting point for a new skill\nscripts/check_workspace.py\n```\n\n## Install\n\nEvery `SKILL.md` follows the open [Agent Skills](https://agentskills.io) standard, so the skills run\nacross many hosts. Treat each `skills/<skill-name>/` folder as the portable package boundary; see\n[docs/host-packaging.md](docs/host-packaging.md) for per-host details.\n\nTo deploy the tagged release through one provenance-aware workflow without installing a permanent\nCLI command:\n\n```sh\npipx run \\\n  --spec \"git+https://github.com/tacticaldoll/fornax.git@v0.4.1#subdirectory=tools/fornax-cli\" \\\n  fornax deploy --all\n```\n\nFrom a clone, build the command from the workspace instead and let the release number come from\n`distribution.json`, so no version is typed at all:\n\n```sh\nuvx --from ./tools/fornax-cli fornax deploy --all\n```\n\nPersistent `pipx` installation and the equivalent `uvx` commands are documented in\n[`tools/fornax-cli`](tools/fornax-cli/). Every entry point executes the same formal release\npipeline and deploys the canonical remote tag; none of them deploys a local source checkout.\n\n- **Claude Code** — install as a plugin (`.claude-plugin/`); skills appear as `/fornax:<skill>`.\n- **Codex / Cursor** — install as a plugin (`.codex-plugin/`, `.cursor-plugin/`).\n- **OpenCode** — add `fornax@git+https://github.com/tacticaldoll/fornax.git` to `opencode.json`\n  (see [.opencode/INSTALL.md](.opencode/INSTALL.md)).\n- **Gemini CLI / Antigravity** — install as an extension (`gemini-extension.json`) from the Git\n  repository URL (both use `~/.gemini/extensions/`).\n- **GitHub Copilot CLI / Cline** — open-standard discovery: place skill folders in `.github/skills`,\n  `.agents/skills`, `.cline/skills`, `~/.copilot/skills`, or `~/.cline/skills` as appropriate.\n- **Git-based installers** — `gh skill`, `npx skills`, or `shskills` against this repo.\n\n## Add a skill\n\nCopy `templates/skill/` into `skills/<skill-name>/` and replace the placeholders. Write `skill.yaml`\nfirst (discovery metadata), then `SKILL.md` (the portable workflow). Use\n[docs/skill-types.md](docs/skill-types.md) to pick the dominant type,\n[docs/skill-yaml-schema.md](docs/skill-yaml-schema.md) for the manifest, and\n[docs/host-packaging.md](docs/host-packaging.md) for how host-specifics are packaged.\nAdd the optional [portable interface sidecar](docs/skill-interface.md) only when another skill\nactually consumes or produces the declared record.\n\n## Validate\n\nCreate the pinned Python 3.10 maintenance environment once per clone:\n\n```sh\nuv python install\nuv venv\nuv pip sync --python .venv/bin/python requirements-maintenance.txt\n```\n\nOne public command then runs all fast deterministic checks in CI and in the pre-commit hook once\nenabled with `git config core.hooksPath .githooks`:\n\n```sh\n.venv/bin/python scripts/check_workspace.py\n```\n\nIt runs these checks, in this order:\n\n<!-- GATE-STEPS:START (generated by scripts/gate_steps.py — do not edit by hand) -->\n\n1. the maintenance runtime contract — `.python-version`, Ruff's target, and the running interpreter\n2. production skill structure, including any optional interface sidecar\n3. the same structure for `templates/skill`\n4. the generated README skill maps\n5. the generated record-seam inventory\n6. the `development-knowns.yaml` registry\n7. recorded behavioural evidence against the prose it measured\n8. this list, derived from the gate rather than transcribed\n9. tracked text hygiene and repository-local Markdown links\n10. that durable reasoning cites a symbol rather than a line number\n11. each Disposition Record's tables against the shape its contract declares\n12. Python style, at the pinned Ruff\n13. every non-Python source the repository ships, through its own parser\n14. the validation test suite\n\n<!-- GATE-STEPS:END -->\n\nRun it before installing, publishing, or copying skills. A stale generated block is fixed with its\nmatching `--write` command.\n\nWhat stays CI-only needs what the pinned maintenance environment does not declare — Node for the\nOpenCode plugin, and the deployment engine for the CLI suite:\n\n```sh\nnode --input-type=module --check < .opencode/plugins/fornax.js   # the OpenCode plugin parses\nPYTHONPATH=tools/fornax-cli python3 -m unittest discover -s tools/fornax-cli/tests\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 13158,
  "sha": "58b4c0b8b684c0dcd06eef2a7a86e16576317e0f7f9d3ddded80a455b587b7d6",
  "repo_slug": "tacticaldoll/fornax",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_tacticaldoll_fornax_928fbd6f/readme"
}