coentrify 0.0.2 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +18 -0
- package/README.md +2 -1
- package/bin/coentrify.js +79 -12
- package/package.json +3 -2
- package/src/changelog/0.0.1.md +259 -0
- package/src/changelog/0.0.2.md +219 -0
- package/src/changelog/0.0.3.md +81 -0
- package/src/changelog/0.0.4.md +198 -0
- package/src/changelog/0.0.5.md +160 -0
- package/src/changelog/0.0.6.md +282 -0
- package/src/changelog/0.0.7.md +113 -0
- package/src/changelog/0.0.8.md +212 -0
- package/src/changelog/0.1.0.md +9 -0
- package/src/changelog/overview.md +13 -0
- package/src/coentrify-json.md +72 -0
- package/src/commands.md +48 -0
- package/src/glossary.md +132 -0
- package/src/how-it-works.md +51 -0
- package/src/onboarding.md +140 -0
- package/src/origin.md +19 -0
- package/src/philosophy.md +99 -0
- package/src/proof.md +596 -0
- package/src/readme.md +76 -0
- package/src/recommendations.md +100 -0
- package/src/standards/ai/match-known-commands-deterministically-classify-the-rest.md +22 -0
- package/src/standards/ai/overview.md +6 -0
- package/src/standards/ai/prompt-small-models-differently.md +21 -0
- package/src/standards/angular/canmatch-wildcard-for-route-access.md +22 -0
- package/src/standards/angular/interface-not-abstract-class-for-mock-swap.md +37 -0
- package/src/standards/angular/no-any-in-templates.md +25 -0
- package/src/standards/angular/no-inline-templates.md +14 -0
- package/src/standards/angular/one-component-per-folder-flat.md +12 -0
- package/src/standards/angular/one-projected-node-per-control-flow-block.md +19 -0
- package/src/standards/angular/overview.md +16 -0
- package/src/standards/angular/prefer-content-projection-over-props-angular.md +17 -0
- package/src/standards/angular/projected-content-is-never-styled-by-the-host.md +23 -0
- package/src/standards/angular/static-attribute-not-literal-binding.md +23 -0
- package/src/standards/angular/track-timed-items-by-an-id.md +17 -0
- package/src/standards/angular/ui-copy-in-template.md +26 -0
- package/src/standards/angular/use-modern-angular-template-apis.md +20 -0
- package/src/standards/architecture/adopt-configure-override.md +25 -0
- package/src/standards/architecture/app-shield.md +57 -0
- package/src/standards/architecture/converge-only-once-proven.md +22 -0
- package/src/standards/architecture/folder-concerns.md +28 -0
- package/src/standards/architecture/overview.md +11 -0
- package/src/standards/architecture/per-application-split-over-shared-branching.md +25 -0
- package/src/standards/architecture/separation-before-layer-standards.md +17 -0
- package/src/standards/architecture/unique-where-it-counts.md +19 -0
- package/src/standards/behavior/a-go-before-work-elsewhere.md +17 -0
- package/src/standards/behavior/a-maybe-is-a-trigger-to-investigate.md +20 -0
- package/src/standards/behavior/a-name-describes-its-unit.md +19 -0
- package/src/standards/behavior/a-quiet-tree-while-a-suite-runs.md +19 -0
- package/src/standards/behavior/always-make-no-mistakes.md +45 -0
- package/src/standards/behavior/always-verify-before-reporting-done.md +18 -0
- package/src/standards/behavior/always-work-from-a-plan.md +29 -0
- package/src/standards/behavior/anchor-edits-after-formatting.md +17 -0
- package/src/standards/behavior/backward-trace-missing-prerequisites.md +20 -0
- package/src/standards/behavior/code-review-compounds-into-patterns-and-sweeps.md +21 -0
- package/src/standards/behavior/communication-boundary.md +18 -0
- package/src/standards/behavior/dev-tiers.md +25 -0
- package/src/standards/behavior/docs-hold-only-what-the-director-decided.md +23 -0
- package/src/standards/behavior/dont-filter-data-without-a-spec.md +20 -0
- package/src/standards/behavior/dont-introduce-tech-debt.md +25 -0
- package/src/standards/behavior/feature-workflow.md +31 -0
- package/src/standards/behavior/file-a-change-with-coentrify.md +24 -0
- package/src/standards/behavior/flag-every-addition-of-your-own.md +22 -0
- package/src/standards/behavior/free-text-replies-no-buttons.md +20 -0
- package/src/standards/behavior/general-working-rules.md +37 -0
- package/src/standards/behavior/non-destructive-documenting-and-test-automation.md +20 -0
- package/src/standards/behavior/normal-dashes.md +15 -0
- package/src/standards/behavior/note-issues.md +26 -0
- package/src/standards/behavior/overview.md +46 -0
- package/src/standards/behavior/own-ports-own-processes.md +37 -0
- package/src/standards/behavior/project-lifecycle.md +21 -0
- package/src/standards/behavior/propagate-renames-and-convention-changes-everywhere.md +16 -0
- package/src/standards/behavior/prose-style.md +24 -0
- package/src/standards/behavior/prototype-mode-is-speed-first.md +20 -0
- package/src/standards/behavior/regular-layered-gap-analysis.md +20 -0
- package/src/standards/behavior/reload-the-standards-after-compacting.md +16 -0
- package/src/standards/behavior/review-changes-before-reporting-done.md +17 -0
- package/src/standards/behavior/review-every-capture-before-reporting.md +21 -0
- package/src/standards/behavior/standards-maintenance.md +65 -0
- package/src/standards/behavior/standards-over-skills.md +17 -0
- package/src/standards/behavior/sweeps-enumerate-into-tech-debt-first.md +20 -0
- package/src/standards/behavior/sync-the-docs-after-every-change.md +20 -0
- package/src/standards/behavior/the-quality-of-the-question.md +17 -0
- package/src/standards/behavior/things-of-one-kind-are-consistent.md +20 -0
- package/src/standards/behavior/understand-the-need.md +69 -0
- package/src/standards/behavior/use-us-english-everywhere.md +17 -0
- package/src/standards/behavior/verify-apis-against-docs-and-the-installed-artifact.md +17 -0
- package/src/standards/behavior/verify-control-before-rename.md +11 -0
- package/src/standards/code/code-principles.md +32 -0
- package/src/standards/code/escape-hatch-comments.md +20 -0
- package/src/standards/code/name-by-concept-not-copy.md +20 -0
- package/src/standards/code/no-abbreviated-names.md +20 -0
- package/src/standards/code/no-describe-what-comments.md +26 -0
- package/src/standards/code/overview.md +10 -0
- package/src/standards/code/pre-empt-recurring-code-review-nits.md +31 -0
- package/src/standards/commits/commits.md +44 -0
- package/src/standards/commits/gate-commits-on-exit-codes.md +22 -0
- package/src/standards/commits/main-stays-green-work-stays-clean.md +23 -0
- package/src/standards/commits/overview.md +8 -0
- package/src/standards/commits/verify-staging-before-committing.md +29 -0
- package/src/standards/docs/application-template.md +89 -0
- package/src/standards/docs/docs-are-hierarchical-explicit-and-short.md +48 -0
- package/src/standards/docs/docs-describe-behavior-not-wiring.md +24 -0
- package/src/standards/docs/docs-folder-structure.md +38 -0
- package/src/standards/docs/docs-state-knowledge.md +23 -0
- package/src/standards/docs/documentation-philosophy.md +62 -0
- package/src/standards/docs/feature-spec-template.md +89 -0
- package/src/standards/docs/feature-template.md +62 -0
- package/src/standards/docs/file-names.md +20 -0
- package/src/standards/docs/glossary.md +18 -0
- package/src/standards/docs/library-feedback.md +20 -0
- package/src/standards/docs/no-faux-headers-in-lists.md +18 -0
- package/src/standards/docs/overview.md +20 -0
- package/src/standards/docs/ui-vocabulary.md +31 -0
- package/src/standards/docs/workspace-levels.md +24 -0
- package/src/standards/docs/workspace-suite.md +24 -0
- package/src/standards/docs/workspace-template.md +41 -0
- package/src/standards/e2e/e2e-assert-before-interacting.md +21 -0
- package/src/standards/e2e/e2e-mock-contract.md +20 -0
- package/src/standards/e2e/e2e-runs-on-the-development-build.md +18 -0
- package/src/standards/e2e/e2e-test-conventions.md +61 -0
- package/src/standards/e2e/e2e-tests-must-demonstrate-behavior.md +28 -0
- package/src/standards/e2e/one-check-for-many-canvas-clicks.md +17 -0
- package/src/standards/e2e/overview.md +14 -0
- package/src/standards/e2e/per-feature-overview-test.md +30 -0
- package/src/standards/e2e/real-input-for-frame-races.md +25 -0
- package/src/standards/e2e/substring-locator-collisions.md +23 -0
- package/src/standards/e2e/use-the-e2e-pipeline-for-browser-probing.md +18 -0
- package/src/standards/electron/electron-packaging-and-suite.md +22 -0
- package/src/standards/electron/electron-shell-shape.md +21 -0
- package/src/standards/electron/overview.md +6 -0
- package/src/standards/gamedev/2d-visual-design.md +22 -0
- package/src/standards/gamedev/budget-exceptions.json +6 -0
- package/src/standards/gamedev/captures-and-reels.md +39 -0
- package/src/standards/gamedev/devbox.md +21 -0
- package/src/standards/gamedev/game-design-laws-experience.md +68 -0
- package/src/standards/gamedev/game-design-laws-guidance.md +43 -0
- package/src/standards/gamedev/game-design-laws-own-style.md +33 -0
- package/src/standards/gamedev/game-design-laws-progress.md +54 -0
- package/src/standards/gamedev/game-design-laws-quality.md +30 -0
- package/src/standards/gamedev/game-design-laws-story.md +45 -0
- package/src/standards/gamedev/game-design-laws-ui.md +52 -0
- package/src/standards/gamedev/game-design-laws-world.md +38 -0
- package/src/standards/gamedev/game-design-laws.md +112 -0
- package/src/standards/gamedev/game-phases-concept.md +29 -0
- package/src/standards/gamedev/game-phases-design.md +39 -0
- package/src/standards/gamedev/game-phases-development.md +30 -0
- package/src/standards/gamedev/game-phases-live.md +19 -0
- package/src/standards/gamedev/game-phases.md +52 -0
- package/src/standards/gamedev/game-work-workflow.md +47 -0
- package/src/standards/gamedev/gamedev-working-cadence.md +52 -0
- package/src/standards/gamedev/incremental-pacing.md +22 -0
- package/src/standards/gamedev/launch-strategy.md +50 -0
- package/src/standards/gamedev/measure-sound-never-guess.md +24 -0
- package/src/standards/gamedev/overview.md +29 -0
- package/src/standards/gamedev/own-icons.md +19 -0
- package/src/standards/gamedev/silent-runs.md +26 -0
- package/src/standards/gamedev/sprite-sheet-frames.md +23 -0
- package/src/standards/overview.md +43 -0
- package/src/standards/records/activity-log.md +33 -0
- package/src/standards/records/changelog-per-version.md +43 -0
- package/src/standards/records/healing-log.md +23 -0
- package/src/standards/records/overview.md +10 -0
- package/src/standards/records/playtest-files.md +38 -0
- package/src/standards/records/request-log.md +30 -0
- package/src/standards/records/user-test-files.md +21 -0
- package/src/standards/reporting/change-report.md +43 -0
- package/src/standards/reporting/overview.md +6 -0
- package/src/standards/reporting/reels-and-video-proof.md +32 -0
- package/src/standards/scripts/no-npx-in-scripts.md +20 -0
- package/src/standards/scripts/npm-script-naming.md +43 -0
- package/src/standards/scripts/overview.md +7 -0
- package/src/standards/scripts/thin-wrappers-in-ci-and-hooks.md +25 -0
- package/src/standards/security/keep-personal-data-out-of-requests.md +16 -0
- package/src/standards/security/keep-secrets-away-from-agents.md +21 -0
- package/src/standards/security/never-access-the-keychain.md +16 -0
- package/src/standards/security/overview.md +7 -0
- package/src/standards/simple-workflow/bugs-template.md +38 -0
- package/src/standards/simple-workflow/overview.md +12 -0
- package/src/standards/simple-workflow/plan-template.md +50 -0
- package/src/standards/simple-workflow/plans-vs-persistent-files.md +31 -0
- package/src/standards/simple-workflow/remove-completed-items-from-docs.md +19 -0
- package/src/standards/simple-workflow/roadmap-template.md +41 -0
- package/src/standards/simple-workflow/technical-debt-template.md +44 -0
- package/src/standards/simple-workflow/the-simple-workflow.md +48 -0
- package/src/standards/simple-workflow/todo-template.md +31 -0
- package/src/standards/tests/a-bugs-test-reproduces-with-real-input.md +18 -0
- package/src/standards/tests/bracket-state-changes-with-contrast-assertions.md +37 -0
- package/src/standards/tests/gestures-in-tests.md +35 -0
- package/src/standards/tests/implementation-agnostic-assertions.md +20 -0
- package/src/standards/tests/implementation-agnostic-locators.md +18 -0
- package/src/standards/tests/overview.md +13 -0
- package/src/standards/tests/realistic-test-data-variance.md +24 -0
- package/src/standards/tests/seed-surfaces-every-state-on-page-1.md +17 -0
- package/src/standards/tests/test-design.md +47 -0
- package/src/standards/tests/test-the-system-behind-a-mock.md +21 -0
- package/src/standards/tickets-workflow/agent-roles.md +54 -0
- package/src/standards/tickets-workflow/budget-exceptions.json +6 -0
- package/src/standards/tickets-workflow/building-a-ticket.md +47 -0
- package/src/standards/tickets-workflow/overview.md +15 -0
- package/src/standards/tickets-workflow/stabilize-before-adding.md +18 -0
- package/src/standards/tickets-workflow/the-builder.md +28 -0
- package/src/standards/tickets-workflow/the-conductor.md +44 -0
- package/src/standards/tickets-workflow/the-done-part.md +23 -0
- package/src/standards/tickets-workflow/ticket-template.md +96 -0
- package/src/standards/tickets-workflow/work-item-names.md +30 -0
- package/src/standards/tickets-workflow/work-tracking.md +177 -0
- package/src/standards/tickets-workflow/work-workflow.md +123 -0
- package/src/standards/tickets-workflow/writing-a-ticket.md +50 -0
- package/src/standards/tooling/browser-captures-go-to-disk.md +20 -0
- package/src/standards/tooling/check-where-a-pane-click-landed.md +19 -0
- package/src/standards/tooling/defer-tooling-until-the-cost-shows-up.md +19 -0
- package/src/standards/tooling/develop-against-mocks.md +19 -0
- package/src/standards/tooling/hygiene-tests-run-on-their-own-runner.md +18 -0
- package/src/standards/tooling/lightweight-test-reporting-only.md +16 -0
- package/src/standards/tooling/node-versions.md +24 -0
- package/src/standards/tooling/overview.md +17 -0
- package/src/standards/tooling/parallel-agents.md +45 -0
- package/src/standards/tooling/playwright-parallel-runs.md +30 -0
- package/src/standards/tooling/playwright-video-recording.md +32 -0
- package/src/standards/tooling/read-before-you-truncate.md +19 -0
- package/src/standards/tooling/start-playwright-on-a-clean-port.md +22 -0
- package/src/standards/tooling/vitepress-wiki.md +38 -0
- package/src/standards/typescript/always-add-explicit-types.md +32 -0
- package/src/standards/typescript/barrel-imports.md +21 -0
- package/src/standards/typescript/no-magic-values.md +52 -0
- package/src/standards/typescript/one-artifact-per-file.md +19 -0
- package/src/standards/typescript/overview.md +8 -0
- package/src/standards/ui/communicate-state.md +21 -0
- package/src/standards/ui/never-obscure-information-the-user-needs.md +26 -0
- package/src/standards/ui/overview.md +16 -0
- package/src/standards/ui/pixel-perfect-design-check.md +22 -0
- package/src/standards/ui/ui-component-design.md +34 -0
- package/src/standards/ui/ui-components-first.md +25 -0
- package/src/standards/ui/ui-layout-via-slot-composition.md +33 -0
- package/src/standards/ui/ui-library-is-domain-agnostic.md +20 -0
- package/src/standards/ui/ui-refactor-preserve-dont-redesign.md +25 -0
- package/src/standards/ui/ui-styleguide.md +30 -0
- package/src/standards/ui/ui-variants-by-function-not-by-color.md +23 -0
- package/src/standards/ui/validation-errors-fire-on-submit.md +20 -0
- package/src/standards/ui/walk-the-users-journey.md +29 -0
- package/src/standards/web/always-use-design-tokens-for-colors.md +24 -0
- package/src/standards/web/dark-mode-through-tokens.md +19 -0
- package/src/standards/web/hidden-attribute-loses-to-display.md +22 -0
- package/src/standards/web/overview.md +9 -0
- package/src/standards/web/scss-shared-partial-imports.md +16 -0
- package/src/standards/web/transitions-only-on-user-toggle.md +19 -0
- package/src/standards.md +66 -0
- package/src/tools/overview.md +22 -0
- package/src/tools/scripts/coentrify-update.py +242 -0
- package/src/tools/scripts/unlink-missing-standards.py +138 -0
- package/src/tools/specs/changelog-append.md +15 -0
- package/src/tools/specs/coentrify-json-check.md +21 -0
- package/src/tools/specs/commit-gate.md +32 -0
- package/src/tools/specs/healing-append.md +15 -0
- package/src/tools/specs/landing.md +29 -0
- package/src/tools/specs/refuse-wrap-up-questions.md +22 -0
- package/src/tools/specs/reload-core-rules.md +20 -0
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Name By Concept, Not Copy
|
|
2
|
+
|
|
3
|
+
Identifiers carry the generic concept they represent, never the specific UI copy, translation, or content they happen to hold. A tab helper is `ordersTab`, never a name spelled from its label, even when the label is in the UI's own language. The label string is content and keeps its language. The identifier is code and stays generic English.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Naming by concept keeps the code stable while the copy is free to move.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Name the identifier for what it represents in generic English: `ordersTab`, `SETTINGS_TAB`, `notesLabel`.
|
|
12
|
+
- Keep the literal copy as the string value it points at: `tab(page, '<label in the UI language>')`.
|
|
13
|
+
- Applies everywhere a name is chosen: consts, locals, params, helpers, and test fixtures.
|
|
14
|
+
- Catch it with a lint rule or a sweep ([Pre-Empt Recurring Code-Review Nits](pre-empt-recurring-code-review-nits.md)).
|
|
15
|
+
|
|
16
|
+
## Related
|
|
17
|
+
|
|
18
|
+
- [No Abbreviated Names](no-abbreviated-names.md)
|
|
19
|
+
- [Use US English Everywhere](../behavior/use-us-english-everywhere.md)
|
|
20
|
+
- [Pre-Empt Recurring Code-Review Nits](pre-empt-recurring-code-review-nits.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# No Abbreviated Names
|
|
2
|
+
|
|
3
|
+
Every identifier carries the full name of what it holds, never a single letter or clipped abbreviation. This is language-agnostic: TypeScript locals, params and aliases, SCSS variables, map keys, and CSS/BEM class modifiers all spell things out.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
An abbreviation is an unnecessary abstraction: working out what it stands for costs extra compute.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Name a control-flow alias after the value it holds: `@if (order(); as order)`, never `as o`.
|
|
12
|
+
- In SCSS, name map keys and loop variables for what they are: `@each $modifier, $color in ...`, keys like `categorical-1`, not `c1`.
|
|
13
|
+
- Class/BEM modifiers spell out the concept: `--categorical-1`, `--brand`, not `--c1`.
|
|
14
|
+
- When the source getter, signal, or token already has a good name, reuse it.
|
|
15
|
+
- Enforce it with a lint rule ([Pre-Empt Recurring Code-Review Nits](pre-empt-recurring-code-review-nits.md)).
|
|
16
|
+
|
|
17
|
+
## Related
|
|
18
|
+
|
|
19
|
+
- [Code Principles](code-principles.md)
|
|
20
|
+
- [Pre-Empt Recurring Code-Review Nits](pre-empt-recurring-code-review-nits.md)
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# No Describe-What Comments
|
|
2
|
+
|
|
3
|
+
Don't add comments that describe what a class/function does or which other code consumes it. Naming and reading the code is enough. Behavior lives in the feature docs, and change history in the commits.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
What the code does is said once, by the code and its names.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
Default is no comment. Only keep one for:
|
|
12
|
+
|
|
13
|
+
- Hidden constraints (an invariant the code doesn't make obvious).
|
|
14
|
+
- Library quirks that would tempt a wrong rewrite.
|
|
15
|
+
- Workarounds for a specific bug.
|
|
16
|
+
- Escape hatches that must stay.
|
|
17
|
+
|
|
18
|
+
Two kinds of comment to drop on sight:
|
|
19
|
+
|
|
20
|
+
- A call-graph paraphrase, such as `Builds one config per entity; triggered by the selection page...`.
|
|
21
|
+
- A hardcoded route or path, which rots the moment the route moves.
|
|
22
|
+
|
|
23
|
+
## Related
|
|
24
|
+
|
|
25
|
+
- [Feature Template](../docs/feature-template.md)
|
|
26
|
+
- [Escape Hatch Comments](escape-hatch-comments.md)
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Overview
|
|
2
|
+
|
|
3
|
+
The Code standards: rules that hold in any language.
|
|
4
|
+
|
|
5
|
+
- [Code Principles](code-principles.md) - single responsibility, compose don't extend, generic types, no caller-identity branching
|
|
6
|
+
- [Escape Hatch Comments](escape-hatch-comments.md) - remove an escape hatch if possible, otherwise a why-comment
|
|
7
|
+
- [Name By Concept, Not Copy](name-by-concept-not-copy.md) - identifiers name the concept, never the UI copy
|
|
8
|
+
- [No Abbreviated Names](no-abbreviated-names.md) - spell out every identifier
|
|
9
|
+
- [No Describe-What Comments](no-describe-what-comments.md) - no comments describing what code does. Behavior lives in docs
|
|
10
|
+
- [Pre-Empt Recurring Code-Review Nits](pre-empt-recurring-code-review-nits.md) - pre-empt recurring review nits and lint-enforce them
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Pre-Empt Recurring Code-Review Nits
|
|
2
|
+
|
|
3
|
+
Pre-empt the known recurring review nits while writing the code. When review checks a convention by eye, make tooling enforce it so it stops recurring.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A human reviewer sees only what needs judgment.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Enforce a convention with a lint rule, and run `lint --fix` where the rule can fix it.
|
|
12
|
+
- Before defending a review comment as mistaken, verify the claim against the code or the spec.
|
|
13
|
+
- The CSS `@property` case below is a spec requirement worth defending.
|
|
14
|
+
- An empty override defended on an assumed base throw or call is often harmless and deletable, and the reviewer was right.
|
|
15
|
+
|
|
16
|
+
## Examples
|
|
17
|
+
|
|
18
|
+
- Any language: an empty override reads as dead code. Delete it unless it suppresses an *observable* base side effect (a throw, a network call, a real state change). Building an object that nothing then reads is not observable. Verify the side effect is real before keeping one, and leave a why-comment if it stays.
|
|
19
|
+
- GitHub Actions: pin every action to its full commit SHA, with the version in a comment (`actions/checkout@<sha> # v5.0.0`), and let Dependabot keep the pins current. When one workflow is already ahead, align the rest in the same change.
|
|
20
|
+
- Angular: the order of template attributes is a setting of `@angular-eslint/template/attributes-order`, configured strictly in one shared fragment spread into every template-bearing project's config, so the lint fixes it. Which order is the project's choice.
|
|
21
|
+
- CSS: `@property` with a typed (non-`*`) `syntax` requires `initial-value`, or the registration is invalid and silently dropped. Never delete it to simplify.
|
|
22
|
+
- SCSS: the suffix ampersand (`.modifier &`) is correct but easily misread. Where it is a one-off in the file or codebase, prefer the explicit selector (`.modifier .block__element`).
|
|
23
|
+
|
|
24
|
+
## Related
|
|
25
|
+
|
|
26
|
+
- [Honest Assessments](../behavior/general-working-rules.md#honest-assessments)
|
|
27
|
+
- [Escape Hatch Comments](escape-hatch-comments.md)
|
|
28
|
+
- [Static Attribute, Not Literal Binding](../angular/static-attribute-not-literal-binding.md)
|
|
29
|
+
- [Don't Introduce Tech Debt](../behavior/dont-introduce-tech-debt.md)
|
|
30
|
+
- [Always Add Explicit Types](../typescript/always-add-explicit-types.md)
|
|
31
|
+
- [Code Review Compounds Into Patterns And Sweeps](../behavior/code-review-compounds-into-patterns-and-sweeps.md)
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Commits
|
|
2
|
+
|
|
3
|
+
A commit message names the change at a glance, with a ticket's id where there is one and no attribution. A commit holds one unit a reviewer wants to see.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The history reads and searches by what each commit holds.
|
|
8
|
+
|
|
9
|
+
## Message
|
|
10
|
+
|
|
11
|
+
Name what changed, specifically, so the subject tells the change at a glance without opening the diff.
|
|
12
|
+
|
|
13
|
+
- A commit made for a ticket starts with the ticket's id and a colon: `FEAT-123: the upload retries after a dropped connection`. The id already reads as the ticket's name, so no other prefix or trailer is added.
|
|
14
|
+
- Every other commit uses Conventional Commits: `type(scope): description`, its types `feat`, `fix`, `chore`, `docs`, `refactor`, `revert`, its scope freeform (`deps`, `log`, `standards`).
|
|
15
|
+
- The description starts with a lowercase letter. A project's commitlint accepts both forms and enforces the rest.
|
|
16
|
+
- Commitlint also enforces `body-max-line-length` 100. Each `-m` of `git commit -m` becomes one unwrapped body line, so split a long body across several `-m` flags. The commit-msg hook rejects the whole commit otherwise, after lint-staged has already run.
|
|
17
|
+
|
|
18
|
+
## Ticket Prefix
|
|
19
|
+
|
|
20
|
+
In a project on the tickets workflow ([Work Tracking](../tickets-workflow/work-tracking.md)):
|
|
21
|
+
|
|
22
|
+
- Every commit made for a ticket carries its id: its code, its tests, the wiki's tooling, its Done part and its archive move.
|
|
23
|
+
- A story's merge commit carries the story's id: `STORY-1: users sign up and sign in`. A ticket outside a story merges under its own id.
|
|
24
|
+
- The commit message hook refuses a commit of code or tests without a ticket's or a story's id in front.
|
|
25
|
+
- The main session's commits that serve no single ticket, such as a [Request Log](../records/request-log.md) entry, keep the conventional form.
|
|
26
|
+
- A ticket's commits are found by its id, `git log --grep FEAT-123`, never listed in the ticket.
|
|
27
|
+
|
|
28
|
+
## No Attribution
|
|
29
|
+
|
|
30
|
+
Commit messages contain only the message itself. No `Co-Authored-By` trailers, no "Generated with Claude Code", no AI attribution of any kind. The same holds for PR descriptions. Where the agent adds attribution by itself, its setting switches it off, such as `"attribution": { "commit": "", "pr": "" }` in Claude Code's `.claude/settings.json`.
|
|
31
|
+
|
|
32
|
+
## Size
|
|
33
|
+
|
|
34
|
+
Make smaller commits, grouped by review interest. Mechanical changes can batch. Complex changes get their own commit so a reviewer can find and verify them.
|
|
35
|
+
|
|
36
|
+
For migrations or refactors, batch the mechanical updates, then split out each complex case. Ask: "what would a reviewer want to look at separately?"
|
|
37
|
+
|
|
38
|
+
A branch only ever holds commits ready to land. A commit is never amended once pushed, and a fix goes in as a new commit. An unpushed wrong commit is redone ([Verify Staging Before Committing](verify-staging-before-committing.md)).
|
|
39
|
+
|
|
40
|
+
## Related
|
|
41
|
+
|
|
42
|
+
- [Verify Staging Before Committing](verify-staging-before-committing.md)
|
|
43
|
+
- [A Name Describes Its Unit](../behavior/a-name-describes-its-unit.md)
|
|
44
|
+
- [Work Tracking](../tickets-workflow/work-tracking.md)
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Gate Commits On Exit Codes
|
|
2
|
+
|
|
3
|
+
A commit, a tag or a "done" claim is gated on the exit code of the check itself, never on its printed output.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Only the exit code tells whether a check passed.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Only `&&` stands between the exit-code test and the commit or the tag: no `;`, no `echo "exit $?"`, no edit on the line before that can fail without stopping what follows.
|
|
12
|
+
- Never pipe a check into `grep`, `tail` or `head` before deciding on it, background runs included. Redirect to a file, save `$?`, then read the file. The shape that works: `npm run test:hygiene >check.log 2>&1; rc=$?; [ $rc -eq 0 ] && git commit ...` (never `status` as the variable, zsh holds it read only).
|
|
13
|
+
- A filtered check that prints nothing is not a pass. Read its exit code or its raw tail first.
|
|
14
|
+
- Re-read the last check's output before committing, even when it was green by construction.
|
|
15
|
+
- Where a rule keeps being broken by hand, the check moves into a hook or a script that refuses on its own, a project's commit hook running the hygiene suite on every commit, say ([Parallel Agents](../tooling/parallel-agents.md) lists the scripts).
|
|
16
|
+
- A pipe returns the exit code of its last command, so `build | grep ERROR && git commit` and `suite | tail -30` report green while the check failed. A `;` or an `echo $?` between test and commit runs the commit whatever happened. Each of these has landed broken work, even with this rule loaded.
|
|
17
|
+
- A hook refuses a `git commit` or `git tag` right after a `;`, or after a piped check anywhere before it. A newline between test and commit is not caught, so the same rule holds there.
|
|
18
|
+
|
|
19
|
+
## Related
|
|
20
|
+
|
|
21
|
+
- [Always Verify Before Reporting Done](../behavior/always-verify-before-reporting-done.md)
|
|
22
|
+
- [Verify Staging Before Committing](verify-staging-before-committing.md)
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Main Stays Green, Work Stays Clean
|
|
2
|
+
|
|
3
|
+
Main is always green. Every unit of work leaves the codebase better than it found it, tests included. Agents work clean: no agent makes a mess for another to clean up.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A version can be cut from main at any moment, and red always means something.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- A story's branch is rebased onto main, and its types, unit specs, build and touched suites run green, before it merges ([Parallel Agents](../tooling/parallel-agents.md#landing)). Two branches green apart can be red together (a new field from one, a spec without it from the other).
|
|
12
|
+
- A red main is priority one: it is fixed before anything else lands ([Dev Tiers](../behavior/dev-tiers.md)).
|
|
13
|
+
- Nothing lands red. Tests written failing first live with their work until the implementation turns them green, and land together with it.
|
|
14
|
+
- A failing test gets fixed - the code or the test, whichever is wrong.
|
|
15
|
+
- A flaky test is surfaced as debt and fixed at its cause, never by faking load. Most often the test is not written to be predictable: it waits on time where it should wait on the state it checks, races a frame or a clock, or leans on another case's leftovers. Sometimes the machine runs more suites than it carries, and fewer run at once. A flaky test is never retried until green and never waved through.
|
|
16
|
+
- A test that is no longer relevant is removed only with proof or a solid argument, stated in the commit and the report.
|
|
17
|
+
- A test that exposes a bug becomes that bug's reproducing test: it lands with the fix, never red on its own and never marked to fail.
|
|
18
|
+
- A violation the agent finds is fixed or noted as [Don't Introduce Tech Debt](../behavior/dont-introduce-tech-debt.md) says.
|
|
19
|
+
|
|
20
|
+
## Related
|
|
21
|
+
|
|
22
|
+
- [Work Workflow](../tickets-workflow/work-workflow.md)
|
|
23
|
+
- [Gate Commits On Exit Codes](gate-commits-on-exit-codes.md)
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Overview
|
|
2
|
+
|
|
3
|
+
The Commits standards: how work is committed.
|
|
4
|
+
|
|
5
|
+
- [Commits](commits.md) - a ticket's commits start with its id, FEAT-123: description. Every other commit is a lowercase conventional commit. NO AI attribution anywhere. Split by review interest
|
|
6
|
+
- [Gate Commits On Exit Codes](gate-commits-on-exit-codes.md) - only `&&` stands between the exit-code test and the commit or tag. Never pipe a check into grep or tail
|
|
7
|
+
- [Main Stays Green, Work Stays Clean](main-stays-green-work-stays-clean.md) - main always green and versionable. Nothing lands red. Agents clean their own mess
|
|
8
|
+
- [Verify Staging Before Committing](verify-staging-before-committing.md) - read the staged list before every commit. Explicit paths when others share the tree
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Verify Staging Before Committing
|
|
2
|
+
|
|
3
|
+
Before every `git commit`, read `git diff --cached --name-status` and confirm the commit will hold exactly the files meant for it, no more and no fewer.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
No one else's work is swept into a commit, and nothing meant for it is left behind.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Edit and stage in one call, read the staged status, commit in the next.
|
|
12
|
+
- A batched `git add a b c` aborts on the first bad pathspec and stages nothing new, while earlier staged changes still commit.
|
|
13
|
+
- Printing the stat in the same chained command as the commit is no check, since the commit runs regardless.
|
|
14
|
+
- Never chain the add and the commit: a `git mv` or `git rm` staged early rides into an unrelated commit through `git add ... && git commit`.
|
|
15
|
+
- A hook refuses a commit that follows a `git add` in the same command.
|
|
16
|
+
- Where a project can, a commit-msg hook refuses a `docs(log)` commit that holds anything but the log ([Request Log](../records/request-log.md)).
|
|
17
|
+
- When earlier `git rm` or `git mv` calls of your own left things in the index, `git reset -- <your paths>` first, then stage each commit's list.
|
|
18
|
+
- While anyone else works in the tree - the director, a parallel session, a sub-agent - stage by explicit file name, never a bare `git add -A` and never a directory pathspec, which is `-A` in disguise. A "changed on disk" note about a file you are not editing is the sign.
|
|
19
|
+
- Index entries you did not stage are the director's or another session's: leave them staged, and commit only your own paths with `git commit -- <paths>`.
|
|
20
|
+
- If a wrong commit lands and is unpushed:
|
|
21
|
+
- `git reset HEAD~1` and redo the staging.
|
|
22
|
+
- With someone else in the tree, `git reset --soft HEAD~1`, unstage only what your own staging swept in, leave their entries as they were, and commit only your own paths with `git commit -- <paths>`.
|
|
23
|
+
- The index is shared with everything else in the tree: the director stages files too, and a parallel session or a capture run leaves half-done and untracked files beside yours.
|
|
24
|
+
|
|
25
|
+
## Related
|
|
26
|
+
|
|
27
|
+
- [Review Changes Before Reporting Done](../behavior/review-changes-before-reporting-done.md)
|
|
28
|
+
- [Gate Commits On Exit Codes](gate-commits-on-exit-codes.md)
|
|
29
|
+
- [Commits](commits.md)
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Application Template
|
|
2
|
+
|
|
3
|
+
A workspace contains one or more applications. Each application has its own docs under `docs/<app>/`. Anything cross-app belongs in workspace docs at `docs/`.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Every application's docs have the same structure, and keep the focus of the application.
|
|
8
|
+
|
|
9
|
+
## overview.md
|
|
10
|
+
|
|
11
|
+
Entry point for the application - a reader should grasp the application's size and what it does at a glance. Basis for feature-specific docs that go deeper. Functional only, no implementation detail.
|
|
12
|
+
|
|
13
|
+
- Title: `# <Name>` (optionally with alias in parentheses).
|
|
14
|
+
- Subtitle: one sentence stating the application's purpose.
|
|
15
|
+
- Sections: Users, Features, Views, Functional Debt, Notes.
|
|
16
|
+
|
|
17
|
+
### Sections
|
|
18
|
+
|
|
19
|
+
- `Users` - functional user roles (e.g. "Administrator"). A flat list, then a `###` subheader with a short description per role.
|
|
20
|
+
- `Features` - brief noun phrases in Title Case (e.g. "User Overview", "Create User"). A flat list, then a `###` subheader with a short description per feature (same shape as `Users`).
|
|
21
|
+
- `Views` - user-facing pages and dialogs (e.g. "User List", "Create User (dialog)").
|
|
22
|
+
- `Functional Debt` - what an existing feature lacks (e.g. "Sort Users").
|
|
23
|
+
- `Notes` - caveats and product quirks (e.g. "Role is set on Create. It cannot be changed on Edit.").
|
|
24
|
+
|
|
25
|
+
### Status Markers
|
|
26
|
+
|
|
27
|
+
- A whole feature or view not built yet stands under Features or Views with a `(Not Yet Implemented)` suffix, linking its ticket, or its roadmap item in the simple workflow.
|
|
28
|
+
- The mark stands only on the feature itself, where it is described. A page that merely refers to it carries no mark, since marks spread over references rot once the feature lands.
|
|
29
|
+
- Each `Functional Debt` item links to the roadmap item that resolves it.
|
|
30
|
+
|
|
31
|
+
### Features Ordering
|
|
32
|
+
|
|
33
|
+
- Overview/landing view first.
|
|
34
|
+
- Group by entity (e.g. all User features together).
|
|
35
|
+
- Core features first, secondary later.
|
|
36
|
+
|
|
37
|
+
### Features Naming
|
|
38
|
+
|
|
39
|
+
Lookup/info features use a noun: `<Entity> <Noun>` (e.g. "User Overview"). Action features use a verb: `<Verb> <Entity>` (e.g. "Create User").
|
|
40
|
+
|
|
41
|
+
Standard nouns:
|
|
42
|
+
|
|
43
|
+
- `Overview` - landing view.
|
|
44
|
+
- `Table` - tabular listing.
|
|
45
|
+
- `Pagination` - paginated listing.
|
|
46
|
+
- `Summary` - condensed entity info (e.g. inline row).
|
|
47
|
+
- `Detail` - full entity info (page or drawer).
|
|
48
|
+
|
|
49
|
+
Standard verbs:
|
|
50
|
+
|
|
51
|
+
- `Filter` - narrow a set by criteria.
|
|
52
|
+
- `Sort` - order a set by columns or values.
|
|
53
|
+
- `Search` - targeted lookup by query.
|
|
54
|
+
- `Create` - new entity.
|
|
55
|
+
- `Edit` - mutate existing entity.
|
|
56
|
+
- `Delete` - remove entity.
|
|
57
|
+
|
|
58
|
+
Pluralization:
|
|
59
|
+
|
|
60
|
+
- Nouns: singular (entity type, not instance) - "User Overview", "User Detail".
|
|
61
|
+
- Verbs: plural for set-level operations ("Filter Users", "Sort Users").
|
|
62
|
+
- Verbs: singular for single-entity actions ("Create User", "Edit User", "Delete User", "Search User").
|
|
63
|
+
|
|
64
|
+
### Views Naming
|
|
65
|
+
|
|
66
|
+
Dialog labels follow Features Naming - most are user actions and use the verb pattern (e.g. "Create User (dialog)"). Confirmation dialogs prefix with "Confirm" (e.g. "Confirm Delete User (dialog)").
|
|
67
|
+
|
|
68
|
+
Common kinds: view, dialog, drawer, card.
|
|
69
|
+
|
|
70
|
+
Split logically distinct views even if they share code (e.g. Create and Edit User dialogs).
|
|
71
|
+
|
|
72
|
+
## architecture.md
|
|
73
|
+
|
|
74
|
+
- Technical companion to the app's overview.md - how this app is built, linking out to the workspace docs for shared concerns.
|
|
75
|
+
- Holds per-app technical detail while apps diverge.
|
|
76
|
+
|
|
77
|
+
## Work
|
|
78
|
+
|
|
79
|
+
- An application's work is tracked in the workspace's `docs/development/`.
|
|
80
|
+
- An epic can group the work of one application.
|
|
81
|
+
|
|
82
|
+
## Related
|
|
83
|
+
|
|
84
|
+
- [Documentation Philosophy](documentation-philosophy.md)
|
|
85
|
+
- [Things Of One Kind Are Consistent](../behavior/things-of-one-kind-are-consistent.md)
|
|
86
|
+
- [Docs Folder Structure](docs-folder-structure.md)
|
|
87
|
+
- [Workspace Template](workspace-template.md)
|
|
88
|
+
- [Converge Only Once Proven](../architecture/converge-only-once-proven.md)
|
|
89
|
+
- [Work Tracking](../tickets-workflow/work-tracking.md)
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Docs Are Hierarchical, Explicit And Short
|
|
2
|
+
|
|
3
|
+
Knowledge pages are organized as a hierarchy and written for a human to read: a page per thing, its items under headings, every thing named outright, and one short sentence per list item.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A hierarchy gives every page the right focus level, for efficient and effective communication.
|
|
8
|
+
|
|
9
|
+
## A Page
|
|
10
|
+
|
|
11
|
+
- The page opens with a summary at its own focus level, one or two lines right under the title: what the thing is and what it is for, no details and no visual description, which rot when the look changes.
|
|
12
|
+
- An introduction, when the page needs one, is distinct from the summary: it is the first item of the contents, where the content begins.
|
|
13
|
+
- Then a contents section one focus level deeper, under a heading that fits the thing: `## Parts`, `## Features`. The items are grouped by what they do (`### Account Settings`, `### Billing`), one line each with a dash and a few words ("The Profile - Name And Photo").
|
|
14
|
+
- Then a `##` heading per item, in the same order. An item with one or a few things to say gets one line under its heading and a link to its own page. An item with more gets a page of its own, its features under headings. Sub-items take `###`.
|
|
15
|
+
- The look of the thing goes under an `## <Thing> Aesthetics` heading, in prose.
|
|
16
|
+
- A section with subsections opens with a short list of them as in-page links before its own text.
|
|
17
|
+
- A page holds only what relates to its own thing and its state. A fact that is always true, or that belongs to another thing, lives on that thing's page.
|
|
18
|
+
- An overview nests its stages by their grouping, never one flat list across groups.
|
|
19
|
+
- A summary or a description of a linked page stays at the focus level of the page it stands on, without details or specs.
|
|
20
|
+
- A line in a list relates its item to its siblings and its parent only, so it shows how the items differ in function and where they relate.
|
|
21
|
+
- The focus level of an overview is how it all ties together.
|
|
22
|
+
|
|
23
|
+
## Folders
|
|
24
|
+
|
|
25
|
+
- A thing whose items have pages of their own is a folder: its `overview.md` is the thing's own page and every item's page sits beside it, never a page standing outside the folder of its name. A simple thing stays a single file.
|
|
26
|
+
- The same holds one level up: a group's index page is its folder's `overview.md`.
|
|
27
|
+
- The wiki's sidebar follows the folders ([VitePress Wiki](../tooling/vitepress-wiki.md)).
|
|
28
|
+
|
|
29
|
+
## Writing
|
|
30
|
+
|
|
31
|
+
- Name things outright: the settings page, never "the page the gear icon opens".
|
|
32
|
+
- An abbreviation the project coins is spelled out where a page first uses it, headings included, the short form in brackets after: Single Source Of Truth (SSOT). Common ones, UI or CPU, need no spelling out.
|
|
33
|
+
- One short sentence per list item. Several facts become several items or a short paragraph under a heading, never a long list of long items.
|
|
34
|
+
- Good organization beats both lists and prose: structure first, then short lists, prose only for descriptive matter such as the look.
|
|
35
|
+
- A one-line statement under a heading is a spec that leads to a test.
|
|
36
|
+
- Plans, logs and changelogs keep their own shapes.
|
|
37
|
+
|
|
38
|
+
## How To Apply
|
|
39
|
+
|
|
40
|
+
- Legacy pages get rewritten page by page, with one model page reviewed by the director first.
|
|
41
|
+
|
|
42
|
+
## Related
|
|
43
|
+
|
|
44
|
+
- [Documentation Philosophy](documentation-philosophy.md)
|
|
45
|
+
- [Docs Describe Behavior, Not Wiring](docs-describe-behavior-not-wiring.md)
|
|
46
|
+
- [Feature Template](feature-template.md)
|
|
47
|
+
- [Docs State Knowledge](docs-state-knowledge.md)
|
|
48
|
+
- [VitePress Wiki](../tooling/vitepress-wiki.md)
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Docs Describe Behavior, Not Wiring
|
|
2
|
+
|
|
3
|
+
A doc describes its thing at the focus level of its page: what it does, and how it is built as a whole ([Docs Are Hierarchical, Explicit And Short](docs-are-hierarchical-explicit-and-short.md)). A detail that only the code keeps true lives in the code.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A doc stays true while the code changes.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- The overview, a feature doc and a spec describe what something does for the user, and the states it goes through.
|
|
12
|
+
- The paths a user takes, as flows and use cases, live in the spec.
|
|
13
|
+
- The architecture doc holds the decisions and describes the whole: the layers and the folders that carry them, such as `ui`, the libraries chosen and why, and the conventions.
|
|
14
|
+
- A concern doc does the same for one concern, such as authentication or testing.
|
|
15
|
+
- File paths, the names of classes, services and components, and the wiring between them stay in the code, since they change with it.
|
|
16
|
+
- A debt ticket or debt entry holds the technical detail its work needs.
|
|
17
|
+
- Concrete endpoints and environment URLs live only in a concern doc of their own under `docs/workspace/`, such as `api.md` and `environments.md`. Credentials live in no doc.
|
|
18
|
+
- When a doc reads like a copy of the code, cut to the throughline: keep the essence, and drop the specifics.
|
|
19
|
+
|
|
20
|
+
## Related
|
|
21
|
+
|
|
22
|
+
- [Documentation Philosophy](documentation-philosophy.md)
|
|
23
|
+
- [Docs Are Hierarchical, Explicit And Short](docs-are-hierarchical-explicit-and-short.md)
|
|
24
|
+
- [Workspace Template](workspace-template.md)
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Docs Folder Structure
|
|
2
|
+
|
|
3
|
+
A project's docs live at `docs/`, the main entry point and the wiki's root. Each folder has one job.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Every folder answers one question, so a reader knows where a fact belongs before looking.
|
|
8
|
+
|
|
9
|
+
## Root
|
|
10
|
+
|
|
11
|
+
- `overview.md` - what the product is, functional only.
|
|
12
|
+
- `architecture.md` - how it is built: the decisions, layers, libraries and conventions.
|
|
13
|
+
- Nothing feature-specific or work-tracking sits at the root.
|
|
14
|
+
|
|
15
|
+
## Knowledge
|
|
16
|
+
|
|
17
|
+
- `docs/features/` - the feature docs: the product as decided ([Feature Template](feature-template.md)).
|
|
18
|
+
- `docs/<app>/` - in a workspace with several apps, each app's docs, shaped like the root: its overview, architecture and features ([Application Template](application-template.md)).
|
|
19
|
+
- `docs/workspace/` - the cross-cutting concern docs as flat files: `authentication.md`, `design-system.md`, `testing.md` and the like ([Workspace Template](workspace-template.md)).
|
|
20
|
+
|
|
21
|
+
## Work
|
|
22
|
+
|
|
23
|
+
- `docs/development/` - all work tracking, whichever the workflow: the lists of the simple workflow ([The Simple Workflow](../simple-workflow/the-simple-workflow.md)), or the tickets, their generated lists and the archive ([Work Tracking](../tickets-workflow/work-tracking.md)), and the director's own tasks beside either ([Communication Boundary](../behavior/communication-boundary.md)).
|
|
24
|
+
|
|
25
|
+
## Records
|
|
26
|
+
|
|
27
|
+
All records sit together under `docs/records/`, one group in the wiki with an `overview.md` listing them. Each record folder is a dated trail, written as things happen. Its shape lives in its own standard.
|
|
28
|
+
|
|
29
|
+
- `docs/records/log/` - everything the director says, one file per day ([Request Log](../records/request-log.md)).
|
|
30
|
+
- `docs/records/activity/` - the work done, one file per day ([Activity Log](../records/activity-log.md)).
|
|
31
|
+
- `docs/records/playtests/` - one file per playtest of a game ([Playtest Files](../records/playtest-files.md)).
|
|
32
|
+
- `docs/records/user-tests/` - one file per session with real users ([User Test Files](../records/user-test-files.md)).
|
|
33
|
+
- `docs/records/changelog/` - one page per version ([Changelog Per Version](../records/changelog-per-version.md)).
|
|
34
|
+
- Any other dated trail a project keeps joins them under `docs/records/`, never at the docs root.
|
|
35
|
+
|
|
36
|
+
## Related
|
|
37
|
+
|
|
38
|
+
- [Docs Are Hierarchical, Explicit And Short](docs-are-hierarchical-explicit-and-short.md)
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Docs State Knowledge
|
|
2
|
+
|
|
3
|
+
A knowledge page (feature docs, specs, design pages, laws, architecture, overview) stands on its own and states what is true, the way an encyclopedia does: no attribution markers, no dates of decisions, no quoted sentences of the director's, no account of how a decision came about or what it replaced.
|
|
4
|
+
|
|
5
|
+
The provenance lives in the request log, where every message is written first, and in the process records that point back to it: user tests, changelogs, activity, the plan, the refine list, and any other record the project keeps. Those may name who said what and when.
|
|
6
|
+
|
|
7
|
+
## Why
|
|
8
|
+
|
|
9
|
+
A knowledge page reads as what is true now. The log holds who said what and when.
|
|
10
|
+
|
|
11
|
+
## How To Apply
|
|
12
|
+
|
|
13
|
+
- Writing or editing a knowledge page: state the fact in plain present tense. Leave the attribution, the date and the quote in the log.
|
|
14
|
+
- The director's say over the docs still holds ([Docs Hold Only What The Director Decided](../behavior/docs-hold-only-what-the-director-decided.md)): only what the director said or approved goes in. The check is the log, never a marker on the line.
|
|
15
|
+
- Organize a page by topic, broad to specific, the way an encyclopedia article is. Never a running list in the order things were decided.
|
|
16
|
+
- Briefs tell agents the same. A brief never asks an agent to mark what it quotes.
|
|
17
|
+
- The project's hygiene suite can enforce it: no attribution markers and no dated attribution outside the log and the process records.
|
|
18
|
+
|
|
19
|
+
## Related
|
|
20
|
+
|
|
21
|
+
- [Documentation Philosophy](documentation-philosophy.md)
|
|
22
|
+
- [Request Log](../records/request-log.md)
|
|
23
|
+
- [Agent Roles](../tickets-workflow/agent-roles.md)
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Documentation Philosophy
|
|
2
|
+
|
|
3
|
+
Project docs describe what the product does, briefly and with one purpose per file, and hold enough to rebuild the product from them.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The docs orient every reader, and they are the basis for manual testing and for generating tests.
|
|
8
|
+
|
|
9
|
+
## What The Product Does
|
|
10
|
+
|
|
11
|
+
Docs describe what the product does and who uses it. The architecture doc holds the decisions about how it is built, and the details stay in the code ([Docs Describe Behavior, Not Wiring](docs-describe-behavior-not-wiring.md)).
|
|
12
|
+
|
|
13
|
+
## Brevity
|
|
14
|
+
|
|
15
|
+
A name of a feature, a view or an item is a short phrase ("Invite User", "Deactivate User"). A fact is a short sentence. Small lists of short items beat connecting sentences. The overview is a scannable product summary. Depth lives in the feature pages and their parts' pages, shaped and worded per [Docs Are Hierarchical, Explicit And Short](docs-are-hierarchical-explicit-and-short.md), which also owns naming things outright.
|
|
16
|
+
|
|
17
|
+
## One Purpose Per File
|
|
18
|
+
|
|
19
|
+
Each doc has a narrow job. Don't cram specifications into an overview. Don't cram technical debt into a feature list. If a fact doesn't fit the file's job, it lives in another file.
|
|
20
|
+
|
|
21
|
+
## No Meta About The Doc Inside The Doc
|
|
22
|
+
|
|
23
|
+
Don't open a doc with a paragraph explaining what the doc is for or how to read it ("Known bugs in the current build. Each entry links to..."). That kind of rule lives in the template or standard for the doc type. The doc itself jumps straight to content - readers know what `bugs.md` is from the filename and the H1.
|
|
24
|
+
|
|
25
|
+
## User-Facing Concepts
|
|
26
|
+
|
|
27
|
+
Even when the code reuses a single component for multiple flows, doc readers care about the user-facing concept. Split "Create User dialog" and "Edit User dialog" into two items. Don't collapse them because the code does.
|
|
28
|
+
|
|
29
|
+
## Plain Punctuation
|
|
30
|
+
|
|
31
|
+
ASCII over typographic polish, per [Normal Dashes](../behavior/normal-dashes.md).
|
|
32
|
+
|
|
33
|
+
## Readable Headings
|
|
34
|
+
|
|
35
|
+
Title case for document titles (`# Admin`). Sections use short functional names (`## Users`, `## Features`, `## Views`), not compound labels like `## Pages / views` or `## Flows / use-cases`.
|
|
36
|
+
|
|
37
|
+
## Consistent Structure Across Apps
|
|
38
|
+
|
|
39
|
+
When a structure is agreed for one app's doc, the same structure applies to every app. No per-app prose variations.
|
|
40
|
+
|
|
41
|
+
## Simple Markdown
|
|
42
|
+
|
|
43
|
+
Standard syntax. Prefer flat dash lists. Avoid numbered lists. Hierarchy comes from headings and from a page per part: a point with parts gets a subsection of its own. Nested bullets are allowed but strongly discouraged. E.g.:
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
## List
|
|
47
|
+
- Item 1
|
|
48
|
+
- Item 2
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
## The Product As It Is Now
|
|
53
|
+
|
|
54
|
+
A product doc states what the product is now, one fact per bullet, grouped under headings, without dates, provenance or change history ([Docs State Knowledge](docs-state-knowledge.md)).
|
|
55
|
+
|
|
56
|
+
## Reproducible From The Docs
|
|
57
|
+
|
|
58
|
+
The rule of thumb for a project's docs as a whole: another agent, handed the docs without the codebase, rebuilds the product in its essence, small changes and interpretations expected. A fact the product depends on that lives only in the code or the chat is a gap. A cleanup moves information to its right place and never drops anything valuable.
|
|
59
|
+
|
|
60
|
+
## Related
|
|
61
|
+
|
|
62
|
+
- [Docs Describe Behavior, Not Wiring](docs-describe-behavior-not-wiring.md)
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Feature Spec Template
|
|
2
|
+
|
|
3
|
+
One spec per feature, beside its [feature doc](feature-template.md).
|
|
4
|
+
|
|
5
|
+
## Purpose
|
|
6
|
+
|
|
7
|
+
The functional list of use cases a person can run by hand and the e2e file implements as `test()`s, one per stable id. Use cases are functional. "Test case" is reserved for the e2e code.
|
|
8
|
+
|
|
9
|
+
The spec is the only place use cases and step-by-step scenarios live.
|
|
10
|
+
|
|
11
|
+
Title: `# <Feature Name>`, matching the feature doc. A subtitle only when the scope isn't obvious.
|
|
12
|
+
|
|
13
|
+
## Why
|
|
14
|
+
|
|
15
|
+
A feature is verified the same way by hand and by e2e, through one set of use cases.
|
|
16
|
+
|
|
17
|
+
## Use Cases
|
|
18
|
+
|
|
19
|
+
`## Use Cases` opens with a flat overview list of every case, ``<description> (`<feature-id>-N`)``, ordered by id. Below it, each case is its own `###` heading, which scans better than a nested-bullet wall and gives each case a real anchor.
|
|
20
|
+
|
|
21
|
+
## Use Case Shape
|
|
22
|
+
|
|
23
|
+
- Subheading: ``### <Use Case Name> (`<feature-id>-N`)``, the name in Title Case and the same as its test's title ([E2E Test Conventions](../e2e/e2e-test-conventions.md#title)). ID format matches the overview list so the two read identically.
|
|
24
|
+
- Body: flat dash list. No nesting.
|
|
25
|
+
- Step order: start state, action, confirm(s), each step its own bullet. Never one arrow-chained sentence. Multi-action cases add more action and confirm bullets. Tightly coupled inverse actions (open + dismiss) can share one case.
|
|
26
|
+
- Static-baseline cases (e.g. touch-target sizing) may use a start-state bullet then confirm bullet(s) without an action - the case is an observation about the rendered state.
|
|
27
|
+
|
|
28
|
+
Example:
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
### List Unresolved Requests (`inbox-1`)
|
|
32
|
+
|
|
33
|
+
- On the request overview
|
|
34
|
+
- open the inbox from the navigation
|
|
35
|
+
- confirm the list shows the unresolved requests
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Start State
|
|
39
|
+
|
|
40
|
+
- First step describes the start state functionally, not as an action. Prefix with `On ` so it reads as a state declaration: "On mobile viewport, sidebar overlay open."
|
|
41
|
+
- Auth, navigation, and prior setup are implied by the state, not enumerated as steps. Auth is mocked - never write "Sign in" as a step.
|
|
42
|
+
- Self-contained: each case repeats whatever start state it needs, never "Reach the state from `<other-id>`". The IDs are anchors for e2e tags, not for chaining.
|
|
43
|
+
- Be explicit about preconditions that flip the case: "On a fresh visit, not signed in." is clearer than "On a fresh visit." when the case is about the unauthenticated flow. Extra confirms beat leaving anything ambiguous.
|
|
44
|
+
- State declarations and confirms are from the user's side, never the system's: "with an expired session", not "with stored credentials that have expired".
|
|
45
|
+
|
|
46
|
+
### Actions
|
|
47
|
+
|
|
48
|
+
- An action states the user's intent: what they are trying to do and, where it helps, what for. "The user submits the details to get into the records", not "clicks the login button" and not "triggers the login" - a reworded gesture is still a gesture.
|
|
49
|
+
- Each layer toward the code gets more technical: the feature doc states a capability ("the user can save a draft"), the spec states the intent per step ("saves the draft to finish it later"), the e2e does the gestures ("fill the form, press save").
|
|
50
|
+
- Never implementation verbs: tap, click, type, drag, swipe, press, hover, unless the gesture is the feature itself.
|
|
51
|
+
- One user intent per step.
|
|
52
|
+
|
|
53
|
+
### Confirms
|
|
54
|
+
|
|
55
|
+
- Always confirm the result of an action - the action step alone is not enough. The case is verified by the visible outcome.
|
|
56
|
+
- One observation per step. Multiple confirms after a single action are fine and often clearer than one packed sentence.
|
|
57
|
+
- Insert an intermediate confirm between two actions when the first action could realistically fail or produce an unexpected state - otherwise the second action runs on an unverified premise and the eventual failure points the wrong way. Pure data-entry actions (type a comment, tick a box) can skip the intermediate confirm and merge with the next action.
|
|
58
|
+
- Negative confirms must be observable. "No silent re-auth is attempted" is too vague to assert. "No redirect to the sign-in provider occurs" is concrete.
|
|
59
|
+
|
|
60
|
+
### Other Rules
|
|
61
|
+
|
|
62
|
+
- No state-marker tags like `(auth required)` on cases. A case that is about such a state lives in that feature's own spec.
|
|
63
|
+
- Steps stay brief, succinct, and functional - no selectors, no component names, no implementation language. Literal UI labels in backticks are allowed (e.g. `Save`).
|
|
64
|
+
|
|
65
|
+
## Stable IDs
|
|
66
|
+
|
|
67
|
+
- IDs never renumber. Adding a case adds a new ID. Removing one leaves the gap.
|
|
68
|
+
- An id changes only together with every reference to it, its tags and links included, in one change ([Propagate Renames And Convention Changes Everywhere](../behavior/propagate-renames-and-convention-changes-everywhere.md)).
|
|
69
|
+
- E2E tests carry the matching `@<feature-id>-N` tag. The spec is the source of truth.
|
|
70
|
+
|
|
71
|
+
## Coverage
|
|
72
|
+
|
|
73
|
+
- One use case per scenario worth verifying, including each edge case from the feature doc.
|
|
74
|
+
- Every spec ends with an `Overview` use case (`<feature-id>-overview` ID, no number) that strings the happy-path flows of the feature into a single showcase tour. This case is the source of truth for the overview take. Keep it concise - showcase main features, skip edge cases.
|
|
75
|
+
- Add the spec entry first, then the test that covers it.
|
|
76
|
+
- When finalizing, audit coverage in both directions: every feature and edge case in the feature doc has at least one use case here, and every use case maps to a feature or edge case there. Close a gap by writing the missing entry or moving the case to the spec that owns it.
|
|
77
|
+
- A use case lives in the spec of its *primary* feature. If a case is really about another feature (e.g. a search behavior that only happens to be exercised through a responsive scenario), move it to that feature's spec - don't duplicate.
|
|
78
|
+
- Not every use case lands as an e2e test. Visual, styling, and a11y assertions (font sizing, border radius, touch-target sizes) belong in the UI / styleguide test layer.
|
|
79
|
+
- The spec still lists the case. The layer depends on what the case verifies.
|
|
80
|
+
- The e2e file leaves a comment pointing to the layer that owns a skipped case, and the case in the spec gets a trailing `_Verified at the UI / styleguide layer._` italic note.
|
|
81
|
+
- One case = one scenario. If a case has conditional confirms that depend on environment or context ("In production... / In non-production..."), split it - a real test can only run in one mode at a time, and a smashed-together case verifies one branch in any single run.
|
|
82
|
+
|
|
83
|
+
## Related
|
|
84
|
+
|
|
85
|
+
- [Feature Workflow](../behavior/feature-workflow.md)
|
|
86
|
+
- [No Faux Headers In Lists](no-faux-headers-in-lists.md)
|
|
87
|
+
- [E2E Test Conventions](../e2e/e2e-test-conventions.md)
|
|
88
|
+
- [E2E Tests Must Demonstrate Behavior](../e2e/e2e-tests-must-demonstrate-behavior.md)
|
|
89
|
+
- [Per-Feature Overview Test](../e2e/per-feature-overview-test.md)
|