sdev is a framework for developing software from specifications with people and AI. Record purposes, requirements, and design decisions so implementation and review can follow their reasons. The CLI provides writing guidelines and templates.
Specifications have three responsibilities. Follow the consuming project's existing documents and conventions when available.
| Document | What it defines |
|---|---|
| Product | Whose problem to solve and what to provide |
| Requirements | Feature behavior and acceptance criteria |
| Design | How to meet requirements and why that approach was chosen |
Run these commands at the root of the project where you want to use sdev. The installer selects the latest stable release for your OS and CPU and initializes the project. No Rust, Node.js, or PATH setup is required.
curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/azu/sdev/main/install.sh | sh -s -- --init
./bin/sdev helpInitialization prepares these files, preserving existing AGENTS.md instructions.
| File | Purpose |
|---|---|
bin/sdev |
A launcher pinned to a version and every target's SHA-256 |
AGENTS.md |
Instructions for agents to read sdev's guides |
sdev.toml |
The project's default and translation languages |
.gitignore |
Excludes downloaded binaries in .sdev/ from Git |
Commit these four files so a clone can use ./bin/sdev help too.
Initialization fetches the published checksums for all five targets and stores them in the launcher. It requires curl and network access.
The launcher downloads a missing binary, checks it against the committed SHA-256, and runs cached copies without network access. A later replacement of the remote binary and checksum is rejected.
Initialization creates no specifications or empty specification directories.
Downloads are checked against their checksum and version.
Add --verify to the installer to verify GitHub's evidence of the build's origin too.
See bootstrap and attestation verification for details.
Use initialization's --path option to choose a location other than bin/sdev.
Download the initial binary elsewhere first; generated AGENTS.md instructions will use the chosen path.
curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/azu/sdev/main/install.sh | sh -s -- --install-dir ./.sdev/setup
./.sdev/setup/sdev init --path ./scripts/sdev
./scripts/sdev helpExisting unrelated files and edited launchers are preserved. For changing an initialized location, see Releasing and updating.
Projects using mise can install the same Release binaries through its GitHub backend. Follow installation with mise to configure the platform files and generate mise.lock, then run:
mise install --locked
mise exec -- sdev helpCommit mise.toml and mise.lock. Point AGENTS.md to mise exec -- sdev help.
This route uses mise for version selection and updates; it does not require bin/sdev or sdev init.
Download the Windows x64 executable from GitHub Releases and place it at bin/sdev.exe.
Initialize and read a guide from PowerShell:
.\bin\sdev.exe init
.\bin\sdev.exe helpWindows uses the installed executable directly. See distribution targets and selection for OS requirements and manual installation.
Run from the project root to update the version shared by its launcher:
./bin/sdev updateUse --version X.Y.Z to select a release, or --verify to check its provenance.
The command keeps the launcher path and project documents. Review and commit the updated launcher.
It stops if the launcher has been edited or verification fails.
For versions without update, rerun the installation command above. An existing generated launcher is updated in place, including when --init is passed.
A custom launcher can be selected with sh install.sh --update --path ./scripts/sdev using a reviewed installer.
Updates run when requested; ordinary guide commands continue to use the committed version.
English is the default when no language is configured.
For a new project, sdev init --lang en --translations ja records English as the default with Japanese translations in sdev.toml.
For an initialized project, edit that file to change the choices:
language = "en"
translations = ["ja"]Default-language documents use .md; other language versions use names such as requirements.ja.md.
Maintain both versions as the same specification in the same change.
Select Japanese for a single command with ./bin/sdev help design --lang ja.
The project's default also selects the language of guides and templates when --lang is omitted.
Pass a task name to help to read its guide.
List the available choices first. Each description explains when to use the guide and what it helps accomplish, including early discussions of ideas and feature changes:
./bin/sdev help| Command | Guide |
|---|---|
./bin/sdev help product |
Product purpose, users, and value |
./bin/sdev help requirements |
Feature behavior and acceptance criteria |
./bin/sdev help design |
Methods for meeting requirements |
./bin/sdev help documents |
Document responsibilities, placement, and updates |
./bin/sdev help workflow |
Dialogue, research, implementation, and verification |
./bin/sdev help scenarios |
Acceptance scenarios |
./bin/sdev help brownfield |
Starting specifications in a project with existing code |
Agents use these guides to clarify purpose and scope with the user. An idea alone does not authorize implementation; a request limited to writing a document ends with presenting it for review. See Agent working principles for the workflow.
Use a template designated by the consuming project when available. Otherwise, choose an embedded fallback:
./bin/sdev template
./bin/sdev template requirementsCommands display template bodies. Respect an existing specification's structure when editing it. Guides and templates are embedded in the executable, so no separate download is needed.
Run lint at the project root to check broken links and reference directions.
It checks README.md, AGENTS.md, their language versions, and Markdown under docs.
./bin/sdev lint
./bin/sdev lint --format jsonText output is the default; JSON is available for other tools. See document-lint Requirements for scope and exit codes.
review captures real Git differences and opens the specifications as a reading surface.
With JEV_API_KEY set privately in the server environment, enable Jev to find related Requirements and Design passages and check changed code for missing specification coverage:
./bin/sdev help review
./bin/sdev review --base main --serve --jev
./bin/sdev review --base main --serve --jev --jev-model jev-1.13.0 --cache-dir "$HOME/.cache/sdev/review"Read with J/K, or click a passage to focus it and open related text in place. Hovering or tabbing through text does not open or change details. The related-view selector also offers a popover. Press Enter or type a character other than J/K to start an inline comment.
Use "Copy notes" to paste comments with their original context into the agent conversation. In server mode, "Send to agent" writes a review.feedback JSON line to the launching command output for that agent to read; it does not automatically resume an idle agent. Markdown and JSON file exports remain available.
Jev classifies the actual captured passages and changes; it does not generate rationale. The code check returns unmatched or uncertain candidates for human inspection. It does not certify specification completeness. Results are cached by actual input, model, and judgment conditions. Credentials remain on the server, and only explicit --jev permits external transmission of specification and code context.
A portable offline HTML remains available with --output /tmp/review.html. Optional --prepare and --input retain a fixed comparison and supplementary agent items; hand-written relationship JSON is unnecessary for live queries. Working-tree servers update saved specifications and code without a page reload, retaining comments and replacing old judgments. Prepared input, two-commit comparisons, and standalone HTML remain fixed. Existing output files are preserved.
See the review Requirements for scope.
Prepare Rust, then use mise for development tools and commands. At the repository root, trust the configuration and install locked tools:
mise trust
mise install --lockedThe postinstall hook installs dependencies and registers hk to check document and Rust changes before commits. English README prose uses slopless; Japanese README prose uses textlint's technical-writing preset.
mise run md:lint
mise run md:fix # Review automatic changes
mise run rs:check # Rust formatting, static checks, and testsRead the Rust development guide for setup and verification, and Releasing and updating for distributions and publication. Start from the sdev Product and documentation entry point to explore its purpose and specifications.
sdev is released under the MIT License.