v2.1.0 — Kivax is now a pip package

Install

pipx install kivax

Same command on Linux, macOS, and Windows. Upgrading is pipx upgrade kivax, and that is the whole story — the agents, skills, and templates Kivax installs into projects now ship inside the package, so the CLI and the material it copies can never be out of step.

Breaking: install.py is gone

Kivax used to be installed by cloning the repository and running install.py, which left a store in ~/.kivax and a kivax symlink in ~/.local/bin. Neither is used any more, and if that old symlink sits earlier on your PATH it will keep shadowing the version you just installed.

rm -rf ~/.kivax ~/.local/bin/kivax

kivax version and kivax doctor detect the leftovers and tell you. Projects need no migration — everything kivax init wrote is already committed in your repository.

Why

install.py reimplemented what pip already does: dependency resolution (with a --break-system-packages workaround for PEP 668), PATH placement, and a kivax.bat shim on Windows. pipx does all three properly and sidesteps the "externally-managed-environment" error on Debian, Ubuntu, and Homebrew Python by isolating the tool in its own virtualenv.

It also let the CLI and the global store drift: updating one didn't update the other. With the store shipped as package data they are one artifact and cannot disagree about which version they are.

Also in this release

• Editing the store by hand no longer works. It was never supported — agents are generated and kivax upgrade overwrites a project's copies — so this stops pretending rather than removing a feature. Use the agents: block in .kivax/config.yml for models, upstream changes for behavior, or point KIVAX_HOME at your own copy of the store if you genuinely need a divergent one.
• The sample CI gate is now copy-pasteable. Installing Kivax on a runner is pip install kivax instead of a placeholder for your own infrastructure.
• Windows is covered by CI, not just claimed: the full suite plus a real wheel install and kivax init run on every push.

Verified

482 tests, 96.89% coverage, across Python 3.10–3.13 on Linux, macOS, and Windows. A dedicated package job builds the wheel, asserts its store file count matches the tree exactly, installs it into a clean virtualenv with no access to the checkout, and drives a real init / feature new / doctor / validate.

Full changelog: v2.0.0...v2.1.0

v0.1.0 — Spec-Driven Development framework with lessons store

What is Kivax?

Spec-anchored Spec-Driven Development runtime: your narrative spec compiles into a canonical YAML, from which the plan, tests, and code are derived, with hash-verifiable traceability between them.

Works with Claude Code, opencode, Cursor, GitHub Copilot (VS Code + CLI), and OpenAI Codex CLI — one project can use several at once.

v0.1.0 Features

Core SDD Pipeline

• 9-phase flow: principles → architecture → spec → compile → plan → tdd → it → audit → retro
• Spec-first enforcement: every behavior change traces to a REQ
• Immutable REQ IDs: hashes drive selective invalidation only for what changed
• Per-feature isolation: specs/01-feature/, specs/02-feature/, etc.

The Lessons Store (New in v0.1.0)

• Binding feedback loop: retro phase writes what iterations cost; plan/tdd/it read it back
• Mechanical enforcement: audit gate fails on unanswered lessons (phase-scoped, path-scoped, or project-wide)
• Anti-rot rules: reinforce on recurrence, retire when false, never delete
• Knowledge curator: specialist agent that turns cycle cost into actionable rules

New in v0.1.0

• Researcher agent: investigates vague ideas, provides options + prior art before spec-analyst starts
• Resumable task lists: ^C mid-work, resume from exact point; kivax task tracks where you left off
• Principles + architecture phases: optional one-time setup phases (constitution renamed to principles)
• Wiki curator: maintains derived knowledge, one page per domain concept
• Traceability gate: spec-first verification at audit, locks hashes, catches stale specs in other features

Artifacts

• specs/NN-slug/spec.md — narrative spec
• specs/NN-slug/spec.yml — canonical anchor with immutable REQ IDs
• specs/NN-slug/plan.md — contracts, REQ→module→test mapping, lessons applied
• specs/wiki/ — derived knowledge pages
• specs/lessons/LSN-*.md — what past iterations cost (new)
• .kivax/state.yml — phase + per-REQ status (portable across sessions)
• .kivax/traceability.lock.json — hashes from the last PASSING cycle

Getting Started

git clone https://github.com/null-result/kivax.git
cd kivax
python3 install.py

# Then in your project:
kivax init

Answer the setup wizard (greenfield vs. existing, include principles/architecture, choose stack), then open your AI assistant and ask it to start a new feature — the kivax-new skill does the rest.

Documentation

• README.md: full guide, pipeline overview, file layout, CLI reference
• Agents + Skills: inside the repo at share/agents/ and share/runtime/skills/; every phase is a skill your assistant reads
• Tests: 465 passing, 97%+ coverage (run pytest tests)

Testing

pytest tests                                                             # all tests
pytest tests/unit/test_kivax_lessons.py -v                             # lessons store only
pytest tests --cov=. --cov-config=.coveragerc --cov-report=term-missing # coverage

License

MIT