Project foundation
Summary
The foundation is the work done before implementation: agree why the product exists and for whom, what it must do, how it will be built, which hard choices were made and why, in which order it will be delivered, and by which rules people and agents work in its repository. This playbook runs that work as nine stages, each with entry and exit criteria and one artefact made from a Hub template, and ends with a single owner approval gate. It is written for a team of an owner, an optional technical lead and a lead developer that is an AI coding agent, but works the same with human developers.
Rules
- R1. Foundation work MUST start from the owner’s brief, recorded verbatim in a foundation issue (or a file linked from it), together with the tailoring: which stages run, which are merged or skipped, and why.
- R2. Stages MUST be run in the order listed under Stages. A later stage MAY start as a draft before an earlier one is closed; when an earlier artefact changes, every later artefact that depends on it MUST be checked and updated in the same pull request or in a linked one.
- R3. A stage MUST NOT be reported as closed until all of its exit criteria are met, and the owner approval gate MUST NOT be requested while a stage kept by the tailoring is open.
- R4. Each artefact MUST be created from the Hub template named for its stage, MUST keep the template’s front matter fields and required sections, and MUST be stored in the project repository at the path given for its stage or at the path the tailoring records (for example, where an existing repository already keeps its decision records).
- R5. Scenarios, requirements, acceptance criteria, milestones and decisions MUST carry stable ids (for
example
S-A,FR-1,NFR-1,AC-1,M1,ADR-0001) that are never renumbered or reused; later artefacts, issues and tests MUST refer to them by id. - R6. Every significant or hard-to-reverse choice in the blueprint MUST be recorded as an architecture
decision record as defined in
arch.adr, and the blueprint MUST mark the choice with a link to it. - R7. The blueprint MUST contain a system context view and SHOULD contain a container view, drawn as
defined in
arch.c4-model. - R8. A technical claim in a research note, the blueprint or an ADR MUST cite a source with an access date, a measurement or a reproducible check; a statement that is not verified MUST be marked as an assumption.
- R9. An agent MUST NOT set an artefact to
approvedor an ADR toaccepted; it submits them asreviewandproposed. The owner’s decision MUST be recorded, with its date, in the artefact itself (its status and, for an ADR, its owner decision section), not only in chat. - R10. Code that implements the work this foundation plans MUST NOT be merged before the owner approval gate is passed; maintenance of a running product continues under its existing rules. Spikes and prototypes MAY be built during research when a research note names them; they are evidence, not product code.
- R11. Rules specific to the product MUST live in the project’s own repository (
AGENTS.md,project/); Hub items SHOULD be referred to by id and Hub version rather than copied into it.
Stages
| # | Stage | Artefact | Template | Drafts → approves |
|---|---|---|---|---|
| 1 | Intake | foundation issue, working branch | — | lead developer → owner confirms tailoring |
| 2 | Vision | project/VISION.md |
templates/vision.md |
lead developer → owner |
| 3 | Requirements | project/PRD.md |
templates/prd.md |
lead developer → owner |
| 4 | Research | research/<topic>.md |
— | lead developer → technical lead reviews |
| 5 | Blueprint | project/BLUEPRINT.md |
templates/blueprint.md |
lead developer → technical lead reviews, owner approves |
| 6 | Decisions | project/decisions/NNNN-<slug>.md |
templates/adr.md |
lead developer → owner accepts or rejects |
| 7 | Roadmap and issues | project/ROADMAP.md, milestones, issues |
templates/roadmap.md |
lead developer → owner |
| 8 | Repository bootstrap | AGENTS.md, tool entry files, CI |
templates/agents.md |
lead developer → owner |
| 9 | Owner approval gate | merged foundation pull request | — | owner |
1. Intake
- Entry. The owner asks for a new product, a re-foundation of an existing one (a rewrite, a new major version, a move to a new platform), or large new work on a product that has no foundation documents.
- Do. Quote the brief verbatim. List what is already known: existing code and data, users, constraints,
deadlines, budget, other projects it depends on. Name who holds each role (see Guidance). Decide where the
artefacts live (the product repository, branch
docs/<issue>-foundation). Tailor the stages. Collect the questions only the owner can answer and ask them in one batch. - Outputs. A foundation issue with the brief, the tailoring, the roles and the questions; the working branch or, for a new product, a new repository whose visibility the owner has chosen.
- Exit. The owner has confirmed the tailoring and answered the blocking questions, or agreed to treat them as assumptions.
2. Vision
- Entry. Intake closed.
- Do. Write the positioning statement (who, what need, what product, which benefit, unlike which alternatives), the audiences and what each gets, three to five observable outcomes with a time horizon, and the non-goals.
- Outputs.
project/VISION.mdfromtemplates/vision.md, statusreview. - Exit. It fits on one page; every outcome can be checked by someone other than its author; non-goals are listed; the owner has confirmed the statement and the non-goals (a comment in the issue is enough — formal approval comes at the gate).
3. Requirements
- Entry. Vision confirmed.
- Do. State the problem; describe the scenarios end to end with their inputs and results; derive functional requirements and quality requirements with measurable targets; write acceptance criteria as checks; list constraints, assumptions and what is out of scope.
- Outputs.
project/PRD.mdfromtemplates/prd.md. - Exit. Every requirement has an id and is testable or measurable; every vision outcome is served by at least one scenario or requirement; the out-of-scope list exists; open questions name who answers them.
4. Research
- Entry. PRD in draft, and a list of questions that block the blueprint: technology and platform choices, limits of the hosting or the platform, licences, the state of existing code.
- Do. For each question compare at least two options against the PRD’s requirements, with sources, measurements or a spike. For an existing product, record the current state: code, data, integrations, hosting, known defects. Run independent questions in parallel; keep results in files, not in chat.
- Outputs. Dated notes
research/<topic>.md, informative only, each ending with a recommendation. - Exit. Every question that blocks a blueprint choice has a recommendation backed by evidence, or is recorded as an assumption with a planned check.
5. Blueprint
- Entry. PRD in review; research recommendations available.
- Do. Draw the system context and containers; describe the building blocks and the repository layout,
data and interfaces, the technology stack, cross-cutting concerns (security, privacy, performance,
accessibility, operations, licensing), deployment, risks with mitigations and the implementation
sequence. Mark every significant choice [ADR-NNNN]. For a product with a user interface, plan the
design work with the
hifstandard; for an operating system, withscf. - Outputs.
project/BLUEPRINT.mdfromtemplates/blueprint.md. - Exit. Every requirement is covered by a part of the blueprint or explicitly deferred; every significant choice is marked; every risk has a mitigation; the technical lead, where there is one, has reviewed it.
6. Decisions
- Entry. Blueprint draft with marked choices.
- Do. Write one ADR per marked choice, with real options and the evidence from research. Record decisions already in force in an existing product as ADRs too, so that the record is complete.
- Outputs.
project/decisions/NNNN-<slug>.mdfromtemplates/adr.md, statusproposed. - Exit. Every [ADR-NNNN] mark in the blueprint resolves to a file; every ADR meets
arch.adr.
7. Roadmap and issues
- Entry. Blueprint and ADRs in review.
- Do. Cut the implementation sequence into milestones, each with one exit criterion. Create one issue per deliverable, with acceptance criteria that cite requirement ids, and group them in tracker milestones. Mark what waits for an owner decision.
- Outputs.
project/ROADMAP.mdfromtemplates/roadmap.md; milestones and issues in the tracker. - Exit. Every milestone has an exit criterion and at least one issue; every issue cites the ids it serves; the first milestone can start without further owner decisions.
8. Repository bootstrap
- Entry. Roadmap drafted. A new repository may need this stage earlier, to hold the documents; then it starts minimal and is completed here.
- Do. Write
AGENTS.mdfrom the template: product, roles, where each kind of information lives, workflow, decisions, the one command that runs all checks, reporting. Point tool-specific files to it (for Claude Code, aCLAUDE.mdwith@AGENTS.md). Set up CI that runs that command, a pull request template, branch and commit conventions (config.conventional-commits) and release numbering (config.semantic-versioning). In an existing repository, align what is there instead of replacing it, and take a verified backup before touching a live system (ops.backups). - Outputs.
AGENTS.mdfromtemplates/agents.md; tool entry files; CI workflow; pull request template. - Exit. CI is green on the default branch; a new contributor or agent finds the rules, the documents and
the check command from
AGENTS.mdalone.
9. Owner approval gate
- Entry. Every stage kept by the tailoring is closed.
- Do. Open or update the foundation pull request with a short summary: the artefacts, one list of decisions needed from the owner, the assumptions and the main risks. The owner reviews, sets statuses and accepts or rejects each ADR; a change goes back to its stage and is carried forward to later artefacts.
- Outputs. The merged foundation pull request; the foundation issue closed.
- Exit. This is the definition of done: vision, PRD, blueprint and roadmap are
approved; every ADR isacceptedorrejectedwith the owner decision recorded; issues exist for the first milestone;AGENTS.mdis on the default branch and CI is green; open assumptions are tracked as issues. Implementation starts with the first milestone.
Guidance
When to use
Use it for a new product, for a re-foundation of an existing one, and before large new work on a product that has no vision, requirements or blueprint. Do not use it for a bug fix, a small feature in a product whose foundation is approved (an issue and, if needed, one ADR are enough) or a throw-away experiment.
Roles
| Role | Does | Does not |
|---|---|---|
| Owner | gives the brief, answers questions, approves artefacts, accepts or rejects ADRs, decides scope, visibility, licences, hosting and budget | write the artefacts |
| Technical lead | reviews research, blueprint and ADRs for risks; may write briefs for stages | decide alone |
| Lead developer (agent) | drafts every artefact, runs research, proposes ADRs, bootstraps the repository, reports with evidence | approve, accept, or widen the scope |
In a small team the owner can also be the technical lead, or a second agent can review independently. Whoever reviews should not be the author of what is reviewed.
Tailoring
- A small product can merge stages into one pull request, but keeps one file per artefact so that later changes stay small.
- Research can be skipped when the brief already fixes the stack and nothing blocks the blueprint; the intake records that.
- A re-foundation starts research with the current state and records the decisions already in force as ADRs before proposing new ones.
- A product that already has some of the artefacts brings them to the template instead of writing new ones, and keeps paths its repository already uses (an existing decisions folder, say) when the intake records them.
Working with agents
- Give an agent one stage (or one research question) per task, as a brief in a file with the stage’s exit criteria as the definition of done. Ask for results in files and a short report.
- Batch the questions to the owner at intake and at the gate; between them, decide technical details from the artefacts and record them, instead of asking.
- Ask a second agent, with no access to the author’s reasoning, to review the blueprint and the ADRs.
Anti-patterns
- Coding first and writing the documents afterwards to match the code.
- Decisions that live only in chat or meeting notes.
- A PRD without ids, or requirements that cannot be checked (“fast”, “user-friendly”).
- One option per ADR, or an ADR written after the choice was already merged.
- A blueprint that lists technologies but no context, risks or implementation sequence.
- Rules copied from the Hub into the project, where they drift from their source.
- An agent marking its own artefacts approved, or asking the owner about every technical detail.
- A foundation so heavy that the first milestone never starts; tailor instead.
Explanation
Choices about structure, technology, interfaces and data are the most expensive to change later, and they are made early. Writing them down before code exists lets the owner correct direction while it is still cheap, and gives every later reviewer the reasons, not only the result. The same approach underlies design documents in large engineering organisations: context and goals, the design, the alternatives considered and cross-cutting concerns, reviewed before implementation.
Agents raise the stakes. An agent given a vague brief produces plausible work in the wrong direction quickly,
and a long chat is a poor memory. Artefacts with stable ids give the owner, reviewers and agents one shared,
versioned reference: an issue cites FR-3, a test checks AC-2, a module exists because of ADR-0004. The
single approval gate at the end keeps human approval where it matters without stopping the agent at every
step, and the stage order follows the requirements, architecture and initiation and planning activities that
SWEBOK v4 and ISO/IEC/IEEE 12207 describe.
Examples
Good — the UASK Engineering Hub went through its foundation on 2026-11-19 and 2026-11-20, under one issue
for the repository bootstrap and one for the foundation work. Research notes compared portal engines, agent
formats and licences. project/VISION.md and project/PRD.md defined scenarios S-A…S-C, FR-1…FR-10,
NFR-1…NFR-8 and AC-1…AC-6. project/BLUEPRINT.md marked its choices [ADR-0002]…[ADR-0005],
and the ADRs were proposed. The owner accepted ADR-0003…ADR-0005 and replaced the portal engine decision
ADR-0002 with ADR-0006, each recorded in the files. project/ROADMAP.md split the work into milestones
M0…M8 with issues. The repository bootstrap (M0) ran first, because the documents needed a home.
Bad — “Build a theme like the one in this screenshot.” The agent starts coding at once. A week later the owner mentions that the theme must also serve a second product line; the layout engine chosen on day one cannot do it, the reasons for that choice are somewhere in a chat, and nobody can say which requirement a given module serves.
Sources
- SWEBOK Guide v4.0 — IEEE Computer Society, all rights reserved; the stage order follows its Software Requirements, Software Architecture and Software Engineering Management (initiation and scope definition, planning) knowledge areas; summarised, not copied. Accessed 2026-11-20.
- Malte Ubl, “Design Docs at Google” — all rights reserved; the blueprint’s context, goals, alternatives and cross-cutting concerns, and review before implementation. Accessed 2026-11-20.
- GitHub Docs — About milestones — CC BY 4.0; milestones grouping issues in stage 7. Accessed 2026-11-20.
- AGENTS.md — © AGENTS.md, a Series of LF Projects, LLC; one instruction file for every coding agent, used in stage 8. Accessed 2026-11-20.
- Agent Skills specification — documentation CC BY 4.0; the format of the skill that runs this playbook. Accessed 2026-11-20.
- ISO/IEC/IEEE 29148:2018 (requirements engineering), ISO/IEC/IEEE 42010:2022 (architecture description) and ISO/IEC/IEEE 12207:2017 (software life cycle processes) — referenced by name only.