DIXI Spec Kit documentation Español · Source on GitHub

DIXI Spec Kit

English · Español · Documentation site

Purpose

DIXI Spec Kit is a Dixi Project tool for specification-driven development (SDD) with traceability and verification: from an idea to linked specs, tests first, verified code and human review. It ships a CLI (dixi) and commands for Claude Code.

Documentation

Everything is listed in the documentation index, by what you want to do. The pages people open most:

ToOpen
Learn the method by building one featureTutorial, seven short steps
Know which command to use and whenCommand guide
Look up one command of the agentCommand reference, one page for each of the thirty-three
Look up one terminal command or optionCLI reference
Use the Claude Code subagentsSubagents
Have the rules enforced by hooksAutomatic controls
Add your own operations or textsExtensions and presets

Installation

Requirements: Python 3.11 or later, macOS or Linux. On Windows, use WSL 2 with the project under ~, not /mnt/c (details); native Windows is not supported.

uv tool install dixi-spec-kit
# or
pipx install dixi-spec-kit

The package is on PyPI. To pin a tag from Git instead: uv tool install git+https://github.com/dixi-project/dixi-spec-kit@v1.14.0. Without network access to PyPI, download the wheel from the v1.14.0 release and install it with pipx install dixi_spec_kit-1.14.0-py3-none-any.whl.

Quickstart

dixi init my-project --agent claude   # or --agent none to use it without an agent
cd my-project
dixi doctor
dixi check
make verify

Open Claude Code in my-project and walk through:

/dixi.discover <your idea>
/dixi.specify <feature>
/dixi.clarify <spec ID>
/dixi.plan <FEATURE-ID>
/dixi.tasks <FEATURE-ID>
/dixi.build <T-ID>
/dixi.verify
/dixi.review main

/dixi.constitution sets the project's versioned principles, which every operation reads; /dixi.checklist tests the quality of a feature's requirements before building; /dixi.converge compares the code with its specs and appends the missing work as tasks. For existing projects, /dixi.onboard drafts modules and features from the code for you to validate; /dixi.bugfix fixes a bug with a failing test committed first and a traced record; /dixi.issues publishes a feature's tasks as GitHub issues with gh, after you confirm a preview. /dixi.analyze checks consistency and the impact of a change; /dixi.status suggests the next step. Design with /dixi.domain, /dixi.architecture, /dixi.contract and /dixi.threat-model; propose changes with /dixi.change; leave a resumable handoff with /dixi.handoff. /dixi.interview fills the {{pending: …}} blanks one question at a time and /dixi.risk-review prepares a risk-based review; subagents dixi-architect, dixi-tester, dixi-developer and dixi-reviewer live in .claude/agents/. Specialized operations: /dixi.data, /dixi.quality, /dixi.ai, /dixi.release, /dixi.promote, /dixi.operate, /dixi.finops, /dixi.compliance and /dixi.duediligence write documents only; they never run migrations, deploy, change MODE or claim certifications. Documents and messages are in English by default; use dixi --lang es init … for Spanish. Inside a project, messages follow the project's language.

The command guide maps the journey, says which command to use when and walks through a small example from dixi init to a release. Every command has its own page in the command reference: what it does, when to use it, what it reads and writes, where it stops and how to invoke it from Claude Code, Codex or Agent Skills.

Profiles

dixi init installs a minimal documentary baseline by default. Choose a profile to also get standards, guides and blanks for governance, business, data, architecture, engineering, quality, security, observability, delivery, operations, product, UX, AI, FinOps, research, growth and customer success:

ProfileForAdds
minimal (default)Trying the method or adding documents by handNothing: the 16-file baseline
siteLanding page or content site without its own backend77 templates
appA few deployable parts: web, admin, API, one database190 templates
platformSeveral services, events, apps or teams241 templates
--regulatedPayments, health, sensitive data or enterprise customersCompliance (GDPR, SOC 2, ISO 27001, HIPAA, PCI DSS), due diligence and stricter security templates on top of site, app or platform (94, 226 or 273 in total)
dixi init my-app --agent claude --profile app

Templates are guidance with {{pending: …}} blanks, not decisions: delete the ones that do not apply (dixi check does not require them). The exact list per profile is in the profiles contract. dixi upgrade --dry-run --profile <name> shows what another profile would add.

Terminal commands

CommandWhat it does
`dixi init <dir> [--agent none\claude\codex] [--profile …] [--regulated] [--controls]`Creates the documentary baseline, plus the profile's templates, in a new or empty directory (. for the current one); never overwrites.
dixi init <dir> --existing [same options]Adds DIXI to a folder that already has files (an existing repository): creates only what is missing, never overwrites, and lists the files it kept.
dixi doctorDiagnoses environment and project without network or credentials.
dixi checkChecks structure, links and traceability. Runs no code.
`dixi workflow list\show\prepare`Lists and prepares the discover, specify, clarify, domain, architecture, contract, threat-model and plan procedures.
dixi placeholders [--strict]Lists the {{pending: …}} markers left in the project's documents.
dixi pr-size [--base main] [--max 1500]Measures the current branch: changed lines without docs, lockfiles, generated files or tests (reported apart). Read-only; exit 1 over the limit.
dixi modeShows MODE and, for mvp, which of the items /dixi.promote reviews have no evidence yet. Read-only: it cannot change MODE.
dixi preset add <folder> · list · remove <id>Replaces kit operation texts and templates with your team's versions from a local, data-only folder; only files you have not edited, .dixi/overrides/ always wins, and removal restores the kit text.
dixi extension add <folder> · list · remove <id>Adds your team's own operations from a local, data-only folder, as dixi-<extension>-<operation> for the project's agent; never runs anything and never shadows a kit operation.
dixi upgrade --dry-run [--profile …] [--controls]Previews what the installed kit version would change: unchanged, updatable, conflicting, new, missing and obsolete files. Writes nothing.
dixi upgrade --apply [--profile …] [--controls]Writes only updatable and new kit files, each atomically and re-checked right before writing; never your edits, deleted or obsolete files.
dixi --help, dixi --versionHelp and version. Global options: `--lang es\en, --json`.

Exit codes: 0 success, 1 invalid content, 2 usage error or missing project, 3 occupied or unsafe destination, 4 unsupported version or platform, 5 I/O failure. Every command, subcommand and option is in the CLI reference.

Examples

examples/notes is a notes library and CLI built with this flow, including an evolution with its impact analysis. make verify runs dixi check and 12 real tests.

examples/i18n-site is a Next.js (TypeScript) site in English and Spanish created with --profile site: language-prefixed routes, a root redirect by Accept-Language, hreflang and canonical URLs per language, and JSON catalogs. Its logic is dependency-free ES modules; make verify runs dixi check and 18 node --test tests when Node.js is installed, with no npm install.

What is and is not included

See the support matrix. In short: by default the adapters install commands and instructions, not hooks or permissions; rules are instructions for the agent, and effective protection comes from your review and branch protection. Add --controls (with --agent claude or codex) to install hooks that enforce frozen tests, no secrets, no signing or merging, production-mode safety and verification before stopping; in Codex they run once you trust the project and approve them with /hooks. Hooks are a second layer, not the last one. --agent skills installs the operations as Agent Skills in .agents/skills/ for other compatible agents (Cursor, Gemini CLI, OpenCode…), without hooks; see the support matrix for what is verified. The Codex adapter (--agent codex, skills invoked as $dixi-specify, $dixi-plan, …) installs the same operations as Agent Skills, with implicit invocation disabled. dixi upgrade --apply takes kit updates without touching your edits. Windows works through WSL 2 only.

Coming from GitHub Spec Kit

Every Spec Kit command has a DIXI counterpart (/speckit.implement is /dixi.build), plus twenty-four more operations. See the command map and a dated, sourced comparison, including the gaps DIXI still has.

Contributing

Anyone can use, clone and fork. Propose changes with a pull request from your fork; only maintainers merge into main, after review and green checks. See CONTRIBUTING.md and the code of conduct; for help, see SUPPORT.md. Report vulnerabilities privately as described in SECURITY.md.

License

MIT © 2026 Dixi Project. Projects you generate with dixi init are yours.