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.
Files changed (73) hide show
  1. package/CHANGELOG.md +87 -0
  2. package/LICENSE +21 -0
  3. package/MIGRATION.md +63 -0
  4. package/README.md +81 -2
  5. package/dist/commands.js +294 -0
  6. package/dist/create.js +4 -0
  7. package/dist/engine.js +124 -0
  8. package/dist/groundwork.js +4 -0
  9. package/dist/profiles.js +77 -0
  10. package/dist/prompter.js +42 -0
  11. package/dist/scaffold.js +274 -0
  12. package/dist/text.js +31 -0
  13. package/package.json +48 -4
  14. package/template/.github/README.md +14 -0
  15. package/template/.github/pull_request_template.md +22 -0
  16. package/template/.github/workflows/docs-check.yml +23 -0
  17. package/template/AGENTS.md +88 -0
  18. package/template/BUILD.md +27 -0
  19. package/template/LICENSE.md +5 -0
  20. package/template/PROJECT.md +26 -0
  21. package/template/README.md +40 -0
  22. package/template/_gitignore +26 -0
  23. package/template/config/README.md +3 -0
  24. package/template/docs/README.md +53 -0
  25. package/template/docs/architecture/REPOSITORY_STRUCTURE.md +37 -0
  26. package/template/docs/architecture/SYSTEM_DESIGN.md +30 -0
  27. package/template/docs/architecture/adr/0000-template.md +28 -0
  28. package/template/docs/architecture/adr/README.md +11 -0
  29. package/template/docs/architecture/system-design/README.md +15 -0
  30. package/template/docs/engineering/SECURITY.md +22 -0
  31. package/template/docs/engineering/TEST_STRATEGY.md +33 -0
  32. package/template/docs/examples/EXAMPLE.md +56 -0
  33. package/template/docs/examples/PROFILES.md +75 -0
  34. package/template/docs/plans/README.md +10 -0
  35. package/template/docs/plans/_template/PLAN.md +39 -0
  36. package/template/docs/product/PRD.md +39 -0
  37. package/template/docs/product/SPEC.md +63 -0
  38. package/template/docs/product/specs/README.md +37 -0
  39. package/template/docs/product/specs/_template/SPEC.md +78 -0
  40. package/template/infrastructure/README.md +3 -0
  41. package/template/profiles/README.md +96 -0
  42. package/template/profiles/ai-systems/README.md +44 -0
  43. package/template/profiles/ai-systems/profile.json +35 -0
  44. package/template/profiles/ai-systems/templates/docs/ai-systems/EVALUATION.md +35 -0
  45. package/template/profiles/ai-systems/templates/docs/ai-systems/MODEL_INTEGRATION.md +37 -0
  46. package/template/profiles/ai-systems/templates/docs/ai-systems/RETRIEVAL.md +26 -0
  47. package/template/profiles/ai-systems/templates/docs/ai-systems/SAFETY.md +35 -0
  48. package/template/profiles/application/README.md +43 -0
  49. package/template/profiles/application/profile.json +47 -0
  50. package/template/profiles/application/templates/docs/application/RELEASES.md +28 -0
  51. package/template/profiles/backend-api/README.md +40 -0
  52. package/template/profiles/backend-api/profile.json +42 -0
  53. package/template/profiles/backend-api/templates/docs/backend-api/DATA.md +27 -0
  54. package/template/profiles/core/profile.json +74 -0
  55. package/template/profiles/core/templates/docs/architecture/contracts/README.md +11 -0
  56. package/template/profiles/core/templates/docs/architecture/system-design/01-system-overview.md +29 -0
  57. package/template/profiles/core/templates/docs/architecture/system-design/02-domain-and-state-model.md +27 -0
  58. package/template/profiles/core/templates/docs/architecture/system-design/03-behaviour-and-business-rules.md +29 -0
  59. package/template/profiles/core/templates/docs/architecture/system-design/04-architecture-and-interfaces.md +27 -0
  60. package/template/profiles/core/templates/docs/architecture/system-design/05-execution-and-resilience.md +30 -0
  61. package/template/profiles/core/templates/docs/architecture/system-design/06-operations-and-scalability.md +27 -0
  62. package/template/profiles/core/templates/docs/architecture/system-design/07-ui-and-interaction-mapping.md +35 -0
  63. package/template/profiles/core/templates/docs/design/DESIGN.md +202 -0
  64. package/template/profiles/web/README.md +41 -0
  65. package/template/profiles/web/profile.json +34 -0
  66. package/template/profiles/web/templates/docs/web/CONTENT.md +39 -0
  67. package/template/profiles/web/templates/docs/web/SEO.md +35 -0
  68. package/template/scaffold-manifest.json +77 -0
  69. package/template/scripts/README.md +29 -0
  70. package/template/scripts/check_docs.py +989 -0
  71. package/template/scripts/groundwork.py +716 -0
  72. package/template/src/README.md +3 -0
  73. package/template/tests/README.md +3 -0
@@ -0,0 +1,39 @@
1
+ # Product Requirements Document (PRD)
2
+
3
+ What we're building and why, in product terms — no implementation detail.
4
+
5
+ ## Problem
6
+ Describe the user's problem and the evidence that it's real.
7
+
8
+ ## Users and stakeholders
9
+ Who uses the product, and who operates, funds or is otherwise affected by it: their situation, needs and constraints.
10
+
11
+ ## What success looks like
12
+ Describe the results we want for users and for the business — not how we'll build it.
13
+
14
+ ## Product capabilities
15
+ The top-level things the product lets people do. Give each one a stable ID in the form `CAP-NNN` (for example, `CAP-001`) — requirements in `docs/product/SPEC.md` and feature specs name the capability they serve.
16
+
17
+ | ID | What it does | Why users care | Priority |
18
+ |---|---|---|---|
19
+ | | | | |
20
+
21
+ ## Scope
22
+ ### In scope
23
+ -
24
+ ### Out of scope
25
+ -
26
+
27
+ ## Key user journeys
28
+ Describe the important end-to-end journeys.
29
+
30
+ ## How we'll measure success
31
+ | Metric | Baseline | Target | How we'll measure it |
32
+ |---|---|---|---|
33
+ | | | | |
34
+
35
+ ## Risks, assumptions and dependencies
36
+ -
37
+
38
+ ## Open questions
39
+ -
@@ -0,0 +1,63 @@
1
+ # System Specification
2
+
3
+ Testable requirements for the whole system — what it must do, and how well.
4
+
5
+ ## 1. Purpose
6
+
7
+ What this specification covers, and how it relates to the product requirements (PRD).
8
+
9
+ Requirement IDs follow `{SCOPE}-{TYPE}-NNN`. `SCOPE` is `SYS` for requirements that apply to the whole system, or a short feature code (like `AUTH`) in a feature spec. `TYPE` is `FR` (functional requirement — something the system must do), `NFR` (non-functional requirement — a quality goal like speed or uptime) or `BR` (business rule). Examples: `SYS-FR-001`, `AUTH-BR-002`.
10
+
11
+ Capabilities in the PRD have IDs in the form `CAP-NNN`. Every requirement names, in its **Serves** column, the PRD capability it contributes to — that is the first link in the traceability chain.
12
+
13
+ ## 2. System Scope
14
+
15
+ The capabilities this specification covers. Product scope — what gets built, and what doesn't — lives in `PRD.md`; this section only bounds which requirements belong here.
16
+
17
+ ## 3. System Context
18
+
19
+ Who and what surrounds the system: external users, other systems, and the environment it runs in.
20
+
21
+ ## 4. System-Wide Functional Requirements
22
+
23
+ Requirements that apply across the whole system, not just one feature. Feature-specific requirements belong in that feature's spec under `specs/`.
24
+
25
+ | ID | Serves | Requirement | Priority | Verification |
26
+ |---|---|---|---|---|
27
+ | SYS-FR-001 | [CAP-NNN] | [Requirement] | [Must/Should/Could] | [How it will be verified] |
28
+
29
+ ## 5. Non-Functional Requirements
30
+
31
+ Measurable quality goals: performance, availability, accessibility, reliability, maintainability and similar.
32
+
33
+ | ID | Serves | Quality Attribute | Requirement | Verification |
34
+ |---|---|---|---|---|
35
+ | SYS-NFR-001 | [CAP-NNN] | [Attribute] | [Measurable requirement] | [How it will be verified] |
36
+
37
+ ## 6. System Constraints
38
+
39
+ System-wide limits: legal, operational, platform, compatibility and technical constraints.
40
+
41
+ ## 7. Global Business Rules
42
+
43
+ Rules that apply across multiple features — things that must always or never happen. Feature-specific rules belong in that feature's spec.
44
+
45
+ ## 8. Global Acceptance Criteria
46
+
47
+ Acceptance criteria are the checkable conditions for saying "this is done". These apply to the system as a whole, before release.
48
+
49
+ ## 9. Feature Specification Index
50
+
51
+ Links to every feature spec. Keep this list in sync with the contents of `specs/` — `scripts/check_docs.py` verifies it.
52
+
53
+ | Feature | Specification | Status |
54
+ |---|---|---|
55
+ | [Feature name] | [specs/feature-name/SPEC.md](specs/feature-name/SPEC.md) | [Draft/In Review/Approved] |
56
+
57
+ ## 10. Open Questions
58
+
59
+ System-level questions that are still unresolved. Feature-specific questions stay in that feature's spec.
60
+
61
+ ## 11. References
62
+
63
+ Links to the PRD, architecture docs, relevant ADRs and other authoritative project documents.
@@ -0,0 +1,37 @@
1
+ # Feature Specifications
2
+
3
+ Detailed specs for individual features or capabilities.
4
+
5
+ ## Organisation
6
+
7
+ One directory per independently specifiable feature:
8
+
9
+ ```text
10
+ specs/
11
+ ├── README.md
12
+ ├── _template/
13
+ │ └── SPEC.md
14
+ ├── authentication/
15
+ │ └── SPEC.md
16
+ └── another-feature/
17
+ └── SPEC.md
18
+ ```
19
+
20
+ Use lowercase kebab-case (words separated by hyphens) for directory names. Each feature directory contains a `SPEC.md` — the authoritative spec for that feature. Add supporting documents only if the feature is complex enough to need them.
21
+
22
+ ## Rules
23
+
24
+ 1. Give each requirement a stable, unique ID, such as `AUTH-FR-001`, and name the PRD capability (`CAP-NNN`) it serves in the **Serves** column.
25
+ 2. Write requirements that are clear and can be checked.
26
+ 3. Keep everything specific to one feature in that feature's spec: behaviour, rules, data, workflows, edge cases and acceptance criteria.
27
+ 4. Keep requirements that span several features in the root `../SPEC.md`.
28
+ 5. Never copy a requirement into multiple documents — link to the one authoritative copy.
29
+ 6. When you add, rename or retire a feature spec, update the index in `../SPEC.md`.
30
+ 7. Link implementation and architecture decisions to the feature requirements where useful.
31
+
32
+ ## Creating a feature specification
33
+
34
+ 1. Copy `_template/SPEC.md` into a new directory named after the feature (kebab-case).
35
+ 2. Replace the template content with the feature's real requirements.
36
+ 3. Add the feature to the index in `../SPEC.md`.
37
+ 4. Delete `_template/` when it's no longer needed.
@@ -0,0 +1,78 @@
1
+ # Feature Specification: [Feature Name]
2
+
3
+ **Status:** Draft
4
+ **Requirement ID prefix:** [PREFIX]
5
+ **Owner:** [Person or team]
6
+ **Last updated:** [YYYY-MM-DD]
7
+
8
+ ## 1. Overview
9
+
10
+ Describe the feature in a few sentences: what it is and what it lets people do.
11
+
12
+ ## 2. Objectives
13
+
14
+ What outcomes this feature must deliver. Name the PRD capabilities (`CAP-NNN`) it serves where you can.
15
+
16
+ ## 3. Actors and Permissions
17
+
18
+ Who and what interacts with this feature — users, roles, external systems, automated jobs — and what each one is allowed to do.
19
+
20
+ ## 4. Preconditions
21
+
22
+ What must already be true before this feature (or a specific workflow) can be used.
23
+
24
+ ## 5. Functional Requirements
25
+
26
+ Write each requirement as a clear statement that can be checked on its own.
27
+
28
+ | ID | Serves | Requirement | Priority | Verification |
29
+ |---|---|---|---|---|
30
+ | [PREFIX]-FR-001 | [CAP-NNN] | The system shall [observable behaviour]. | [Must/Should/Could] | [Test or other verification] |
31
+
32
+ ## 6. Business Rules and Invariants
33
+
34
+ Rules that must always hold: domain rules, validation, limits, calculations. An invariant is something that stays true no matter what happens.
35
+
36
+ | ID | Serves | Rule | Expected system behaviour |
37
+ |---|---|---|---|
38
+ | [PREFIX]-BR-001 | [CAP-NNN] | [Rule] | [Enforcement or outcome] |
39
+
40
+ ## 7. Data Requirements
41
+
42
+ The information the feature receives, keeps, exposes or retains. Name the important fields, relationships, validation and lifecycle rules — describe the data, not a database schema, unless one is truly needed.
43
+
44
+ ## 8. Behaviour and Workflows
45
+
46
+ The main workflows: what triggers them, how state changes, and what results users see. Use diagrams or tables where they make things clearer.
47
+
48
+ ## 9. Edge Cases and Failure States
49
+
50
+ Bad input, unavailable dependencies, conflicting actions, retries, timeouts, partial completion — whatever can go wrong, and what should happen then.
51
+
52
+ | Scenario | Expected behaviour |
53
+ |---|---|
54
+ | [Condition] | [Required system response] |
55
+
56
+ ## 10. Acceptance Criteria
57
+
58
+ The observable conditions that prove the feature is done. Given/When/Then (a standard format for acceptance tests) helps where it fits:
59
+
60
+ - **Given** [starting situation]
61
+ - **When** [action or event]
62
+ - **Then** [observable result]
63
+
64
+ ## 11. Dependencies and Interfaces
65
+
66
+ What this feature relies on: other features, external systems, shared capabilities. Link to their specs and interface contracts.
67
+
68
+ ## 12. Out of Scope
69
+
70
+ Related behaviour this spec deliberately does not cover — say so explicitly.
71
+
72
+ ## 13. Open Questions
73
+
74
+ Unresolved requirements, assumptions to validate, and decisions still to make.
75
+
76
+ ## 14. References
77
+
78
+ Links to PRD capabilities (`CAP-NNN`), system-wide requirements, architecture docs, ADRs, designs and related feature specs.
@@ -0,0 +1,3 @@
1
+ # Infrastructure (Optional)
2
+
3
+ Infrastructure-as-code (Terraform, CloudFormation, Pulumi and similar) and environment provisioning go here — but only if the project needs them. Link to it from the architecture documentation.
@@ -0,0 +1,96 @@
1
+ # Profiles
2
+
3
+ Groundwork Core gives every project the same base: the project definition, agent instructions, product and system requirements with traceable IDs, the architecture starting point, decisions and the documentation checks. **Profiles** add what a particular kind of system needs on top: extra documents, engineering standards, agent instructions and checks. A project uses as many profiles as it has kinds of responsibility, and no more.
4
+
5
+ | Profile | For | Adds |
6
+ |---|---|---|
7
+ | [Web](web/README.md) | Landing pages, marketing, corporate and content sites | Content architecture, search and sharing, design, accessibility and performance checks |
8
+ | [Application](application/README.md) | Interactive web, mobile and desktop apps | Feature-level specs, the interaction model, application architecture |
9
+ | [Backend/API](backend-api/README.md) | Services, APIs, workers, integrations | Domain model, contracts, data architecture, resilience, operations |
10
+ | [AI Systems](ai-systems/README.md) | LLM features, retrieval, agents, model-driven workflows | Model integration and context, evaluation and observability, AI safety and data governance |
11
+
12
+ Some examples: a company landing page uses Web. An online shop uses Application and Backend/API. An AI-powered SaaS product uses Application, Backend/API and AI Systems. A marketing site with a visitor-facing AI assistant uses Web and AI Systems. More worked combinations are in `docs/examples/PROFILES.md`.
13
+
14
+ ## Initialization
15
+
16
+ Do this once at the start, and again whenever the system takes on a new kind of responsibility. An agent can run every step; a person confirms the choice in step 4.
17
+
18
+ 1. **Inspect the requirements.** Read `PROJECT.md`, `docs/product/PRD.md` and whatever brief exists. If they are empty, ask what the system must do, for whom, and what it must keep running.
19
+ 2. **Recommend profiles.** Run `python3 scripts/groundwork.py list` and compare each profile's "use when" and "not when" with what the system actually does. Answer these questions:
20
+ - Is the main job publishing content people read? → Web.
21
+ - Do people do work in it — sign in, create and change their own data? → Application.
22
+ - Does it own server-side logic or data that other software depends on, with failures and operations to design for? → Backend/API.
23
+ - Does the system's behaviour depend on a model at run time? → AI Systems (with at least one of the others).
24
+ - None of these, such as a library or a command-line tool? → `none`: core alone is enough.
25
+ 3. **Explain the choice briefly.** One sentence per profile, naming the responsibility that justifies it, plus any profile you considered and left out, and why.
26
+ 4. **Confirm.** Ask the person to confirm or change the selection. Don't go ahead on a guess.
27
+ 5. **Generate the structure.** Run `groundwork init <profile> [<profile> ...]`, or `python3 scripts/groundwork.py init ...` without Node (add `--dry-run` first to preview). For a brand-new project, `npx create-groundwork` asks these questions and does this step for you. It records the profiles in `PROJECT.md`, creates each missing required document from its template, adds the profiles' checks to the tooling table in `AGENTS.md`, and lists new files in `scaffold-manifest.json`. It never overwrites or deletes anything. Then write the explanation from step 3 under "Why:" in `PROJECT.md`.
28
+ 6. **Apply the profile.** Read each active profile's README: its standards and agent instructions now apply. Run `python3 scripts/check_docs.py` — it now checks the profile rules too.
29
+
30
+ **Classify by responsibility, not technology.** A React front end doesn't make a project an Application, and an installed AI SDK doesn't make it an AI System. What counts is what the system must do and keep doing. When a case is borderline, choose the smaller set: adding a profile later is one command, and nothing has to move.
31
+
32
+ ## How composition works
33
+
34
+ Several profiles can be active at once. These rules keep that simple and predictable:
35
+
36
+ 1. **Core is always active.** Profiles add to core; they never remove or change a core document.
37
+ 2. **Requirements add up.** A project needs core's required documents plus every active profile's required documents. If any active profile requires a document, it is required. Nothing outranks anything else, so the order of profiles in `PROJECT.md` doesn't matter.
38
+ 3. **Every document has one owner.** Core owns the documents it lists. Any other profile owns exactly the documents it has templates for, and it may list only its own documents and core's. If two profiles need the same document, that document belongs in core — which is why all seven system-design parts and `DESIGN.md` are core documents that profiles switch on. There is one template per document, and the checker rejects a second owner.
39
+ 4. **Shared documents describe every side once.** When Application and Backend/API both require `04-architecture-and-interfaces.md`, there is one copy, and it describes client and services as separate components. Profiles add *where to put things*, never a second copy.
40
+ 5. **Dependencies are declared.** A profile can require another profile, or one of several (`requires`). AI Systems requires one of Web, Application or Backend/API, because AI is a capability of a product, not a product on its own.
41
+ 6. **Real conflicts are declared, not ranked.** If two profiles truly can't be combined, their manifests say so (`incompatible_with`), and the checker stops the combination. None of the four current profiles conflict.
42
+ 7. **Conflicting guidance is resolved explicitly.** Each profile's standards apply to the part of the system that has that responsibility (Web to the public pages, Application to the signed-in product). Where two standards still disagree about the same part, no profile wins by default: decide, and record the decision in an ADR. A project requirement or an accepted ADR always overrides a profile default.
43
+ 8. **Optional documents start when their condition is true.** Each optional document has a `when` condition. Create it then with `python3 scripts/groundwork.py add <path>`, not before.
44
+ 9. **Checks are merged by name.** If two profiles need an "Accessibility" check, one tooling-table row covers both.
45
+ 10. **Dropping a profile deletes nothing.** Re-run `init` without it. Its documents stay, and the checker warns about them until you delete them or bring the profile back.
46
+
47
+ ## What the checker enforces
48
+
49
+ `scripts/check_docs.py` validates profiles whenever this folder exists:
50
+
51
+ - **Errors:** an invalid manifest, a document with two owners, a profile listing another profile's document, an unknown or duplicated profile in `PROJECT.md`, a missing dependency, an incompatible pair, or a missing required document.
52
+ - **Hygiene warnings** (fail under `--strict`): a document from a profile that isn't active, and a profile check with no row in the `AGENTS.md` tooling table.
53
+
54
+ Templates under `profiles/<id>/templates/` aren't checked for IDs or links where they sit; they are checked once copied into place.
55
+
56
+ ## Manifest reference
57
+
58
+ Each profile is a folder: `profile.json` (what machines read), `README.md` (standards and instructions people and agents read), and `templates/` (one template per owned document, at the path it will have in the project).
59
+
60
+ ```json
61
+ {
62
+ "schema": 1,
63
+ "id": "example",
64
+ "name": "Example",
65
+ "purpose": "One or two sentences: what kind of system this is for, and what it adds.",
66
+ "use_when": ["A responsibility that justifies this profile."],
67
+ "not_when": ["A look-alike case that does not, and what to do instead."],
68
+ "requires": ["other-profile", ["either-this", "or-this"]],
69
+ "incompatible_with": [],
70
+ "documents": [
71
+ { "path": "docs/example/THING.md", "required": true },
72
+ { "path": "docs/example/EXTRA.md", "required": false, "when": "The condition that makes it worth writing." }
73
+ ],
74
+ "checks": [
75
+ { "name": "Example check", "what": "What must be verified, in tool-neutral words." }
76
+ ]
77
+ }
78
+ ```
79
+
80
+ - `id` matches the folder name: lowercase letters, digits and hyphens.
81
+ - `requires`: each entry is a profile ID that must be active, or a list of IDs of which at least one must be active.
82
+ - `documents`: `path` is where the document lives in the project. A path with a template in this profile's `templates/` is owned by this profile; any other path must be a core document. Optional documents need `when`; required ones must not have it.
83
+ - `checks`: concerns the project must verify. `init` adds a row named after each check to the tooling table in `AGENTS.md`; the project fills in the tool. Name the concern, not a product, to keep Groundwork technology-neutral.
84
+ - Core (`core/profile.json`) has only `schema`, `id`, `name`, `purpose` and `documents`. Its required documents ship in place; its optional modules have templates in `core/templates/`.
85
+
86
+ Engineering standards are prose, so they live in the profile's README, not in the manifest.
87
+
88
+ ## Adding a profile
89
+
90
+ 1. Ask whether the new kind of system needs *different documents or checks*, or just different content in existing ones. Only the first justifies a profile; the second belongs in your project's docs.
91
+ 2. Copy an existing profile folder and rename it. Set `id` to the folder name.
92
+ 3. Keep only the templates for concerns no core document covers. Use core documents by listing them; never copy them.
93
+ 4. Write the README: purpose, where each concern lives, engineering standards, agent instructions, and how it composes with the other profiles.
94
+ 5. List the new files in `scaffold-manifest.json` and run `python3 scripts/check_docs.py --strict`.
95
+
96
+ No change to core or to the scripts is needed. Delete the folder of any profile you are sure you won't use, and remove its files from `scaffold-manifest.json`; keep `core/`.
@@ -0,0 +1,44 @@
1
+ # AI Systems Profile
2
+
3
+ For systems whose behaviour depends on AI models at run time: LLM features (large language models), retrieval, agents and model-driven workflows. When it applies, which documents it adds and which checks it needs are declared in [profile.json](profile.json).
4
+
5
+ AI Systems is never used alone. AI is a capability of a product, so this profile requires at least one of Web, Application or Backend/API. That other profile describes the product that carries the AI features.
6
+
7
+ ## Where each concern lives
8
+
9
+ | Concern | Lives in |
10
+ |---|---|
11
+ | AI features, models, prompts, context management, tools and agents | `docs/ai-systems/MODEL_INTEGRATION.md` |
12
+ | Retrieval: sources, indexing, freshness, permissions (optional) | `docs/ai-systems/RETRIEVAL.md` |
13
+ | Quality criteria, evaluation sets, thresholds, AI observability | `docs/ai-systems/EVALUATION.md` |
14
+ | AI risks, prompt injection, human oversight, data governance | `docs/ai-systems/SAFETY.md` |
15
+ | Where model calls sit among the components | `docs/architecture/system-design/04-architecture-and-interfaces.md` |
16
+ | General security: sign-in, access, secrets | `docs/engineering/SECURITY.md` |
17
+ | What the AI features must do, as requirements | `docs/product/SPEC.md` and feature specs |
18
+
19
+ ## Engineering standards
20
+
21
+ Defaults for the AI features. A project can override any of them with a requirement in `SPEC.md` or an accepted ADR.
22
+
23
+ - Every AI feature has written quality criteria and an evaluation set before it ships. "It looked fine when I tried it" is not evidence.
24
+ - A change to a prompt, model, retrieval setup or tool is a code change: reviewed, versioned and evaluated against the thresholds in `EVALUATION.md`.
25
+ - Model output is untrusted input. Validate it before it changes state, reaches another system or is shown as fact.
26
+ - Retrieved content and user input can carry hidden instructions. Keep them apart from system instructions, and never let them widen what the model may do.
27
+ - Agents get the narrowest tools that do the job. Actions that cannot be undone need a person's approval or a hard limit.
28
+ - Every model call has a timeout, a cost limit and a fallback the user can understand.
29
+ - Send a model only the data it needs. Follow the data rules in `SAFETY.md`.
30
+ - Pin model versions, and treat a version upgrade as a change that must pass evaluation.
31
+
32
+ ## Agent instructions
33
+
34
+ - Before changing an AI feature, read its row in `MODEL_INTEGRATION.md`, its quality criteria in `EVALUATION.md` and its risks in `SAFETY.md`.
35
+ - When you change a prompt, model or retrieval setting, run the AI evaluation and report the scores against the thresholds in the change's plan or pull request.
36
+ - When you add a tool an agent can call, add it to `MODEL_INTEGRATION.md` and review its limits in `SAFETY.md`.
37
+ - When you add a new kind of data sent to a model, add a row to the data governance table in `SAFETY.md`.
38
+ - Don't let a passing ordinary test suite stand in for evaluation.
39
+
40
+ ## Composing with other profiles
41
+
42
+ - **With Backend/API:** model calls follow that profile's rules on timeouts, retries and failure, as well as these.
43
+ - **With Application:** AI output in the interface needs UI states for slow, failed and low-confidence answers, recorded in `docs/design/DESIGN.md` §6.4.
44
+ - **With Web:** only for AI that runs for visitors. Content written with AI help is ordinary content.
@@ -0,0 +1,35 @@
1
+ {
2
+ "schema": 1,
3
+ "id": "ai-systems",
4
+ "name": "AI Systems",
5
+ "purpose": "Systems whose behaviour depends on AI models at run time: LLM features, retrieval, agents and model-driven workflows. Adds model integration and context management, evaluation and observability, and AI-specific safety and data governance.",
6
+ "use_when": [
7
+ "Users get output that a model produces at run time, or a model decides what the system does next.",
8
+ "Output quality cannot be proven by ordinary tests alone and has to be measured.",
9
+ "User or company data is sent to a model, or retrieved to ground its answers."
10
+ ],
11
+ "not_when": [
12
+ "AI was only used to write the code or the content. That is a way of working, not a system responsibility.",
13
+ "A model is called once at build time and its output is reviewed and committed like any other content.",
14
+ "An AI SDK is installed. Technology alone never activates a profile."
15
+ ],
16
+ "requires": [["web", "application", "backend-api"]],
17
+ "incompatible_with": [],
18
+ "documents": [
19
+ { "path": "docs/ai-systems/MODEL_INTEGRATION.md", "required": true },
20
+ { "path": "docs/ai-systems/EVALUATION.md", "required": true },
21
+ { "path": "docs/ai-systems/SAFETY.md", "required": true },
22
+ { "path": "docs/architecture/system-design/04-architecture-and-interfaces.md", "required": true },
23
+ { "path": "docs/engineering/SECURITY.md", "required": true },
24
+ { "path": "docs/engineering/TEST_STRATEGY.md", "required": true },
25
+ {
26
+ "path": "docs/ai-systems/RETRIEVAL.md",
27
+ "required": false,
28
+ "when": "The system retrieves documents or records to ground model output: search, retrieval-augmented generation (RAG) or long-term memory."
29
+ }
30
+ ],
31
+ "checks": [
32
+ { "name": "AI evaluation", "what": "The evaluation suite in EVALUATION.md runs and meets its thresholds before a model, prompt or retrieval change ships." },
33
+ { "name": "AI safety tests", "what": "Adversarial cases from SAFETY.md, including prompt injection and data leakage, run and pass." }
34
+ ]
35
+ }
@@ -0,0 +1,35 @@
1
+ # AI Evaluation and Observability
2
+
3
+ > AI Systems profile. How we know the AI features are good enough, and how we notice when they stop being good enough. Ordinary tests stay in `docs/engineering/TEST_STRATEGY.md`; this document covers what ordinary tests cannot prove.
4
+
5
+ ## Quality criteria
6
+ For each AI feature in `docs/ai-systems/MODEL_INTEGRATION.md`: what a good result looks like, what is unacceptable, and how results are scored (exact match, a rubric, human rating, or another model grading against a rubric).
7
+
8
+ ## Evaluation sets
9
+ Representative cases, hard cases, and cases taken from real failures. Say how personal data is removed from them.
10
+
11
+ | Set | Feature | Size | Source | Owner | Last refreshed |
12
+ |---|---|---|---|---|---|
13
+ | | | | | | |
14
+
15
+ ## Metrics and thresholds
16
+ These thresholds are the release gate behind the "AI evaluation" check in the tooling table in `AGENTS.md`.
17
+
18
+ | Metric | Feature | Threshold to ship | Current |
19
+ |---|---|---|---|
20
+ | | | | |
21
+
22
+ ## When evaluations run
23
+ On every change to a prompt, model, retrieval setup or tool; before upgrading a model version; and on a schedule against samples from production.
24
+
25
+ ## Human review
26
+ Where people review output (a sample, flagged cases, high-risk cases), who reviews it, and how their judgements flow back into the evaluation sets.
27
+
28
+ ## Production observability
29
+ - Traces: each model call with its inputs, context size, output, response time, cost and model version, with sensitive data handled as `docs/ai-systems/SAFETY.md` requires.
30
+ - Quality signals: user feedback, retries, edits and escalations.
31
+ - Drift: changes over time in what users ask or in output quality.
32
+ - Alerts: the quality, cost or error levels that trigger action, and who acts.
33
+
34
+ ## Known limitations
35
+ What the AI features are known to get wrong, and how users are told.
@@ -0,0 +1,37 @@
1
+ # Model Integration
2
+
3
+ > AI Systems profile. Where and how the system uses AI models at run time, and how it builds what each model sees. Quality measurement lives in `docs/ai-systems/EVALUATION.md`, risks and data rules in `docs/ai-systems/SAFETY.md`, and retrieval, if the system has it, in `docs/ai-systems/RETRIEVAL.md`. Components and their boundaries stay in `docs/architecture/system-design/04-architecture-and-interfaces.md`.
4
+
5
+ ## AI features
6
+ Every place a model shapes what the system does or shows. Name the requirement IDs each one serves.
7
+
8
+ | Feature | Model task | What the model decides or produces | What happens when it is wrong | Requirements |
9
+ |---|---|---|---|---|
10
+ | | | | | |
11
+
12
+ ## Models and providers
13
+ Record the choices that are hard to reverse (provider, hosting, open or closed model) in an ADR.
14
+
15
+ | Model | Provider or hosting | Used for | Why this one | Fallback |
16
+ |---|---|---|---|---|
17
+ | | | | | |
18
+
19
+ ## Prompts and instructions
20
+ Where prompts live, how they are versioned and reviewed, and how a prompt change is evaluated before it ships. Treat prompts as code.
21
+
22
+ ## Context management
23
+ What goes into each model call, in what order, and what is left out: instructions, user input, conversation history, retrieved content, tool results. Set a budget for how much of the model's context (its input limit, counted in tokens) each part may use, and say what is trimmed or summarised first when the budget runs out.
24
+
25
+ ## Tools and agents
26
+ Only if models call tools or run multi-step loops: the tools each agent may use, what each tool can change, the limits on steps and cost, and where a person must approve. `docs/ai-systems/SAFETY.md` reviews these permissions.
27
+
28
+ ## Output handling
29
+ How model output is checked before it is used: the expected structure, how it is validated, and what the system does with output that fails.
30
+
31
+ ## Failure and fallback
32
+ Timeouts, rate limits, provider outages and refusals: how each is detected, and what the user sees.
33
+
34
+ ## Cost and latency
35
+ | Feature | Response-time target | Cost per call or per user | Limit or alert |
36
+ |---|---|---|---|
37
+ | | | | |
@@ -0,0 +1,26 @@
1
+ # Retrieval
2
+
3
+ > AI Systems profile, optional. Create this when the system retrieves documents or records to ground model output: search, retrieval-augmented generation (RAG) or long-term memory. How retrieved content fits into each model call is decided in `docs/ai-systems/MODEL_INTEGRATION.md` (context management).
4
+
5
+ ## Sources
6
+ | Source | Content | Owner | How often it changes | Who may see it |
7
+ |---|---|---|---|---|
8
+ | | | | | |
9
+
10
+ ## Ingestion
11
+ How content is collected, cleaned, split into chunks and indexed, how often that runs, and what is left out.
12
+
13
+ ## Indexing and search
14
+ How content is represented (embeddings, which are numeric representations of meaning; keywords; or both), how results are ranked, and how many results reach the model.
15
+
16
+ ## Freshness
17
+ How changes and deletions in a source reach the index, and how stale content is spotted.
18
+
19
+ ## Access control
20
+ Retrieval must never show a user content they could not open themselves. Say how permissions travel from each source to each result.
21
+
22
+ ## Retrieval quality
23
+ How retrieval is measured on its own, separately from the final answer — for example, how often the right document appears in the results for a set of known questions. The thresholds live in `docs/ai-systems/EVALUATION.md`.
24
+
25
+ ## Citations
26
+ Whether answers cite their sources, and how users can check them.
@@ -0,0 +1,35 @@
1
+ # AI Safety and Data Governance
2
+
3
+ > AI Systems profile. The risks that come from model behaviour, and the rules for the data models see. General security (sign-in, access, secrets) stays in `docs/engineering/SECURITY.md`; this document covers what is specific to AI.
4
+
5
+ ## Risk assessment
6
+ Consider at least: confident wrong answers (often called hallucinations), harmful or off-brand output, prompt injection (instructions hidden in user input or retrieved content that take over the model), data leaking between users, unsafe tool actions, and users relying on output more than they should.
7
+
8
+ | Risk | Feature | Impact if it happens | Likelihood | Mitigation | Test |
9
+ |---|---|---|---|---|---|
10
+ | | | | | | |
11
+
12
+ ## Trust boundaries
13
+ What the model may read, what it may do, and what it must never be trusted with. Treat model output as untrusted input everywhere the system uses it.
14
+
15
+ ## Tool and action limits
16
+ For agents and tool use: which actions can be undone, which need a person's approval, and which are never allowed.
17
+
18
+ ## Human oversight
19
+ Where a person can review, override or undo what the AI did, and how users report a problem.
20
+
21
+ ## Data governance
22
+ - What data may go into prompts, and what must be removed or masked first.
23
+ - Each provider's terms: how long it keeps data, whether it trains on it, and where it processes it.
24
+ - The right to use the data behind retrieval, fine-tuning or evaluation.
25
+ - How a user's data is removed from logs, evaluation sets and indexes when they ask.
26
+
27
+ | Data | Sent to | Purpose | Kept by provider? | Used for training? | Legal basis or consent |
28
+ |---|---|---|---|---|---|
29
+ | | | | | | |
30
+
31
+ ## Transparency
32
+ How users are told that output comes from AI, and what the system says about its limits.
33
+
34
+ ## Incident response
35
+ What counts as an AI incident (harmful output, a data leak, an agent acting out of bounds), how a feature is switched off quickly, and who decides.
@@ -0,0 +1,43 @@
1
+ # Application Profile
2
+
3
+ For interactive web, mobile and desktop applications with real product behaviour: people sign in, create and change data, and work through multi-step workflows. When it applies, which documents it adds and which checks it needs are declared in [profile.json](profile.json).
4
+
5
+ This profile adds almost no documents of its own, on purpose. The core already has the right homes for product requirements, feature specs and the seven-part system design. This profile turns on the parts an application needs and sets the standards for using them.
6
+
7
+ ## Where each concern lives
8
+
9
+ | Concern | Lives in |
10
+ |---|---|
11
+ | Product requirements and capabilities | `docs/product/PRD.md` |
12
+ | Feature specifications — one per feature people use | `docs/product/specs/<feature>/SPEC.md` |
13
+ | Domain concepts and state | `docs/architecture/system-design/02-domain-and-state-model.md` |
14
+ | State transitions and rules | `docs/architecture/system-design/03-behaviour-and-business-rules.md` |
15
+ | Application architecture (client structure, state handling, integrations) | `docs/architecture/system-design/04-architecture-and-interfaces.md` |
16
+ | Interaction model: what each user action does to the system | `docs/architecture/system-design/07-ui-and-interaction-mapping.md` |
17
+ | How it looks and feels, UI states, accessibility standard | `docs/design/DESIGN.md` |
18
+ | Offline use, sync, on-device background work (optional) | `docs/architecture/system-design/05-execution-and-resilience.md` |
19
+ | Releasing installed clients (optional) | `docs/application/RELEASES.md` |
20
+
21
+ ## Engineering standards
22
+
23
+ Defaults for the application. A project can override any of them with a requirement in `SPEC.md` or an accepted ADR.
24
+
25
+ - Every user-facing feature has a feature spec with acceptance criteria before it is built.
26
+ - Every screen handles all the UI states in `DESIGN.md` §6.4: loading, empty, error, offline and no permission, not only success.
27
+ - Each piece of state has one owner and one authoritative copy, recorded in `02-domain-and-state-model.md`. The client caches; it does not quietly become the source of truth.
28
+ - Check permissions on the server. Hiding a button is not access control.
29
+ - The critical journeys in the PRD have end-to-end tests.
30
+ - Meet the accessibility standard named in `DESIGN.md` §6.7.
31
+
32
+ ## Agent instructions
33
+
34
+ - Before changing a feature, read its feature spec and the rows for it in `07-ui-and-interaction-mapping.md`.
35
+ - When you add a screen or a user action, add it to `07-ui-and-interaction-mapping.md` (system side) and `DESIGN.md` §7.5 (design side) with the same name.
36
+ - When you change state or rules, update `02` and `03` together.
37
+ - Name the requirement IDs a test verifies in the test itself.
38
+
39
+ ## Composing with other profiles
40
+
41
+ - **With Backend/API:** Application owns the client and the user's view of behaviour; Backend/API owns the services, their data and how they run. Shared documents (`01`–`04`) have one copy: describe both sides in it, client and services as separate components.
42
+ - **With Web:** see the Web profile — draw the boundary between public pages and the product in `docs/web/CONTENT.md`.
43
+ - **Without Backend/API:** if the app relies on a hosted backend used as-is, describe it as an integration in `04-architecture-and-interfaces.md`.
@@ -0,0 +1,47 @@
1
+ {
2
+ "schema": 1,
3
+ "id": "application",
4
+ "name": "Application",
5
+ "purpose": "Interactive web, mobile and desktop applications with real product behaviour: people sign in, create and change data, and move through multi-step workflows. Adds feature-level specification, the interaction model and the application architecture.",
6
+ "use_when": [
7
+ "People do work in the product: create, edit, manage or transact, not just read.",
8
+ "Screens depend on who the user is and what state their data is in.",
9
+ "The product has several features that each need their own requirements and acceptance criteria."
10
+ ],
11
+ "not_when": [
12
+ "The product is mostly published content with a contact form. Use Web.",
13
+ "There is no user interface, only an API or service. Use Backend/API.",
14
+ "A single-page framework is in use. Technology alone never activates a profile."
15
+ ],
16
+ "requires": [],
17
+ "incompatible_with": [],
18
+ "documents": [
19
+ { "path": "docs/architecture/system-design/01-system-overview.md", "required": true },
20
+ { "path": "docs/architecture/system-design/02-domain-and-state-model.md", "required": true },
21
+ { "path": "docs/architecture/system-design/03-behaviour-and-business-rules.md", "required": true },
22
+ { "path": "docs/architecture/system-design/04-architecture-and-interfaces.md", "required": true },
23
+ { "path": "docs/architecture/system-design/07-ui-and-interaction-mapping.md", "required": true },
24
+ { "path": "docs/design/DESIGN.md", "required": true },
25
+ { "path": "docs/engineering/SECURITY.md", "required": true },
26
+ { "path": "docs/engineering/TEST_STRATEGY.md", "required": true },
27
+ {
28
+ "path": "docs/architecture/system-design/05-execution-and-resilience.md",
29
+ "required": false,
30
+ "when": "The app works offline, syncs data, or runs background work on the device."
31
+ },
32
+ {
33
+ "path": "docs/architecture/system-design/06-operations-and-scalability.md",
34
+ "required": false,
35
+ "when": "The app team deploys and runs its own services, and no Backend/API profile covers them."
36
+ },
37
+ {
38
+ "path": "docs/application/RELEASES.md",
39
+ "required": false,
40
+ "when": "The app ships as an installed client (app store, desktop installer), so older versions stay in use after a release."
41
+ }
42
+ ],
43
+ "checks": [
44
+ { "name": "End-to-end", "what": "The critical user journeys from the PRD run end to end against a working build." },
45
+ { "name": "Accessibility", "what": "Automated accessibility checks on the main screens, against the standard named in DESIGN.md §6.7." }
46
+ ]
47
+ }