Skip to content

Workflow

The generator prescribes how a repository is developed, not only which files it holds: the guidelines set the design philosophy, the documents and the CI pipeline set the workflow. This document describes that workflow. The target picture explains why it is built around Capability Specifications.

Documents

Every document of a repository is of one of three kinds. The kind decides who writes it and whether the assistant works with it.

Kind Location Written by Assistant
Input Document specs/inputs/ Customer or business department Reads it only when asked, to derive Capability Specifications
Working Document specs/, test/bdd/features/, test/manual/ Developer, with the assistant Reads and maintains it in every task
Derived Document docs/ Developer, with or without the assistant Reads and changes it only when asked
  • The Working Documents are the single source of truth: Capability Specifications, the glossary, the domain model, design documents that serve several capabilities, ADRs, interface descriptions, feature files, and manual tests. Every change starts there.
  • An Input Document is never implemented directly: the developer translates it into Capability Specifications and keeps it as a reference.
  • A Derived Document is never a source: whoever needs a change in it changes the Working Documents first.
  • A use case can be either: the customer's use case is an Input Document, the use case written for an acceptance review is a Derived Document.
  • docs/ holds every document written for people rather than for development, such as a user's guide or a deployment procedure. Its content is up to the developer.
  • A Derived Document may refer to the Capability Specifications it describes. It needs no further bookkeeping. It is committed, because deriving it again, by hand or with an assistant, may give a different text each time.

Information flows in one direction only:

flowchart LR
    I["Input Documents:
 requirements specification, use cases, issues"]
    C["Capability Specifications"]
    W["Glossary, domain model, design documents,
 ADRs, interface descriptions"]
    F["Feature files, manual tests"]
    S["Code and automated tests"]
    D["Derived Documents:
 use cases, business rules, architecture, user's guide"]

    I -->|translated into| C
    C --> W
    C -->|acceptance criteria| F
    W --> S
    F -->|verify| S
    C -.->|derived from| D
    W -.->|derived from| D

Phases

Development passes from requirement to functional design, technical design, and implementation. Where the result of a phase lives depends on the Documentation Mode:

Phase Result lean extended, in addition
Requirement Context, requirements, acceptance criteria Capability Specification –
Functional design Domain model, business rules, use cases, business processes, roles Capability Specification (Details), glossary, domain model Use cases, business rules in docs/
Technical design Architecture, data model, interfaces, solutions for non-functional requirements, operations ADRs, interface descriptions, design documents in specs/technical_design/ Architecture description in docs/
Implementation Code, configuration, automated tests, builds Repository, make targets, CI pipeline –

Documentation Mode

documentation in .repo.yaml sets how much the repository documents beyond the Working Documents:

  • lean: ADRs in the lean template; no Derived Documents beyond what the developer adds.
  • extended: ADRs in the MADR template, with considered options and their pros and cons. Derived Documents for readers outside the development team, such as a business department or an auditor.

Both modes work with the same Working Documents. extended adds documents, never sources.

Requirements Source

requirements in .repo.yaml sets where the Capability Specifications are kept:

  • repo: as files in specs/capabilities/.
  • external: as issues in an issue tracker, such as GitLab, GitHub, or Jira. specs/capabilities/ then holds one document that points to the tracker. Feature files, manual tests, and ADRs refer to the issue keys and stay in the repository.

The issue templates for Capability Specifications are generated for GitLab and GitHub in either case.

Development Steps

  1. The developer writes a Capability Specification, alone or from a proposal of the assistant.
  2. The developer reviews it and sets its status to Accepted.
  3. The assistant derives:
    • Gherkin scenarios from the acceptance criteria, in test/bdd/features/
    • changes to interface descriptions (OpenAPI, DBC, …)
    • new glossary terms
    • an ADR, only for a decision that reaches beyond the capability and is hard to reverse
  4. The assistant implements test-first.
  5. Tools verify the result: make test, make bdd-test, make lint, make arch-test.

A Capability Specification describes the current target state of its capability, not a change. If a later capability contradicts an earlier one, the earlier specification is corrected.

Design documents that serve several capabilities live in specs/functional_design/ or specs/technical_design/. A Capability Specification links them under References.

Docs Site

The docs site renders every document of every kind: Input, Working, and Derived Documents, including feature files and manual tests, with their diagrams, formulas, and tables. Its navigation, not the directory layout, sets where a document appears. People read the documents there, for example while carrying out a manual test.