Version: v0.13.0 | Status: Final | License: BSD 3-Clause
SDAIS is a software development paradigm in which humans author requirements and adopted reference contracts while AI agents synthesise, review, and refine all implementation code. No human writes implementation code. Human-authored RSF determines intent and adoption scope; pinned libraries supply the adopted contract details.
Read docs/INTRODUCTION.md for the full concept and motivation. For step-by-step workflows see docs/GREENFIELD.md and docs/TRANSFORMATION.md. Terms and acronyms are defined in docs/GLOSSARY.md.
Create a directory for your project, copy or download the distribution archive into it, unpack the archive, and run the installer:
mkdir my-project
cd my-project
cp /path/to/sdais-v0.13.0.tgz .
tar xzf sdais-v0.13.0.tgz
./install.sh "My Project"The archive expands directly into the current directory; it does not create an
extra version-named directory. You can replace the cp command with a download
command that saves the archive as sdais-v0.13.0.tgz.
install.sh and update.sh must be run from this project root — the directory
that contains SDAIS.md, install.sh, update.sh, and scaffold/. Do not run
them from inside the SDAIS distribution repository.
The installer argument is a human-readable label substituted into AGENTS.md
— it does not have to match your directory name.
install.sh creates AGENTS.md, the full sdais/ scaffold, and the managed
implementation/ workspace. The repository-local launcher is ./sdais.sh.
The installer also places a convenience copy in ~/.local/bin/sdais; the
canonical invocation used by SDAIS documentation remains ./sdais.sh from the
project root.
SDAIS.md in the project root is the distribution file. install.sh copies it into sdais/SDAIS.md — the project-local copy that agents read. These are intentionally two separate files at different paths: when you upgrade, you replace the root-level SDAIS.md and run ./update.sh, which refreshes sdais/SDAIS.md without touching any project content.
To upgrade an existing project, copy or download the new archive into the project root, unpack it there, and run:
tar xzf sdais-v0.13.0.tgz
./update.sh --from v0.12.2Unpacking replaces only distribution files and the bundled scaffold/ tree.
update.sh then refreshes managed project files while preserving project
content as documented below.
Place reusable human-authored contracts under
sdais/library/<library-id>/v<N>/. Requirements adopt them explicitly with an
exact file path, for example:
The puzzle UI must follow `sdais/library/tds/v1/tds.md`.The generated or human-authored RSF item carries the same contract separately from its prose provenance:
- **Source:** sdais/gspec/v2/ui.md
- **Libraries:** sdais/library/tds/v1/tds.mdThe mechanism is generic: an API requirement can instead adopt
sdais/library/example-api/v2/openapi.yaml#paths. Libraries are normative only
where human prose or RSF explicitly adopts them. The SemanticAuditor resolves
and checks them; Architect traces them; Generator and Transformation implement
them; Reviewer verifies conformance; Refiner and TestGenerator use the same
pinned files. To amend a published contract, add v<N+1> and update only the
requirements that adopt it—old requirements keep using their pinned version.
Update preserves every file under sdais/library/.
Fresh projects keep every agent-managed product artefact under
implementation/. The zero-byte marker implementation/.sdais-root activates
this contract:
implementation/
├── .sdais-root
├── go.mod
├── cmd/
├── internal/
└── tests/
The same rule applies to other languages and to source, tests, package
manifests, lockfiles, fixtures, assets, migrations, build/deployment files, and
product documentation. These files are committed project content.
generated/ is intentionally not used because the reviewed implementation is
not disposable build output.
Update does not create the marker or move code in an existing unmarked project;
that project keeps the legacy in-place behavior. To opt in, move the complete
implementation workspace into implementation/, then create the zero-byte
marker last. In SDAIS-T, legacy source may remain outside the root: Analyzer
annotates it in place, Transformation writes the complete target under
implementation/, and downstream agents operate only on that target.
The ./sdais.sh script launches any agent role against a model of your choice. Run it from the project root—the directory containing sdais/prompts/:
./sdais.sh <tool> <model> <role>
| Argument | Values | Example |
|---|---|---|
tool |
claude, ollama, codex, gemini |
claude |
model |
Any model ID supported by the tool | claude-opus-4-5 |
role |
CamelCase or kebab-case role name | RequirementsEngineer or requirements-engineer |
Examples:
./sdais.sh claude claude-opus-4-5 RequirementsEngineer
./sdais.sh claude claude-sonnet-4-5 Generator
./sdais.sh claude claude-opus-4-5 SemanticAuditor
./sdais.sh ollama gemma4 Reviewer
./sdais.sh codex codex-mini Generator
./sdais.sh gemini gemini-2.0-flash Generator
Pin the model per role in your AGENTS.md to prevent version drift between rounds.
You write specifications. AI writes code. The loop looks like this:
Phase 0 — Draft (optional)
If you find it easier to start with free-form prose, write your ideas into sdais/gspec/v1/ (any filename, any format) and run the RequirementsEngineer. It will ask clarifying questions via [[QN]] markers; you answer each with [[AN answer]]. The loop repeats until the spec is clean, then the agent generates sdais/rsf/v1/ for you with a **Source:** traceability field and the smallest applicable **Libraries:** set on every adopting item. Skip this phase if you prefer to author RSF items directly.
Phase 1 — Specify
- Author or review requirement files (FR, NFR, C, E, AC) in
sdais/rsf/v1/using the installed templates. - Run the SemanticAuditor — it reads your requirements and writes findings for anything ambiguous, incomplete, or contradictory.
- Resolve each finding: fix the requirement in place, drop it, split it, or waive the finding with a rationale.
- If you have environment items (
E-), run the Grounder to verify they exist in your infrastructure. - Optionally run the Architect to produce the architecture document set and ADRs before any code is written.
Repeat phases 1–5 until all findings are resolved. That cleared RSF is your contract with the AI.
Phase 2 — Synthesise
- Run the Generator — it reads the cleared RSF and synthesises a complete, annotated implementation under
implementation/. - Run the Reviewer — it checks every annotated code unit against the RSF and writes findings for any violations.
- Run the Refiner — it fixes every violation guided by the Reviewer's hints.
- Return to step 7. Repeat until the Reviewer reports zero violations.
Phase 3 — Approve
- Review the result. Approve, amend the RSF and restart, or reject and regenerate.
- Optionally run the SecurityAuditor and TestGenerator at any point after generation.
You have an existing codebase. You want to migrate it, modularise it, or bring it under formal specification.
Phase 0 — Draft (optional)
If you find it easier to start with free-form prose, write your ideas about the existing system and desired changes into sdais/tspec/v1/ and run the TransformationEngineer. It will ask clarifying questions via [[QN]] markers; you answer each with [[AN answer]]. The loop repeats until the spec is clean, then the agent generates TRS items in sdais/trs/v1/ and draft CDF files in sdais/cdf/v1/. Skip this phase if you prefer to author TRS items and CDF files directly.
- Write hypothesis files (TRS) capturing what you believe the system does.
- Run the Analyzer — it reads the codebase, adds annotation blocks to every unit, derives formal RSF items from observed behaviour, and opens findings for anything unclear.
- Resolve findings and refine the derived RSF through the standard semantic audit loop.
- Activate one or more Change Definition Files (CDF) describing the transformation you want (language migration, modularisation, new persistence layer, etc.).
- Run the Transformation agent — it applies the CDFs to the annotated codebase, writes the managed target under
implementation/, and preserves all annotation identifiers without deleting legacy source. - Continue from step 7 of the greenfield loop above (Review → Refine → Approve).
Repository-maintenance commands live under scripts/ and are not included in
the SDAIS distribution archive:
make check
make release VERSION=v0.13.0
make verify ARCHIVE=dist/sdais-v0.13.0.tgzmake check runs shell syntax checks, repository tests, Markdown link and fence
checks, managed-prompt inventory checks, and git diff --check.
make release verifies that the requested version matches the specification,
README, guides, changelog, installer, and updater. It then runs all checks,
builds the complete archive in temporary staging, installs and updates temporary
projects from that archive, verifies project-library and custom-agent
preservation, and writes the result under dist/ with its SHA-256 checksum. It
refuses to overwrite an existing archive; use make release-force explicitly
when rebuilding the same version.
The generated dist/ directory is ignored by git. Release archives contain
only the user-facing distribution files; scripts/, tests/, dist/, and
project-specific libraries are excluded.
| File / Directory | Purpose |
|---|---|
SDAIS.md |
Full normative specification — single source of truth |
install.sh |
Scaffolds a new project |
update.sh |
Upgrades an existing project's scaffold |
sdais.sh |
Launcher — runs any agent role with a chosen tool and model |
Makefile |
Convenience entry points for checks and release automation |
scripts/ |
Developer-only checking, release building, and archive verification |
tests/ |
Repository regression tests; not included in releases |
dist/ |
Ignored output directory for generated release archives |
scaffold/ |
Prompt files and templates installed by install |
sdais/library/ (installed projects) |
Project-owned, immutable versioned reference contracts; never bundled with project-specific content |
sdais-vX.Y.Z.tgz |
Complete distribution archive; unpack before running install.sh or update.sh |
docs/INTRODUCTION.md |
Concepts, motivation, agent roles, and prompt reference |
docs/GREENFIELD.md |
Detailed greenfield workflow with process diagram |
docs/TRANSFORMATION.md |
Detailed transformation workflow with process diagram |
docs/GLOSSARY.md |
All acronyms, document types, and annotation identifiers |
CHANGELOG.md |
Version history |
LICENSE |
BSD 3-Clause License |
BSD 3-Clause — see LICENSE.