Structure your AI for code or for models. Ship with confidence.

CognitiveSDD

---

Software Development

The problem

AI coding assistants are powerful, but without structure they produce fragile results. Developers prompt, get code, prompt again, and end up with software that has no traceable requirements, no architectural rationale, and no guarantee that what was built matches what was needed. When something breaks, there is no trail. When requirements change, there is no protocol for controlled adaptation. The result is "vibe coding" — fast but brittle.

The solution

For software developers, CognitiveSDD orchestrates a structured workflow through user story discovery, requirements derivation, architecture design with ADRs, test specification with traceability markers, autonomous implementation inside firewalled containers, and full verification — producing source code, automated test suites, and a traceable build where every test links back to its requirement.

Software project phases

Phase	Output
Setup	Scaffolded project with language-idiomatic structure, build files, and CI-ready layout
User Stories	Structured discovery through questioning and web research, producing validated user stories
Requirements	INCOSE-compliant functional and non-functional requirements, linted for ambiguity, escape clauses, passive voice
Architecture	Section-by-section design proposals with Architecture Decision Records (ADRs)
Test Specs	Test stubs pre-wired with @req traceability markers linking every test to its requirement
Implementation	Autonomous coding against the spec, with total git lockout and network firewall
Verification	Full traceability matrix, all tests green, gap analysis, technical debt report, coherence check
Update	Issue-based change loop — impact analysis, scoped re-execution, verification

---

Systems Engineering (MBSE)

The problem

The same drift affects Model-Based Systems Engineering adoption. Requirements live in Word, architecture in Visio, verification in Excel, analysis in a notebook nobody owns. SysML v2 — the OMG specification where requirement def, verification case def, satisfy, and verify are first-class language elements — promises to fix this. But teams adopting it face the same problem: no phase gates, no enforced traceability discipline, no protocol for amendment when an architectural decision invalidates an earlier requirement, no automated checks against ambiguity in requirement text.

The solution

For systems engineers, CognitiveSDD applies the same phase-gated discipline to Model-Based Systems Engineering. The orchestrator guides the AI through stakeholder needs elicitation, INCOSE-compliant requirements (materialised as requirement def elements), structural architecture (part def, ports, interfaces), verification specs (verification case def stubs), and behavioural modelling — producing a complete SysML v2 model with end-to-end requirement-to-verification traceability.

Engineering (MBSE) project phases

Phase	Output
Setup	Scaffolded MBSE tree, Standard Library vendored, toolchain pinned
Stakeholder Needs	Structured elicitation of system needs and use cases
Requirements	INCOSE-compliant requirements materialised as requirement def elements with require constraints
Architecture	Structural model (part def hierarchy, ports, interfaces, allocations), with ADRs
Verification Specs	verification case def stubs with verify requirement clauses for every Must-priority requirement
Modelling	Behavioural and analytical model (action def, state def, calc def, constraint def)
Verification	Toolchain parse-validate, verification case execution, requirement coverage, pass/fail report
Update	Same issue-based change loop, scoped to model elements

---

Under the hood: The high-integrity engine

While the outputs, scaffolding templates, phase prompts, and quality rules are tailored to either software or systems engineering, both use-cases share a robust technical core designed for defense-in-depth security, strict mathematical traceability, and deterministic phase control.

Core engine capabilities

• Directed-graph workflow engine. Steps are nodes in a directed graph, not items in a list. The engine supports backward transitions, loop detection with configurable visit limits, crash recovery, and parameterised workflows with runtime variables.

• Defense-in-depth container security. The AI runs inside a Docker / Podman container with an iptables default-deny firewall that allows ONLY the AI provider API. GitHub, npm, PyPI, and all general internet are blocked at the kernel level. A pre-tool-use hook blocks ALL git commands. A host-side git agent handles all version control. A separate research container provides internet access for web research but cannot see the source code or the model.

• INCOSE requirements linting. An automated validator catches ambiguous verbs, escape clauses, vague quantifiers, passive voice, unqualified references, and implementation details that belong in architecture — not in requirements.

• Full traceability. Every requirement traces forward to tests and source code (software) or to verification cases and satisfying model elements (engineering) via @req markers. An event-driven traceability DB updates incrementally after each AI turn. Coverage summaries, orphan detection, and a queryable MCP tool give instant visibility.

• Phase gates with exit criteria. Seven criterion kinds (file_exists, dir_nonempty, file_contains, command_succeeds, user_approves, ai_validates, coherence_check) with retry logic. The AI cannot silently advance with incomplete work.

• Amendment protocol. From the architecture phase onward, if any agent discovers a conflict with a validated artefact, it stops, documents the issue, proposes a fix, and waits for human approval. No silent deviations — ever.

• Technical debt tracking. An automated debt scanner runs at every user gate. Critical debt blocks phase transitions. Engineering projects extend the catalogue with model-debt categories: orphan requirements, vacuous constraints, missing verify links.

• Automated git agent. A host-side git agent commits and pushes at every step boundary. Rollback to any point in the workflow is a single git checkout.

• Human-in-the-loop by design. The user's role reduces to three activities: write the project description, review and approve at gates, and submit change requests. Everything else is automated.

Workflow modes

• Greenfield — new projects from a description (software or engineering)
• Brownfield — reverse-engineering and improving existing artefacts
• Change Management — post-deployment change requests with impact analysis and scoped routing

Who it's for

• Solo developers and small software teams who want fully documented, tested, traceable software at a pace that normally requires a full engineering department.
• Systems engineers and MBSE teams adopting SysML v2 who want phase gates, INCOSE-compliant requirements discipline, end-to-end traceability, and an amendment protocol.
• Safety-critical and regulated-industry engineers (aerospace, automotive, medical, defence) who need auditable, INCOSE-aligned artefacts.
• Security-conscious organizations that require AI agents to operate within defense-in-depth boundaries — not just a sandbox, but a firewalled sandbox with total VCS lockout.

How it works

1. Install CognitiveSDD and run csdd doctor to verify prerequisites.
2. Run csdd run in your project directory. The wizard asks for the project category, language, personas, and thresholds.
3. Describe your project in one paragraph.
4. The workflow engine launches a firewalled container for each step. The AI works autonomously. The git agent commits at every boundary.
5. At each gate, review artefacts, approve, reject with feedback, or request amendments.
6. Ship software with full traceability from requirement to test to code — or ship a SysML v2 model with full traceability from requirement to verification case to satisfying model element.

After deployment, submit change requests via csdd run --workflow change --var change_id=CR-001.