coentrify 0.0.1 → 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 +5 -4
- 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
package/src/readme.md
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Spec-Driven Development
|
|
2
|
+
|
|
3
|
+
Humans direct. Systems check. Agents work.
|
|
4
|
+
|
|
5
|
+
Coentrify is a harness for working with AI in a spec-driven way: standards, checks and tools, resting on four principles.
|
|
6
|
+
|
|
7
|
+
Every caught mistake strengthens the harness, so the system heals itself and keeps learning.
|
|
8
|
+
|
|
9
|
+
## Quick Start
|
|
10
|
+
|
|
11
|
+
To coentrify a project is to align the project with spec-driven development.
|
|
12
|
+
|
|
13
|
+
Prompt your agent to start the [onboarding](onboarding.md):
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
npx coentrify
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
On a machine without Node, the prompt carries the source instead:
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
set up coentrify in this project: https://github.com/coentrify/coentrify
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Adopt the defaults, pick what to use, and customize to fit the project.
|
|
26
|
+
|
|
27
|
+
See all [commands](commands.md).
|
|
28
|
+
|
|
29
|
+
## The Problem With Vibe Coding
|
|
30
|
+
|
|
31
|
+
The dream version of vibe coding is a one-prompt wonder. For example:
|
|
32
|
+
|
|
33
|
+
> build GTA6 in minecraft. make no mistakes.
|
|
34
|
+
|
|
35
|
+
The result will have elements of both games, along with bugs, assumptions and random creative choices. If you expect a perfect game, you're going to have a bad time.
|
|
36
|
+
|
|
37
|
+
An agent can build anything. Without a functional specification, anything is what you'll get.
|
|
38
|
+
|
|
39
|
+
## Always Make No Mistakes
|
|
40
|
+
|
|
41
|
+
Mistakes keep happening, and that is expected.
|
|
42
|
+
|
|
43
|
+
[Always Make No Mistakes](standards/behavior/always-make-no-mistakes.md) builds a self-healing feedback loop into the project. A mistake or a gap that is caught gets fixed twice: once in the work, and once in the harness, as a standard or a check.
|
|
44
|
+
|
|
45
|
+
A mistake can still come back. Round after round the system learns: it slowly stabilizes, and it adapts to its director, its agents and its project.
|
|
46
|
+
|
|
47
|
+
The [proof](proof.md) page shows the loop at work.
|
|
48
|
+
|
|
49
|
+
## What Is Spec-Driven Development?
|
|
50
|
+
|
|
51
|
+
Spec-driven development (SDD) starts with one question:
|
|
52
|
+
|
|
53
|
+
> What is it, exactly, that you want?
|
|
54
|
+
|
|
55
|
+
What you want is written down in layers. Overview and feature docs come first, then use cases and specs, then tests and code. Every layer is checked against the layer before, and a gap between two layers shows what is missing.
|
|
56
|
+
|
|
57
|
+
Humans are creative, agents are hardworking, and systems are rigid. So humans decide what the product does, agents do the work, and systems run the checks. The human who directs a project is called the director.
|
|
58
|
+
|
|
59
|
+
Coentrify gives any input a quality baseline. The creating and the deciding stay with the director.
|
|
60
|
+
|
|
61
|
+
## Elements
|
|
62
|
+
|
|
63
|
+
- [Philosophy](philosophy.md) - The four principles the system rests on, a compass.
|
|
64
|
+
- [Standards](standards.md) - The rules and templates a project adopts.
|
|
65
|
+
- [Tools](tools/overview.md) - The update script, and a spec for every check a project builds itself.
|
|
66
|
+
- [How It Works](how-it-works.md) - From any input to what you want.
|
|
67
|
+
- [Proof](proof.md) - The experiments behind the standards, with the models tested.
|
|
68
|
+
- [Glossary](glossary.md) - The terms coentrify uses most, in plain words.
|
|
69
|
+
|
|
70
|
+
## Wiki
|
|
71
|
+
|
|
72
|
+
Everything here reads as a wiki at [coentrify.com](https://coentrify.com/).
|
|
73
|
+
|
|
74
|
+
## License
|
|
75
|
+
|
|
76
|
+
MIT-0. Take what you need. There is no notice to carry.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Recommendations
|
|
2
|
+
|
|
3
|
+
Recommendations and considerations for adopting coentrify.
|
|
4
|
+
|
|
5
|
+
- Standards - which modules a project adopts
|
|
6
|
+
- Workflow - how the work is tracked
|
|
7
|
+
- Records - which dated trails the project keeps
|
|
8
|
+
- Wiki - whether the docs are served as a wiki
|
|
9
|
+
- Healing - who strengthens the harness after a mistake
|
|
10
|
+
- Folders - where the docs and the standards go
|
|
11
|
+
|
|
12
|
+
## Standards
|
|
13
|
+
|
|
14
|
+
### Always
|
|
15
|
+
|
|
16
|
+
- Behavior - how an agent works and what an agent checks, with the Core Rules in it
|
|
17
|
+
- Docs - documentation rules and templates
|
|
18
|
+
- Security - hard boundaries: no personal data in a request, no secret within an agent's reach, and no keychain
|
|
19
|
+
|
|
20
|
+
Normal Dashes and Prose Style are taste. Coentrify recommends both, because docs that sound like AI annoy a human reader fast, and a project can leave them out.
|
|
21
|
+
|
|
22
|
+
Use US English Everywhere is a choice. One variant everywhere is what counts, and a project that writes UK English overrides the standard with its own.
|
|
23
|
+
|
|
24
|
+
### When The Stack Fits
|
|
25
|
+
|
|
26
|
+
- Code - any codebase
|
|
27
|
+
- Architecture - a codebase with more than one application or layer
|
|
28
|
+
- Tests - a project that has tests, or needs them
|
|
29
|
+
- TypeScript - a TypeScript codebase
|
|
30
|
+
- Angular - an Angular application
|
|
31
|
+
- Web - a project that runs in a browser, for the rules about HTML and CSS
|
|
32
|
+
- UI - a project with a user interface
|
|
33
|
+
- E2E - a project with a browser interface
|
|
34
|
+
- Electron - an Electron application
|
|
35
|
+
- Tooling - a project with a dev server, a wiki or browser tests
|
|
36
|
+
- Scripts - a project that runs on npm scripts
|
|
37
|
+
- AI - a project that builds with models
|
|
38
|
+
|
|
39
|
+
### Picked By The Director
|
|
40
|
+
|
|
41
|
+
- Gamedev - a game, where the director picks the game design laws that apply. It brings the tickets workflow, the activity log, and playtests once others play
|
|
42
|
+
- Reporting - a project whose director wants reports and reels
|
|
43
|
+
- Commits - how work is committed and gated. The module is strongly opinionated, so the director decides which of its standards to adopt
|
|
44
|
+
|
|
45
|
+
## Workflow
|
|
46
|
+
|
|
47
|
+
- Simple - recommended for a small project, a proof of concept or a prototype
|
|
48
|
+
- Tickets - recommended for a medium or larger project
|
|
49
|
+
|
|
50
|
+
Tracking the work is part of coentrify, and a workflow is strongly recommended.
|
|
51
|
+
|
|
52
|
+
- Where the work lives outside the repository, such as in Jira, the Simple workflow is recommended, with its lists left out of version control.
|
|
53
|
+
- Where the project already has a different or better system, adopt that system.
|
|
54
|
+
- Hook the entry points for debt, bugs and inbox items into the system that is used, so every finding has a place to go.
|
|
55
|
+
|
|
56
|
+
## Records
|
|
57
|
+
|
|
58
|
+
A record is a dated trail, written as things happen. An agent starts every session without the last one, so records are how a project remembers.
|
|
59
|
+
|
|
60
|
+
- [Request log](standards/records/request-log.md) - everything the director asks, a page per day, so nothing that was asked gets lost
|
|
61
|
+
- [Activity log](standards/records/activity-log.md) - the work that was done, a page per day that opens like a standup, so the director catches up at a glance
|
|
62
|
+
- [Changelog](standards/records/changelog-per-version.md) - a page per version, so everyone sees what landed
|
|
63
|
+
- [Healing log](standards/records/healing-log.md) - every change automatic healing made, so the director can rule on each one later
|
|
64
|
+
- [Playtests](standards/records/playtest-files.md) - a page per playtest of a game, so feedback turns into work
|
|
65
|
+
- [User tests](standards/records/user-test-files.md) - the same for a product, a page per session with real users
|
|
66
|
+
|
|
67
|
+
Which records to keep depends on the project, record by record.
|
|
68
|
+
|
|
69
|
+
- The request log - for a project with one director. Where other people read the project, the director weighs it first, since it holds every word the director said.
|
|
70
|
+
- The activity log - for a team that holds standups, and for a game whose director wants a daily trail
|
|
71
|
+
- The changelog - for every project that ships versions
|
|
72
|
+
- The healing log - for every project whose healing is automatic
|
|
73
|
+
- Playtests - for a game, once other people play it
|
|
74
|
+
- User tests - for a product, once real users try it
|
|
75
|
+
|
|
76
|
+
Records also keep their value. A newer or better model can go back through the records, find patterns and hidden gems, and improve the system. That use is optional.
|
|
77
|
+
|
|
78
|
+
## Wiki
|
|
79
|
+
|
|
80
|
+
- A wiki - recommended for every project that keeps docs, built with VitePress or a similar tool
|
|
81
|
+
- No wiki - for a project too small to need one
|
|
82
|
+
|
|
83
|
+
## Healing
|
|
84
|
+
|
|
85
|
+
A caught mistake strengthens the harness: a rule gets sharper, or a check is added. `healing` in `coentrify.json` says who makes that change.
|
|
86
|
+
|
|
87
|
+
- Automatic - recommended: a subagent makes the change outside the task at hand, logs it in the healing log, and the report names it for a veto
|
|
88
|
+
- Review - the change is filed in the project's workflow, and waits for the director
|
|
89
|
+
|
|
90
|
+
### Filing
|
|
91
|
+
|
|
92
|
+
A contributor also files a change that holds beyond the project with coentrify ([File A Change With Coentrify](standards/behavior/file-a-change-with-coentrify.md)). `filing` says who files it.
|
|
93
|
+
|
|
94
|
+
- Review - recommended: the director looks at the issue before it is filed, since the source is public
|
|
95
|
+
- Automatic - the subagent files it on its own
|
|
96
|
+
|
|
97
|
+
## Folders
|
|
98
|
+
|
|
99
|
+
- `docs` - the docs
|
|
100
|
+
- `standards` - the standards
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Match Known Commands Deterministically, Classify The Rest
|
|
2
|
+
|
|
3
|
+
Route known requests through exact matching first, and use the model only for what the matcher misses. Never let the model invent the set of things the system can do.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A command the user relies on behaves the same every time, costs no latency and works without the model.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Match the common phrasings deterministically, and treat that as the fast path.
|
|
12
|
+
- Exact matching alone is brittle: a typo drops the user into a conversational path that may refuse them.
|
|
13
|
+
- On a miss, ask the model to classify the request into a fixed list of known actions plus an explicit "none".
|
|
14
|
+
- Classifying into a fixed list is the one job small models do reliably, so the model belongs on the fallback path.
|
|
15
|
+
- Give the classifier worked examples, including deliberate misspellings, and negative examples for requests that merely sound like a command.
|
|
16
|
+
- Build any capability or help listing from what is wired up, never from the model, or it will describe abilities that do not exist.
|
|
17
|
+
- Only the action path may report an action as done, and every request that can reach both paths is tested for a false "done".
|
|
18
|
+
|
|
19
|
+
## Related
|
|
20
|
+
|
|
21
|
+
- [Prompt Small Models Differently](prompt-small-models-differently.md)
|
|
22
|
+
- [General Working Rules](../behavior/general-working-rules.md)
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# Overview
|
|
2
|
+
|
|
3
|
+
The AI standards: building with models.
|
|
4
|
+
|
|
5
|
+
- [Match Known Commands Deterministically, Classify The Rest](match-known-commands-deterministically-classify-the-rest.md) - exact-match known commands, let the model classify only the misses
|
|
6
|
+
- [Prompt Small Models Differently](prompt-small-models-differently.md) - small models get their own short, rule-shaped, low-temperature prompt
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Prompt Small Models Differently
|
|
2
|
+
|
|
3
|
+
A prompt written for a frontier model degrades a small local one. Give each model tier its own prompt and let them diverge.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Each model tier answers best on a prompt written for it.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- A small model loses the thread in long, multi-part instructions and fills gaps confidently: asked about state it cannot see, it answers with a plausible number instead of saying it cannot know.
|
|
12
|
+
- Keep the instruction short and rule-shaped: a numbered list of hard rules beats prose paragraphs.
|
|
13
|
+
- Lower the temperature for rule-following work. Creative defaults invent state.
|
|
14
|
+
- State a fact more than one way when it must survive rephrasing, since a small model will answer one phrasing and miss its synonym.
|
|
15
|
+
- Bound the reply length in the request as well as in the prompt.
|
|
16
|
+
- Each time the system gains a capability, re-read the prompt for rules that now contradict it: a rule from before, such as "you cannot see the screen", keeps the model refusing once the screen is wired up, and the symptom looks like a model problem.
|
|
17
|
+
|
|
18
|
+
## Related
|
|
19
|
+
|
|
20
|
+
- [Match Known Commands Deterministically, Classify The Rest](match-known-commands-deterministically-classify-the-rest.md)
|
|
21
|
+
- [Honest Assessments](../behavior/general-working-rules.md#honest-assessments)
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# canMatch + Wildcard For Route Access
|
|
2
|
+
|
|
3
|
+
Route access guards, for logged-in and logged-out gating, use `canMatch` with a wildcard at the bottom of the route table.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A user who may not enter a route still lands on the right page.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Use CanMatch in favor of CanActivate in order to allow multiple root redirects.
|
|
12
|
+
- Pair with `{ path: '**', redirectTo: '/' }` wildcard at the bottom of the route table.
|
|
13
|
+
- Guards stay route-agnostic in the core layer of [App-Shield](../architecture/app-shield.md) - no `Router`, no path strings, no `UrlTree`.
|
|
14
|
+
- The route table in the app layer owns all redirect targets.
|
|
15
|
+
- Structure `appRoutes` as parallel `canMatch`-gated subtrees (logged-in / logged-out), ending with the wildcard.
|
|
16
|
+
- A `CanActivateFn` returning `false` cancels the in-flight navigation in place: no redirect, no retry, the URL just stops.
|
|
17
|
+
- Returning a `UrlTree` works but forces the guard to know the redirect target, which leaks app routing concerns into core.
|
|
18
|
+
- With `canMatch`, a `false` skips the route definition during matching and Angular continues to the next match. The `**` wildcard catches anything that fell through and bounces back to root, where matching re-runs and lands on the correct subtree.
|
|
19
|
+
|
|
20
|
+
## Related
|
|
21
|
+
|
|
22
|
+
- [App-Shield](../architecture/app-shield.md)
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Interface, Not Abstract Class, For Mock Swap
|
|
2
|
+
|
|
3
|
+
A real and a mock service share a TypeScript `interface` that both implement, and the app config swaps one for the other at provider time:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
export interface OrdersApiInterface {
|
|
7
|
+
getOrders(): Observable<Order[]>;
|
|
8
|
+
// ...the public surface both implementations must honor
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
@Injectable()
|
|
12
|
+
export class OrdersApiService implements OrdersApiInterface { /* real */ }
|
|
13
|
+
|
|
14
|
+
@Injectable()
|
|
15
|
+
export class MockOrdersApiService implements OrdersApiInterface { /* mock */ }
|
|
16
|
+
|
|
17
|
+
// app config - one token, swap the implementation
|
|
18
|
+
{ provide: OrdersApiService, useClass: environment.useMocks ? MockOrdersApiService : OrdersApiService }
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Why
|
|
22
|
+
|
|
23
|
+
The mock and the real service keep one surface, held by the compiler.
|
|
24
|
+
|
|
25
|
+
## How To Apply
|
|
26
|
+
|
|
27
|
+
- Declare an `interface` for the service's public surface, named after its concept with an `Interface` suffix (`XInterface`), and write `implements` on both `XService` and `MockXService`.
|
|
28
|
+
- Swap via `useClass` at the app-config layer.
|
|
29
|
+
- An interface is erased at runtime, so it cannot be a DI token: keep the concrete service as the token, or inject an `InjectionToken<XInterface>` when there is no natural default.
|
|
30
|
+
- An `abstract class` port only earns its keep when several production implementations coexist, never for mock substitution.
|
|
31
|
+
- `implements` on both sides makes the compiler enforce parity. With bare structural typing a missing method only bites at runtime.
|
|
32
|
+
- An interface adds no inheritance, no runtime layer and nothing to construct, which keeps the DI seam simple.
|
|
33
|
+
|
|
34
|
+
## Related
|
|
35
|
+
|
|
36
|
+
- [Code Principles](../code/code-principles.md)
|
|
37
|
+
- [General Working Rules](../behavior/general-working-rules.md)
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# No `$any` In Templates
|
|
2
|
+
|
|
3
|
+
Templates are view-only. No `$any($event)`, no inline casts, no inline narrowing, no ternaries that decide behavior. Any cast, narrowing, or logic lives in the typed handler method on the component class - the handler's parameter type is the source of truth.
|
|
4
|
+
|
|
5
|
+
```html
|
|
6
|
+
(selected)="onSelect($event)"
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
onSelect(value: string): void { ... }
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Why
|
|
14
|
+
|
|
15
|
+
MVC discipline: the template shows, and the typed class decides.
|
|
16
|
+
|
|
17
|
+
## How To Apply
|
|
18
|
+
|
|
19
|
+
- When a binding seems to need `$any`, fix the binding type or move the work into TS.
|
|
20
|
+
- A template that holds casts or logic fragments behavior across files, and TypeScript can no longer verify it.
|
|
21
|
+
|
|
22
|
+
## Related
|
|
23
|
+
|
|
24
|
+
- [App-Shield](../architecture/app-shield.md)
|
|
25
|
+
- [Static Attribute, Not Literal Binding](static-attribute-not-literal-binding.md)
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# No Inline Templates
|
|
2
|
+
|
|
3
|
+
Components reference their template via `templateUrl: 'name.html'` in a sibling `.html` file. Anything with attributes, multiple elements, or control flow goes there.
|
|
4
|
+
|
|
5
|
+
Inline `template:` is only for the app-root single-element wrapper (e.g. `<router-outlet />`). "Small enough to inline" creep quietly buries non-trivial template logic inside an inline template string.
|
|
6
|
+
|
|
7
|
+
## Why
|
|
8
|
+
|
|
9
|
+
MVC best practice: the view lives in its own file, with the formatter, the lint and the editor's support.
|
|
10
|
+
|
|
11
|
+
## Related
|
|
12
|
+
|
|
13
|
+
- [One Component Per Folder, Flat](one-component-per-folder-flat.md)
|
|
14
|
+
- [No `$any` In Templates](no-any-in-templates.md)
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# One Component Per Folder, Flat
|
|
2
|
+
|
|
3
|
+
Every component gets its own folder, named after it, under the right `components/` directory: `<components>/<component-name>/` holding `<component-name>.{ts,html,scss}` and an `index.ts`. Sibling components (for example `switcher` and `switcher-item`) are sibling folders, never nested or sharing a folder. An inner file hidden in another component's folder is an "I'll clean it up later" smell.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A component is found where its name says, and moves as one folder.
|
|
8
|
+
|
|
9
|
+
## Related
|
|
10
|
+
|
|
11
|
+
- [Folder Concerns](../architecture/folder-concerns.md)
|
|
12
|
+
- [No Inline Templates](no-inline-templates.md)
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# One Projected Node Per Control-Flow Block
|
|
2
|
+
|
|
3
|
+
A control-flow block around projected content holds one projected node. Two nodes with `slot="x"` under one `@if` never reach the named slot of the parent component.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Projected content lands in the slot it was written for.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Set `extendedDiagnostics.checks.controlFlowPreventingContentProjection` to `error` in `angularCompilerOptions`, so the build fails on NG8011.
|
|
12
|
+
- A visibility check does not prove projection.
|
|
13
|
+
- A capture or a position check proves projection.
|
|
14
|
+
- The misplaced nodes still have a size, which is why a visibility check passes on them.
|
|
15
|
+
|
|
16
|
+
## Related
|
|
17
|
+
|
|
18
|
+
- [Prefer Content Projection Over Props (Angular)](prefer-content-projection-over-props-angular.md)
|
|
19
|
+
- [Review Every Capture Before Reporting](../behavior/review-every-capture-before-reporting.md)
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Overview
|
|
2
|
+
|
|
3
|
+
The Angular standards: rules for Angular.
|
|
4
|
+
|
|
5
|
+
- [canMatch + Wildcard For Route Access](canmatch-wildcard-for-route-access.md) - canMatch guards plus a `**` wildcard for route access
|
|
6
|
+
- [Interface, Not Abstract Class, For Mock Swap](interface-not-abstract-class-for-mock-swap.md) - real and mock services share an interface, swapped via useClass
|
|
7
|
+
- [No `$any` In Templates](no-any-in-templates.md) - no casts or logic in templates
|
|
8
|
+
- [No Inline Templates](no-inline-templates.md) - templates in sibling .html files
|
|
9
|
+
- [One Component Per Folder, Flat](one-component-per-folder-flat.md) - one component per folder, siblings flat
|
|
10
|
+
- [One Projected Node Per Control-Flow Block](one-projected-node-per-control-flow-block.md) - the build fails on NG8011, and a visibility check does not prove projection
|
|
11
|
+
- [Prefer Content Projection Over Props (Angular)](prefer-content-projection-over-props-angular.md) - ng-content slots over data props
|
|
12
|
+
- [Projected Content Is Never Styled By The Host](projected-content-is-never-styled-by-the-host.md) - projected content is styled from its own component, never through ::ng-deep
|
|
13
|
+
- [Static Attribute, Not Literal Binding](static-attribute-not-literal-binding.md) - constant strings are plain attributes, not bindings
|
|
14
|
+
- [Track Timed Items By An Id](track-timed-items-by-an-id.md) - timed list items track by an id the item carries
|
|
15
|
+
- [UI Copy In Template](ui-copy-in-template.md) - UI copy lives in the template's matching branch
|
|
16
|
+
- [Use Modern Angular Template APIs](use-modern-angular-template-apis.md) - built-in control flow and the signal APIs over their legacy forms, and one legacy usage starts a sweep
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Prefer Content Projection Over Props (Angular)
|
|
2
|
+
|
|
3
|
+
Angular UI and app components take their content through `ng-content` slots, following the projection rule of [UI Component Design](../ui/ui-component-design.md).
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Responsibility and authority over content stay with the consumer: content lives where it is listened to. The consumer orchestrates, and the component presents.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- For a collection, define a `<*-item>` child component and read it via `contentChildren()`.
|
|
12
|
+
- Conditionals live in the consumer template (`@if`), not in TS.
|
|
13
|
+
|
|
14
|
+
## Related
|
|
15
|
+
|
|
16
|
+
- [UI Component Design](../ui/ui-component-design.md)
|
|
17
|
+
- [UI Layout Via Slot Composition](../ui/ui-layout-via-slot-composition.md)
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Projected Content Is Never Styled By The Host
|
|
2
|
+
|
|
3
|
+
A component's styles never reach content projected through `ng-content`. The content is styled from its own component, or the host renders the element itself.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A style belongs with the component that owns the element.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Style projected children from their own component, or give the host an input that renders the element itself (such as an `emptyText` input).
|
|
12
|
+
- Put state that must affect projected content on the container the host owns (the host's own wrapper element, not the projected child).
|
|
13
|
+
- Never reach for `::ng-deep` or `ViewEncapsulation.None` for this. Treat the miss as a design smell.
|
|
14
|
+
|
|
15
|
+
## Examples
|
|
16
|
+
|
|
17
|
+
- An overlay's `pointer-events: auto` for projected panels never applies, so no button takes clicks.
|
|
18
|
+
- An empty-state paragraph projected into a section renders unstyled.
|
|
19
|
+
|
|
20
|
+
## Related
|
|
21
|
+
|
|
22
|
+
- [No Inline Templates](no-inline-templates.md)
|
|
23
|
+
- [Prefer Content Projection Over Props (Angular)](prefer-content-projection-over-props-angular.md)
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Static Attribute, Not Literal Binding
|
|
2
|
+
|
|
3
|
+
A constant string value is a plain template attribute (`aria-label="Menu"`), never a binding wrapping a string literal (`[attr.aria-label]="'Menu'"`, `[label]="'Menu'"`). Applies to attribute bindings and component-input bindings alike.
|
|
4
|
+
|
|
5
|
+
Dynamic values still need the binding: signals, `t(...)` translations, ternaries. A literal never changes, so a binding around it is pure change-detection overhead and indirection.
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!-- avoid -->
|
|
9
|
+
<button [attr.aria-label]="'Menu'"></button>
|
|
10
|
+
<!-- prefer -->
|
|
11
|
+
<button aria-label="Menu"></button>
|
|
12
|
+
<!-- binding is correct when the value is dynamic -->
|
|
13
|
+
<button [attr.aria-label]="t('layout.menu')"></button>
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Why
|
|
17
|
+
|
|
18
|
+
A binding tells the reader that a value changes.
|
|
19
|
+
|
|
20
|
+
## Related
|
|
21
|
+
|
|
22
|
+
- [UI Copy In Template](ui-copy-in-template.md)
|
|
23
|
+
- [No `$any` In Templates](no-any-in-templates.md)
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Track Timed Items By An Id
|
|
2
|
+
|
|
3
|
+
A list of short-lived items that each close on their own timer (toasts, notifications, inline hints) tracks every item by an id the item carries.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Every item keeps its own element and its own timer.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Track by an id the item carries, never by position, for anything that can leave out of order.
|
|
12
|
+
- With index tracking, removing the first entry shifts the data under the existing elements: the element made for the oldest item takes the next item's data, and the element at the end, the newest, is destroyed. An older item's timer then kills the newest element early, and a longer-lived item vanishes almost instantly.
|
|
13
|
+
- Tracking by the item itself raises Angular's NG0956 whenever a short list turns over whole in one update (one closing as the next arrives on a slow page), and a suite failing on dev-mode warnings fails on it.
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [Use Modern Angular Template APIs](use-modern-angular-template-apis.md)
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# UI Copy In Template
|
|
2
|
+
|
|
3
|
+
UI copy (labels, errors, tooltips) lives in the template. The component exposes booleans or an `Enum<T>` union ([No Magic Values](../typescript/no-magic-values.md)) for the condition. The template inlines the literal text inside the matching `@if` or `@switch` branch.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Everything the user reads is found in the template.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
Flag names describe the state (`hasForbiddenError`), not the message.
|
|
12
|
+
|
|
13
|
+
```html
|
|
14
|
+
@if (hasForbiddenError) { <callout>No access to this app.</callout> }
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
With a translate pipe:
|
|
18
|
+
|
|
19
|
+
```html
|
|
20
|
+
@if (hasForbiddenError) { <callout>{{ 'errors.forbidden' | translate }}</callout> }
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Related
|
|
24
|
+
|
|
25
|
+
- [Name By Concept, Not Copy](../code/name-by-concept-not-copy.md)
|
|
26
|
+
- [Static Attribute, Not Literal Binding](static-attribute-not-literal-binding.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Use Modern Angular Template APIs
|
|
2
|
+
|
|
3
|
+
Use the current Angular idiom over the legacy one it replaced. One legacy usage that surfaces is the start of a sweep ([Code Review Compounds Into Patterns And Sweeps](../behavior/code-review-compounds-into-patterns-and-sweeps.md)).
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The code follows where the framework is going.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Use `@if`, `@for` and `@switch` over `*ngIf`, `*ngFor` and `[ngSwitch]`.
|
|
12
|
+
- Use `input()` and `output()` over `@Input()` and `@Output()`, and `model()` over an `@Input()` and `@Output()` pair for two-way binding.
|
|
13
|
+
- Use the signal queries `viewChild()`, `viewChildren()`, `contentChild()` and `contentChildren()` over their decorator forms.
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [Code Review Compounds Into Patterns And Sweeps](../behavior/code-review-compounds-into-patterns-and-sweeps.md)
|
|
18
|
+
- [Always Use Design Tokens For Colors](../web/always-use-design-tokens-for-colors.md)
|
|
19
|
+
- [Pre-Empt Recurring Code-Review Nits](../code/pre-empt-recurring-code-review-nits.md)
|
|
20
|
+
- [Don't Introduce Tech Debt](../behavior/dont-introduce-tech-debt.md)
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Adopt, Configure, Override
|
|
2
|
+
|
|
3
|
+
Anything made to be reused across projects comes in three layers. A project adopts the defaults, configures where it differs, and overrides where it wants something of its own.
|
|
4
|
+
|
|
5
|
+
- Defaults: it just works. Adopting asks for no choices, and out of the box it does everything it finds relevant.
|
|
6
|
+
- Configs: choose your flavors. The named choices the thing offers, picked where projects differ.
|
|
7
|
+
- Overrides: customization. What a project changes for itself, past the choices on offer.
|
|
8
|
+
|
|
9
|
+
## Why
|
|
10
|
+
|
|
11
|
+
Reuse costs the least code and time.
|
|
12
|
+
|
|
13
|
+
## How To Apply
|
|
14
|
+
|
|
15
|
+
- A default just works, a flavor is thought out beforehand and easy to pick, and an override is there for the custom case and the escape hatch, only when needed.
|
|
16
|
+
- The default path asks nothing. The person is involved only for a decision that is theirs to make.
|
|
17
|
+
- A choice becomes a config only once projects differ on it. Until then it is a default.
|
|
18
|
+
- Each layer has a place of its own. A default is never edited to configure or to override, which keeps an update of the defaults mechanical.
|
|
19
|
+
- An override may drift for good. Offering one back to the source is the exception, kept for what clearly holds in general.
|
|
20
|
+
- It applies to a library, a design system's tokens, a set of rules and a project template alike.
|
|
21
|
+
|
|
22
|
+
## Related
|
|
23
|
+
|
|
24
|
+
- [Game Design Laws](../gamedev/game-design-laws.md)
|
|
25
|
+
- [Converge Only Once Proven](converge-only-once-proven.md)
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# App-Shield
|
|
2
|
+
|
|
3
|
+
Every file in a front-end web app's workspace belongs to exactly one of five layers, and dependencies between them flow one direction only. Keeping each piece in its proper layer shields the app against creep.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Every layer stands on its own, with its own responsibility and its own qualities, so the whole works in harmony.
|
|
8
|
+
|
|
9
|
+
## The Five Layers
|
|
10
|
+
|
|
11
|
+
### ui
|
|
12
|
+
|
|
13
|
+
Pure, standalone UI components and their styles, holding all visual presentation, markup and styling alike ([UI Component Design](../ui/ui-component-design.md)). Every ui component is covered in the [UI Styleguide](../ui/ui-styleguide.md). Favor many small components over fewer bespoke ones.
|
|
14
|
+
|
|
15
|
+
### app
|
|
16
|
+
|
|
17
|
+
Feature and domain libs that wire ui components together, hold pages and routes, and orchestrate user-facing behavior (state, app logic). The app layer owns no presentation, with no exceptions and no "acceptable composition residue": its templates only arrange ui components, and it holds no SCSS, no hand-authored presentational markup, no bare `:host {}` rule (even `display:`), no inline `style="..."` attribute and no `[style.x]`/`[ngStyle]` binding. Any of these means a missing or under-built ui component: build it, cover it in the styleguide, then compose it. This is MVC kept strict: app components are wiring, ui components are the view.
|
|
18
|
+
|
|
19
|
+
### data
|
|
20
|
+
|
|
21
|
+
Data-access layer (API services, mappers, DTOs). Talks to backends. No UI imports.
|
|
22
|
+
|
|
23
|
+
### core
|
|
24
|
+
|
|
25
|
+
Shared cross-cutting infrastructure that the app layer consumes: services, guards, interceptors, stores. No business logic. Stores and services are content-agnostic / generic. Eagerly loaded.
|
|
26
|
+
|
|
27
|
+
### config
|
|
28
|
+
|
|
29
|
+
Environment shape, types, and configuration tokens. Pure types/interfaces and DI tokens.
|
|
30
|
+
|
|
31
|
+
## Dependency Direction
|
|
32
|
+
|
|
33
|
+
- app depends on ui, core, data, config.
|
|
34
|
+
- data depends on core and config.
|
|
35
|
+
- core depends on config.
|
|
36
|
+
- ui is standalone - depends only on design-system packages, nothing else in the workspace.
|
|
37
|
+
- The styles split between ui and the app: the shared token layer and partials sit with ui, and an app's own theme, such as its palette and global styles, sits in its shell. The app's feature libs hold no SCSS.
|
|
38
|
+
- Never reach upwards (e.g. core importing from app).
|
|
39
|
+
|
|
40
|
+
## How To Apply
|
|
41
|
+
|
|
42
|
+
Before creating a new file, ask "which layer does this belong to?":
|
|
43
|
+
|
|
44
|
+
- A `Type`/`Interface`/`InjectionToken` describing config or env shape -> config.
|
|
45
|
+
- A guard/interceptor/cross-cutting service -> core.
|
|
46
|
+
- A backend client / mapper / DTO -> data.
|
|
47
|
+
- A page/component tied to a feature -> that feature's app lib.
|
|
48
|
+
- A reusable, presentation-only component -> ui.
|
|
49
|
+
- Stylesheet rules or hand-authored presentational markup -> a ui component, covered in the styleguide.
|
|
50
|
+
|
|
51
|
+
If a new shared concept appears that doesn't fit, surface it before scattering it. Do not bypass the boundary by static-importing across lazy-loaded edges.
|
|
52
|
+
|
|
53
|
+
Misplacing a file (e.g. putting a guard in a lazy-loaded route lib) creates circular deps, breaks lazy-loading boundaries, and forces static imports across edges that should stay decoupled. In Nx workspaces this is enforced mechanically. Without Nx, the same discipline applies by convention.
|
|
54
|
+
|
|
55
|
+
## Related
|
|
56
|
+
|
|
57
|
+
- [Code Principles](../code/code-principles.md)
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Converge Only Once Proven
|
|
2
|
+
|
|
3
|
+
In a multi-app workspace, apps can start divergent - different designs, different wiring - and converge into a shared style only once it has proven itself. Intentional divergence is not debt to flatten on sight.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A shared design or wiring fits every app that uses it.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Fold a pattern up to the shared layer only once it has repeated, stabilized and the apps have shown they agree on it. Convergence is earned, never scheduled.
|
|
12
|
+
- A UI primitive goes in the ui layer from its first use, also when one place uses it ([UI Components First](../ui/ui-components-first.md)). Convergence is about the designs and the wiring of apps.
|
|
13
|
+
- Keep per-app technical specifics in per-app docs (`docs/<app>/architecture.md`). The workspace architecture doc holds only shared concerns and points to the per-app docs.
|
|
14
|
+
- Whether a given app is currently diverging or converging is a project fact. Record it in the project's docs.
|
|
15
|
+
- Collapsing apps early couples every app to one app's choices and breeds app-flag branching. Premature uniformity costs as much as premature abstraction.
|
|
16
|
+
|
|
17
|
+
## Related
|
|
18
|
+
|
|
19
|
+
- [Per-Application Split Over Shared Branching](per-application-split-over-shared-branching.md)
|
|
20
|
+
- [Defer Tooling Until The Cost Shows Up](../tooling/defer-tooling-until-the-cost-shows-up.md)
|
|
21
|
+
- [Separation Before Layer Standards](separation-before-layer-standards.md)
|
|
22
|
+
- [Application Template](../docs/application-template.md)
|