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,41 @@
1
+ # Web Profile
2
+
3
+ For websites whose main job is to publish content: landing pages, marketing and corporate sites, documentation and content sites. When it applies, which documents it adds and which checks it needs are declared in [profile.json](profile.json).
4
+
5
+ ## Where each concern lives
6
+
7
+ | Concern | Lives in |
8
+ |---|---|
9
+ | Site map, page types, content model, publishing and ownership | `docs/web/CONTENT.md` |
10
+ | Search, sharing previews, redirects, analytics consent | `docs/web/SEO.md` |
11
+ | Visual identity, tokens, components | `docs/design/DESIGN.md` §3–5 |
12
+ | Page structure and screen names | `docs/design/DESIGN.md` §7, using the page types from `CONTENT.md` |
13
+ | Accessibility standard | `docs/design/DESIGN.md` §6.7 |
14
+ | Accessibility and performance targets (measurable) | `SYS-NFR` rows in `docs/product/SPEC.md` §5 |
15
+ | Hosting, CMS and build pipeline | `docs/architecture/SYSTEM_DESIGN.md` (or `04-architecture-and-interfaces.md` if the site integrates with several services) |
16
+
17
+ There is no separate performance or accessibility document on purpose: measurable targets are requirements, and requirements live in `SPEC.md`.
18
+
19
+ ## Engineering standards
20
+
21
+ Defaults for the public pages. A project can override any of them with a requirement in `SPEC.md` or an accepted ADR.
22
+
23
+ - Pages are readable and navigable before scripts load. Scripts add to the page; they don't build it.
24
+ - Meet the accessibility standard named in `DESIGN.md` §6.7 — WCAG 2.2 level AA (the common web accessibility standard) unless the project says otherwise.
25
+ - Set a performance budget per page type (page weight, loading-speed metrics) in `SPEC.md`, and measure it on a realistic device and connection.
26
+ - Every moved or removed page gets a redirect. Never break a URL that has been public.
27
+ - Images have text alternatives, explicit sizes, and formats suited to the screen.
28
+ - No tracking runs before the visitor consents where the law requires consent.
29
+ - Content changes do not need a code change, unless the project has decided they should (record that in `CONTENT.md`).
30
+
31
+ ## Agent instructions
32
+
33
+ - Before changing a page, find its page type in `CONTENT.md` and its metadata rules in `SEO.md`.
34
+ - When you add, move or remove a page: update the site map in `CONTENT.md`, add a redirect to `SEO.md` if the URL changes, and keep the page names in `DESIGN.md` §7.5 the same.
35
+ - When you change a page type's layout, run the accessibility and performance checks for that page type.
36
+ - Do not add a second copy of a fact that already lives in `CONTENT.md`, `SEO.md` or `DESIGN.md` — link to it.
37
+
38
+ ## Composing with other profiles
39
+
40
+ - **With Application:** Web covers the public pages; Application covers the signed-in product. Say in `CONTENT.md` where the boundary is (for example, "everything under `/app` is the application").
41
+ - **With AI Systems:** only when the site has an AI feature that runs for visitors, such as a chat assistant. Using AI to write the content does not count.
@@ -0,0 +1,34 @@
1
+ {
2
+ "schema": 1,
3
+ "id": "web",
4
+ "name": "Web",
5
+ "purpose": "Websites whose main job is to publish content: landing pages, marketing and corporate sites, documentation and content sites. Adds content architecture, search and sharing, and the accessibility and performance checks public pages need.",
6
+ "use_when": [
7
+ "The main thing people do is read, browse or find content, then leave or convert (contact, sign up, buy elsewhere).",
8
+ "Most pages are the same for every visitor, or vary only by language or simple personalisation.",
9
+ "Being found through search engines and shared links matters."
10
+ ],
11
+ "not_when": [
12
+ "People sign in to create, change or manage their own data. Use Application for that part.",
13
+ "The site only exists as the front door of an app, with a page or two of marketing. Record those pages in DESIGN.md instead.",
14
+ "A framework or CMS is in use. Technology alone never activates a profile."
15
+ ],
16
+ "requires": [],
17
+ "incompatible_with": [],
18
+ "documents": [
19
+ { "path": "docs/web/CONTENT.md", "required": true },
20
+ { "path": "docs/web/SEO.md", "required": true },
21
+ { "path": "docs/design/DESIGN.md", "required": true },
22
+ { "path": "docs/engineering/TEST_STRATEGY.md", "required": true },
23
+ {
24
+ "path": "docs/architecture/system-design/04-architecture-and-interfaces.md",
25
+ "required": false,
26
+ "when": "The site connects to a CMS, form handler, search service or other systems worth describing beyond SYSTEM_DESIGN.md."
27
+ }
28
+ ],
29
+ "checks": [
30
+ { "name": "Accessibility", "what": "Automated accessibility checks on every page type, against the standard named in DESIGN.md §6.7." },
31
+ { "name": "Performance budget", "what": "Page weight and loading-speed budgets, measured on the key page types against the targets in SPEC.md." },
32
+ { "name": "Links and metadata", "what": "No broken links, and every page has the title, description and sharing metadata SEO.md requires." }
33
+ ]
34
+ }
@@ -0,0 +1,39 @@
1
+ # Content Architecture
2
+
3
+ > Web profile. How the site's content is organised, modelled, owned and kept current. How it looks lives in `docs/design/DESIGN.md`; how people find it lives in `docs/web/SEO.md`.
4
+
5
+ ## Audiences and goals
6
+ Who visits, what each audience came to do, and the action we want them to take next. Name the PRD capability (`CAP-NNN`) each goal serves.
7
+
8
+ | Audience | What they came for | Next action we want | Capability |
9
+ |---|---|---|---|
10
+ | | | | |
11
+
12
+ ## Site map
13
+ The pages and sections, and how they nest. A tree or a table is enough.
14
+
15
+ | Page or section | Audience | Purpose | Main call to action |
16
+ |---|---|---|---|
17
+ | | | | |
18
+
19
+ ## Page types
20
+ The reusable page layouts (home, article, landing page and so on) and the content blocks each one holds. `docs/design/DESIGN.md` §7.5 uses the same names.
21
+
22
+ | Page type | Content blocks | Used by |
23
+ |---|---|---|
24
+ | | | |
25
+
26
+ ## Content model
27
+ The structured content types (article, author, product, question and answer...), their fields, which fields are required, and how the types relate. Describe the content, not a CMS (content management system) schema.
28
+
29
+ ## Sources and publishing
30
+ Where content is written and stored (files in the repository, a CMS, a spreadsheet), who may publish, and how a change reaches the live site: preview, review, approval.
31
+
32
+ ## Ownership and lifecycle
33
+ Who owns each section, how often it is reviewed, and what happens to outdated pages: update, redirect (record it in `docs/web/SEO.md`) or remove.
34
+
35
+ ## Languages and regions
36
+ Only if the site is translated or regional: which languages, what varies by region, and who translates.
37
+
38
+ ## Forms and conversions
39
+ Every form or conversion point: what it collects, where the data goes, and what the visitor sees afterwards. If forms collect personal data, record how it is protected in `docs/engineering/SECURITY.md`.
@@ -0,0 +1,35 @@
1
+ # Search and Sharing (SEO)
2
+
3
+ > Web profile. How people find the site through search engines and shared links. SEO means search engine optimisation. The pages themselves are listed in `docs/web/CONTENT.md`.
4
+
5
+ ## Goals
6
+ The searches and audiences that matter most, and which pages should answer them.
7
+
8
+ ## URL structure
9
+ The patterns for page addresses, and the rules for changing them (case, trailing slashes, language prefixes).
10
+
11
+ ## Redirects
12
+ Every moved or removed page gets a redirect, so links and search rankings survive.
13
+
14
+ | Old URL | New URL | Reason | Date |
15
+ |---|---|---|---|
16
+ | | | | |
17
+
18
+ ## Page metadata
19
+ For each page type: the title pattern, where the description comes from, the canonical URL (the one official address of a page), and whether search engines may index it.
20
+
21
+ | Page type | Title pattern | Description source | Indexed? |
22
+ |---|---|---|---|
23
+ | | | | |
24
+
25
+ ## Structured data
26
+ Machine-readable descriptions of page content that search engines use for richer results. Add them only where they earn their place, and name the types used.
27
+
28
+ ## Sharing previews
29
+ The image, title and text shown when a page is shared in social or messaging apps.
30
+
31
+ ## Crawling
32
+ The sitemap, the robots rules, and the pages kept out of search (drafts, thank-you pages, internal search results).
33
+
34
+ ## Measurement
35
+ How search traffic and conversions are measured, and how visitor consent for analytics and tracking is collected and respected.
@@ -0,0 +1,77 @@
1
+ {
2
+ "name": "Groundwork",
3
+ "description": "A simple starting point for new software projects — no language, framework or hosting chosen for you. Profiles adapt its documents and checks to the kind of system you build.",
4
+ "version": "3.1.0",
5
+ "technology_agnostic": true,
6
+ "principle": "progressive documentation",
7
+ "file_count": 60,
8
+ "files": [
9
+ ".github/README.md",
10
+ ".github/pull_request_template.md",
11
+ ".github/workflows/docs-check.yml",
12
+ ".gitignore",
13
+ "AGENTS.md",
14
+ "BUILD.md",
15
+ "LICENSE.md",
16
+ "PROJECT.md",
17
+ "README.md",
18
+ "config/README.md",
19
+ "docs/README.md",
20
+ "docs/architecture/REPOSITORY_STRUCTURE.md",
21
+ "docs/architecture/SYSTEM_DESIGN.md",
22
+ "docs/architecture/adr/0000-template.md",
23
+ "docs/architecture/adr/README.md",
24
+ "docs/architecture/system-design/README.md",
25
+ "docs/engineering/SECURITY.md",
26
+ "docs/engineering/TEST_STRATEGY.md",
27
+ "docs/examples/EXAMPLE.md",
28
+ "docs/examples/PROFILES.md",
29
+ "docs/plans/README.md",
30
+ "docs/plans/_template/PLAN.md",
31
+ "docs/product/PRD.md",
32
+ "docs/product/SPEC.md",
33
+ "docs/product/specs/README.md",
34
+ "docs/product/specs/_template/SPEC.md",
35
+ "infrastructure/README.md",
36
+ "profiles/README.md",
37
+ "profiles/ai-systems/README.md",
38
+ "profiles/ai-systems/profile.json",
39
+ "profiles/ai-systems/templates/docs/ai-systems/EVALUATION.md",
40
+ "profiles/ai-systems/templates/docs/ai-systems/MODEL_INTEGRATION.md",
41
+ "profiles/ai-systems/templates/docs/ai-systems/RETRIEVAL.md",
42
+ "profiles/ai-systems/templates/docs/ai-systems/SAFETY.md",
43
+ "profiles/application/README.md",
44
+ "profiles/application/profile.json",
45
+ "profiles/application/templates/docs/application/RELEASES.md",
46
+ "profiles/backend-api/README.md",
47
+ "profiles/backend-api/profile.json",
48
+ "profiles/backend-api/templates/docs/backend-api/DATA.md",
49
+ "profiles/core/profile.json",
50
+ "profiles/core/templates/docs/architecture/contracts/README.md",
51
+ "profiles/core/templates/docs/architecture/system-design/01-system-overview.md",
52
+ "profiles/core/templates/docs/architecture/system-design/02-domain-and-state-model.md",
53
+ "profiles/core/templates/docs/architecture/system-design/03-behaviour-and-business-rules.md",
54
+ "profiles/core/templates/docs/architecture/system-design/04-architecture-and-interfaces.md",
55
+ "profiles/core/templates/docs/architecture/system-design/05-execution-and-resilience.md",
56
+ "profiles/core/templates/docs/architecture/system-design/06-operations-and-scalability.md",
57
+ "profiles/core/templates/docs/architecture/system-design/07-ui-and-interaction-mapping.md",
58
+ "profiles/core/templates/docs/design/DESIGN.md",
59
+ "profiles/web/README.md",
60
+ "profiles/web/profile.json",
61
+ "profiles/web/templates/docs/web/CONTENT.md",
62
+ "profiles/web/templates/docs/web/SEO.md",
63
+ "scaffold-manifest.json",
64
+ "scripts/README.md",
65
+ "scripts/check_docs.py",
66
+ "scripts/groundwork.py",
67
+ "src/README.md",
68
+ "tests/README.md"
69
+ ],
70
+ "notes": [
71
+ "Groundwork Core is always active. Profiles in profiles/ add documents, standards and checks; choose them with scripts/groundwork.py init.",
72
+ "SYSTEM_DESIGN.md is the architecture starting point. The seven system design parts and DESIGN.md are core documents that profiles switch on; their templates are in profiles/core/templates/.",
73
+ "Every document has one owner: core, or the one profile with a template for it.",
74
+ "Repository layout is a choice, not a fixed monorepo or multi-repo rule.",
75
+ "Delete optional folders and documents you don't use, and remove them from this list."
76
+ ]
77
+ }
@@ -0,0 +1,29 @@
1
+ # Scripts
2
+
3
+ Repeatable development, maintenance, migration and release scripts live here. Document any destructive operations and required environment variables.
4
+
5
+ Both Groundwork scripts use the Python 3 standard library only.
6
+
7
+ - `groundwork.py`: sets up and grows the project's documents from its profiles (see `profiles/README.md`). It never overwrites or deletes a file, and `--dry-run` shows what would change.
8
+
9
+ - `list`: shows every profile — its purpose, when to use it and when not to, its documents and its checks.
10
+ - `init <profile> [<profile> ...]` (or `init none`): 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`. Run it again with a new list to add or drop a profile.
11
+ - `add <path>`: creates one optional document from its template, such as `docs/ai-systems/RETRIEVAL.md`.
12
+ - `new <folder> [--name ...] [--description ...] [--profiles ...]`: creates a new project from this copy of Groundwork. It copies the files listed in `scaffold-manifest.json`, fills in the name, description and date in `PROJECT.md`, writes `.groundwork/config.json`, and runs `init` there. It builds everything in a temporary folder and moves it into place only if every step worked.
13
+ - `config`: shows the project name and profiles (from `PROJECT.md`), the Groundwork version, and which files Groundwork generated that the project has since changed or deleted (from `.groundwork/config.json`).
14
+
15
+ Add `--json` to any command for machine-readable output. The `groundwork` command-line tool (npm package `create-groundwork`) runs these same scripts, so the two ways of working always agree. Profiles are always recorded in sorted order, so the order you give them in doesn't matter.
16
+
17
+ `.groundwork/config.json` records which Groundwork version generated the project, and a SHA-256 checksum of every file Groundwork generated. A recorded file whose checksum still matches is managed by Groundwork; one that differs has been changed by the project; an unrecorded file belongs to the project. Future upgrades use this to avoid overwriting your edits. Don't edit the config by hand. Active profiles are recorded only in `PROJECT.md`.
18
+
19
+ - `check_docs.py`: read-only consistency check. Validates `scaffold-manifest.json` against the repository, keeps the Feature Specification Index in `docs/product/SPEC.md` in sync with `docs/product/specs/`, checks requirement and capability ID grammar, uniqueness and traceability (including IDs referenced in `tests/` and `src/`), verifies internal markdown links, and validates profiles: manifests, single ownership of each document, the profiles chosen in `PROJECT.md`, their dependencies and conflicts, and their required documents. It ignores `docs/examples/` and the templates under `profiles/<id>/templates/`. Run it after adding, renaming or removing documents, feature specs, requirement IDs, links or profiles.
20
+
21
+ Errors always exit 1. Warnings come in two groups: hygiene (invalid status values, unserved capabilities, documents from inactive profiles, profile checks missing from the tooling table) and coverage (a requirement nothing references). Each group fails only under its flag:
22
+
23
+ - Default: only errors fail.
24
+ - `--strict`: hygiene warnings fail too.
25
+ - `--strict-coverage`: coverage warnings fail too.
26
+
27
+ `--strict-coverage` does not include `--strict`. Use both flags together to fail on everything.
28
+
29
+ The manifest rule: files you add under `src/`, `tests/`, `config/`, `infrastructure/` or `scripts/` don't need to be listed, but template files must stay listed and a deleted template file must also be removed from `scaffold-manifest.json`. Projects without a `profiles/` folder (such as projects started on Groundwork 2.x) get exactly the checks they had before.