create-groundwork 0.0.0-stage → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +87 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +63 -0
- package/README.md +81 -2
- package/dist/commands.js +294 -0
- package/dist/create.js +4 -0
- package/dist/engine.js +124 -0
- package/dist/groundwork.js +4 -0
- package/dist/profiles.js +77 -0
- package/dist/prompter.js +42 -0
- package/dist/scaffold.js +274 -0
- package/dist/text.js +31 -0
- package/package.json +48 -4
- package/template/.github/README.md +14 -0
- package/template/.github/pull_request_template.md +22 -0
- package/template/.github/workflows/docs-check.yml +23 -0
- package/template/AGENTS.md +88 -0
- package/template/BUILD.md +27 -0
- package/template/LICENSE.md +5 -0
- package/template/PROJECT.md +26 -0
- package/template/README.md +40 -0
- package/template/_gitignore +26 -0
- package/template/config/README.md +3 -0
- package/template/docs/README.md +53 -0
- package/template/docs/architecture/REPOSITORY_STRUCTURE.md +37 -0
- package/template/docs/architecture/SYSTEM_DESIGN.md +30 -0
- package/template/docs/architecture/adr/0000-template.md +28 -0
- package/template/docs/architecture/adr/README.md +11 -0
- package/template/docs/architecture/system-design/README.md +15 -0
- package/template/docs/engineering/SECURITY.md +22 -0
- package/template/docs/engineering/TEST_STRATEGY.md +33 -0
- package/template/docs/examples/EXAMPLE.md +56 -0
- package/template/docs/examples/PROFILES.md +75 -0
- package/template/docs/plans/README.md +10 -0
- package/template/docs/plans/_template/PLAN.md +39 -0
- package/template/docs/product/PRD.md +39 -0
- package/template/docs/product/SPEC.md +63 -0
- package/template/docs/product/specs/README.md +37 -0
- package/template/docs/product/specs/_template/SPEC.md +78 -0
- package/template/infrastructure/README.md +3 -0
- package/template/profiles/README.md +96 -0
- package/template/profiles/ai-systems/README.md +44 -0
- package/template/profiles/ai-systems/profile.json +35 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/EVALUATION.md +35 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/MODEL_INTEGRATION.md +37 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/RETRIEVAL.md +26 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/SAFETY.md +35 -0
- package/template/profiles/application/README.md +43 -0
- package/template/profiles/application/profile.json +47 -0
- package/template/profiles/application/templates/docs/application/RELEASES.md +28 -0
- package/template/profiles/backend-api/README.md +40 -0
- package/template/profiles/backend-api/profile.json +42 -0
- package/template/profiles/backend-api/templates/docs/backend-api/DATA.md +27 -0
- package/template/profiles/core/profile.json +74 -0
- package/template/profiles/core/templates/docs/architecture/contracts/README.md +11 -0
- package/template/profiles/core/templates/docs/architecture/system-design/01-system-overview.md +29 -0
- package/template/profiles/core/templates/docs/architecture/system-design/02-domain-and-state-model.md +27 -0
- package/template/profiles/core/templates/docs/architecture/system-design/03-behaviour-and-business-rules.md +29 -0
- package/template/profiles/core/templates/docs/architecture/system-design/04-architecture-and-interfaces.md +27 -0
- package/template/profiles/core/templates/docs/architecture/system-design/05-execution-and-resilience.md +30 -0
- package/template/profiles/core/templates/docs/architecture/system-design/06-operations-and-scalability.md +27 -0
- package/template/profiles/core/templates/docs/architecture/system-design/07-ui-and-interaction-mapping.md +35 -0
- package/template/profiles/core/templates/docs/design/DESIGN.md +202 -0
- package/template/profiles/web/README.md +41 -0
- package/template/profiles/web/profile.json +34 -0
- package/template/profiles/web/templates/docs/web/CONTENT.md +39 -0
- package/template/profiles/web/templates/docs/web/SEO.md +35 -0
- package/template/scaffold-manifest.json +77 -0
- package/template/scripts/README.md +29 -0
- package/template/scripts/check_docs.py +989 -0
- package/template/scripts/groundwork.py +716 -0
- package/template/src/README.md +3 -0
- package/template/tests/README.md +3 -0
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Agent Instructions
|
|
2
|
+
|
|
3
|
+
## Read before changing
|
|
4
|
+
|
|
5
|
+
Read in this order — each step narrows the last:
|
|
6
|
+
|
|
7
|
+
1. `PROJECT.md` — what the project is called, where it stands, where things live, and which profiles it uses. Then read `profiles/<id>/README.md` for each profile it lists: they add documents, standards and instructions for that kind of system. If no profiles are chosen yet, follow the initialization steps in `profiles/README.md` first.
|
|
8
|
+
2. `docs/product/PRD.md` — the problem, users, outcomes and capabilities (each capability has a `CAP-NNN` ID); needed when the change touches product intent.
|
|
9
|
+
3. `docs/product/SPEC.md` — the testable requirements. Check its feature index (§9) for a feature spec covering the area you're changing, and read that too.
|
|
10
|
+
4. `docs/architecture/SYSTEM_DESIGN.md` and the design docs for the parts you touch (in `docs/architecture/system-design/`) — `docs/design/DESIGN.md` for UI work — plus any profile documents for the area (for example `docs/ai-systems/`).
|
|
11
|
+
5. `BUILD.md` — how to build, run and test locally.
|
|
12
|
+
6. Any local instructions, plus the code and tests you're about to change.
|
|
13
|
+
|
|
14
|
+
If documents disagree, the more specific one wins for its area: a feature spec over `SPEC.md` for that feature's behaviour, an accepted ADR over the design summary. Profile standards are defaults: a project requirement or an accepted ADR overrides them. If two active profiles' standards disagree, no profile outranks another — record the resolution in an ADR. Record the conflict in the completion report instead of silently choosing.
|
|
15
|
+
|
|
16
|
+
## Rules
|
|
17
|
+
- Treat approved requirements, domain invariants (rules that must always hold) and ADRs (short records of important decisions, in `docs/architecture/adr/`) as fixed constraints.
|
|
18
|
+
- Read the existing code and tests before changing them.
|
|
19
|
+
- Make the smallest change that does the job. Don't add code, structure or libraries "just in case".
|
|
20
|
+
- Never quietly change public interfaces, stored data, permissions or security boundaries.
|
|
21
|
+
- Never weaken, skip or delete tests to make a change pass. If a test must change, say why in the completion report.
|
|
22
|
+
- If requirements are unclear, ask — or write down the assumption you're making.
|
|
23
|
+
- Keep the code, its tests and its docs telling the same story.
|
|
24
|
+
- Never commit secrets or sensitive data.
|
|
25
|
+
|
|
26
|
+
## Project style (change freely)
|
|
27
|
+
|
|
28
|
+
These are the template's defaults for how writing should read. Change or replace them to suit the project.
|
|
29
|
+
|
|
30
|
+
- Write documentation in plain language: short sentences, everyday words, and a plain-language explanation alongside any technical term the first time it appears.
|
|
31
|
+
- Keep the same plain tone in replies and reports: short, direct sentences, everyday words, and no jargon without an explanation.
|
|
32
|
+
|
|
33
|
+
## Code standards
|
|
34
|
+
|
|
35
|
+
> These are placeholders — adapt them to the project. Rules a machine can check belong in formatters, linters and CI (the automated checks that run on every change) — not in this file.
|
|
36
|
+
|
|
37
|
+
### Principles
|
|
38
|
+
- Write code that's easy to read and leaves nothing to guess.
|
|
39
|
+
- Keep each module focused on one job, and add dependencies on purpose, not by accident.
|
|
40
|
+
- Make it obvious who owns each piece of data, and what code reaches outside itself.
|
|
41
|
+
- Check input at the edges of the system, before it gets in.
|
|
42
|
+
- Decide what happens when things go wrong — don't let errors slip past unnoticed.
|
|
43
|
+
|
|
44
|
+
### Naming and layout
|
|
45
|
+
Agree on names for files, folders, types, functions, variables, database objects and public APIs. Say which modules may depend on which, and in which direction.
|
|
46
|
+
|
|
47
|
+
### Types, data and errors
|
|
48
|
+
Decide how strictly types are checked, how input is validated, how missing values are handled, and how errors are grouped and passed along.
|
|
49
|
+
|
|
50
|
+
### Testing and documentation
|
|
51
|
+
Say where tests live, how they're named, what fixtures are, and how much coverage you expect. Name tests so they mention the requirement IDs they verify — a test covering `AUTH-FR-001` says so — making requirement coverage searchable. Document public interfaces, surprising behaviour, and anything someone on call would need to know.
|
|
52
|
+
|
|
53
|
+
### Tooling
|
|
54
|
+
Active profiles add rows for the checks they need (`scripts/groundwork.py init` adds them). Fill in the tool, or write why a check doesn't apply — don't delete the row.
|
|
55
|
+
|
|
56
|
+
| Concern | Tool / command | Must pass in CI? |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| Format | | |
|
|
59
|
+
| Lint | | |
|
|
60
|
+
| Type check | | |
|
|
61
|
+
| Tests | | |
|
|
62
|
+
| Security checks | | |
|
|
63
|
+
|
|
64
|
+
## Workflow
|
|
65
|
+
1. Find the requirement IDs — and the `CAP-` capabilities they serve — plus the acceptance criteria the change must satisfy.
|
|
66
|
+
2. Trace what state, behaviour, interfaces and components it touches.
|
|
67
|
+
3. Plan the smallest safe change. For a non-trivial change, write the plan down first: copy `docs/plans/_template/PLAN.md` into `docs/plans/` and fill it in. Name the requirement IDs the plan covers.
|
|
68
|
+
4. Build it and test it.
|
|
69
|
+
5. Run the relevant checks and read the full diff before calling it done.
|
|
70
|
+
6. Update any docs and ADRs the change affects. If the change gives the system a new kind of responsibility (for example its first AI feature), check whether a profile should be added, and add it with `scripts/groundwork.py init`.
|
|
71
|
+
|
|
72
|
+
## Definition of done
|
|
73
|
+
|
|
74
|
+
A change is done when all of this holds:
|
|
75
|
+
|
|
76
|
+
- [ ] It meets the requirements and acceptance criteria it links to.
|
|
77
|
+
- [ ] Domain rules and invariants (rules that must always hold) still hold.
|
|
78
|
+
- [ ] Tests cover the expected behaviour and the important failure cases, and the required checks pass.
|
|
79
|
+
- [ ] Security, privacy, accessibility and performance impacts are considered.
|
|
80
|
+
- [ ] Interfaces and data migrations stay compatible, or there's a migration plan.
|
|
81
|
+
- [ ] Logs and metrics are useful and expose no sensitive data.
|
|
82
|
+
- [ ] Deployment, rollback and operational effects are understood.
|
|
83
|
+
- [ ] Documentation and ADRs are updated where needed (step 6).
|
|
84
|
+
|
|
85
|
+
Mark anything that doesn't apply with a reason. This checklist supports judgement; it doesn't replace it.
|
|
86
|
+
|
|
87
|
+
## Completion report
|
|
88
|
+
Report: what changed, which requirements it satisfies, which checks ran and their results, and anything unfinished or worth flagging. Local `AGENTS.md` files in subfolders may add stricter rules — follow those where present.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Build and Run
|
|
2
|
+
|
|
3
|
+
> How to get the project running locally. Fill this in when the first stack is chosen — a new developer or agent should go from a fresh clone to a running app using only this file.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
What must be installed first (language version, database, tools), and where to get them.
|
|
8
|
+
|
|
9
|
+
## Setup
|
|
10
|
+
|
|
11
|
+
The exact steps from a fresh clone to a working setup. List environment variable names — never values or secrets (see `docs/engineering/SECURITY.md`).
|
|
12
|
+
|
|
13
|
+
## Run locally
|
|
14
|
+
|
|
15
|
+
The command to start the app, which port it uses, and how to tell it's healthy.
|
|
16
|
+
|
|
17
|
+
## Test
|
|
18
|
+
|
|
19
|
+
The full developer loop: run the checks, then the tests. The authoritative command list lives in the tooling table in `AGENTS.md`, including the rows your profiles added; for how multi-app test runs are assembled, see `docs/engineering/TEST_STRATEGY.md`.
|
|
20
|
+
|
|
21
|
+
## Common tasks
|
|
22
|
+
|
|
23
|
+
The few things people do most: reset the database, seed test data, regenerate code.
|
|
24
|
+
|
|
25
|
+
## Troubleshooting
|
|
26
|
+
|
|
27
|
+
The failures people actually hit, with fixes.
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
# Licence (not chosen yet)
|
|
2
|
+
|
|
3
|
+
This template deliberately does not pick a licence for your project — that's a decision for you.
|
|
4
|
+
|
|
5
|
+
Replace this file with the full text of the licence you choose (for example from choosealicense.com), and update it in your package or repository settings. Until then, "all rights reserved" applies by default: others may not legally reuse your code.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Project Definition
|
|
2
|
+
|
|
3
|
+
The cover page: what the project is called, where it stands, what limits the work, and where everything lives. Product substance — the problem, users, outcomes, scope and success measures — lives in `docs/product/PRD.md`; record it there, not here.
|
|
4
|
+
|
|
5
|
+
## The basics
|
|
6
|
+
- Name: {{PROJECT_NAME}}
|
|
7
|
+
- Description: {{PROJECT_DESCRIPTION}}
|
|
8
|
+
- Status: Discovery / Design / Development / Production / Maintenance
|
|
9
|
+
- Owner:
|
|
10
|
+
- Last updated: {{PROJECT_DATE}}
|
|
11
|
+
|
|
12
|
+
## Project constraints
|
|
13
|
+
Limits that shape the work but not the product itself: budget, timeline, team size, regulatory and platform commitments.
|
|
14
|
+
|
|
15
|
+
## Profiles
|
|
16
|
+
Profiles add the documents, standards and checks a kind of system needs on top of Groundwork Core. Choose them by what the system does, not by the technology it uses — see `profiles/README.md`, then run `groundwork init <profiles>` (or `python3 scripts/groundwork.py init <profiles>`), which fills in the line below. Use `none` for core only.
|
|
17
|
+
|
|
18
|
+
- Profiles: [not chosen yet]
|
|
19
|
+
- Why:
|
|
20
|
+
|
|
21
|
+
## Links
|
|
22
|
+
- Profiles and how to choose them: `profiles/README.md`
|
|
23
|
+
- Product requirements: `docs/product/PRD.md`
|
|
24
|
+
- System requirements: `docs/product/SPEC.md`
|
|
25
|
+
- System design: `docs/architecture/SYSTEM_DESIGN.md`
|
|
26
|
+
- Build and run: `BUILD.md`
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Groundwork
|
|
2
|
+
|
|
3
|
+
A simple starting point for new software projects. It doesn't pick a language, framework or hosting setup for you, and it gives each project only the documents and checks its kind of system needs.
|
|
4
|
+
|
|
5
|
+
## How it's organised
|
|
6
|
+
|
|
7
|
+
- **Groundwork Core** — what every project gets: the project definition, agent instructions, product and system requirements with traceable IDs, the architecture starting point, decisions, plans, and the documentation checker.
|
|
8
|
+
- **Profiles** — what a kind of system adds on top: extra documents, engineering standards, agent instructions and checks. There are four to start with, and you can combine them:
|
|
9
|
+
|
|
10
|
+
| Profile | For |
|
|
11
|
+
|---|---|
|
|
12
|
+
| Web | Landing pages, marketing, corporate and content sites |
|
|
13
|
+
| Application | Interactive web, mobile and desktop apps |
|
|
14
|
+
| Backend/API | Services, APIs, workers and integrations |
|
|
15
|
+
| AI Systems | LLM features, retrieval, agents and model-driven workflows (always alongside one of the others) |
|
|
16
|
+
|
|
17
|
+
A company landing page uses Web. An online shop uses Application and Backend/API. An AI-powered SaaS product uses all three of Application, Backend/API and AI Systems. A library or command-line tool may need no profile at all. See `profiles/README.md` for how to choose and how profiles combine, and `docs/examples/PROFILES.md` for worked examples.
|
|
18
|
+
|
|
19
|
+
## Start here
|
|
20
|
+
1. Fill in `PROJECT.md`.
|
|
21
|
+
2. Write down what you're building and why in `docs/product/PRD.md`.
|
|
22
|
+
3. Choose profiles by what the system does, following the initialization steps in `profiles/README.md`. Then run `groundwork init <profiles>` (or `init none`) to create the documents they need. If you started with `npx create-groundwork`, this is already done.
|
|
23
|
+
4. Turn the PRD into testable requirements in `docs/product/SPEC.md`.
|
|
24
|
+
5. Design the system in `docs/architecture/SYSTEM_DESIGN.md` and the design documents your profiles added.
|
|
25
|
+
6. Adapt `AGENTS.md`, including its code standards, and fill in the tools for the checks your profiles added to its tooling table.
|
|
26
|
+
7. Run `python3 scripts/check_docs.py`. Add more documents only when the work needs them: `python3 scripts/groundwork.py add <path>`.
|
|
27
|
+
|
|
28
|
+
Upgrading a project from Groundwork 2.x? See `MIGRATION.md` in the Groundwork package (`create-groundwork` on npm).
|
|
29
|
+
|
|
30
|
+
Every command is available two ways: through the `groundwork` command-line tool (`npm install -g create-groundwork`), or with Python alone (`python3 scripts/groundwork.py` and `python3 scripts/check_docs.py`). Both run the same scripts in this project, so they always agree.
|
|
31
|
+
|
|
32
|
+
## Principles
|
|
33
|
+
- Write things down when the work demands it, not all up front.
|
|
34
|
+
- Each fact lives in one place — link to it, don't copy it. Each document has one owner: core, or one profile.
|
|
35
|
+
- Classify a project by what it must do, not by the technology it uses.
|
|
36
|
+
- Keep tech choices separate from the project docs: pick the stack and repo layout on their own.
|
|
37
|
+
- Keep the trail: every capability, requirement, design and test should connect (see `docs/examples/EXAMPLE.md` for a small worked example — fictional, and safe to delete).
|
|
38
|
+
- Let tools check the code rules wherever possible (linters, tests, CI — the automated checks that run on every change).
|
|
39
|
+
|
|
40
|
+
This scaffold starts you in a single-repository layout for convenience — it's not a rule. Delete anything you don't use.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Operating system files
|
|
2
|
+
.DS_Store
|
|
3
|
+
Thumbs.db
|
|
4
|
+
|
|
5
|
+
# Editor and IDE files
|
|
6
|
+
.idea/
|
|
7
|
+
.vscode/
|
|
8
|
+
*.swp
|
|
9
|
+
*~
|
|
10
|
+
|
|
11
|
+
# Environment variables and secrets — example files are safe to commit
|
|
12
|
+
.env*
|
|
13
|
+
!.env.example
|
|
14
|
+
!.env.sample
|
|
15
|
+
|
|
16
|
+
# Logs
|
|
17
|
+
*.log
|
|
18
|
+
logs/
|
|
19
|
+
|
|
20
|
+
# Build output and dependencies
|
|
21
|
+
build/
|
|
22
|
+
dist/
|
|
23
|
+
out/
|
|
24
|
+
target/
|
|
25
|
+
node_modules/
|
|
26
|
+
__pycache__/
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Documentation Guide
|
|
2
|
+
|
|
3
|
+
## The main documents
|
|
4
|
+
|
|
5
|
+
Every project has these (Groundwork Core):
|
|
6
|
+
|
|
7
|
+
- `../PROJECT.md`: what the project is called, where it stands, which profiles it uses, and where everything lives.
|
|
8
|
+
- `product/PRD.md`: the problem, the users and the outcomes we want.
|
|
9
|
+
- `product/SPEC.md`: testable requirements for the whole system, with feature specs in `product/specs/`.
|
|
10
|
+
- `architecture/SYSTEM_DESIGN.md`: the architecture starting point and index of the seven-part design.
|
|
11
|
+
- `../BUILD.md`: how to build, run and test the project locally.
|
|
12
|
+
- `engineering/SECURITY.md` and `engineering/TEST_STRATEGY.md`: security requirements and how the project is tested.
|
|
13
|
+
- `architecture/adr/`: why the big decisions were made (ADR = Architecture Decision Record).
|
|
14
|
+
- `plans/`: one short plan per non-trivial change (template inside).
|
|
15
|
+
- `examples/`: small, fictional worked examples — delete them when you don't need them.
|
|
16
|
+
- `../AGENTS.md`: how to work on this project, for humans and AI agents.
|
|
17
|
+
|
|
18
|
+
The active profiles add more (see `../profiles/README.md`):
|
|
19
|
+
|
|
20
|
+
- `architecture/system-design/`: the parts of the seven-part system design the project needs.
|
|
21
|
+
- `design/DESIGN.md`: how the product looks, feels and is structured for users.
|
|
22
|
+
- `architecture/contracts/`: detailed API and event contracts, when an interface needs one.
|
|
23
|
+
- One folder per profile for what only that profile covers, such as `web/` or `ai-systems/`.
|
|
24
|
+
|
|
25
|
+
Write each fact in one place and link to it from everywhere else. Give every requirement a stable ID (for example, `AUTH-FR-001`) and every PRD capability a `CAP-NNN` ID. Keep documents as short as the work needs. Write down assumptions and open questions.
|
|
26
|
+
|
|
27
|
+
The traceability chain: `product/PRD.md` states the problem and gives each capability a `CAP-NNN` ID → `product/SPEC.md` and `product/specs/` turn capabilities into testable requirement IDs and name, in each requirement's **Serves** column, the capability it covers → the architecture and profile documents reference the IDs they serve → implementation plans and tests name the IDs they satisfy.
|
|
28
|
+
|
|
29
|
+
When documents disagree, the more specific one wins for its area — a feature spec over `SPEC.md` for that feature, an accepted ADR over the design summary, a project requirement or ADR over a profile's default standard — and the conflict is recorded rather than silently resolved.
|
|
30
|
+
|
|
31
|
+
## Status values
|
|
32
|
+
|
|
33
|
+
Use exactly these values, so tools can check them:
|
|
34
|
+
|
|
35
|
+
- Project status (`PROJECT.md`): Discovery, Design, Development, Production, Maintenance — where the project stands overall.
|
|
36
|
+
- Document and spec status (`SYSTEM_DESIGN.md`, feature specs, the feature index): Draft (being written), In Review (being checked), Approved (agreed — treat as a fixed constraint), Superseded (replaced by a newer version).
|
|
37
|
+
- ADR status (`architecture/adr/`): Proposed (suggested, not yet agreed), Accepted (agreed — treat as fixed), Rejected (considered and turned down), Superseded (replaced by a newer ADR).
|
|
38
|
+
- Requirement priority: Must (required), Should (strongly wanted — defer only with a reason), Could (nice to have).
|
|
39
|
+
|
|
40
|
+
## Tools
|
|
41
|
+
|
|
42
|
+
- `scripts/groundwork.py`: chooses profiles (`init`), creates optional documents from their templates (`add`), shows what each profile offers (`list`) and the project's Groundwork configuration (`config`). It never overwrites or deletes a file. The `groundwork` command-line tool runs the same script: `groundwork init`, `groundwork add`, `groundwork profiles`, `groundwork config`, `groundwork validate`.
|
|
43
|
+
- `scripts/check_docs.py`: run it after adding, renaming or removing documents, feature specs, requirement IDs, links or profiles. It verifies the manifest, the feature index, internal links, requirement traceability and the profile rules, and prints errors and warnings.
|
|
44
|
+
|
|
45
|
+
The warnings come in two groups: hygiene (invalid status values, unserved capabilities, documents from inactive profiles, missing profile checks) and coverage (a requirement no design doc, plan or test references). Each group fails only under its flag:
|
|
46
|
+
|
|
47
|
+
- Default: only errors fail.
|
|
48
|
+
- `--strict`: hygiene warnings fail too.
|
|
49
|
+
- `--strict-coverage`: coverage warnings fail too.
|
|
50
|
+
|
|
51
|
+
`--strict-coverage` does not include `--strict`. Use both flags together to fail on everything.
|
|
52
|
+
|
|
53
|
+
Files you add under `src/`, `tests/`, `config/`, `infrastructure/` or `scripts/` don't need to be in `scaffold-manifest.json`, but template files must stay listed there. `groundwork.py` lists the documents it creates for you.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Repository Structure
|
|
2
|
+
|
|
3
|
+
Pick the layout that matches how the code is owned, deployed and released — not what's fashionable.
|
|
4
|
+
|
|
5
|
+
## Single application
|
|
6
|
+
```text
|
|
7
|
+
repo/
|
|
8
|
+
├── docs/
|
|
9
|
+
├── src/
|
|
10
|
+
├── tests/
|
|
11
|
+
├── scripts/
|
|
12
|
+
└── config/
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Modular monorepo
|
|
16
|
+
```text
|
|
17
|
+
repo/
|
|
18
|
+
├── apps/
|
|
19
|
+
│ ├── web/ # optional
|
|
20
|
+
│ ├── mobile/ # optional
|
|
21
|
+
│ ├── api/ # optional
|
|
22
|
+
│ └── worker/ # optional
|
|
23
|
+
├── packages/ # only when shared code is justified
|
|
24
|
+
├── docs/
|
|
25
|
+
└── infrastructure/ # optional
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Multiple repositories
|
|
29
|
+
```text
|
|
30
|
+
workspace/
|
|
31
|
+
├── project-docs/
|
|
32
|
+
├── client-app/
|
|
33
|
+
├── api-service/ # optional
|
|
34
|
+
└── infrastructure/ # optional
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Ask: do parts need to deploy, ship or be owned separately? Do they need different permissions? Is the shared code big enough to justify `packages/`? Can the team carry the extra tooling and CI complexity? Start with the simplest layout that handles the real constraints.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# System Design
|
|
2
|
+
|
|
3
|
+
> The architecture starting point and index. Detailed design lives in `system-design/`.
|
|
4
|
+
|
|
5
|
+
## Status
|
|
6
|
+
- Status: Draft / In Review / Approved / Superseded
|
|
7
|
+
- Owner:
|
|
8
|
+
- Last reviewed:
|
|
9
|
+
|
|
10
|
+
## Summary
|
|
11
|
+
The system's structure, its biggest choices, and the constraints behind them.
|
|
12
|
+
|
|
13
|
+
## Context and high-level view
|
|
14
|
+
Add a context or container diagram when it helps.
|
|
15
|
+
|
|
16
|
+
## Seven-part system design
|
|
17
|
+
The seven parts are described in [system-design/README.md](./system-design/README.md). A project has only the parts its profiles need (see `PROJECT.md`), and the parts it has live in `system-design/`. Until a part exists, record what matters about it here, in the summary. Add a part when the work needs it: `python3 scripts/groundwork.py add docs/architecture/system-design/<part>.md`.
|
|
18
|
+
|
|
19
|
+
## Cross-cutting concerns
|
|
20
|
+
The concerns that touch several parts of the system: security, privacy, accessibility, performance, compliance. Split them into separate documents only when the depth justifies it.
|
|
21
|
+
|
|
22
|
+
## Key decisions
|
|
23
|
+
Link to the matching ADRs in `adr/` — short records of important decisions: what was chosen and why.
|
|
24
|
+
|
|
25
|
+
## Open questions and risks
|
|
26
|
+
| Item | Impact | Owner | Next action |
|
|
27
|
+
|---|---|---|---|
|
|
28
|
+
| | | | |
|
|
29
|
+
|
|
30
|
+
The seven parts are different views of the same system — not steps to finish in order. When a change touches state, behaviour, boundaries, runtime or UI, update every affected section together. Each numbered document owns its topic; this file owns the summary, the cross-cutting concerns and the decision index.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# ADR-NNNN: Decision title
|
|
2
|
+
|
|
3
|
+
An ADR (Architecture Decision Record) is a short note capturing one important decision: what you chose, why, and what it costs.
|
|
4
|
+
|
|
5
|
+
- Status: Proposed / Accepted / Rejected / Superseded
|
|
6
|
+
- Date:
|
|
7
|
+
- Decision owners:
|
|
8
|
+
- Related requirements:
|
|
9
|
+
|
|
10
|
+
## Context
|
|
11
|
+
What problem, constraints and forces require a decision?
|
|
12
|
+
|
|
13
|
+
## Decision drivers
|
|
14
|
+
What matters when weighing the options?
|
|
15
|
+
|
|
16
|
+
## Options considered
|
|
17
|
+
| Option | Benefits | Costs / risks |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| | | |
|
|
20
|
+
|
|
21
|
+
## Decision
|
|
22
|
+
What did you choose?
|
|
23
|
+
|
|
24
|
+
## Consequences
|
|
25
|
+
What becomes easier, harder or newly constrained?
|
|
26
|
+
|
|
27
|
+
## Follow-up
|
|
28
|
+
What must change in implementation, documentation or operations as a result?
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Architecture Decision Records
|
|
2
|
+
|
|
3
|
+
ADRs are short records of important decisions: what was decided, why, and what follows from it.
|
|
4
|
+
|
|
5
|
+
Write one when a decision is hard or costly to reverse, affects several components, or sets a lasting constraint. Don't use ADRs for routine implementation details.
|
|
6
|
+
|
|
7
|
+
- Name files `NNNN-short-decision-title.md`.
|
|
8
|
+
- Lifecycle: Proposed → Accepted / Rejected → Superseded.
|
|
9
|
+
- Copy `0000-template.md` to start a new one.
|
|
10
|
+
|
|
11
|
+
Link the requirement IDs involved, and update the system design when an accepted decision changes the architecture.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Seven-Part System Design
|
|
2
|
+
|
|
3
|
+
Each document describes the same system from a different angle. Start short; add detail only where it helps.
|
|
4
|
+
|
|
5
|
+
A project has only the parts it needs. Each active profile requires some parts and makes others optional (see `profiles/<id>/profile.json`). `python3 scripts/groundwork.py init` creates the required parts here; create another part when the work needs it with `python3 scripts/groundwork.py add docs/architecture/system-design/<part>.md`. Every part belongs to Groundwork Core, so profiles share one copy rather than each keeping their own.
|
|
6
|
+
|
|
7
|
+
| Step | Document | Core question |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| 1 | `01-system-overview.md` | What is the system, who uses it, and what does it do? |
|
|
10
|
+
| 2 | `02-domain-and-state-model.md` | What data and concepts does it manage? |
|
|
11
|
+
| 3 | `03-behaviour-and-business-rules.md` | How does that state change, and what must always hold? |
|
|
12
|
+
| 4 | `04-architecture-and-interfaces.md` | How is it built, and what connects its parts? |
|
|
13
|
+
| 5 | `05-execution-and-resilience.md` | How does it run, fail and recover? |
|
|
14
|
+
| 6 | `06-operations-and-scalability.md` | How is it run day to day, watched and scaled? |
|
|
15
|
+
| 7 | `07-ui-and-interaction-mapping.md` | How do user actions map to system behaviour? |
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Security Requirements
|
|
2
|
+
|
|
3
|
+
## Objectives and scope
|
|
4
|
+
What we're protecting, from whom, and where the trust boundaries sit (the points where data crosses between levels of trust).
|
|
5
|
+
|
|
6
|
+
## Identity and access
|
|
7
|
+
How people sign in, what each role may do, least privilege, and how privileged operations are handled.
|
|
8
|
+
|
|
9
|
+
## Data protection
|
|
10
|
+
How data is classified, encrypted, retained and deleted, and how secrets are handled.
|
|
11
|
+
|
|
12
|
+
## Input and interface security
|
|
13
|
+
Input validation, rate limiting, abuse prevention and interface protections — where relevant.
|
|
14
|
+
|
|
15
|
+
## Dependencies and supply chain
|
|
16
|
+
How dependencies are reviewed, kept updated and watched for vulnerabilities.
|
|
17
|
+
|
|
18
|
+
## Logging and incident response
|
|
19
|
+
What never goes into logs, what needs an audit trail, and how incidents are escalated.
|
|
20
|
+
|
|
21
|
+
## Verification
|
|
22
|
+
Links to the security tests, reviews, threat models and requirements that verify all of the above.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Test Strategy
|
|
2
|
+
|
|
3
|
+
## Quality objectives
|
|
4
|
+
What risks should testing catch?
|
|
5
|
+
|
|
6
|
+
## Test layers
|
|
7
|
+
| Layer | Purpose | Must pass in CI? |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| Unit | One piece of logic, on its own | |
|
|
10
|
+
| Integration | Components working together | |
|
|
11
|
+
| Contract | Agreements between connected systems stay honoured | |
|
|
12
|
+
| End-to-end | The critical user journeys | |
|
|
13
|
+
| Performance / security | The quality attributes that matter here | |
|
|
14
|
+
|
|
15
|
+
## Critical scenarios
|
|
16
|
+
The high-risk paths, the invariants (things that must always hold) and the failure cases.
|
|
17
|
+
|
|
18
|
+
## Test data and environments
|
|
19
|
+
Fixtures, synthetic data, isolation, and any environment the tests need.
|
|
20
|
+
|
|
21
|
+
## Test environments and orchestration
|
|
22
|
+
How a full test run is assembled when several apps run together (client, API, worker):
|
|
23
|
+
|
|
24
|
+
- Who starts which app, in what order, and how readiness is checked.
|
|
25
|
+
- How the client finds the server (base URLs, ports).
|
|
26
|
+
- Which app seeds shared test data, and when.
|
|
27
|
+
- Isolation: one shared environment vs per-run environments (containers).
|
|
28
|
+
- Teardown: what's collected (logs, screenshots, videos, traces).
|
|
29
|
+
|
|
30
|
+
End-to-end drivers — for example Playwright for browsers, Maestro for mobile — are recorded in the tooling table in `AGENTS.md` and the relevant ADRs.
|
|
31
|
+
|
|
32
|
+
## Release gates
|
|
33
|
+
What must pass before release, and who can approve an exception.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Worked Example
|
|
2
|
+
|
|
3
|
+
A minimal, fictional example of the Groundwork paper trail, for a tiny product: **Linkbag**, an app that saves links behind a sign-in. This file is an example only — you can delete the whole `docs/examples/` directory from your project.
|
|
4
|
+
|
|
5
|
+
The chain it shows: capability → requirement → design → test.
|
|
6
|
+
|
|
7
|
+
## 0. Profiles (`PROJECT.md`)
|
|
8
|
+
|
|
9
|
+
- Profiles: application
|
|
10
|
+
- Why: people sign in and manage their own saved links, so it is an Application. Its server only stores links for this one client, using a hosted database as-is, so Backend/API would add documents nobody needs yet. It gets added when a second client or a public API appears.
|
|
11
|
+
|
|
12
|
+
## 1. PRD capability (`docs/product/PRD.md`)
|
|
13
|
+
|
|
14
|
+
| ID | What it does | Why users care | Priority |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| CAP-001 | Save a link with one click | Finding things again is the point of the app | Must |
|
|
17
|
+
|
|
18
|
+
## 2. System requirement (`docs/product/SPEC.md` §4)
|
|
19
|
+
|
|
20
|
+
| ID | Serves | Requirement | Priority | Verification |
|
|
21
|
+
|---|---|---|---|---|
|
|
22
|
+
| SYS-FR-001 | CAP-001 | The system stores a link with its URL and title. | Must | Feature-spec tests |
|
|
23
|
+
|
|
24
|
+
## 3. Feature spec (`docs/product/specs/sign-in/SPEC.md`, prefix `AUTH`)
|
|
25
|
+
|
|
26
|
+
| ID | Serves | Requirement | Priority | Verification |
|
|
27
|
+
|---|---|---|---|---|
|
|
28
|
+
| AUTH-FR-001 | CAP-001 | A signed-in user can save a link; a signed-out request is rejected. | Must | Unit test |
|
|
29
|
+
|
|
30
|
+
| ID | Serves | Rule | Expected system behaviour |
|
|
31
|
+
|---|---|---|---|
|
|
32
|
+
| AUTH-BR-001 | CAP-001 | A saved link belongs to exactly one account. | Link queries filter by the signed-in account |
|
|
33
|
+
|
|
34
|
+
## 4. ADR (`docs/architecture/adr/0001-sign-in.md`)
|
|
35
|
+
|
|
36
|
+
- Status: Accepted
|
|
37
|
+
- Related requirements: AUTH-FR-001
|
|
38
|
+
- Decision: sign-in is email and password; no social login yet.
|
|
39
|
+
- Consequence: one account model to maintain, no third-party dependency.
|
|
40
|
+
|
|
41
|
+
## 5. Design (`docs/architecture/system-design/07-ui-and-interaction-mapping.md`)
|
|
42
|
+
|
|
43
|
+
| User interaction | System operation | State read / changed | Requirement |
|
|
44
|
+
|---|---|---|---|
|
|
45
|
+
| Press "Save link" | Create link record | One row added to the account's links | SYS-FR-001, AUTH-FR-001 |
|
|
46
|
+
|
|
47
|
+
## 6. Test (`tests/`)
|
|
48
|
+
|
|
49
|
+
`test_sign_in.py::test_wrong_password_rejected` — its docstring says "verifies AUTH-FR-001", so requirement coverage stays searchable in any language.
|
|
50
|
+
|
|
51
|
+
## The chain
|
|
52
|
+
|
|
53
|
+
| From | To |
|
|
54
|
+
|---|---|
|
|
55
|
+
| CAP-001 | served by SYS-FR-001, AUTH-FR-001, AUTH-BR-001 |
|
|
56
|
+
| AUTH-FR-001 | shaped the ADR, the design row and the test |
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Profile Examples
|
|
2
|
+
|
|
3
|
+
Fictional examples of choosing and combining profiles. Profiles are always recorded in alphabetical order, whatever order you give them. Each one shows the `PROJECT.md` lines, the reasoning, and what `python3 scripts/groundwork.py init` creates. Delete this file whenever you like.
|
|
4
|
+
|
|
5
|
+
Core documents (`PRD.md`, `SPEC.md`, `SYSTEM_DESIGN.md`, `SECURITY.md`, `TEST_STRATEGY.md`, ADRs, plans) are present in every example and aren't repeated below.
|
|
6
|
+
|
|
7
|
+
## 1. Company landing page → Web
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
- Profiles: web
|
|
11
|
+
- Why: it publishes content for prospective customers and must be found in search. No sign-in, no data of its own; the contact form posts to a hosted form service.
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Creates `docs/web/CONTENT.md`, `docs/web/SEO.md` and `docs/design/DESIGN.md`, and adds tooling rows for Accessibility, Performance budget, and Links and metadata. There are no system-design parts: the hosting and form service fit in the `SYSTEM_DESIGN.md` summary.
|
|
15
|
+
|
|
16
|
+
Left out: Backend/API, because the form service is used as-is and the project owns no server logic.
|
|
17
|
+
|
|
18
|
+
## 2. Online shop → Application + Backend/API
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
- Profiles: application, backend-api
|
|
22
|
+
- Why: shoppers sign in, manage baskets and place orders (Application). The order, stock and payment services are ours, and their failures cost money (Backend/API).
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Creates system-design parts 01–07 and `docs/design/DESIGN.md`. Parts 01–04 are required by both profiles and are created once: each describes the storefront and the services as separate components. Tooling rows: End-to-end, Accessibility, Integration tests, API compatibility.
|
|
26
|
+
|
|
27
|
+
Optional documents to add later: `docs/backend-api/DATA.md` when stock moves to its own store, and `docs/architecture/contracts/README.md` when a warehouse partner starts calling the API.
|
|
28
|
+
|
|
29
|
+
Left out: Web, unless the shop also runs a content-heavy editorial site. If it does, add Web and record the boundary between the pages and the app in `docs/web/CONTENT.md`.
|
|
30
|
+
|
|
31
|
+
## 3. AI-powered SaaS → Application + Backend/API + AI Systems
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
- Profiles: ai-systems, application, backend-api
|
|
35
|
+
- Why: teams work in the product every day (Application); our services own their data and run model calls (Backend/API); the core feature drafts answers with a language model, whose quality has to be measured (AI Systems).
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Adds `docs/ai-systems/MODEL_INTEGRATION.md`, `EVALUATION.md` and `SAFETY.md` to everything example 2 creates, plus tooling rows for AI evaluation and AI safety tests. The answers draw on each customer's documents, so the team also runs `python3 scripts/groundwork.py add docs/ai-systems/RETRIEVAL.md`.
|
|
39
|
+
|
|
40
|
+
The model calls follow both the Backend/API rules (timeouts, retries) and the AI Systems rules (evaluation, untrusted output). These rules don't conflict: they add up.
|
|
41
|
+
|
|
42
|
+
## 4. AI marketing website → Web, and AI Systems only if there is real AI
|
|
43
|
+
|
|
44
|
+
The same brief can go two ways:
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
- Profiles: web
|
|
48
|
+
- Why: the copy and images were drafted with AI tools, then reviewed and published like any other content. Nothing runs a model for visitors.
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
- Profiles: ai-systems, web
|
|
53
|
+
- Why: visitors ask an assistant about the product, and a model answers live from our documentation. Wrong answers reach prospects, so quality and prompt injection need managing.
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Only the second version gets the AI documents and checks. AI Systems needs at least one other profile; here Web carries it.
|
|
57
|
+
|
|
58
|
+
## 5. Command-line tool → none
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
- Profiles: none
|
|
62
|
+
- Why: a single-user tool with no interface beyond its commands, no service and no model. Core is enough.
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## 6. Growing over time
|
|
66
|
+
|
|
67
|
+
A project starts as example 1. A year later it adds customer accounts, and later still an AI assistant:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
python3 scripts/groundwork.py init web
|
|
71
|
+
python3 scripts/groundwork.py init web application backend-api
|
|
72
|
+
python3 scripts/groundwork.py init web application backend-api ai-systems
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Each run creates only the documents that are missing and keeps everything already written. Nothing is renamed or moved. If a profile is later dropped, its documents stay, and `check_docs.py` warns until they are deleted or the profile comes back.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Implementation Plans
|
|
2
|
+
|
|
3
|
+
One short plan per non-trivial change, written before the work starts. Plans make the change reviewable: what was intended, what it touches, and how it will be checked.
|
|
4
|
+
|
|
5
|
+
## Rules
|
|
6
|
+
|
|
7
|
+
1. Copy `_template/PLAN.md` into this directory and name the file after the change (lowercase words separated by hyphens, for example `add-sign-in.md`).
|
|
8
|
+
2. Name the requirement IDs — and the `CAP-` capabilities — the plan covers. Plans with no IDs are a sign the change is trivial enough not to need a plan.
|
|
9
|
+
3. Keep the plan current as the work changes, and note in it when the approach changes.
|
|
10
|
+
4. Delete a plan once its change is done, or keep it if the reasoning is worth keeping — your choice, but don't leave stale plans.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Plan: [Change title]
|
|
2
|
+
|
|
3
|
+
- Status: Draft / In Review / Approved / Superseded
|
|
4
|
+
- Owner: [Person or team]
|
|
5
|
+
- Date: [YYYY-MM-DD]
|
|
6
|
+
- Related requirements: [Requirement IDs, and the `CAP-` capabilities they serve]
|
|
7
|
+
- Related documents: [Feature spec, design docs, ADRs]
|
|
8
|
+
|
|
9
|
+
## Approach
|
|
10
|
+
|
|
11
|
+
How it will be built, at a high level.
|
|
12
|
+
|
|
13
|
+
## Affected components
|
|
14
|
+
|
|
15
|
+
Which components, modules and interfaces it touches.
|
|
16
|
+
|
|
17
|
+
## Work breakdown
|
|
18
|
+
|
|
19
|
+
Tasks with dependencies, and how each is verified.
|
|
20
|
+
|
|
21
|
+
## Data and migration impact
|
|
22
|
+
|
|
23
|
+
Does stored data change, and how do records migrate? ("None" is an answer.)
|
|
24
|
+
|
|
25
|
+
## Security and privacy impact
|
|
26
|
+
|
|
27
|
+
Any new data, permissions or attack surface? ("None" is an answer.)
|
|
28
|
+
|
|
29
|
+
## Rollout and rollback
|
|
30
|
+
|
|
31
|
+
How it ships, and how to undo it.
|
|
32
|
+
|
|
33
|
+
## Tests and quality gates
|
|
34
|
+
|
|
35
|
+
What must pass before this is done, including the requirement IDs the tests name.
|
|
36
|
+
|
|
37
|
+
## Risks and unresolved questions
|
|
38
|
+
|
|
39
|
+
What could go wrong, and what is still undecided.
|