Skip to content
ditomaxPublic

About

From brief to product, with concept documents as the source of truth — markdown skills an AI agent runs in your folder. Part of the skill suite idea → maquette → build.

Topics

Resources

Stars

7 stars

Watchers

0 watching

Forks

Repository files navigation

build

From brief to product — concept documents as the source of truth, code as their derivative.

Version: see VERSION · September 2026 · https://github.com/ditomax/build

Disclaimer: the skill suite is a set of guidelines — whoever runs it is responsible for inputs, outputs and decisions. See DISCLAIMER.md.

For users, START.md is enough — three steps, no installation. Conversation and output files follow the user's language; headings in the templates stay in English.

For agents

If you are reading this from a link and have no local copy yet:

  1. Get one — git clone https://github.com/ditomax/build or unzip the latest release from https://github.com/ditomax/build/releases — into a project folder on the user's computer that the user chooses and can see and open (default: ./build next to their other work) — never only into your own sandbox or a temporary copy the user cannot see; if you cannot write there, tell the user which step to do themselves. That download is the only network access; the "no network" rule in AGENTS.md applies from then on.
  2. Work from inside that folder and read its AGENTS.md. Do not act as the Director from this README — the rules live in RULES.md and skills/.
  3. Placement: this folder as is (the work then goes into the product repository's planning/build/ — the Director asks for the project folder) unless the user has a project with a planning/ folder — then the suite belongs at planning/suite/build/ and planning/AGENTS.md is the entry point, not this file. That planning/ form is produced by skill-suite-setup (see The suite), never assembled by hand.
  4. A clone gives updates via git pull; the user's work never lands in the clone — it lives in the product repository (builds of 0.3 and earlier in builds/, which git ignores). hooks/ and guard.py are for skillset developers — ignore them.

What is build?

build is the third and last skillset of the suite idea → maquette → build. Where maquette produces a clickable model, build produces the product — and it does so AI-first: the concept documents in planning/build/ are the specification an agent synthesizes the code from, not a description written afterwards. If a concept document is incomplete, the code will be incomplete. There is no developer who "knows what was meant". That standard, and the process that reaches it, is the Concept Document Authoring Manifest (MANIFEST.md, version 8), which build turns into a guided, stage-by-stage skillset.

How it works

The user types start and afterwards only next, redo or stop. A Director skill reads the work folder, says where things stand, calls the next stage, and asks the three gate questions at which a human decides:

Stage "Team member" MANIFEST Result Typical duration
1 intake intake analyst Path B · R · S, Phase 1 10-intake.md — what the prototype already answers, what had to be asked, the draft 1 h with a brief
2 concept concept author Phases 2–6 20-concept.md — numbered requirements, ADRs, interactions, losses, hazards and constraints, control structure and unsafe control actions (STPA-light), architecture in slices, consistency matrix; CONTEXT.md, decisions/ 2 sessions
— gate sponsor Phase 4 PM review: requirements approved before any architecture —
— gate sponsor Phase 6 consistency review: findings accepted, fixed or deferred —
3 synthesis build team Phases 7–9 30-synthesis.md + product code — test concept, red-green-refactor per slice, registers, gap analysis per slice
— gate sponsor Phase 9 gap analysis: implemented vs. specified, before release —
4 rescue maintenance crew Phase 10 40-rescue.md — entropy removed, drift reported; on demand, repeatable 1 h

Finished results look like examples/10-intake.md and examples/20-concept.md (fictitious company). One feature = one concept document. The first feature is the scope of the brief; later features are added one at a time, each checked against the existing ones (interactions and interferences, cross-feature table in 00-build.md). Requirement IDs carry the feature code (F-PRC-12) so two features never collide.

Compatibility. In: 60-brief.md contract H2/3 from maquette ≥ 0.7.0 or H2/2 from maquette ≥ 0.5.0 (H2/1 accepted with a note); 10-register.md contract register/1 from idea ≥ 0.3.0; 10-shortlist.md entry contract H1/2 from idea ≥ 0.2.0 (H1/1 with a note). Out: none. Version triples tested together: skill-suite-setup/compat.md. Changes: CHANGELOG.md.

The suite

Repo What it does
idea vague wish → ranked shortlist (10-shortlist.md, contract H1) — or, for a fixed project, a prioritised requirement register (10-register.md, contract register/1)
maquette one shortlist entry or one register → clickable model and brief (60-brief.md, contract H2)
build — this repo brief (or register or shortlist entry) → product, with concept documents as the source of truth
skill-suite-setup puts the three into one project folder (planning/) with a profile and a single entry point that knows which skillset is up; builds customer-specific versions

Each skillset works on its own. Anyone who wants more than one of them, or a customer-specific version, gets the planning/ form from skill-suite-setup instead of standalone folders side by side.

Reliability, security, robustness — not safety. Every concept carries an STPA-light analysis: losses from a fixed catalogue (data loss, GDPR breach, loss of control, wrong output, outage, runaway cost, leaked secrets, abuse against others, lost maintenance access …), the hazards that lead there, the constraints that prevent them, the control structure of users, components, error handlers and AI components, and the unsafe control actions that would break it — each constraint traced to a requirement and a test. build does not produce safety-critical software: a product that could harm people, controls a safety function, or directly controls, switches or protects electrical power gets a documented warning (simulation / teaching, non-safety part only, or stop). Secrets stay out: before the first line of product code, build adds repo-local ignore rules, a secret-blocking hook for the agent, a pre-commit guard with gitleaks and asks for push protection; a read-only secret audit is available at any time (audit).

Contracts

  • In — H2. 60-brief.md (contract H2/3, or H2/2 from older maquette) — all four parts — plus the frozen vcode/ next to it. Intake extracts first (Path B), grills the rest (Path A). An H2/3 brief built on a register adds Path R: every requirement R-<n> is traced. Neither file is ever written by build.
  • In — register/1 (Path R). Without a maquette, build takes 10-register.md from idea's focus track directly: every R-ID becomes a candidate with a trace R-n → F-<FEAT>-n, mapped to another feature, or deferred with a reason. Intake closes only when every MUST has one.
  • In — H1 (Path S). Without maquette and register, build takes one entry of 10-shortlist.md: card, variants and evaluation are extracted, operation, running cost and load are prefilled — only the gaps are asked.
  • Without a brief build starts from a problem statement and runs the manifest's Path A in full.
  • Out. None — the product and its concept documents are the result.

Structure

build/
  START.md             three steps for the human
  AGENTS.md            entry point for Codex — turns the agent into the Director
  CLAUDE.md            the same for Claude
  VERSION
  README.md            this file
  RULES.md             shared rules — frontmatter, write rules, conversation rules, git, contracts, working principles, definition of done
  QUESTIONS.md         every question the skillset asks, with stable IDs — the tailoring surface for profiles
  CHANGELOG.md         what changed per version
  hooks/               pre-commit guard for development clones (see Release)
  MANIFEST.md          the Concept Document Authoring Manifest v8 — normative process reference
  ATTRIBUTION.md       where the method comes from
  checklists/          requirements.md (Phase 1, by field of application) · architecture-consistency.md (Phase 6) · losses-hazards.md and ai-threats.md (STPA-light, concept §5 / §9)
  profile/             optional customer-specific constraints (empty = core defaults)
  examples/            fictitious finished results — an intake and a concept document (Example GmbH)
  layouts/             the layout catalogue — one profile per stack (py-lib, py-web, c-cpp, rust, ios, android), a template for others, shared tools (dev CLI, layout checks)
  templates/           one template per result file and per shared register (binding content definition)
  skills/
    build/             Director
    build-intake/
    build-concept/
    build-synthesis/
    build-rescue/

Inside a project

Wherever the suite sits, the work lives in the product repository: templates stay with the suite, everything derived from them goes into <project>/planning/build/ and is committed with the code. Inside a project folder the suite itself is copied to planning/suite/build/ (read-only), the work lives in planning/build/, the profile in planning/profile/, briefs wait in planning/maquette/<x>/60-brief.md (register and shortlist in planning/idea/), and the product code lives in the project root outside planning/. The Director recognises the layout by the planning/ folder. A coding agent working on the product reads planning/build/ as its specification and treats planning/idea/ and planning/maquette/ as history.

Code layout and test documentation

The product's folder structure is chosen once, in the first feature's concept, from the layout catalogue (layouts/): py-lib, py-web, c-cpp, rust, ios, android — or, for anything else, the ecosystem's own conventions filled into layouts/_template.md. One feature = one unit (package, crate, target, module); the dependency direction entry → features → core is checked by a test or by the build system. Slice 0 writes the skeleton, a small development command line tools/dev.py (test, check, configuration, environment) and the test documentation: agent-testing.md (tools, fixtures, a fix journal, pitfalls — the agents' memory) and manual-tests.md (what is tested by people, with an execution log).

Distribution and installation

Repo and ZIP share the same structure. Users download the release ZIP, unzip it, open the folder in their AI app and type "start" (START.md). AGENTS.md / CLAUDE.md are read automatically and turn the agent into the Director — nothing to install, no symlinks, no global skill folders, no network, no telemetry. Developers who want the skills globally can symlink skills/build* into ~/.codex/skills/ or ~/.claude/skills/.

Profiles

Customer-specific variants (restricted topics, IT constraints, standards, corporate design, the customer's own review process, questions skipped or added) do not fork this repo. They live in a profile/ folder the Director reads at start; a profile may restrict, never loosen. The format is specified in skill-suite-setup/PROFILE.md; a minimal example is in profile/README.md. QUESTIONS.md lists every question the skillset asks, with stable IDs — read it before a session, and use the IDs in a profile to skip or add questions.

Language

All skill text, template headings, frontmatter keys and status values are English. The conversation follows the user's language (German → informal "du"). The result files are written in the language recorded as language in 00-build.md; template headings, requirement text, identifiers, code and commit messages stay English.

Git

Optional. Skills never create a repository; if one exists, a commit marks a frozen state — a stage done, a green slice, an accepted concept version, a kept refactor — and every commit that changes behaviour cites the requirement IDs it touches (RULES.md §6).

Release

Development clones activate the customer-data guard once: git config core.hooksPath hooks (the hook calls guard.py from the sibling skill-suite-setup repo and blocks commits that carry customer markers). Release ZIPs are built with skill-suite-setup/release.py, which ships only git-tracked, allowlisted, guard-clean files.

Repository: https://github.com/ditomax/build — releases at https://github.com/ditomax/build/releases. New version: bump VERSION, tag vX.Y.Z, GitHub release with the folder attached as build-vX.Y.Z.zip.

Origin

build is the Concept Document Authoring Manifest (Dietmar Millinger, v1–v8, 2026) plus its companions — the requirement checklists, the architecture consistency checklist, the test tooling register and the day-to-day working rules formerly kept in CLAUDE.local.md — restructured into the Director-and-stages form shared with idea and maquette. The manifest text lives on unchanged as MANIFEST.md. The working principles in RULES.md §10 adapt Andrej Karpathy's observations on LLM coding pitfalls.

License

© 2026 Dietmar Millinger, MIT License (LICENSE).

About

From brief to product, with concept documents as the source of truth — markdown skills an AI agent runs in your folder. Part of the skill suite idea → maquette → build.

Topics

Resources

Stars

7 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages