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
package/CHANGELOG.md ADDED
@@ -0,0 +1,87 @@
1
+ # Changelog
2
+
3
+ Notable changes to the Groundwork template itself, not to your project. The format follows Keep a Changelog, and versions follow SemVer (major.minor.patch).
4
+
5
+ ## [Unreleased]
6
+
7
+ ## [3.1.0] - 2026-11-17
8
+
9
+ Groundwork is now an installable command-line tool: `npx create-groundwork`. Nothing changes in the profile model, the documents or the validation rules.
10
+
11
+ ### Added
12
+ - The npm package `create-groundwork`, with two executables. `create-groundwork` creates a project, with a guided setup or entirely from options. `groundwork` runs `create`, `profiles`, `init`, `add`, `validate` and `config`.
13
+ - Guided profile selection. Its questions come from each profile's `use_when` and `not_when` lists; it never guesses from technology. A review step shows the dependencies, the documents to create, the checks and the optional documents before anything is written.
14
+ - `scripts/groundwork.py new`: creates a project from a copy of Groundwork. It builds in a staging folder and moves it into place only when every step succeeded. The CLI uses it, and it works without Node.
15
+ - `scripts/groundwork.py config`, and `--json` output for every `groundwork.py` command.
16
+ - `.groundwork/config.json` in new projects: the Groundwork version, the generation date, and a SHA-256 checksum of each generated file, so a future update can tell framework files from customised ones. `init` and `add` keep it current. Active profiles stay only in `PROJECT.md`.
17
+ - Placeholders in `PROJECT.md` (`{{PROJECT_NAME}}`, `{{PROJECT_DESCRIPTION}}`, `{{PROJECT_DATE}}`), filled in by `new`, and a Description line.
18
+ - Tests for profile resolution, generation, file safety, the CLI and the wizard, validation parity with `check_docs.py` in every mode, and the packed npm artifact.
19
+ - Groundwork itself is released under the MIT Licence (`LICENSE`).
20
+ - CI (`.github/workflows/ci.yml`) and a tag-triggered npm release workflow (`.github/workflows/release.yml`).
21
+
22
+ ### Changed
23
+ - The repository is now the package. The Groundwork template lives in `template/`; this changelog and `MIGRATION.md` moved out of it, because they describe Groundwork rather than your project.
24
+ - `init` records and applies profiles in sorted order, so the order you give them in never changes the result. Before, `init web application` and `init application web` wrote `PROJECT.md` and `AGENTS.md` differently.
25
+ - The scripts run on Python 3.9+ (previously 3.10+, through type annotations).
26
+ - `check_docs.py` no longer requires `.groundwork/` to be listed in `scaffold-manifest.json`, and treats `scripts/groundwork.py` as a template file.
27
+
28
+ ## [3.0.0] - 2026-11-17
29
+
30
+ Groundwork now adapts to the kind of system being built. See `MIGRATION.md` for the decisions behind this release and how to upgrade.
31
+
32
+ ### Added
33
+ - Profiles: `profiles/` with four initial profiles — Web, Application, Backend/API and AI Systems. Each is a `profile.json` manifest (purpose, when to use it, dependencies, documents, checks), a README (where each concern lives, engineering standards, agent instructions) and templates for the documents it owns. Profiles combine; the composition rules are in `profiles/README.md`.
34
+ - Profile documents: `docs/web/CONTENT.md` and `docs/web/SEO.md`; `docs/ai-systems/MODEL_INTEGRATION.md`, `EVALUATION.md`, `SAFETY.md` and the optional `RETRIEVAL.md`; the optional `docs/backend-api/DATA.md` and `docs/application/RELEASES.md`.
35
+ - `scripts/groundwork.py`: `list`, `init` and `add` commands that record the chosen profiles, create missing documents from templates, add profile checks to the `AGENTS.md` tooling table and keep `scaffold-manifest.json` up to date. It never overwrites or deletes a file.
36
+ - An initialization workflow in `profiles/README.md`: inspect, recommend, explain, confirm, generate, apply.
37
+ - `docs/examples/PROFILES.md`: worked profile combinations, including borderline cases.
38
+ - `PROJECT.md`: a Profiles section with the `- Profiles:` line the scripts read.
39
+ - `MIGRATION.md`: the migration summary and upgrade steps.
40
+
41
+ ### Changed
42
+ - **Breaking for new projects:** the seven system-design parts, `docs/design/DESIGN.md` and `docs/architecture/contracts/README.md` are now core optional modules with templates in `profiles/core/templates/`. They are created at their usual paths when a profile needs them. Existing projects keep them where they are.
43
+ - `check_docs.py` validates profiles: manifest schema, single ownership of each document, the selection in `PROJECT.md`, dependencies, incompatibilities and required documents (errors), and documents from inactive profiles or profile checks missing from the tooling table (hygiene warnings). Templates under `profiles/<id>/templates/` are skipped by the ID and link checks. Without a `profiles/` folder, it behaves exactly as in 2.1.3.
44
+ - `SYSTEM_DESIGN.md` refers to `system-design/README.md` for the index of parts, instead of linking to parts that may not exist.
45
+ - `AGENTS.md`: read the active profiles' READMEs; profile standards are defaults that a project requirement or ADR overrides; conflicts between profiles are settled in an ADR; profile checks have rows in the tooling table.
46
+ - `README.md`, `docs/README.md`, `BUILD.md`, `scripts/README.md`, `.github/README.md`, the CI workflow comment and `docs/examples/EXAMPLE.md` describe profiles.
47
+
48
+ ## [2.1.3] - 2026-11-17
49
+
50
+ ### Changed
51
+ - The `check_docs.py` description in `docs/README.md` and `scripts/README.md` is now a short list of the three modes instead of one long paragraph. The same treatment was applied to the modes paragraph in `.github/README.md`.
52
+
53
+ ## [2.1.2] - 2026-11-16
54
+
55
+ ### Fixed
56
+ - Capability ID spelling is now checked in code files too. A `CAP-` token with the wrong number of digits (such as `CAP-9999` or `CAP-12`) in a file under `tests/` or `src/` is now an error.
57
+ - Several error messages were hard to read at first glance. They now start with the file path, keep to one short sentence, and say what to do where it is not obvious.
58
+
59
+ ### Changed
60
+ - `--strict-coverage` does not include `--strict`. The CI workflow comment and the docs now say to use both flags together to fail on everything.
61
+
62
+ ## [2.1.1] - 2026-11-16
63
+
64
+ ### Fixed
65
+ - The manifest check no longer fails when you add your own files under `src/`, `tests/`, `config/`, `infrastructure/` or `scripts/`. Template files must still stay listed: if you delete one you don't need, remove it from `scaffold-manifest.json` too.
66
+ - `.gitignore`: example environment files (`.env.example`, `.env.sample`) can be committed.
67
+
68
+ ### Changed
69
+ - `check_docs.py` warnings are split into two groups. Hygiene warnings (invalid status values, unserved capabilities) fail under `--strict`; coverage warnings (a requirement no design doc, plan or test references) print always and fail only under the new `--strict-coverage`. ADR status values are now checked too, and `CAP-NNN` IDs in `tests/` and `src/` are validated against the PRD.
70
+ - CI workflow: adds `permissions: contents: read`.
71
+
72
+ ## [2.1.0] - 2026-11-16
73
+
74
+ ### Added
75
+ - Capability IDs: PRD capabilities get `CAP-NNN` IDs, and requirements name the capability they serve in a **Serves** column.
76
+ - `docs/examples/EXAMPLE.md`: a short worked example of the traceability chain.
77
+ - `docs/plans/`: a home for implementation plans, with a template.
78
+ - Repository basics: `.gitignore`, `LICENSE.md` note, this changelog, a GitHub pull request template and a docs-check CI workflow.
79
+
80
+ ### Changed
81
+ - `check_docs.py`: added `--strict`, warnings for unreferenced requirements, unserved capabilities and invalid status values; ID checks now cover `tests/` and `src/`; example text is skipped only inside inline code on illustrative lines.
82
+ - `AGENTS.md`: plan fields moved to `docs/plans/`, plain-language rules moved to "Project style (change freely)".
83
+ - `DESIGN.md`: skip notice and a "start here" checklist added.
84
+
85
+ ## [2.0.0]
86
+
87
+ First versioned release of the template.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mich Nduka
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/MIGRATION.md ADDED
@@ -0,0 +1,63 @@
1
+ # Migration to Groundwork 3.0: Profiles
2
+
3
+ This file explains how Groundwork 2.1.3 became a profile-based scaffold, the decisions behind it, and how to upgrade an existing project. It is about the template, not your project — delete it once you have upgraded.
4
+
5
+ ## What changed, in one paragraph
6
+
7
+ Groundwork 2.1.3 gave every project the same full document set and told people to delete what they didn't need. 3.0 starts every project with a small core and lets it choose **profiles** — Web, Application, Backend/API and AI Systems — that add the documents, standards and checks its kind of system needs. Profiles combine, can be added later without moving anything, and are described by JSON manifests, so a new profile needs no code change.
8
+
9
+ ## How 2.1.3 was mapped
10
+
11
+ | 2.1.3 item | 3.0 home | Why |
12
+ |---|---|---|
13
+ | `PROJECT.md`, `AGENTS.md`, `BUILD.md`, `PRD.md`, `SPEC.md`, feature specs, `SYSTEM_DESIGN.md`, ADRs, plans | Core, in place, unchanged in role | Every kind of project needs governance, requirements and traceability |
14
+ | `SECURITY.md`, `TEST_STRATEGY.md`, `REPOSITORY_STRUCTURE.md` | Core, in place, optional | Short and widely useful; profiles that depend on them require them |
15
+ | The seven system-design parts, `DESIGN.md`, `contracts/README.md` | Core optional modules, with templates in `profiles/core/templates/` and the **same paths** in projects | Several profiles need each of them; one owner means one copy |
16
+ | `check_docs.py` | Same file, plus profile checks | Existing checks are untouched |
17
+ | — | `profiles/` (four profiles), `scripts/groundwork.py`, `docs/examples/PROFILES.md` | New |
18
+
19
+ ## Decisions
20
+
21
+ 1. **Profiles select from core rather than copying it.** The seven-part design already splits architecture into good views. Application, Backend/API and AI Systems each need different subsets of the same views, so profiles *require* core parts instead of owning their own versions. As a result, the Application profile owns almost no documents — that's intended, not a gap.
22
+ 2. **One owner per document.** Core owns the documents it lists; any other profile owns exactly the documents it has templates for. A document that two profiles need moves into core. This rule prevents duplicates by construction, and the checker enforces it. There is no merge or override logic for documents, because nothing can be defined twice.
23
+ 3. **Composition is a union, with no precedence order.** The documents a project needs are the union of what core and each active profile require. Because profiles only ever add, profile order never matters. Real incompatibilities are declared (`incompatible_with`) and blocked. Disagreements between standards are resolved explicitly in an ADR, never by a hidden ranking.
24
+ 4. **Profiles add only what the core has no home for.** Web adds content architecture and SEO. Measurable performance and accessibility targets are requirements, so they go in `SPEC.md`, not in a new document. AI Systems adds model integration, evaluation and safety, which no core document covers. Backend/API and Application each add one optional document for a real gap (data architecture; installed-client releases).
25
+ 5. **Optional documents have a condition.** Each optional document states `when` it becomes worth writing, and it is created only then (`groundwork.py add`). That keeps documentation progressive.
26
+ 6. **Validation requirements are named concerns, not tools.** A profile declares checks such as "Accessibility" or "AI evaluation". `init` adds them as rows to the existing tooling table in `AGENTS.md`, and the project fills in the tool. Groundwork stays technology-neutral, and the table stays the single list of checks.
27
+ 7. **Selection is a judgement, recorded in `PROJECT.md`.** Nothing detects profiles from the code: technology doesn't decide responsibility. The scripts do the mechanical work; a person or agent picks the profiles using the "use when" and "not when" lists, and writes down why.
28
+ 8. **AI Systems requires another profile.** AI is a capability of a product, so it is always paired with the profile that describes that product. It is the one dependency among the initial profiles, and it shows how the dependency mechanism works.
29
+ 9. **The scripts never overwrite or delete.** `init` and `add` only create missing files and append. Dropping a profile leaves its documents in place, with a warning. This makes every run safe to repeat.
30
+ 10. **JSON, standard library only.** The manifests are JSON so the scripts stay dependency-free, matching `check_docs.py`. `groundwork.py` imports its rules from `check_docs.py`, so the two scripts can't disagree.
31
+ 11. **`SYSTEM_DESIGN.md` no longer links to all seven parts.** A project may not have them all, and broken links fail the check. The index of parts now lives in `system-design/README.md`.
32
+
33
+ ## Compatibility
34
+
35
+ - **No document moved** within a project. Every 2.1.3 path is still valid, and a 2.1.3 project's design documents count toward its profiles' requirements as they are.
36
+ - **Without a `profiles/` folder, `check_docs.py` behaves exactly as in 2.1.3.** Same checks, same messages.
37
+ - **New projects start smaller.** A fresh clone no longer contains the seven system-design parts, `DESIGN.md` or `contracts/README.md` in `docs/`. `init` creates the ones your profiles need. This is the breaking change, hence version 3.0.0.
38
+ - **New checks apply only once you opt in.** Required core documents are checked once `profiles/` exists. Profile requirements are checked once `PROJECT.md` names profiles.
39
+
40
+ ## Upgrading a 2.1.x project
41
+
42
+ 1. Copy `profiles/`, `scripts/groundwork.py` and the new `scripts/check_docs.py` into your project.
43
+ 2. Run `python3 scripts/check_docs.py`. It lists each new file as "on disk but not in the manifest". Add those files to `scaffold-manifest.json` (keep the list sorted and update `file_count`).
44
+ 3. Choose profiles as described in `profiles/README.md`, then run `python3 scripts/groundwork.py init <profiles>`. It adds the Profiles section to `PROJECT.md`, keeps every document you already have, creates only what's missing, and adds the profile checks to your tooling table.
45
+ 4. Optionally copy the new wording in `README.md`, `AGENTS.md` (the read order and the conflict rule), `docs/README.md` and `docs/architecture/SYSTEM_DESIGN.md`.
46
+ 5. Run `python3 scripts/check_docs.py --strict`. Fill in the new tooling rows, and delete any design documents your profiles don't need.
47
+
48
+ ## Groundwork 3.1: the command-line tool
49
+
50
+ 3.1 packages Groundwork as `npx create-groundwork` and adds the `groundwork` command. The profile model, the documents and the checks are the same as in 3.0.
51
+
52
+ **Your 3.0 projects work with the CLI as they are.** `groundwork init`, `add`, `config` and `validate` run the project's own copies of `scripts/groundwork.py` and `scripts/check_docs.py`. A 2.x project (no `groundwork.py`) can still be validated.
53
+
54
+ To get the 3.1 additions in a 3.0 project, copy `scripts/groundwork.py` and `scripts/check_docs.py` from the package's `template/scripts/`. A 3.0 project has no `.groundwork/config.json`, and nothing creates one for it: Groundwork can't know which of its files you have changed since they were generated, so it records nothing rather than guess.
55
+
56
+ ### Decisions
57
+
58
+ 1. **Python stays the single engine.** All profile resolution, generation and validation stay in the two standard-library Python scripts that ship inside every project. The TypeScript CLI handles prompts, command parsing and output, and calls those scripts. A TypeScript port would have meant either two implementations of the same rules, or generated projects that need Node to check their documents, which would break Groundwork's technology neutrality. The cost is that the CLI needs Python 3.9+; it finds Python, checks the version, and explains how to install it when it's missing.
59
+ 2. **One npm package.** The CLI and the template ship and version together, so a separate template package would add release work without any benefit. `package.json` and the template's `scaffold-manifest.json` carry the same version, and a test checks they match.
60
+ 3. **`new` lives in the engine.** Creating a project means copying exactly the files in `scaffold-manifest.json` and running the existing `init`, so the CLI and `python3 scripts/groundwork.py new` produce identical projects.
61
+ 4. **Active profiles stay in `PROJECT.md` only.** `.groundwork/config.json` records what only a tool needs: the version, the generation date, and the checksums of generated files. Keeping the profiles in two places would let them drift apart. The project name stays in `PROJECT.md` for the same reason.
62
+ 5. **No `update` command yet.** The checksums are what a future `update` needs to leave customised files alone. A merge engine would come too early.
63
+ 6. **`.gitignore` ships as `_gitignore`.** npm never packs files named `.gitignore`, so packing adds a temporary `_gitignore` copy, and `new` restores the real name.
package/README.md CHANGED
@@ -1,3 +1,82 @@
1
- # Temporary Holding Version
1
+ # Groundwork
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Start a software project with the minimum sufficient engineering documentation — project definition, requirements with traceable IDs, architecture, decisions and checks — adapted to what you're building through composable **profiles**.
4
+
5
+ ```bash
6
+ npx create-groundwork
7
+ ```
8
+
9
+ A short guided setup asks for the project name, a one-line description, the folder, and which profiles fit. Then it generates the project and checks it.
10
+
11
+ ## Requirements
12
+
13
+ - Node.js 22 or newer, to run the CLI.
14
+ - Python 3.9 or newer. Groundwork's checks are plain Python scripts that ship inside every project, so any project — in any language — can be checked in CI without Node. If Python isn't on your `PATH` as `python3` or `python`, set `GROUNDWORK_PYTHON` to its path.
15
+
16
+ ## Profiles
17
+
18
+ Groundwork Core is always included. Profiles add the documents, standards and checks a kind of system needs:
19
+
20
+ | Profile | For |
21
+ |---|---|
22
+ | `web` | Landing pages, marketing, corporate and content sites |
23
+ | `application` | Interactive web, mobile and desktop apps |
24
+ | `backend-api` | Services, APIs, workers and integrations |
25
+ | `ai-systems` | LLM features, retrieval, agents and model-driven workflows (always alongside one of the others) |
26
+
27
+ Choose them by what the system must do, not by the technology it uses. Profiles combine freely, and you can add one later without moving anything. Run `groundwork profiles` for the selection guidance.
28
+
29
+ ## Commands
30
+
31
+ ```text
32
+ npx create-groundwork [folder] Create a project (guided)
33
+ groundwork create [folder] Same, once installed (npm install -g create-groundwork)
34
+ groundwork profiles [id] List profiles, or show one in detail
35
+ groundwork init <id...> | none Choose this project's profiles and create their documents
36
+ groundwork add <path> Create an optional document when you need it
37
+ groundwork validate [--strict] [--strict-coverage]
38
+ Check the documentation
39
+ groundwork config Show the project's Groundwork configuration
40
+ ```
41
+
42
+ Non-interactive creation, for scripts and AI agents:
43
+
44
+ ```bash
45
+ npx create-groundwork parkmate --profiles application,backend-api --description "Parking management platform" --yes
46
+ npx create-groundwork tool --profiles none --yes # Groundwork Core only
47
+ npx create-groundwork site --profiles web --dry-run # show the plan, write nothing
48
+ ```
49
+
50
+ `init`, `add` and `--dry-run` work inside any Groundwork project, including ones created before the CLI existed. Every command has `--help`.
51
+
52
+ ## Safety
53
+
54
+ - Groundwork never overwrites or deletes a file. A new project needs a new or empty folder. `init` and `add` only create what's missing.
55
+ - A new project is built in a temporary folder and moved into place only when every step has succeeded.
56
+ - `.groundwork/config.json` records the checksum of every file Groundwork generated, so a future update can tell its own files from the ones you've edited.
57
+
58
+ ## How it fits together
59
+
60
+ ```text
61
+ create-groundwork (npm package)
62
+ ├── dist/ the CLI: prompts, commands, output
63
+ └── template/ Groundwork itself — what every project gets
64
+ ├── profiles/ core and the four profiles: manifests, READMEs, document templates
65
+ └── scripts/ groundwork.py (profiles and generation) and check_docs.py (validation)
66
+ ```
67
+
68
+ The CLI holds no profile rules of its own. It runs the Python scripts — the bundled ones to create a project, and the project's own copies after that — so `groundwork validate` and `python3 scripts/check_docs.py` always give the same result. Profile manifests in `profiles/*/profile.json` are the single source of truth. `template/README.md` and `template/profiles/README.md` explain the documentation model.
69
+
70
+ ## Development
71
+
72
+ ```bash
73
+ bun install
74
+ bun run test # builds, then runs every test (the pack test needs network access)
75
+ npm pack # builds the package exactly as it would be published
76
+ ```
77
+
78
+ Tests create projects in temporary folders and drive the real commands. `test/pack.test.ts` installs the packed tarball and runs it from there. See `CHANGELOG.md` for releases and `MIGRATION.md` for upgrading projects.
79
+
80
+ ## Licence
81
+
82
+ Groundwork is released under the [MIT Licence](LICENSE). Projects you create with it are yours: `LICENSE.md` in a new project is a placeholder for the licence you choose for your own work.
@@ -0,0 +1,294 @@
1
+ // Command parsing and dispatch for both executables.
2
+ // create-groundwork [dir] [options] → create
3
+ // groundwork <command> [options] → create | profiles | init | add | validate | config
4
+ import { parseArgs } from "node:util";
5
+ import { findProject, GroundworkError, runEngine, runScript, TEMPLATE_ROOT, VERSION, } from "./engine.js";
6
+ import { formatProfile, formatProfileList } from "./profiles.js";
7
+ import { Cancelled, clackPrompter } from "./prompter.js";
8
+ import { create } from "./scaffold.js";
9
+ import { red } from "./text.js";
10
+ const CREATE_HELP = `Create a new Groundwork project.
11
+
12
+ Usage:
13
+ npx create-groundwork [folder] [options]
14
+ groundwork create [folder] [options]
15
+
16
+ Without options, a short guided setup asks for the name, description,
17
+ folder and profiles. Give everything as options to skip the questions.
18
+
19
+ Options:
20
+ --name <name> Project name (default: the folder name)
21
+ --description <text> One-line description
22
+ --profiles <ids> Comma-separated profile IDs, or "none" for core only
23
+ (see: groundwork profiles)
24
+ -y, --yes Don't ask anything; requires a folder and --profiles
25
+ --dry-run Show what would be created, write nothing
26
+ -h, --help Show this help
27
+ -v, --version Show the version
28
+
29
+ Examples:
30
+ npx create-groundwork
31
+ npx create-groundwork parkmate
32
+ npx create-groundwork parkmate --profiles application,backend-api --yes
33
+
34
+ Groundwork never overwrites files: the folder must be new or empty.
35
+ Requires Python 3.9+ (the checks ship inside every project as Python scripts).`;
36
+ const MAIN_HELP = `Groundwork ${VERSION} — minimum sufficient engineering documentation,
37
+ adapted to what you're building through composable profiles.
38
+
39
+ Usage: groundwork <command> [options]
40
+
41
+ Commands:
42
+ create [folder] Create a new project (same as npx create-groundwork)
43
+ profiles [id] List profiles, or show one in detail
44
+ init <id...> | none Choose this project's profiles and create their documents
45
+ add <path> Create an optional document from its template
46
+ validate Check the documentation (scripts/check_docs.py)
47
+ config Show this project's Groundwork configuration
48
+
49
+ Run "groundwork <command> --help" for details. Every command except create
50
+ and profiles works inside a Groundwork project (or any folder below one).`;
51
+ const HELP = {
52
+ profiles: `List Groundwork profiles, or show one in detail.
53
+
54
+ Usage:
55
+ groundwork profiles Purpose, selection guidance and dependencies of each
56
+ groundwork profiles <id> Everything about one profile: documents, checks, dependencies
57
+
58
+ Inside a project, the project's own profiles/ folder is used; elsewhere, the
59
+ profiles bundled with this version of Groundwork.
60
+
61
+ Options:
62
+ --json Print the manifests as JSON
63
+ -h, --help Show this help`,
64
+ init: `Choose this project's profiles and create the documents they require.
65
+
66
+ Usage:
67
+ groundwork init <id> [<id> ...] [--dry-run]
68
+ groundwork init none Groundwork Core only
69
+
70
+ Records the profiles in PROJECT.md, creates each missing required document
71
+ from its template, adds the profiles' checks to the AGENTS.md tooling table,
72
+ and lists new files in scaffold-manifest.json. Never overwrites or deletes:
73
+ run it again with a new list to add or drop a profile. Profile order does
74
+ not matter. Same as: python3 scripts/groundwork.py init
75
+
76
+ Options:
77
+ --dry-run Show what would change, write nothing
78
+ --json Print the plan as JSON
79
+ -h, --help Show this help`,
80
+ add: `Create an optional document from its template, when its condition holds.
81
+
82
+ Usage:
83
+ groundwork add <path> [--dry-run]
84
+
85
+ Example:
86
+ groundwork add docs/ai-systems/RETRIEVAL.md
87
+
88
+ The document must belong to core or an active profile ("groundwork profiles
89
+ <id>" lists each profile's optional documents and their conditions).
90
+ Same as: python3 scripts/groundwork.py add
91
+
92
+ Options:
93
+ --dry-run Show what would change, write nothing
94
+ --json Print the result as JSON
95
+ -h, --help Show this help`,
96
+ validate: `Check the project's documentation.
97
+
98
+ Usage:
99
+ groundwork validate [--strict] [--strict-coverage]
100
+
101
+ Runs the project's own scripts/check_docs.py, so results and exit codes are
102
+ identical to running it directly (python3 scripts/check_docs.py).
103
+
104
+ Options:
105
+ --strict Hygiene warnings fail too
106
+ --strict-coverage Coverage warnings fail too (use both to fail on everything)
107
+ -h, --help Show this help`,
108
+ config: `Show this project's Groundwork configuration.
109
+
110
+ Usage:
111
+ groundwork config [--json]
112
+
113
+ Shows the project name and profiles (from PROJECT.md), the Groundwork version,
114
+ and which files Groundwork generated that have since changed or been deleted
115
+ (from .groundwork/config.json). Same as: python3 scripts/groundwork.py config`,
116
+ };
117
+ const HELP_OPTION = { help: { type: "boolean", short: "h" } };
118
+ function parse(args, options) {
119
+ try {
120
+ return parseArgs({ args, options: { ...HELP_OPTION, ...options }, allowPositionals: true });
121
+ }
122
+ catch (error) {
123
+ throw new GroundworkError(`${error.message}\nRun with --help for usage.`, 2);
124
+ }
125
+ }
126
+ function needProject(command, modifies) {
127
+ const project = findProject();
128
+ if (!project) {
129
+ throw new GroundworkError(`Not inside a Groundwork project (no scripts/check_docs.py with a Groundwork scaffold-manifest.json here or above).\n` +
130
+ "Create one with: npx create-groundwork");
131
+ }
132
+ if (command !== "validate" && !project.hasEngine) {
133
+ throw new GroundworkError(`${project.root} predates Groundwork 3.0 profiles (no scripts/groundwork.py).\n` +
134
+ "See MIGRATION.md in the create-groundwork package for how to upgrade it.");
135
+ }
136
+ if (modifies && project.isBundledTemplate) {
137
+ throw new GroundworkError("This is the template bundled with Groundwork itself, not a project. Create a project with: groundwork create");
138
+ }
139
+ return project;
140
+ }
141
+ const CREATE_OPTIONS = {
142
+ name: { type: "string" },
143
+ description: { type: "string" },
144
+ profiles: { type: "string", multiple: true },
145
+ yes: { type: "boolean", short: "y" },
146
+ "dry-run": { type: "boolean" },
147
+ version: { type: "boolean", short: "v" },
148
+ };
149
+ export async function runCreate(args, prompter = clackPrompter) {
150
+ const { values, positionals } = parse(args, CREATE_OPTIONS);
151
+ if (values.help)
152
+ return print(CREATE_HELP);
153
+ if (values.version)
154
+ return print(VERSION);
155
+ if (positionals.length > 1)
156
+ throw new GroundworkError(`Expected one folder, got: ${positionals.join(" ")}`, 2);
157
+ const profiles = values.profiles?.flatMap((value) => value.split(",")).map((id) => id.trim()).filter(Boolean);
158
+ const interactive = !values.yes && process.stdin.isTTY === true && process.stdout.isTTY === true;
159
+ return create({
160
+ dir: positionals[0],
161
+ name: values.name,
162
+ description: values.description,
163
+ profiles,
164
+ yes: values.yes ?? false,
165
+ dryRun: values["dry-run"] ?? false,
166
+ }, interactive ? prompter : null);
167
+ }
168
+ function print(text) {
169
+ console.log(text);
170
+ return 0;
171
+ }
172
+ function profilesCommand(args) {
173
+ const { values, positionals } = parse(args, { json: { type: "boolean" } });
174
+ if (values.help)
175
+ return print(HELP.profiles);
176
+ const project = findProject();
177
+ const root = project?.root ?? TEMPLATE_ROOT;
178
+ const source = project && !project.isBundledTemplate ? `${project.root}/profiles` : `Groundwork ${VERSION}`;
179
+ if (project && !project.hasEngine)
180
+ throw new GroundworkError(`${project.root} predates Groundwork 3.0 profiles.`);
181
+ if (project && !project.hasJsonEngine) {
182
+ // A Groundwork 3.0 project: show its own listing as that version prints it.
183
+ if (positionals.length || values.json) {
184
+ throw new GroundworkError("This project's scripts/groundwork.py is from Groundwork 3.0, which can only list all profiles.\n" +
185
+ "Run `groundwork profiles`, or copy scripts/ from a newer Groundwork (see MIGRATION.md).");
186
+ }
187
+ return runScript(project.root, "groundwork.py", ["list"], "inherit").status;
188
+ }
189
+ const list = runEngine(root, ["list"]);
190
+ if (!list.ok)
191
+ throw new GroundworkError((list.errors ?? []).map((e) => `FAIL: ${e}`).join("\n"));
192
+ const [id] = positionals;
193
+ let shown = list.profiles;
194
+ if (id) {
195
+ const profile = list.profiles.find((p) => p.id === id);
196
+ if (!profile) {
197
+ const known = list.profiles.map((p) => p.id).join(", ");
198
+ throw new GroundworkError(`Unknown profile '${id}'. Known profiles: ${known}`);
199
+ }
200
+ shown = profile;
201
+ }
202
+ if (values.json)
203
+ return print(JSON.stringify(shown, null, 2));
204
+ return print(Array.isArray(shown) ? formatProfileList(shown, source) : formatProfile(shown, list.profiles, source));
205
+ }
206
+ /** Pass a command through to the project's own groundwork.py. */
207
+ function engineCommand(command, args) {
208
+ const { values, positionals } = parse(args, {
209
+ json: { type: "boolean" },
210
+ ...(command === "config" ? {} : { "dry-run": { type: "boolean" } }),
211
+ });
212
+ if (values.help)
213
+ return print(HELP[command]);
214
+ if (command === "init" && positionals.length === 0) {
215
+ throw new GroundworkError("Name at least one profile, or 'none'. See: groundwork profiles", 2);
216
+ }
217
+ if (command === "add" && positionals.length !== 1)
218
+ throw new GroundworkError("Give exactly one document path.", 2);
219
+ if (command === "config" && positionals.length)
220
+ throw new GroundworkError("config takes no arguments.", 2);
221
+ const project = needProject(command, command !== "config" && !values["dry-run"]);
222
+ if ((command === "config" || values.json) && !project.hasJsonEngine) {
223
+ throw new GroundworkError(`This project's scripts/groundwork.py is from Groundwork 3.0, which has no ${command === "config" ? "config command" : "--json output"}.\n` +
224
+ "Copy scripts/groundwork.py and scripts/check_docs.py from a newer Groundwork to get it (see MIGRATION.md).");
225
+ }
226
+ const passthrough = [
227
+ command,
228
+ ...positionals,
229
+ ...(values["dry-run"] ? ["--dry-run"] : []),
230
+ ...(values.json ? ["--json"] : []),
231
+ ];
232
+ return runScript(project.root, "groundwork.py", passthrough, "inherit").status;
233
+ }
234
+ function validateCommand(args) {
235
+ const { values, positionals } = parse(args, {
236
+ strict: { type: "boolean" },
237
+ "strict-coverage": { type: "boolean" },
238
+ });
239
+ if (values.help)
240
+ return print(HELP.validate);
241
+ if (positionals.length)
242
+ throw new GroundworkError("validate takes no arguments.", 2);
243
+ const project = needProject("validate", false);
244
+ const flags = [...(values.strict ? ["--strict"] : []), ...(values["strict-coverage"] ? ["--strict-coverage"] : [])];
245
+ return runScript(project.root, "check_docs.py", flags, "inherit").status;
246
+ }
247
+ export async function runGroundwork(argv, prompter = clackPrompter) {
248
+ const [command, ...rest] = argv;
249
+ switch (command) {
250
+ case undefined:
251
+ case "help":
252
+ case "-h":
253
+ case "--help":
254
+ if (rest[0] === "create")
255
+ return print(CREATE_HELP);
256
+ if (rest[0] && HELP[rest[0]])
257
+ return print(HELP[rest[0]]);
258
+ return print(MAIN_HELP);
259
+ case "-v":
260
+ case "--version":
261
+ return print(VERSION);
262
+ case "create":
263
+ return runCreate(rest, prompter);
264
+ case "profiles":
265
+ return profilesCommand(rest);
266
+ case "init":
267
+ case "add":
268
+ case "config":
269
+ return engineCommand(command, rest);
270
+ case "validate":
271
+ return validateCommand(rest);
272
+ default:
273
+ throw new GroundworkError(`Unknown command '${command}'.\n\n${MAIN_HELP}`, 2);
274
+ }
275
+ }
276
+ /** Run an entry point and turn errors into messages and exit codes. */
277
+ export async function main(run) {
278
+ try {
279
+ process.exitCode = await run();
280
+ }
281
+ catch (error) {
282
+ if (error instanceof Cancelled) {
283
+ console.error(error.message);
284
+ process.exitCode = 130;
285
+ }
286
+ else if (error instanceof GroundworkError) {
287
+ console.error(`${red("Error:")} ${error.message}`);
288
+ process.exitCode = error.exitCode;
289
+ }
290
+ else {
291
+ throw error;
292
+ }
293
+ }
294
+ }
package/dist/create.js ADDED
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ // Entry point for `npx create-groundwork [folder] [options]`.
3
+ import { main, runCreate } from "./commands.js";
4
+ await main(() => runCreate(process.argv.slice(2)));