Version: v0.13.0 | See INTRODUCTION.md for concepts and prerequisites.
The SDAIS-G (Greenfield) workflow applies when you are building a new system from a clean slate. The specification precedes the code — nothing is generated until the RSF has been validated and cleared.
flowchart TD
A([Start]) --> B[Step −1\nInstall scaffold]
B --> B2{Draft prose?}
B2 -- Yes --> B3[Step 0\nWrite loose prose\nsdais/gspec/v1/]
B3 --> B4[RequirementsEngineer\nClarification loop]
B4 --> B5{Open questions?}
B5 -- Yes --> B6[Answer questions in\n## Questions section\nof gspec/vN+1/]
B6 --> B4
B5 -- No --> B7[RequirementsEngineer\nRSF Generation]
B7 --> C
B2 -- No: author directly --> C
LIB[(Adopted pinned files\nsdais/library/id/vN)] --> C
C[Step 1\nAuthor / review RSF items\nFR · NFR · C · E · AC] --> D[Step 2\nSemanticAuditor]
D --> E{Findings?}
E -- Yes --> F[Resolve findings\nFix · Drop · Supersede · Split · Waive]
F --> C
E -- No: Cleared --> G{E- items?}
G -- Yes --> H[Step 3\nGrounder]
H --> I{ENV-UNRESOLVABLE\nfindings?}
I -- Yes --> J[Resolve:\nFix · Drop · Waive]
J --> H
I -- No --> K
G -- No --> K[Step 4\nArchitect\noptional]
K --> L[Step 5\nGenerator\nwrite implementation/]
L --> M[Step 6\nReviewer]
M --> N{Violations?}
N -- Yes --> O[Step 7\nRefiner]
O --> M
LIB -. same resolved files .-> D
LIB -. trace .-> K
LIB -. implement .-> L
LIB -. verify/refine .-> M
LIB -. verify/refine .-> O
N -- No: all Verified --> P[Step 8\nHuman Approval Gate]
P --> Q{Decision}
Q -- Approve --> R([Done])
Q -- Amend RSF --> C
Q -- Reject --> L
style A fill:#2d6a4f,color:#fff
style R fill:#2d6a4f,color:#fff
style B4 fill:#1d3557,color:#fff
style B7 fill:#1d3557,color:#fff
style D fill:#1d3557,color:#fff
style H fill:#1d3557,color:#fff
style K fill:#457b9d,color:#fff
style L fill:#1d3557,color:#fff
style M fill:#1d3557,color:#fff
style O fill:#1d3557,color:#fff
style P fill:#e76f51,color:#fff
Dark blue = AI agent step. Teal = optional AI agent step. Orange = human decision gate.
Create the project root, copy or download the distribution archive into it, unpack the archive there, 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 and includes the
installer, updater, launcher, specification, documentation, and scaffold/.
It does not create an extra version-named directory.
The installer argument is the human-readable project name written to
AGENTS.md; it does not have to match the directory name.
This creates AGENTS.md, the managed implementation workspace, and the
sdais/ directory with all prompt files and templates:
<project-root>/
├── AGENTS.md
├── implementation/
│ └── .sdais-root # zero-byte managed-root marker
└── sdais/
├── SDAIS.md
├── prompts/
│ ├── requirements-engineer.md
│ ├── semantic-auditor.md
│ ├── grounder.md
│ ├── architect.md
│ ├── generator.md
│ ├── reviewer.md
│ ├── refiner.md
│ ├── security-auditor.md
│ ├── test-generator.md
│ ├── analyzer.md
│ ├── transformation.md
│ └── transformation-engineer.md
├── library/ # empty until your project adds a library
├── rsf/
│ └── v1/
│ ├── fr-0000-template.md
│ ├── nfr-0000-template.md
│ ├── c-0000-template.md
│ ├── e-0000-template.md
│ └── ac-0000-template.md
Do not edit AGENTS.md or any file in sdais/prompts/ by hand — run update.sh to refresh them when upgrading SDAIS.
The installer creates sdais/library/ empty. Its contents are project-owned;
SDAIS updates never replace or delete them.
The marker activates managed-root mode. Generator and TestGenerator place the
entire language-native product tree below implementation/, including source,
tests, package manifests, lockfiles, fixtures, assets, migrations, and
build/deployment files. For Go this means implementation/go.mod,
implementation/cmd/, and implementation/internal/, never those paths at the
project root. The implementation is committed project content; it is not an
ignored generated/ directory.
To launch any agent, use ./sdais.sh from the project root:
./sdais.sh <tool> <model> <role>
Example: ./sdais.sh claude claude-opus-4-5 SemanticAuditor. The role may be CamelCase or kebab-case. Supported tools: claude, ollama.
Prompt: sdais/prompts/requirements-engineer.md | Recommended model: High-reasoning (e.g. Claude Opus)
Writing formal requirements from scratch is hard. Step 0 is an optional on-ramp: you write rough prose describing the system you want, and the RequirementsEngineer turns it into formal RSF items through an iterative clarification loop.
Use Step 0 when you have a clear idea of what you want but struggle to express it in the structured FR/NFR/C/E/AC format. Skip it if you are comfortable authoring RSF items directly.
- Create
sdais/gspec/v1/and write one or more files describing what the system should do. No filename convention or format constraint applies — bullet points, paragraphs, or any mixture. - Run the RequirementsEngineer. It reads every spec file, inserts a lightweight
[[Q1]]marker inline at each ambiguous point, and appends a## Questionssection at the bottom of each file (below a—separator) with the full question text as### Q1: question text?. - Open the files in
sdais/gspec/v2/and answer each open question by writing your answer as free prose immediately below the corresponding### QN:heading in the## Questionssection. Do not remove, reword, or add### QN:headings — questions are the agent's domain. - Re-run the RequirementsEngineer. It incorporates answers into the prose, removes answered
[[QN]]inline markers, and appends any newly discovered questions. Repeat until it reports zero open questions. - With no open questions remaining, the agent switches to RSF Generation mode: it reads the clean spec files and writes one RSF item file per derived requirement into
sdais/rsf/v1/, each carrying a**Source:**field pointing to the spec file it was derived from and, where explicitly adopted, the smallest applicable**Libraries:**set. - Review
sdais/rsf/v1/: amend wording, delete artefacts, and add anything the agent could not derive. The**Source:**field traces each item back to the original prose.
Proceed to Step 1 (or directly to Step 2 if satisfied with the generated RSF).
Copy the relevant template, rename it with the next available sequence number and a short description, then replace every bracketed placeholder with real content. This is the only step in the entire process that is purely human.
| Template | Example |
|---|---|
fr-0000-template.md |
fr-0001-authenticate-requests.md |
nfr-0000-template.md |
nfr-0001-response-latency.md |
c-0000-template.md |
c-0001-go-version.md |
e-0000-template.md |
e-0001-database-connection.md |
ac-0000-template.md |
ac-0001-valid-key-accepted.md |
Sequence numbers start at 0001 and are never reused. Items retired during an audit carry status tags and remain in the file as tombstones — the history of every decision is preserved in git.
Functional Requirements (FR): Begin with "The system must" or "The <component> must". Describe observable behaviour, not implementation detail. Every FR must have at least one corresponding AC.
Non-Functional Requirements (NFR): Always include a numeric bound. "Low latency" is not a requirement. "95th-percentile latency must not exceed 200 ms under 1 000 concurrent requests" is.
Constraints (C): Hard rules that narrow the solution space without describing a feature. "The implementation must use Go 1.22 or later." To activate TDD mode, add a constraint item with Generation mode: TDD.
Environment (E): Runtime or deployment facts the AI must know. Set **Verified:** Pending on every E- item at authoring; the Grounder sets it to true after confirming the element exists.
Acceptance Criteria (AC): Programmatically verifiable conditions. Specify inputs, expected outputs, and observable side-effects. Every FR must be covered by at least one AC.
Use [FR-NNNN], [NFR-NNNN], [AC-NNNN], etc. inline in the ## Requirement section to link related items. References resolve to the most recent active version.
Use a library for a reusable contract, language, protocol, schema, notation,
design system, or interface that should remain its own source of truth. Store it
as UTF-8 text under sdais/library/<lower-kebab-id>/v<N>/. Published versions
are immutable.
Human prose must adopt an exact file and scope it clearly. A TUI requirement might say:
The puzzle screen must use the TDS workspace, coordinates, and widgets defined
by `sdais/library/tds/v1/tds.md`.RequirementsEngineer reads the referenced definition for terminology but does not turn its contents into hundreds of requirements. The generated item keeps provenance and normative support separate:
- **Last modified:** v1 (2026-10-08)
- **Source:** sdais/gspec/v1/ui.md
- **Libraries:** sdais/library/tds/v1/tds.md
## Requirement
The puzzle screen must present the game workspace using TDS.The mechanism is not UI-specific. An API requirement can adopt a schema section:
- **Libraries:** sdais/library/billing-api/v3/openapi.yaml#pathsMultiple paths are comma-separated. URLs, latest, unversioned paths,
directories, traversal, and missing files or anchors are invalid. If prose says
only “use TDS” or “follow the billing API,” the RequirementsEngineer asks for
the exact version, file, and adoption scope. A library file creates no
requirement merely by existing.
To amend TDS, add (for example) sdais/library/tds/v2/tds.md; never rewrite
v1. Existing RSF items continue to use v1 until a human-authored amendment
changes their **Libraries:** field. update.sh preserves both versions.
Prompt: sdais/prompts/semantic-auditor.md | Recommended model: High-reasoning (e.g. Claude Opus)
Before any code is generated, the RSF must pass a semantic audit. This is the quality gate that catches problems in the specification itself — ambiguity, gaps, contradictions, NFRs without numeric bounds, and unresolvable library references — before they propagate into code that is hard to fix.
- Run the SemanticAuditor, providing all RSF item files for the current version.
- The agent copies each affected RSF item to
sdais/rsf/v<N+1>/and appends a## Findingssection (below a—separator) with one### F<n>:entry per finding. Each entry contains the category, severity, references, a precise description, and two to four solution variants — complete resolutions to choose from, with{{placeholders}}for the details only you can supply — followed by anOwnoption. RSF files with no findings are not copied. - For each finding in
sdais/rsf/v<N+1>/, tick exactly one variant (- [x]), replace every{{placeholder}}in it, and apply it according to its action.V1is the auditor's recommendation; if none fits, tickOwnand write your own resolution:
| Action | When it is offered | What to do |
|---|---|---|
| Fix | Item kept; wording corrected or quantified | Replace the requirement text above the — separator with the variant text |
| Drop | Item irrecoverably ambiguous or no longer needed | Delete the file from rsf/v<N+1>/ |
| Supersede | Replace with a cleaner formulation under a new ID | Create a new item file with the variant text |
| Split | One item covered two distinct concerns | Create one new item file per variant text |
| Waive | Finding acknowledged; item intentionally unchanged | Leave the requirement text unchanged; the filled {{rationale}} records why |
- Re-run the SemanticAuditor on the amended
rsf/v<N+1>/. Repeat until no new findings are produced — the RSF is now Cleared.
For each **Libraries:** entry the auditor validates the pinned path, UTF-8
file, optional heading anchor, and confined local links, then audits the RSF
against the referenced definitions. Missing or malformed references produce
LIBRARY-UNRESOLVABLE and block Cleared status. Contract contradictions use
CONTRADICTORY; an untestable library-derived AC still uses UNTESTABLE.
Prompt: sdais/prompts/grounder.md | Recommended model: High-reasoning (e.g. Claude Opus or Sonnet)
Mandatory when E- items are present. Skip this step only if the RSF has no environment items.
The Grounder verifies each E- item against real infrastructure — checking database connections, service endpoints, environment variables, file paths, secret mounts, etc. For each confirmed element it sets **Verified:** true. For each element it cannot confirm it appends an ENV-UNRESOLVABLE finding to the affected E- item file in sdais/rsf/v<N+1>/.
Resolve all ENV-UNRESOLVABLE findings before proceeding:
- Fix: update the
E-item to match what actually exists; re-run Grounder. - Drop: remove the
E-item and any FR items that depend on it. - Waive: note in
**Resolution:**that the infrastructure element will be built as part of this project.
Prompt: sdais/prompts/architect.md | Recommended model: High-reasoning (e.g. Claude Opus or Sonnet)
Run the Architect if you want a human-approved architecture checkpoint before any code is written. This is particularly valuable for systems with non-trivial module boundaries or complex data flows — it surfaces structural disagreements early, when they are cheap to fix.
The Architect reads all cleared RSF items and their adopted libraries and produces this UTF-8 Markdown set under sdais/adf/v<N>/:
adf-01-context-and-goals.md— context, goals, stakeholders, scope, quality goals, and constraints.adf-02-internal-architecture.md— components, boundary contracts, data flows, and the Mermaid diagrams needed to describe the internal structure.adf-03-external-architecture.md— actors, external systems, integration contracts, trust boundaries, failure handling, flows, and the Mermaid diagrams needed to describe integrations.adf-04-requirement-trace.md— every active specification ID and title mapped to exactLibrary References(or—), architecture components, external interfaces, decisions, and verification.adf-05-glossary.md— project, domain, integration, component, data, and acronym terms.decisions/adr-NNNN-<short-title>.md— one ADR per significant architecture decision.
Every ADR contains Status, Context, Decision, Justification, Consequences, Alternatives, Relevant Requirements, and Verification Tests. Every entry in the final two sections uses - **[<id>]:** <text>, where the ID is a real specification ID and the text is its exact title.
Components and interfaces name the pinned libraries they realize. UI/design languages belong in internal interfaces and relevant ADRs; API/schema/protocol contracts belong in external architecture and integrations. The ADF links to definitions instead of copying them and cannot weaken the composed RSF plus library contract.
Review the complete ADF set and either approve it—set every core document to **Status:** Approved and every ADR to **Status:** Accepted—or reject it with written feedback for the Architect to revise. A fully approved ADF is read by the Generator as structural context; a partial set is ignored.
Prompt: sdais/prompts/generator.md | Recommended model: High-coding (e.g. Claude Sonnet)
The Generator reads the cleared RSF and synthesises a complete implementation
under implementation/. It selects the language-native structure, idioms, and
implementation strategy within the constraints you specified.
The Generator:
- Reads all active RSF items.
- Reads only the resolved libraries adopted by each active item.
- Reads the complete
sdais/adf/v<N>/set as structural context if all core documents are Approved and all ADRs are Accepted. - Synthesises a complete implementation under
implementation/. - Writes one
[ANN]block per callable unit and type. Every block starts with(VERIFIED) falseand(ROUND) 0.
Do not edit generated code by hand. Any manual change will be overwritten or will conflict with annotation state in the next round. Generator never writes product artefacts beside AGENTS.md or inside sdais/.
If the RSF contains a Constraint item with Generation mode: TDD:
- Run TestGenerator first (
sdais/prompts/test-generator.md), specifying TDD mode. It writes test stubs and fixtures underimplementation/with failing assertions derived from(PRE),(POST), and AC items. Every test block carries(TEST-MODE) TDD. - Run the Generator targeting 100% pass rate on those tests.
TDD mode inverts the order — tests define the target, Generator satisfies them — and gives you an objective completion signal.
Every [ANN] block produced by the Generator contains:
| Label | Value at generation |
|---|---|
(ANN-ID) |
Freshly generated ANN-<8-hex>; stable for the lifetime of the unit |
(ORIGIN) |
RSF item IDs this unit implements |
(TASK) |
Declarative statement of what the unit does |
(CONTEXT) |
Where and why the unit is used |
(CONSTRAINT) |
Hard rules or invariants applying to this unit |
(PRE) / (POST) |
Preconditions and postconditions for functions and methods |
(INPUT) / (OUTPUT) |
Named parameters and return values with types |
(DEPENDS-ON) |
ANN-<8-hex> IDs of units this unit directly calls |
(AGENT) |
Generator |
(VERIFIED) |
false |
(ROUND) |
0 |
These labels are the shared language that all subsequent agents read. They are what makes a stateless Reviewer or Refiner effective without needing access to the original conversation.
Prompt: sdais/prompts/reviewer.md | Recommended model: High-reasoning or high-coding (e.g. Claude Opus or Sonnet)
Run the Reviewer after every Generate or Refine pass. Pass the current round number (1 after the first Generate pass).
The Reviewer checks every [ANN] block:
- Is
(ORIGIN)pointing to a real, active RSF item? - Does the code actually implement what
(TASK)declares? - Are
(PRE)and(POST)enforced in the implementation? - Are all
(CONSTRAINT)labels respected? - Is every FR covered, and does at least one AC pass?
- Does the implementation conform to every library adopted by the relevant RSF item?
Library failures are findings on the relevant [ANN] block. (ORIGIN) remains
RSF/TRS IDs; filesystem paths never go there.
It also runs a dependency cascade check: when a block is set (VERIFIED) false, every block whose (DEPENDS-ON) references that block's (ANN-ID) receives an automatic Medium cascade finding. This prevents silent propagation of errors through the call graph.
After the pass the Reviewer outputs a summary:
Round 1 review complete.
Violations: 3 blocks, 5 total findings.
Cascade findings added: 2 blocks.
Clean: 12 blocks.
Unaddressed RSF items (if any): AC-0003
Clean blocks are set (VERIFIED) true and are not touched again unless their dependencies change.
Prompt: sdais/prompts/refiner.md | Recommended model: High-coding (e.g. Claude Sonnet)
Run the Refiner after every Review pass that contains violations. Pass the same round number used by the Reviewer.
The Refiner works block by block through every (VERIFIED) false block:
- Corrects the code as directed by each
(HINT:n). - Appends
(FINDING:n:STATUS) Resolved — <rationale>for each fix. - If a code fix makes a descriptive label inaccurate (e.g.
(TASK)no longer matches), updates the label and appends(FIELD-CHANGE:n)documenting what changed and why. - Sets
(VERIFIED) truewhen all findings in a block are resolved. - Marks unresolvable findings
Waived — requires RSF amendmentrather than silently papering over them. - Reads the same pinned libraries as the Reviewer and never edits them.
Return to Step 6 at round N+1. Repeat until the Reviewer reports zero violations.
If remaining violations are all Waived, the RSF needs amendment: increment the RSF version, re-audit from Step 2, and restart generation. Waived findings are not ignored — they are evidence that the specification and implementation cannot be reconciled without changing the requirements.
When the Reviewer reports zero violations and all ACs pass, you make the final call:
- Approve — synthesis is complete. Archive RSF files and annotated codebase together in git. Record the approval:
Approved: RSF v<N>, Round <R>. - Amend RSF — requirements have changed or the result reveals a gap. Increment the RSF version, restart from Step 2 with the existing annotated codebase as context.
- Reject — the implementation is correct but you want a different approach. Provide written rationale and restart from Step 5.
Prompt: sdais/prompts/security-auditor.md | Recommended model: High-reasoning (e.g. Claude Opus)
Run the SecurityAuditor on demand or after generation. It checks all (CONSTRAINT:SEC) labels and scans for hard-coded credentials, unvalidated inputs passed to sensitive operations, missing authorisation checks, and unsafe cryptography. When a security claim depends on an adopted protocol, schema, or interface definition, it reads that pinned contract. It uses the same (FINDING:n) / (HINT:n) mechanism as the Reviewer so findings flow directly to the Refiner. Security findings are prefixed SEC:.
Prompt: sdais/prompts/test-generator.md | Recommended model: High-coding (e.g. Claude Sonnet)
After all [ANN] blocks are (VERIFIED) true, run TestGenerator in Standard mode. It derives test functions from (PRE), (POST), AC items, and relevant adopted-library boundaries, grammars, compatibility rules, and conformance clauses. It reads annotation blocks in implementation files but does not modify them.