The spec: the single source of truth

The templates of req42 (for requirements) and arc42 (for architecture) capture the knowledge necessary to create systems and keep them alive. They have been used successfully for more than 20 years in many countries and domains.

Together they form the spec from which source code can be developed. systems42 treats this spec as the single source of truth: not a document written after the fact, but the contract every agent reads before it generates, tests or changes anything.

req42 · requirements

Vision and goals, functional requirements, supporting models, roadmap, team and resources.

arc42 · architecture

Solution strategy, building blocks, runtime, deployment, crosscutting concepts, decisions.

Agentic loops fill and check the spec

Three loops run around the spec. Two are driven by AI, one is a conversation between humans and AI. All three ask for clarification where necessary.

Ingest

Humans provide raw input and trigger the AI to fill the spec.

1. MarkdownifyThe input is transformed into clean, uniform markdown so further processing by AI is easier.
2. Cross-check and linkIf the input can be assigned to one or more spec sections, those sections are filled and cross-linked.
3. Ask questionsIf not, the AI creates questions or issues to be answered by a human, see Clarify.

Audit

Audits can be time-triggered, for example after an ingest or at defined intervals, or explicitly triggered by humans.

1. Detect issuesThe content of the spec is checked against predefined rules, guardrails and constraints.
2. Flag gapsMissing, inconsistent or outdated parts are marked.
3. Update backlogEvery finding is added to the list of issues to be clarified by humans.

Clarify

Clarify is triggered by humans who want to improve the existing spec by resolving issues or providing new rules and guardrails.

1. Pick topicThe AI presents the spec and the list of open issues as a dashboard. Humans pick one.
2. DiscussHumans discuss the issue with the AI until there is a decision, or an explicit "cannot decide yet".
3. Write backHumans ask the AI to update the spec, or the rules and guardrails, with the outcome of the discussion.

Plan, implement, reengineer

From the spec, agents plan and implement: they generate and test source code based on a plan derived from requirements and architecture. The reverse direction exists too. Reengineer recreates the systems42 spec from existing code, so that legacy systems can enter the same cycle.

Why systems42?

For management the advantage is traceability and control. Every line of code can be mapped back to documented requirements and architectural decisions. Strategic decisions stay human, tactical execution goes agentic, and the spec is the handshake between the two.

Technology

systems42 keeps the spec as a markdown wiki in the style Andrej Karpathy described: plain files, versioned, readable by humans and machines alike, with dashboards for open issues and harnesses that run the loops.