@haus-tech/haus-workflow 6.7.1 → 7.0.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 (127) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +41 -85
  3. package/dist/cli.js +17629 -23486
  4. package/docs/before-you-start.md +17 -22
  5. package/docs/glossary.md +10 -8
  6. package/package.json +3 -6
  7. package/packages/agents/issue-creator.md +59 -0
  8. package/packages/configs/eslint/eslint.config.mjs +90 -0
  9. package/packages/configs/lighthouse/lighthouserc.yml +35 -0
  10. package/packages/configs/prettier/.prettierignore +28 -0
  11. package/packages/configs/prettier/prettier.config.cjs +12 -0
  12. package/packages/packages.yaml +81 -0
  13. package/packages/skills/adr-decisions/SKILL.md +113 -0
  14. package/packages/skills/auth-oidc-azure-bankid-patterns/SKILL.md +46 -0
  15. package/packages/skills/auth-oidc-azure-bankid-patterns/references/conventions.md +29 -0
  16. package/packages/skills/auth-oidc-azure-bankid-patterns/references/scope.md +30 -0
  17. package/packages/skills/auth-oidc-azure-bankid-patterns/references/workflow.md +38 -0
  18. package/packages/skills/bullmq-patterns/SKILL.md +53 -0
  19. package/packages/skills/bullmq-patterns/references/conventions.md +33 -0
  20. package/packages/skills/bullmq-patterns/references/scope.md +30 -0
  21. package/packages/skills/bullmq-patterns/references/workflow.md +50 -0
  22. package/{library/global → packages}/skills/haus-workflow/SKILL.md +28 -41
  23. package/packages/skills/haus-workflow/references/init.md +57 -0
  24. package/{library/global → packages}/skills/haus-workflow/references/new.md +15 -20
  25. package/packages/skills/i18next-patterns/SKILL.md +52 -0
  26. package/packages/skills/i18next-patterns/references/conventions.md +32 -0
  27. package/packages/skills/i18next-patterns/references/scope.md +29 -0
  28. package/packages/skills/i18next-patterns/references/workflow.md +39 -0
  29. package/packages/skills/issue-authoring/SKILL.md +184 -0
  30. package/packages/skills/issue-authoring/references/issue-tracker.md +29 -0
  31. package/packages/skills/issue-authoring/references/native-metadata.md +122 -0
  32. package/packages/skills/issue-authoring/references/recording-approval.md +29 -0
  33. package/packages/skills/laravel-nova-patterns/SKILL.md +45 -0
  34. package/packages/skills/laravel-nova-patterns/references/conventions.md +26 -0
  35. package/packages/skills/laravel-nova-patterns/references/scope.md +30 -0
  36. package/packages/skills/laravel-nova-patterns/references/workflow.md +36 -0
  37. package/packages/skills/nextauth-patterns/SKILL.md +48 -0
  38. package/packages/skills/nextauth-patterns/references/conventions.md +33 -0
  39. package/packages/skills/nextauth-patterns/references/scope.md +33 -0
  40. package/packages/skills/nextauth-patterns/references/workflow.md +46 -0
  41. package/packages/skills/nx-tag-conventions/SKILL.md +32 -0
  42. package/packages/skills/package-manager-yarn4-pnpm89/SKILL.md +41 -0
  43. package/packages/skills/package-manager-yarn4-pnpm89/references/conventions.md +25 -0
  44. package/packages/skills/package-manager-yarn4-pnpm89/references/scope.md +30 -0
  45. package/packages/skills/package-manager-yarn4-pnpm89/references/workflow.md +39 -0
  46. package/packages/skills/qliro-patterns/SKILL.md +48 -0
  47. package/packages/skills/qliro-patterns/references/conventions.md +28 -0
  48. package/packages/skills/qliro-patterns/references/scope.md +30 -0
  49. package/packages/skills/qliro-patterns/references/workflow.md +46 -0
  50. package/packages/skills/react-router-v7-patterns/SKILL.md +47 -0
  51. package/packages/skills/react-router-v7-patterns/references/conventions.md +30 -0
  52. package/packages/skills/react-router-v7-patterns/references/scope.md +32 -0
  53. package/packages/skills/react-router-v7-patterns/references/workflow.md +43 -0
  54. package/{library/global → packages}/skills/request/scripts/korning.mjs +1 -1
  55. package/packages/skills/strapi-patterns/SKILL.md +53 -0
  56. package/packages/skills/strapi-patterns/references/conventions.md +33 -0
  57. package/packages/skills/strapi-patterns/references/scope.md +29 -0
  58. package/packages/skills/strapi-patterns/references/workflow.md +47 -0
  59. package/packages/skills/vendure-app-patterns/SKILL.md +34 -0
  60. package/packages/skills/vendure-app-patterns/references/conventions.md +25 -0
  61. package/packages/skills/vendure-app-patterns/references/scope.md +29 -0
  62. package/packages/skills/vendure-app-patterns/references/workflow.md +45 -0
  63. package/packages/skills/vendure-plugin-patterns/SKILL.md +45 -0
  64. package/packages/skills/vendure-plugin-patterns/references/conventions.md +27 -0
  65. package/packages/skills/vendure-plugin-patterns/references/scope.md +30 -0
  66. package/packages/skills/vendure-plugin-patterns/references/workflow.md +42 -0
  67. package/packages/skills/whats-installed/SKILL.md +55 -0
  68. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/SKILL.md +41 -0
  69. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/conventions.md +25 -0
  70. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/scope.md +28 -0
  71. package/packages/skills/wordpress-acf-elementor-jetengine-patterns/references/workflow.md +41 -0
  72. package/packages/skills/wordpress-bedrock-patterns/SKILL.md +41 -0
  73. package/packages/skills/wordpress-bedrock-patterns/references/conventions.md +27 -0
  74. package/packages/skills/wordpress-bedrock-patterns/references/scope.md +28 -0
  75. package/packages/skills/wordpress-bedrock-patterns/references/workflow.md +42 -0
  76. package/packages/skills/writing-documentation/SKILL.md +153 -0
  77. package/packages/skills/writing-documentation/references/claude-template-workspace.md +60 -0
  78. package/packages/skills/writing-documentation/references/claude-template.md +43 -0
  79. package/packages/skills/writing-documentation/references/completeness-criteria.md +26 -0
  80. package/packages/skills/writing-documentation/references/summary-template.md +81 -0
  81. package/packages/skills/writing-documentation/references/topic-file-formats.md +125 -0
  82. package/packages/skills/writing-documentation/references/validation-checklist.md +42 -0
  83. package/packages/templates/agentic-workflow-poc.md +180 -0
  84. package/packages/templates/agentic-workflow-standard.md +170 -0
  85. package/packages/templates/decision-template.md +27 -0
  86. package/packages/templates/decisions-ci-gate.yml +32 -0
  87. package/packages/templates/lefthook-branch-guard.yml +27 -0
  88. package/packages/templates/lefthook-lighthouse.yml +28 -0
  89. package/packages/templates/lefthook-quality.yml +34 -0
  90. package/packages/templates/lefthook-security.yml +27 -0
  91. package/packages/templates/start-here.md +72 -0
  92. package/library/catalog/decisions-triggers.json +0 -26
  93. package/library/catalog/haus-lock.schema.json +0 -4
  94. package/library/catalog/manifest.json +0 -5941
  95. package/library/catalog/validation-rules.json +0 -169
  96. package/library/global/settings-fragments/hooks.json +0 -53
  97. package/library/global/skills/haus-workflow/references/init.md +0 -88
  98. package/scripts/postinstall.mjs +0 -62
  99. /package/{library/global → packages}/agents/request-assessor.md +0 -0
  100. /package/{library/global → packages}/agents/request-design-reviewer.md +0 -0
  101. /package/{library/global → packages}/agents/request-designer.md +0 -0
  102. /package/{library/global → packages}/agents/request-scorer.md +0 -0
  103. /package/{library/global → packages}/agents/request-specifier-eskalerad.md +0 -0
  104. /package/{library/global → packages}/agents/request-specifier.md +0 -0
  105. /package/{library/global → packages}/skills/haus-workflow/references/clone.md +0 -0
  106. /package/{library/global → packages}/skills/request/SKILL.md +0 -0
  107. /package/{library/global → packages}/skills/request/scripts/archive.mjs +0 -0
  108. /package/{library/global → packages}/skills/request/scripts/bedom.mjs +0 -0
  109. /package/{library/global → packages}/skills/request/scripts/check-lasta.mjs +0 -0
  110. /package/{library/global → packages}/skills/request/scripts/compare-scores.mjs +0 -0
  111. /package/{library/global → packages}/skills/request/scripts/contract-check.mjs +0 -0
  112. /package/{library/global → packages}/skills/request/scripts/kontroll.mjs +0 -0
  113. /package/{library/global → packages}/skills/request/scripts/lib.mjs +0 -0
  114. /package/{library/global → packages}/skills/request/scripts/precheck.mjs +0 -0
  115. /package/{library/global → packages}/skills/request/scripts/ref-hash.mjs +0 -0
  116. /package/{library/global → packages}/skills/request/scripts/report.mjs +0 -0
  117. /package/{library/global → packages}/skills/request/scripts/resolve-anchors.mjs +0 -0
  118. /package/{library/global → packages}/skills/request/scripts/svep.mjs +0 -0
  119. /package/{library/global → packages}/skills/request-assess-impact/SKILL.md +0 -0
  120. /package/{library/global → packages}/skills/request-score/SKILL.md +0 -0
  121. /package/{library/global → packages}/skills/request-score/references/poangskala.md +0 -0
  122. /package/{library/global → packages}/skills/request-sync/SKILL.md +0 -0
  123. /package/{library/global → packages}/skills/request-write-spec/SKILL.md +0 -0
  124. /package/{library/global → packages}/skills/request-write-spec/references/specformat.md +0 -0
  125. /package/{library/global → packages}/skills/slack-cowork/SKILL.md +0 -0
  126. /package/{library/global → packages}/skills/slack-cowork/references/canvas-markdown.md +0 -0
  127. /package/{library/global → packages}/skills/slack-cowork/references/synk.md +0 -0
@@ -0,0 +1,27 @@
1
+ ## Naming conventions
2
+
3
+ - Application config: `config/application.php` — PHP constants and environment bindings
4
+ - Environment overrides: `config/environments/production.php`, `config/environments/development.php`
5
+ - Must-use plugins: `web/app/mu-plugins/` (not `web/wp-content/mu-plugins/`)
6
+ - Regular plugins: `web/app/plugins/` (Composer-installed; never uploaded via WP admin)
7
+ - Themes: `web/app/themes/<theme-name>/`
8
+ - WP core: `web/wp/` — treated as read-only Composer dependency
9
+ - Uploads: `web/app/uploads/` (gitignored)
10
+
11
+ ## Do / don't
12
+
13
+ DO: Install and manage all plugins via `composer.json` only — DON'T: install or update plugins via the WP admin dashboard
14
+ DO: Add every new environment variable to `.env.example` with a descriptive example value or blank marker — DON'T: commit real secret values in `.env.example`
15
+ DO: Treat `web/wp/` as a Composer-managed read-only directory — DON'T: edit any file under `web/wp/` (overwritten on `composer update`)
16
+ DO: Reference `WP_HOME` and `WP_SITEURL` from env vars in `config/application.php` — DON'T: hardcode URLs in config files
17
+ DO: Use `Config::define()` / `env()` helper for all env var access in config files — DON'T: call `getenv()` or `$_ENV` directly in application code
18
+ DO: Change WP core version by updating `composer.json` and running `composer update roots/wordpress` — DON'T: change WP version by editing files in `web/wp/`
19
+
20
+ ## Forbidden patterns
21
+
22
+ NEVER: Secret or credential value in `config/application.php` — committed to version control; use env vars
23
+ NEVER: Reference `web/wp-content/` path — Bedrock uses `web/app/` as the content directory
24
+ NEVER: WP core version change without running `composer update` — `web/wp/` becomes inconsistent
25
+ NEVER: Plugin activated via WP admin that is not tracked in `composer.json` — disappears on next deploy
26
+ NEVER: `.env` file committed to version control — contains real credentials
27
+ NEVER: `define()` in `web/wp/wp-config.php` — that file is Composer-managed and will be overwritten
@@ -0,0 +1,28 @@
1
+ # Scope
2
+
3
+ ## In-scope files and dirs
4
+
5
+ - `config/application.php` — WP config constants, env loading via `Dotenv`
6
+ - `config/environments/` — per-environment overrides (`development.php`, `staging.php`, `production.php`)
7
+ - `composer.json`, `composer.lock` — PHP dependency management (WP core, plugins, mu-plugins via Packagist/WPackagist)
8
+ - `web/app/` — WordPress web root: `themes/`, `plugins/`, `mu-plugins/`, `uploads/`
9
+ - `web/wp/` — WordPress core (Composer-managed, do not edit)
10
+ - `web/index.php`, `web/wp-config.php` — web entry points (minimal; generated by Bedrock)
11
+ - `.env`, `.env.example` — environment variable files (`DB_*`, `WP_HOME`, `AUTH_KEY`, etc.)
12
+ - `Trellis/` (if present) — Ansible provisioning for Bedrock deployment
13
+
14
+ ## Stack boundaries
15
+
16
+ - Bedrock: env-based config, Composer-managed WP core and plugins, `web/` vs `app/` separation
17
+ - Not in scope: WordPress hook/template logic inside themes/plugins (use wordpress-patterns)
18
+ - Not in scope: ACF/Elementor/JetEngine data layer (use wordpress-acf-elementor-jetengine-patterns)
19
+ - Not in scope: infrastructure provisioning beyond Trellis config
20
+
21
+ ## Triggers
22
+
23
+ - Adding or upgrading a plugin via Composer (not WP admin)
24
+ - Changing WP version constraint in `composer.json`
25
+ - Adding a new constant or config to `config/application.php`
26
+ - Adding environment-specific config override in `config/environments/`
27
+ - Changing `.env` variables (and updating `.env.example`)
28
+ - Adding a mu-plugin or must-use plugin to `web/app/mu-plugins/`
@@ -0,0 +1,42 @@
1
+ # Workflow
2
+
3
+ ## Implementation steps
4
+
5
+ 1. For plugin installs: use Composer — never install via WP admin in Bedrock projects
6
+ 2. Check WPackagist availability: `wpackagist-plugin/plugin-slug` for free WP.org plugins
7
+ 3. Add plugin to `composer.json` under `require`; run `composer install`
8
+ 4. For WP core upgrade: change `roots/wordpress` version constraint; run `composer update roots/wordpress`
9
+ 5. For new config constant: add to `config/application.php`; add env var to `.env` and `.env.example`
10
+ 6. For environment-specific overrides: add to correct file in `config/environments/`
11
+ 7. Verify `WP_HOME` and `WP_SITEURL` are correct for each environment in `.env`
12
+ 8. For Trellis deployment: update `group_vars/` if new env vars added; run `ansible-playbook deploy.yml`
13
+
14
+ ## Commands
15
+
16
+ ```bash
17
+ # Composer (plugin/dependency management)
18
+ composer require wpackagist-plugin/plugin-slug
19
+ composer require wpackagist-theme/theme-slug
20
+ composer update roots/wordpress # upgrade WP core
21
+ composer install # install from lockfile
22
+ composer show # list installed packages
23
+
24
+ # WP-CLI (run inside web root context)
25
+ wp core version # confirm WP version
26
+ wp plugin list # list active plugins
27
+ wp db check # verify DB connection
28
+
29
+ # Trellis provisioning/deployment (if used)
30
+ ansible-playbook server.yml -e env=staging
31
+ ansible-playbook deploy.yml -e env=production -e site=example.com
32
+ ```
33
+
34
+ ## Validation checklist
35
+
36
+ - [ ] No plugin installed via WP admin — only via `composer require`
37
+ - [ ] `composer.lock` committed after every dependency change
38
+ - [ ] `.env.example` updated with any new required env var (without real values)
39
+ - [ ] `WP_HOME` and `WP_SITEURL` correct for each environment
40
+ - [ ] Secrets never committed in `config/*.php` — use `.env` for all sensitive values
41
+ - [ ] `web/wp/` not modified — WordPress core is Composer-managed
42
+ - [ ] mu-plugins added to `web/app/mu-plugins/` — not `web/wp-content/mu-plugins/`
@@ -0,0 +1,153 @@
1
+ ---
2
+ name: writing-documentation
3
+ description: >-
4
+ Creates or refreshes AI-oriented project documentation (CLAUDE.md, docs/SUMMARY.md,
5
+ README pointers, setup/workflow/deployment topic files) for app and workspace repos.
6
+ Use when the user runs /docs or asks to init or sync docs from code for agent context.
7
+ ---
8
+
9
+ # Writing Documentation
10
+
11
+ Produces **agent-operable** docs: `CLAUDE.md` and `docs/SUMMARY.md` as primary entry points; file-path references over copied prose. README links humans into topic files. Client-agnostic — use only the current repo’s names, manifest, and code.
12
+
13
+ ## Use when
14
+
15
+ - The user runs the docs sync (e.g. `/docs`) or asks to initialise or refresh project documentation for agent context.
16
+ - After setup, commands, env, dependencies, deploy, or integrations changed and the docs must catch up.
17
+ - A repo has no `CLAUDE.md`/`docs/` and needs the initial agent-operable doc set.
18
+
19
+ ## Do not use when
20
+
21
+ - The task is a code change with no documentation impact.
22
+ - You would have to invent facts (URLs, hosts, release steps) not present in code/config — mark those gaps with `> CONFIRM-WITH-TEAM:` instead.
23
+ - Editing generated/vendor directories — docs are an index, not a copy of source.
24
+
25
+ ## Integration with haus
26
+
27
+ This skill ships in haus's `software-engineering` package. When run inside a haus-managed repo:
28
+
29
+ - **Seed from the scanner, don't re-derive.** If `.haus-workflow/context-map.json` exists, read it for roles, stacks, dependencies, and package manager and treat those as given. Spend effort on the deep inventory the shallow scanner cannot produce (wired modules, env→consumer mapping, runtime topology, deploy pipeline).
30
+ - **Preserve the haus import block.** Never alter or drop the `<!-- HAUS:BEGIN haus-imports v=1 -->` … `<!-- HAUS:END haus-imports -->` block in `CLAUDE.md`; write your body around it.
31
+ - **Name a package the scan missed.** If the deep read finds a stack the shallow scan did not (for example Vendure in a nested folder) and `haus.json` does not list its package, tell the user which package fits; they add it with `haus init --packages <list>`, then `haus sync`.
32
+
33
+ - **App mode only under haus.** haus drives single-repo (app mode). Workspace mode is for manual multi-repo use; haus does not orchestrate it.
34
+
35
+ ## Workflow
36
+
37
+ Copy and track:
38
+
39
+ ```text
40
+ Docs Progress
41
+ - [ ] 1. Context scan
42
+ - [ ] 2. Detect mode (app | workspace)
43
+ - [ ] 3. Write/update outputs (templates in references/)
44
+ - [ ] 4. Run references/validation-checklist.md + completeness-criteria.md
45
+ ```
46
+
47
+ ### 1. Context scan
48
+
49
+ Read existing docs, then discover facts from code/config only (no invented URLs, architecture, or release steps).
50
+
51
+ **Always scan**
52
+
53
+ 1. `CLAUDE.md`, `docs/SUMMARY.md`, existing `docs/`
54
+ 2. `README.md`, key config (`package.json`, `composer.json`, CI workflows, `docker-compose.yml`, etc.)
55
+ 3. `GLOSSARY.md` at the repo root if present (index it; it is written by the interview skills, never by this skill) and `docs/research/` if present (list the folder as dated notes; never lift a note into a rule).
56
+ 4. `.env.example` or `.env.sample`
57
+ 5. `git log --oneline -20` when updating
58
+ 6. Test/lint/build scripts and pre-commit hooks (note explicitly if absent)
59
+
60
+ **App mode — discover and document**
61
+
62
+ | Discover | Document in |
63
+ | ------------------------------------------------------------------------------------- | --------------------------------------------- |
64
+ | Bootstrap entry points (`index`, `main`, server, worker, CLI) | `architecture.md`, `codebase.md` |
65
+ | Central wiring/config file(s) | `codebase.md`, `CLAUDE.md` conventions |
66
+ | **Every** top-level module/plugin/package area **and** packages wired only via config | `codebase.md` inventory |
67
+ | Generated dirs (`gql/`, `generated`, etc.) + regen scripts | `development-workflow.md` or `conventions.md` |
68
+ | Migration/schema tooling | `CLAUDE.md`, workflow, architecture |
69
+ | Runtime processes (API + worker + scheduler, etc.) | `architecture.md` |
70
+ | External integrations (CMS, search, queue, email) + env vars | `setup.md`, `architecture.md` |
71
+ | Env vars → consumer (grep config for each key from `.env.example`) | `setup.md` env table |
72
+ | CI deploy pipeline (triggers, build, migrate, verify) | `deployment.md` |
73
+
74
+ **Inventory rule:** If it is registered or imported in central config, it must appear in the codebase map (name, path, one-line purpose). No “major plugins only” sampling.
75
+
76
+ **Workspace mode — discover**
77
+
78
+ 1. `repos.manifest.json`, `repos.local.json.example`, path overrides
79
+ 2. Per-repo pointers only — do not copy app install/deploy tables
80
+ 3. Cross-repo startup order, env alignment, release order (or CONFIRM-WITH-TEAM)
81
+
82
+ ### 2. Detect mode
83
+
84
+ | Mode | Signal |
85
+ | ------------- | ---------------------------------------------------------------- |
86
+ | **App** | Application source in this repo |
87
+ | **Workspace** | Multi-repo orchestration (`repos.manifest.json`, path overrides) |
88
+
89
+ State the mode. Ask if unclear.
90
+
91
+ ### 3. Write outputs
92
+
93
+ **Both modes (always):** `CLAUDE.md`, `README.md`, `docs/SUMMARY.md`
94
+
95
+ **App mode — add when justified** (formats and triggers in `references/topic-file-formats.md`):
96
+
97
+ | File | Typical trigger |
98
+ | ------------------------------ | --------------------------------------------------------- |
99
+ | `docs/setup.md` | Non-trivial local setup or env |
100
+ | `docs/development-workflow.md` | Non-obvious change paths or quality checks |
101
+ | `docs/deployment.md` | CI/CD or remote deploy |
102
+ | `docs/architecture.md` | DB, queue, search, external APIs, or multi-process |
103
+ | `docs/codebase.md` | Application source tree exists |
104
+ | `docs/conventions.md` | Extensions, plugins, custom metadata, workers, or codegen |
105
+
106
+ **Optional app topics** (only when triggered — see `topic-file-formats.md`):
107
+
108
+ `integrations.md`, `testing.md`, `data-model.md`, `security.md`
109
+
110
+ **Workspace mode — glue only** (no per-repo install/deploy copies):
111
+
112
+ `docs/system-overview.md`, `docs/repositories.md`, `docs/local-development.md`, `docs/environments.md`, `docs/release-flow.md`
113
+
114
+ | Owns detail | Content |
115
+ | ----------- | -------------------------------------------------------------- |
116
+ | App repo | Setup, commands, env, architecture, deploy, pre-PR |
117
+ | Workspace | Repo map, integration, cross-repo env alignment, release order |
118
+
119
+ Missing app-repo docs → create in **app repo**, not by expanding workspace docs. Workspace points with `{folder}/path` to config or app docs.
120
+
121
+ **Init:** no `CLAUDE.md` or `docs/` — create full set for mode.
122
+ **Update:** surgical edits; preserve good content; align to current code.
123
+
124
+ ### 4. Validate
125
+
126
+ Run every item in:
127
+
128
+ - `references/validation-checklist.md`
129
+ - `references/completeness-criteria.md`
130
+
131
+ ## References (read per output)
132
+
133
+ | File | Use for |
134
+ | ----------------------------------------- | ------------------------------- |
135
+ | `references/claude-template.md` | `CLAUDE.md` (app mode) |
136
+ | `references/claude-template-workspace.md` | `CLAUDE.md` (workspace mode) |
137
+ | `references/summary-template.md` | `docs/SUMMARY.md` |
138
+ | `references/topic-file-formats.md` | All topic files + optional docs |
139
+ | `references/completeness-criteria.md` | Definition of done |
140
+ | `references/validation-checklist.md` | Final pass |
141
+
142
+ Read the matching reference before writing that output. Do not invent structures the project does not already use.
143
+
144
+ When writing `CLAUDE.md`, use the app or workspace template and include a **keep docs in sync** convention plus PR checklist rows. App repos: update topic docs in-repo. Workspace: update glue docs only; implementation changes stay in app repos.
145
+
146
+ ## Rules
147
+
148
+ - One home per fact; link elsewhere.
149
+ - `{folder}` = manifest folder name or actual repo directory.
150
+ - `> CONFIRM-WITH-TEAM: confirm with team.` for gaps.
151
+ - Concise updates over full rewrites.
152
+ - Ask only when inference fails.
153
+ - Docs are for **routing and decisions**; implementation detail stays in source.
@@ -0,0 +1,60 @@
1
+ # CLAUDE.md template — workspace mode
2
+
3
+ Multi-repo orchestration repos (`repos.manifest.json`, path overrides). **No application source here** — setup, commands, and deploy detail live in app repos. **App repos:** use `claude-template.md`. Keep concise (~150 lines or less).
4
+
5
+ ```markdown
6
+ # [Workspace name]
7
+
8
+ Meta-repo for **multi-repo context**: manifest, integration boundaries, cross-repo env alignment, coordinated release order. **No application source here** — setup, commands, and deploy detail live in app repos (`repos.manifest.json` folders).
9
+
10
+ ## Setup
11
+
12
+ 1. `repos.local.json.example` → `repos.local.json` if app repos are outside this tree (`pathOverrides` keys = manifest `folder` names).
13
+ 2. Or clone per `repos.manifest.json` into workspace root (gitignored).
14
+ 3. [docs/local-development.md](docs/local-development.md) — layout and startup order only.
15
+ 4. Per app repo: [docs/repositories.md](docs/repositories.md) → `{folder}/README.md`, `.env.example`, config (see index table).
16
+
17
+ ## Commands
18
+
19
+ No runtime in this repo. Commands live in each app’s `package.json` / `composer.json` (or equivalent).
20
+
21
+ ## Key conventions
22
+
23
+ - **Agent entry:** `CLAUDE.md` + [docs/SUMMARY.md](docs/SUMMARY.md); load topic files from SUMMARY tables as needed.
24
+ - **Single source of truth:** facts in one repo; workspace docs use `{folder}/path` pointers, not copies of app setup/deploy.
25
+ - Do not commit `repos.local.json`.
26
+ - Cross-repo env alignment: [docs/environments.md](docs/environments.md).
27
+ - **Keep docs in sync (all manifest repos):** after code changes, run the **writing-documentation** skill in every affected repo (this workspace + app repos). App implementation → that repo’s docs; manifest/integration → this workspace. Regenerate `docs/SUMMARY.md` when doc files change in that repo.
28
+
29
+ ## Before opening a PR (workspace)
30
+
31
+ - [ ] `docs/SUMMARY.md` matches files on disk.
32
+ - [ ] Workspace docs reflect this PR (manifest, integration, cross-repo process) or N/A.
33
+ - [ ] No duplicated install/deploy tables from app repos.
34
+ - [ ] New operational detail added in the **app repo** first; pointer here only if cross-cutting
35
+ - [ ] Ran the **writing-documentation** skill in this workspace and in each affected app repo (or N/A)
36
+
37
+ App-repo PR checks: each repo’s `CLAUDE.md` when present.
38
+
39
+ ## Docs
40
+
41
+ [docs/SUMMARY.md](docs/SUMMARY.md)
42
+ ```
43
+
44
+ ## Workspace glue docs (create when justified)
45
+
46
+ Point to these from `docs/SUMMARY.md`; do not copy app-repo install/deploy prose.
47
+
48
+ | File | Owns |
49
+ | --------------------------- | ------------------------------------------------ |
50
+ | `docs/system-overview.md` | Integration boundaries, data flow between repos |
51
+ | `docs/repositories.md` | Repo map, links to each app’s README and config |
52
+ | `docs/local-development.md` | Layout, clone/path overrides, startup order only |
53
+ | `docs/environments.md` | Cross-repo env alignment |
54
+ | `docs/release-flow.md` | Coordinated release order across manifest repos |
55
+
56
+ Missing app-repo detail → create or update in **that app repo**, not by expanding workspace docs.
57
+
58
+ ## Workspace completeness
59
+
60
+ Before finishing, verify `references/completeness-criteria.md` workspace section: repo map complete, startup/release/env documented or CONFIRM-WITH-TEAM, no duplicated app tables.
@@ -0,0 +1,43 @@
1
+ # CLAUDE.md template — app mode
2
+
3
+ Single-codebase repos. **Workspace:** use `claude-template-workspace.md`. Keep concise (~150 lines or less).
4
+
5
+ ```markdown
6
+ # [Project name]
7
+
8
+ [1-2 sentences on repo purpose and role.]
9
+
10
+ ## Setup
11
+
12
+ [Brief prerequisites/install/env. Link to docs/setup.md when it exists.]
13
+
14
+ ## Commands
15
+
16
+ | Command | Action |
17
+ | --------- | ---------------- |
18
+ | `[dev]` | ... |
19
+ | `[build]` | ... |
20
+ | `[test]` | ... |
21
+ | `[check]` | Lint / typecheck |
22
+
23
+ Omit rows that do not exist in package.json (or equivalent).
24
+
25
+ ## Key conventions
26
+
27
+ - [3-8 project-specific bullets from code scan: wiring file, runtime split, schema tool, etc.]
28
+ - **Docs are an index:** use path references in `docs/`; read source for implementation detail.
29
+ - **Regenerate, don't patch:** after schema/API changes, run documented codegen/migration commands — do not hand-edit generated dirs.
30
+ - **Keep docs in sync:** after setup, commands, env, deploy, or integration changes, run the **writing-documentation** skill in **this repo** and commit doc updates with the code change.
31
+
32
+ ## Before opening a PR
33
+
34
+ - [ ] Run available checks (test/lint/build)
35
+ - [ ] Run the **writing-documentation** skill in this repo when setup, commands, env, deploy, or integration changed (or N/A)
36
+ - [ ] Docs reflect this change or explicitly N/A
37
+ - [ ] Run repo-specific steps (migrations, codegen, i18n, etc.) when applicable
38
+ - [ ] Smoke-test impacted flows if no automated coverage
39
+
40
+ ## Docs
41
+
42
+ [docs/SUMMARY.md](docs/SUMMARY.md)
43
+ ```
@@ -0,0 +1,26 @@
1
+ # Completeness criteria
2
+
3
+ Use with `validation-checklist.md` before finishing a docs update. Every item must be **answered in docs**, marked **N/A**, or **`> CONFIRM-WITH-TEAM: confirm with team.`** — never guessed.
4
+
5
+ ## App mode
6
+
7
+ 1. **Install and run** — prerequisites, install command, how to start locally, how to verify success.
8
+ 2. **Runtime** — processes/services (API, worker, CLI, etc.) and how they interact, or N/A for single-process apps.
9
+ 3. **Wiring** — path(s) to bootstrap entry points and central configuration.
10
+ 4. **Change routing** — where typical changes go (table or bullets): feature logic, config, schema, tests, CI.
11
+ 5. **Pre-PR checks** — commands for test/lint/build and repo-specific steps (migrations, codegen, etc.).
12
+ 6. **Deploy** — how releases run, ordered steps, post-deploy checks, rollback — or explicit CONFIRM-WITH-TEAM.
13
+ 7. **Environment** — key vars from `.env.example` with purpose and consumer (subsystem or config path).
14
+ 8. **Regeneration** — migrations, codegen, or other generated artifacts: commands and “do not hand-edit” paths, or N/A.
15
+ 9. **Agent guardrails** — generated/vendor/secret paths agents must not edit; docs are an index, not a code copy.
16
+ 10. **Unknowns** — gaps use team CONFIRM-WITH-TEAM, not invented URLs, hosts, or ops steps.
17
+
18
+ ## Workspace mode
19
+
20
+ 1. **Repo map** — every manifest repo with pointer to its `CLAUDE.md` / README / config.
21
+ 2. **Layout** — clone/path overrides and local directory layout.
22
+ 3. **Startup order** — which repos/services start in what order, or CONFIRM-WITH-TEAM.
23
+ 4. **Cross-repo env** — shared env alignment documented or CONFIRM-WITH-TEAM in `docs/environments.md`.
24
+ 5. **Release order** — coordinated release across repos documented or CONFIRM-WITH-TEAM in `docs/release-flow.md`.
25
+ 6. **No duplication** — install/deploy/env tables live in app repos only; workspace uses `{folder}/path` pointers.
26
+ 7. **Unknowns** — gaps use team CONFIRM-WITH-TEAM, not invented URLs, hosts, or ops steps.
@@ -0,0 +1,81 @@
1
+ # SUMMARY.md template
2
+
3
+ Use when creating or regenerating `docs/SUMMARY.md`. Remove sections with zero files on disk.
4
+
5
+ ```markdown
6
+ # [Project Name]
7
+
8
+ [One paragraph: what this repo is, its role in the wider system if applicable, core capability. Factual only.]
9
+
10
+ ## Agent Context Guide
11
+
12
+ - Use this file as the documentation index; open detail docs from the tables below only when needed.
13
+ - Start with **CLAUDE.md** for setup, commands, conventions, and pre-PR checks.
14
+ - Route by task (load one primary topic, not every file):
15
+ - **Run / debug locally** → Setup (app: `setup.md`; workspace: `local-development.md`)
16
+ - **Code change** → Codebase; add Conventions and Architecture if the change is cross-cutting or touches integrations
17
+ - **Ship / release** → Development workflow + Deployment (app) or Release flow (workspace)
18
+ - **Multi-repo** (workspace only) → Repositories + Environments + System overview as needed
19
+ - Prefer path references in docs over duplicating source; read code for implementation detail.
20
+ - If docs conflict with code or user intent, ask before making broad changes.
21
+
22
+ ## Architecture
23
+
24
+ | File | Description |
25
+ | ---------------------------------- | ----------- |
26
+ | [architecture.md](architecture.md) | … |
27
+
28
+ ## Codebase
29
+
30
+ | File | Description |
31
+ | -------------------------- | ----------- |
32
+ | [codebase.md](codebase.md) | … |
33
+
34
+ ## Conventions
35
+
36
+ Omit if `docs/conventions.md` does not exist.
37
+
38
+ | File | Description |
39
+ | -------------------------------- | -------------------------------------------------- |
40
+ | [conventions.md](conventions.md) | Extension patterns, schema/codegen, change recipes |
41
+
42
+ ## Setup
43
+
44
+ | File | Description |
45
+ | -------------------- | ----------- |
46
+ | [setup.md](setup.md) | … |
47
+
48
+ ## Development workflow
49
+
50
+ Omit if `docs/development-workflow.md` does not exist.
51
+
52
+ | File | Description |
53
+ | -------------------------------------------------- | --------------------------------------------- |
54
+ | [development-workflow.md](development-workflow.md) | Common changes, where to edit, quality checks |
55
+
56
+ ## Deployment
57
+
58
+ Omit if no deployment docs exist.
59
+
60
+ | File | Description |
61
+ | ------------------------------ | ----------- |
62
+ | [deployment.md](deployment.md) | … |
63
+
64
+ ## Other
65
+
66
+ Optional. Non-standard docs only (integrations, testing, data-model, security, etc.).
67
+
68
+ | File | Description |
69
+ | ----------------------------- | --------------------------------------------- |
70
+ | [path.md](path.md) | … |
71
+ | [GLOSSARY.md](../GLOSSARY.md) | Domain terms, written by the interview skills |
72
+ | [research/](research/) | Dated research notes; evidence, never a rule |
73
+ ```
74
+
75
+ ## Regeneration rules
76
+
77
+ - List every file that exists on disk; no phantom rows.
78
+ - Omit empty sections.
79
+ - Links relative to `docs/`.
80
+ - One-line descriptions in tables; detail in linked files.
81
+ - **Workspace repos:** SUMMARY describes glue docs only; link app-repo paths from `repositories.md`, do not duplicate app `setup.md` / `deployment.md` content here.
@@ -0,0 +1,125 @@
1
+ # Topic file formats
2
+
3
+ Use this file for detailed formatting guidance. Keep SKILL.md high-level.
4
+
5
+ ## Inventory rule (app mode)
6
+
7
+ When scanning central config/wiring, **every registered module, plugin, package, or top-level source area** must appear in `docs/codebase.md` (at least name, path, one-line purpose). Do not document only a “major” subset.
8
+
9
+ ## `docs/setup.md`
10
+
11
+ **Create when:** multiple services, external dependencies, non-obvious env vars, or troubleshooting needs.
12
+
13
+ **Required sections:**
14
+
15
+ - Prerequisites
16
+ - Related systems (what must run locally: DB, queue, search, etc.)
17
+ - Install
18
+ - Environment — table from `.env.example` with columns: **Variable | Purpose | Used by** (subsystem name or config file path; grep config if needed)
19
+ - Run locally
20
+ - Verify — concrete checks (URLs, health endpoints, log lines) from README/scripts, or CONFIRM-WITH-TEAM
21
+ - Troubleshooting
22
+
23
+ ## `docs/development-workflow.md`
24
+
25
+ **Create when:** split runtime, missing test script, hooks, i18n, external CMS/API, or non-obvious change paths.
26
+
27
+ **Required sections:**
28
+
29
+ - Scope of this repo
30
+ - Common changes
31
+ - Where to change what (table: change type → primary path(s))
32
+ - Quality checks (test/lint/build commands; note if lint/hooks absent)
33
+ - Link to deployment docs when they exist
34
+
35
+ **Include when discovered:**
36
+
37
+ - Generated artifact dirs and regen commands (`codegen`, OpenAPI, etc.)
38
+ - Schema/migration workflow order
39
+ - If multiple extension patterns exist (e.g. central registry vs module config), point to `docs/conventions.md` or document briefly here
40
+
41
+ ## `docs/deployment.md`
42
+
43
+ **Create when:** CI/CD, multiple environments, remote deploy, or post-deploy tasks.
44
+
45
+ **Required sections:**
46
+
47
+ - Hosting/runtime overview
48
+ - Deploy triggers (branch, tag, manual dispatch — from workflows)
49
+ - Environment differences
50
+ - Release checklist (numbered, from CI/scripts)
51
+ - Artifacts — what is built and where it lands (if inferable)
52
+ - Post-deploy verification — smoke checks from workflows/scripts, or CONFIRM-WITH-TEAM
53
+ - Rollback notes — only if inferable from workflows/docs; else CONFIRM-WITH-TEAM
54
+
55
+ ## `docs/architecture.md`
56
+
57
+ **Create when:** app has two or more of: database, queue/cache, search index, external APIs, multiple processes.
58
+
59
+ **Required sections:**
60
+
61
+ - Runtime model — processes and roles
62
+ - Core components — names from config (DB, cache, queue, search, etc.)
63
+ - Extension model — how domain logic is organized (plugins, modules, packages) and registration location
64
+ - Request/job flow — short numbered flow (e.g. API → logic → async job)
65
+ - Integration boundaries — external systems and env vars that configure them (not full API specs)
66
+ - Schema evolution — migrations/versioning if present, or N/A
67
+
68
+ ## `docs/codebase.md`
69
+
70
+ **Create when:** application source exists (`src/`, `app/`, `lib/`, etc.).
71
+
72
+ **Required sections:**
73
+
74
+ - Top-level directories (table: path → purpose)
75
+ - Entry points and wiring — bootstrap files + central config path(s)
76
+ - **Complete inventory** — all top-level modules/plugins/packages under main source root and wired external packages (from central config)
77
+ - Where to change what (table: task → path(s))
78
+ - Tests — where unit/e2e/integration tests live, or N/A
79
+
80
+ ## `docs/conventions.md`
81
+
82
+ **Create when:** framework extensions, plugins/modules, custom metadata/fields, workers, or codegen — and patterns are not obvious from layout alone.
83
+
84
+ **Suggested sections:**
85
+
86
+ - Extension patterns — how the app extends the framework; where registration happens (paths only)
87
+ - Configuration vs code — env vs config files vs database
88
+ - Schema/data changes — tool and order of operations
89
+ - Generated artifacts — paths and regen commands; do not hand-edit
90
+ - Common change recipes (table filled from scan):
91
+
92
+ | Task | Start here | Also touch |
93
+ | ---- | ---------- | ---------- |
94
+
95
+ - Multiple ways to add the same kind of metadata (e.g. central file vs module config): document both and when to use each, if the repo has both
96
+
97
+ ## Optional topic files
98
+
99
+ Create only when triggered; link from `docs/SUMMARY.md` **Other** section.
100
+
101
+ | File | Trigger |
102
+ | ---------------------- | ------------------------------------------------------------------------- |
103
+ | `docs/integrations.md` | Three or more external systems, or non-obvious sync/webhooks |
104
+ | `docs/testing.md` | Multiple test types, custom fixtures, or heavy e2e setup |
105
+ | `docs/data-model.md` | Frequent schema/migration pain; complex custom persistence |
106
+ | `docs/security.md` | Non-obvious auth boundaries or PII handling (high-level only; no secrets) |
107
+
108
+ ## Workspace glue docs
109
+
110
+ See `claude-template-workspace.md`. Do not copy app-repo install/deploy tables.
111
+
112
+ | File | Owns |
113
+ | --------------------------- | ------------------------------------------------ |
114
+ | `docs/system-overview.md` | Integration boundaries, data flow between repos |
115
+ | `docs/repositories.md` | Repo map, links to each app README and config |
116
+ | `docs/local-development.md` | Layout, clone/path overrides, startup order only |
117
+ | `docs/environments.md` | Cross-repo env alignment |
118
+ | `docs/release-flow.md` | Coordinated release order across manifest repos |
119
+
120
+ ## Topic file rules
121
+
122
+ - Use content-based names (e.g. `api-design.md`, not `overview.md`).
123
+ - Prefer flat files unless there are two or more distinct documents in that area.
124
+ - Avoid copied content from other docs; reference source paths.
125
+ - One home per fact; link elsewhere.
@@ -0,0 +1,42 @@
1
+ # Validation checklist
2
+
3
+ Run this before finishing a docs update. Also run `completeness-criteria.md`.
4
+
5
+ ## Required checks
6
+
7
+ - Path from setup → develop → verify → deploy is documented or explicitly CONFIRM-WITH-TEAM.
8
+ - `CLAUDE.md` includes setup, commands, conventions, PR checklist, and guidance to update docs when setup/commands/env/deploy/integration changes.
9
+ - `docs/SUMMARY.md` matches files on disk (no phantom links).
10
+ - README links to `docs/SUMMARY.md` and relevant setup/workflow docs.
11
+ - No invented requirements, URLs, hosts, or release steps.
12
+ - `.env.example` or `.env.sample` is referenced when environment is discussed.
13
+ - All items in `completeness-criteria.md` for the detected mode are satisfied or CONFIRM-WITH-TEAM.
14
+
15
+ ## App-mode checks
16
+
17
+ - Codebase map lists **all** top-level source areas and wired modules found in central config (not a partial sample).
18
+ - Env table includes **Used by** (consumer/subsystem or config path) or explicit CONFIRM-WITH-TEAM to add.
19
+ - Generated-code directories are named with regen command, or marked N/A.
20
+ - Multi-process runtime is documented in architecture, or explicitly single-process / N/A.
21
+ - External/wired packages are distinguished from in-repo modules.
22
+ - Agent Context Guide in SUMMARY includes task → doc routing.
23
+
24
+ ## Workspace-mode checks
25
+
26
+ - Manifest/repo map is complete with pointers to each app’s docs.
27
+ - Startup order and cross-repo env/release are documented or CONFIRM-WITH-TEAM.
28
+ - Workspace docs do not duplicate app install/deploy/env tables.
29
+
30
+ ## Single-source checks
31
+
32
+ - App repo docs own implementation detail; workspace docs point to app file paths.
33
+ - Workspace docs do not duplicate app repo setup/deploy internals.
34
+ - References in workspace docs use real repo folder names or manifest folder names.
35
+ - Commands and conventions are not duplicated at length in both `CLAUDE.md` and topic files (one primary home, link elsewhere).
36
+
37
+ ## Quality checks
38
+
39
+ - Unknowns are marked with `> CONFIRM-WITH-TEAM: confirm with team.`
40
+ - Terminology is consistent across docs.
41
+ - Changes are concise and aligned with current code/config.
42
+ - Docs prefer path references over copying implementation detail.