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
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Normal Dashes
|
|
2
|
+
|
|
3
|
+
In all markdown, docs, commit messages, and prose, use the plain hyphen `-` as a punctuation dash. Never use em dashes `—` or en dashes `–`, even where they would be typographically correct. Applies to bullet list separators, inline asides, and ranges.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Plain ASCII is readable, grep-able, and consistent with keyboard input. Fancy dashes show up as AI-written polish and clash with the house style.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
When editing existing content that contains em or en dashes, replace them with `-` as part of the edit.
|
|
12
|
+
|
|
13
|
+
## Related
|
|
14
|
+
|
|
15
|
+
- [Prose Style](prose-style.md)
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Note Issues
|
|
2
|
+
|
|
3
|
+
When you encounter a problem during other work (bug, code smell, lint suppression, deprecated pattern, missing test, broken doc), write it down where the project's workflow says - never silently absorb it - without letting it block the work in front of you.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Every finding is kept, so all debt stays visible.
|
|
8
|
+
|
|
9
|
+
## Where To Note
|
|
10
|
+
|
|
11
|
+
The project's workflow names the home of each kind of finding: [The Simple Workflow](../simple-workflow/the-simple-workflow.md#where-a-finding-goes) or [Work Workflow](../tickets-workflow/work-workflow.md#where-a-finding-goes).
|
|
12
|
+
|
|
13
|
+
- Friction with a library -> surfaced to the director in the report ([Library Feedback](../docs/library-feedback.md)).
|
|
14
|
+
|
|
15
|
+
## How To Apply
|
|
16
|
+
|
|
17
|
+
- Stop briefly, add a short entry to the right doc, return to current work. One line is enough most of the time, with supporting context only when necessary.
|
|
18
|
+
- Never just suppress (eslint-disable, ts-ignore, swallowed error) without a matching note.
|
|
19
|
+
- Filing means writing it to a doc. Mentioning it in chat, or asking "want me to file this?", is not filing: the mention scrolls away. If you flag it at all, write it down the same turn.
|
|
20
|
+
- When unsure whether it's worth tracking or where it belongs, file it as debt, or as a question when it is functional, rather than drop it.
|
|
21
|
+
|
|
22
|
+
## Related
|
|
23
|
+
|
|
24
|
+
- [The Simple Workflow](../simple-workflow/the-simple-workflow.md)
|
|
25
|
+
- [Work Workflow](../tickets-workflow/work-workflow.md)
|
|
26
|
+
- [Library Feedback](../docs/library-feedback.md)
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Overview
|
|
2
|
+
|
|
3
|
+
The Behavior standards: how an agent works and what an agent checks.
|
|
4
|
+
|
|
5
|
+
- [A Go Before Work Elsewhere](a-go-before-work-elsewhere.md) - never start work in another project, or a session that outlives this one, without an explicit go. "Next is X" names only the topic. Projects come from the director's words, never a recent-folders list
|
|
6
|
+
- [A Maybe Is A Trigger To Investigate](a-maybe-is-a-trigger-to-investigate.md) - an idea the director phrases with uncertainty gets investigated in the same pass, never parked
|
|
7
|
+
- [A Name Describes Its Unit](a-name-describes-its-unit.md) - a name describes its unit clearly and precisely, neither too broad nor too narrow
|
|
8
|
+
- [A Quiet Tree While A Suite Runs](a-quiet-tree-while-a-suite-runs.md) - no source edits while a suite runs on a live dev server
|
|
9
|
+
- [Always Make No Mistakes](always-make-no-mistakes.md) - use your standards, own mistakes and strengthen the harness with a rule or check
|
|
10
|
+
- [Always Verify Before Reporting Done](always-verify-before-reporting-done.md) - run the check that matches the change before claiming done
|
|
11
|
+
- [Always Work From A Plan](always-work-from-a-plan.md) - work that survives the session or grows out of scope gets a written plan. In a project all work follows the project's workflow
|
|
12
|
+
- [Anchor Edits After Formatting](anchor-edits-after-formatting.md) - no write while a commit hook runs, check every anchor of a batch first, no edit by line number after a formatter
|
|
13
|
+
- [Backward-Trace Missing Prerequisites](backward-trace-missing-prerequisites.md) - a missing prerequisite is filed above the item. Recurse, never patch around
|
|
14
|
+
- [Code Review Compounds Into Patterns And Sweeps](code-review-compounds-into-patterns-and-sweeps.md) - a review finding is a pattern: a review check or a standard through healing, and a sweep ticket
|
|
15
|
+
- [Communication Boundary](communication-boundary.md) - never contact users or testers or speak for the director. A follow-up only the director can do goes on the director tasks
|
|
16
|
+
- [Dev Tiers](dev-tiers.md) - the recommended order: build, bugs, debt, features, within the current phase's goal. The director decides, and a pick that skips open bugs or debt gets a reminder
|
|
17
|
+
- [Docs Hold Only What The Director Decided](docs-hold-only-what-the-director-decided.md) - docs hold only what the director decided. Ideas go to chat first
|
|
18
|
+
- [Don't Filter Data Without A Spec](dont-filter-data-without-a-spec.md) - never drop data unless the exclusion is specced and tested
|
|
19
|
+
- [Don't Introduce Tech Debt](dont-introduce-tech-debt.md) - new code follows conventions even when neighbors don't. Fix what your change caused
|
|
20
|
+
- [Feature Workflow](feature-workflow.md) - plan -> doc -> laws -> spec -> failing e2e -> implement -> regression -> proof the director can verify
|
|
21
|
+
- [File A Change With Coentrify](file-a-change-with-coentrify.md) - a contributor files a harness change that holds beyond its project, one point per issue, without project details
|
|
22
|
+
- [Flag Every Addition Of Your Own](flag-every-addition-of-your-own.md) - name a decision of your own that no law, rule or guideline settles, for a veto. An impactful change is discussed first
|
|
23
|
+
- [Free Text Replies, No Buttons](free-text-replies-no-buttons.md) - no answer buttons or wrap-up questions. Ask in prose and keep going. No closing prompts where a dashboard shows the director's inboxes
|
|
24
|
+
- [General Working Rules](general-working-rules.md) - honest assessments, the model only for judgment calls, surface conflicts, read before you write, follow the written conventions
|
|
25
|
+
- [Non-Destructive Documenting And Test Automation](non-destructive-documenting-and-test-automation.md) - doc, spec and e2e steps never touch production code
|
|
26
|
+
- [Normal Dashes](normal-dashes.md) - always `-`, never em or en dashes
|
|
27
|
+
- [Note Issues](note-issues.md) - write down every finding where the project's workflow says, never only in chat
|
|
28
|
+
- [Own Ports, Own Processes](own-ports-own-processes.md) - own fixed non-default port per project, kill only your own PIDs, stop what you started
|
|
29
|
+
- [Project Lifecycle](project-lifecycle.md) - a project is in one phase at a time, the phase decides what matters now, and a phase gate ends it
|
|
30
|
+
- [Propagate Renames And Convention Changes Everywhere](propagate-renames-and-convention-changes-everywhere.md) - a rename updates every reference in the same change, grep before and after. A changed convention updates the pages that state it, and its occurrences go to a sweep
|
|
31
|
+
- [Prose Style](prose-style.md) - no AI sentence patterns. Calm, concrete, varied. Reports brief
|
|
32
|
+
- [Prototype Mode Is Speed First](prototype-mode-is-speed-first.md) - prototyping means speed: no tests, kept apart from the product's code, run it and share the link
|
|
33
|
+
- [Regular Layered Gap Analysis](regular-layered-gap-analysis.md) - walk the doc, spec, test and code layers both ways. Rules against the code too
|
|
34
|
+
- [Reload The Standards After Compacting](reload-the-standards-after-compacting.md) - after a compaction, read the Core Rules again, by a hook where the agent has one
|
|
35
|
+
- [Review Changes Before Reporting Done](review-changes-before-reporting-done.md) - before claiming done, check the relevant standards and surface changes you did not make
|
|
36
|
+
- [Review Every Capture Before Reporting](review-every-capture-before-reporting.md) - read every capture for regressions, caption match and unintended shapes
|
|
37
|
+
- [Standards Maintenance](standards-maintenance.md) - a periodic sweep for bloat, stale rules, duplicates, drift and dead links, with a word budget per standard. How a standard is added
|
|
38
|
+
- [Standards Over Skills](standards-over-skills.md) - on conflict with a skill from outside the project, the standard wins. A wrong line goes into a standard, never into the skill
|
|
39
|
+
- [Sweeps Enumerate Into Tech-Debt First](sweeps-enumerate-into-tech-debt-first.md) - a sweep lists every instance in one debt entry before fixing
|
|
40
|
+
- [Sync The Docs After Every Change](sync-the-docs-after-every-change.md) - after a landing, grep the docs for its terms and fix what went stale. A plan it conflicts with goes to the director as a question
|
|
41
|
+
- [The Quality Of The Question](the-quality-of-the-question.md) - an answer is as good as its question. Suspect the question first, and ask a vector question over a binary one
|
|
42
|
+
- [Things Of One Kind Are Consistent](things-of-one-kind-are-consistent.md) - things of one kind share a structure and a behavior, and fit with the rest
|
|
43
|
+
- [Understand The Need](understand-the-need.md) - the need before the solution, and the right solution fitted to the need
|
|
44
|
+
- [Use US English Everywhere](use-us-english-everywhere.md) - US spelling everywhere. Convert British spellings when touching them
|
|
45
|
+
- [Verify APIs Against Docs And The Installed Artifact](verify-apis-against-docs-and-the-installed-artifact.md) - when a pinned dependency and its docs disagree, the installed artifact decides, or the dependency is updated. Endpoints are checked against the spec, generated assets against their documented rule
|
|
46
|
+
- [Verify Control Before Rename](verify-control-before-rename.md) - trace a control to its handler before relabeling it
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Own Ports, Own Processes
|
|
2
|
+
|
|
3
|
+
Every server the agent starts (dev server, preview, e2e web server) runs on a port of its own, and the agent only ever stops what it started.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
More worktrees could be using the same machine.
|
|
8
|
+
|
|
9
|
+
## Own Ports
|
|
10
|
+
|
|
11
|
+
- Each project gets a fixed, random 5-digit port (e.g. `41737`) for the agent's servers, stable so launch configs and tooling can rely on it, and different per project so parallel agents never collide.
|
|
12
|
+
- The framework's default port stays free for the director, who tests the build by hand with a separate `npm start`.
|
|
13
|
+
- Never fall back to the default port, and never reuse a server that already listens on a port: it may be the director's app, another project, or stale code.
|
|
14
|
+
- A session in a worktree can find the launch config's port taken by another session's server. It adds an entry of its own on a free port for the run and leaves that entry out of the commit.
|
|
15
|
+
|
|
16
|
+
## Kill Only Your Own
|
|
17
|
+
|
|
18
|
+
- Capture `$!` when you background a process, and kill that PID.
|
|
19
|
+
- Start every process of your own so it is easy to find again: a distinctive port or a marker of its own in its command line, and match on that.
|
|
20
|
+
- Before any `pkill`, list what would die with its full command line, `ps -o pid=,args= -p "$(pgrep -d, -f <pattern>)"`, and read it.
|
|
21
|
+
- Never free a port by killing whatever listens on it. Start your own on another port instead.
|
|
22
|
+
- When you do kill something of theirs, say so plainly and restart it before continuing.
|
|
23
|
+
|
|
24
|
+
### Why
|
|
25
|
+
|
|
26
|
+
A pattern kill that looks local can hit a process of the director's that runs the same script, such as a server a desktop app forks behind an open window. It happens during cleanup, after attention has moved on, and the damage shows up where the terminal is not looking.
|
|
27
|
+
|
|
28
|
+
## Stop What You Started
|
|
29
|
+
|
|
30
|
+
- Stop every server and process you started once you are done with it, so nothing lingers on a port.
|
|
31
|
+
- The exception is a server the director asked to keep running, such as the docs wiki, or a prototype the director uses from its link.
|
|
32
|
+
|
|
33
|
+
## Related
|
|
34
|
+
|
|
35
|
+
- [Start Playwright On A Clean Port](../tooling/start-playwright-on-a-clean-port.md)
|
|
36
|
+
- [VitePress Wiki](../tooling/vitepress-wiki.md)
|
|
37
|
+
- [General Working Rules](general-working-rules.md)
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Project Lifecycle
|
|
2
|
+
|
|
3
|
+
A project is in one phase at a time, and the phase decides what matters now.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The same work is right in one phase and wasted in another.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Name the phase the project is in.
|
|
12
|
+
- State the goal of the current phase, and keep the work on that goal.
|
|
13
|
+
- File what does not serve the current phase for a later one.
|
|
14
|
+
- A phase ends at a phase gate: a leading question together with everything it takes to answer it. The answer sends the project on or back a phase.
|
|
15
|
+
- A game follows the [Game Phases](../gamedev/game-phases.md), in four stages.
|
|
16
|
+
- A web product can go from a prototype to a skeleton, a design and production.
|
|
17
|
+
- A product in production is live, and most web projects are from the start: what ships is polished.
|
|
18
|
+
|
|
19
|
+
## Related
|
|
20
|
+
|
|
21
|
+
- [Game Phases](../gamedev/game-phases.md)
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Propagate Renames And Convention Changes Everywhere
|
|
2
|
+
|
|
3
|
+
When you rename a concept, file, route or label, update every reference in the same change: sibling docs, links, specs, labels. Never fix one and wait to be told to "align the others". A changed doc or code convention updates every page that states it in the same change, and its existing occurrences go to a sweep, filed as debt ([Sweeps Enumerate Into Tech-Debt First](sweeps-enumerate-into-tech-debt-first.md)).
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A name or a convention reads the same in every place.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
Enumerate first: grep the old term to list every site. Sweep them all. Re-grep afterward to confirm none remain.
|
|
12
|
+
|
|
13
|
+
## Related
|
|
14
|
+
|
|
15
|
+
- [Review Changes Before Reporting Done](review-changes-before-reporting-done.md)
|
|
16
|
+
- [Always Work From A Plan](always-work-from-a-plan.md)
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Prose Style
|
|
2
|
+
|
|
3
|
+
Write with elegance and subtlety in all prose (chat, docs, commits). Recognizable AI sentence patterns are banned.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Patterned prose reads as machine output and annoys the reader. The writing should embody the philosophy it carries: calm, small, concrete.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Don't lean on contrastive scaffolding as the default rhythm: "X, not Y", "not X but Y", "it's not about X, it's about Y".
|
|
12
|
+
- Don't chain copulas: "the x is the y, and the y is the z".
|
|
13
|
+
- One thought per bullet or sentence. Never pair two contrasting cases in one line with a semicolon, `a user who does not know it is invited; one who does is told something new`: that pairing is the same scaffolding in disguise. Give each case its own bullet.
|
|
14
|
+
- Drop hype adjectives and rhetorical build-ups. State the thing.
|
|
15
|
+
- Vary sentence length and structure across a paragraph.
|
|
16
|
+
- A reference resolves inside its own text.
|
|
17
|
+
- A point is made in one sentence, once.
|
|
18
|
+
- A word the context already gives is dropped: the module, the title or the heading above. A law in the game laws never says game.
|
|
19
|
+
- Reports to the director are brief, a helicopter view: what changed, what needs the director's call. Detail only on request.
|
|
20
|
+
|
|
21
|
+
## Related
|
|
22
|
+
|
|
23
|
+
- [Normal Dashes](normal-dashes.md)
|
|
24
|
+
- [Use US English Everywhere](use-us-english-everywhere.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Prototype Mode Is Speed First
|
|
2
|
+
|
|
3
|
+
When the director calls a piece of work prototyping (a throwaway tool, a one-pager to extract later), speed wins: no tests, no probes, no stories, no doc ceremony beyond the [Request Log](../records/request-log.md). Build the smallest thing the director can run. The product itself keeps its full cadence.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The director wants to see or try the idea, fast.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Keep a prototype apart from the product's code, in its own folder with its own copies, no imports from it.
|
|
12
|
+
- Its ticket, where the workflow has tickets, is its one piece of tracking ([Work Workflow](../tickets-workflow/work-workflow.md)).
|
|
13
|
+
- Time to the first thing the director can see or try is the measure. Ask before growing it.
|
|
14
|
+
- Run it yourself on its own port, give the link, and keep it running until the director is done with it, since the agent often works in a worktree the director is not in.
|
|
15
|
+
- No headless checks, not even a throwaway one. The check is a quick look in the browser, muted where the product plays sound.
|
|
16
|
+
|
|
17
|
+
## Related
|
|
18
|
+
|
|
19
|
+
- [Work Workflow](../tickets-workflow/work-workflow.md)
|
|
20
|
+
- [Always Verify Before Reporting Done](always-verify-before-reporting-done.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Regular Layered Gap Analysis
|
|
2
|
+
|
|
3
|
+
The workspace is layered in more than one dimension, and the layers drift apart unless checked. Periodically walk them, step by step, looking for inconsistencies.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The layers stay in step, and drift is caught while it is cheap.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Walk each dimension in both directions and file the gaps as issues.
|
|
12
|
+
- Documentation depth: workspace -> app -> feature. Confirm each level describes the same reality.
|
|
13
|
+
- Build pipeline: functional doc -> spec -> e2e test -> implementation. Confirm each step lines up with the ones before and after it - every feature specced, every spec case tested, every test reflecting real behavior, nothing shipped undocumented.
|
|
14
|
+
- Rules against the system: the standards and conventions versus the actual codebase. Re-check that the code still meets them, and that a newly added or strengthened rule has been swept across everything that predates it.
|
|
15
|
+
|
|
16
|
+
## Related
|
|
17
|
+
|
|
18
|
+
- [Feature Workflow](feature-workflow.md)
|
|
19
|
+
- [Note Issues](note-issues.md)
|
|
20
|
+
- [Code Review Compounds Into Patterns And Sweeps](code-review-compounds-into-patterns-and-sweeps.md)
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Reload The Standards After Compacting
|
|
2
|
+
|
|
3
|
+
After a compaction, read the Core Rules again.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
An agent works from the standards themselves, at every point in a session.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Read again any other standard the work at hand needs.
|
|
12
|
+
- Where the agent does not read its entry point again after a compaction, and supports hooks, let a hook reload the Core Rules, so no step depends on remembering.
|
|
13
|
+
|
|
14
|
+
## Related
|
|
15
|
+
|
|
16
|
+
- [Always Make No Mistakes](always-make-no-mistakes.md)
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Review Changes Before Reporting Done
|
|
2
|
+
|
|
3
|
+
Before reporting work as done or committing, check the change against the relevant standards, and surface every change in the diff that you did not make.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
No one's work is lost or swept along, and a missed standard is applied while it is still cheap.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Check the relevant standards - was anything you should have applied missed? Apply it before declaring done.
|
|
12
|
+
- If the diff shows changes you didn't make, surface them and confirm before reverting or committing.
|
|
13
|
+
- Never assume an unexplained change is a tool side effect and silently revert it.
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [General Working Rules](general-working-rules.md)
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Review Every Capture Before Reporting
|
|
2
|
+
|
|
3
|
+
Look at each capture the pipeline produced before the report, and check it against the states list and the last feedback from testers. A capture that shows a regression is a finding.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A capture is proof, so it is checked before the director sees it.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- After a capture run, read every new image and compare it with the previous set of the same state.
|
|
12
|
+
- Fix what regressed before committing, or file it and say so.
|
|
13
|
+
- Look at what a capture shows, not only whether it matches: seeded names, colors, icons and every new image get the question "what does this shape remind you of?" A doubtful default goes to the director as a question.
|
|
14
|
+
- Name in the review what the picture shows (which scenario, which record, which state) before it goes on a page, and check that it matches its caption and line. A conductor reviews an agent's capture the same way, never trusting its path name.
|
|
15
|
+
- A build warning at the close, such as a crossed size budget, counts as a finding of the capture pass: it is fixed or filed before the release, never carried as "clean".
|
|
16
|
+
- Keep the list of states the captures cover next to the captures.
|
|
17
|
+
|
|
18
|
+
## Related
|
|
19
|
+
|
|
20
|
+
- [Pixel-Perfect Design Check](../ui/pixel-perfect-design-check.md)
|
|
21
|
+
- [Always Verify Before Reporting Done](always-verify-before-reporting-done.md)
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Standards Maintenance
|
|
2
|
+
|
|
3
|
+
Sweep the standards periodically to keep them tight and lean.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Standards rot if left alone.
|
|
8
|
+
|
|
9
|
+
## Recurring Sweep
|
|
10
|
+
|
|
11
|
+
A sweep analyzes the standards, documents what it finds, and files it as work to pick up, in a batch or as tickets ([Sweeps Enumerate Into Tech-Debt First](sweeps-enumerate-into-tech-debt-first.md)). It looks for:
|
|
12
|
+
|
|
13
|
+
- Bloat - sections that yap when one sentence would do.
|
|
14
|
+
- Stale rules - standards that contradict current practice or reference removed concepts. Update or delete.
|
|
15
|
+
- Duplication - two standards saying the same thing. Pick the most correct home, defer from the other.
|
|
16
|
+
- Drift - the line in the overview no longer matches the standard's gist. Rewrite the line.
|
|
17
|
+
- Format violations - em dashes, numbered lists, non-Title-Case headers, hard-wrapped lines.
|
|
18
|
+
- Dead cross-links - links to files that have been renamed or deleted.
|
|
19
|
+
|
|
20
|
+
## Format
|
|
21
|
+
|
|
22
|
+
- A header is in Title Case, every word capitalized, apart from code and a name that is lowercase by nature, such as `npm`.
|
|
23
|
+
- A paragraph or a list item is one line.
|
|
24
|
+
- No semicolon in prose: two thoughts are two sentences, or two bullets.
|
|
25
|
+
- No filler word, such as `genuinely` or `truly`, and no British spelling.
|
|
26
|
+
- A standard opens with its rule, its Why is its first section, and it ends with Related.
|
|
27
|
+
|
|
28
|
+
## Budget
|
|
29
|
+
|
|
30
|
+
Soft caps: past a cap, a standard is trimmed or split before anything is added to it.
|
|
31
|
+
|
|
32
|
+
- The count is the body: the Related list stays out of it.
|
|
33
|
+
- A standard: about 600 words.
|
|
34
|
+
- A template: about 1,200 words.
|
|
35
|
+
- A hub, such as a workflow: about 3,000 words.
|
|
36
|
+
- A page accepted past its budget is listed in its module's `budget-exceptions.json`, with the words accepted and the reason. It surfaces again once it grows past them.
|
|
37
|
+
|
|
38
|
+
## Adding A Standard
|
|
39
|
+
|
|
40
|
+
- Check first whether another standard owns the rule. A rule with a home is added there.
|
|
41
|
+
- A rule lives on one page. Every other page that needs it links there, and never says it again.
|
|
42
|
+
- A new standard goes in the module it belongs to. A subject without a module gets a module of its own.
|
|
43
|
+
- The file is named after its title ([File Names](../docs/file-names.md)).
|
|
44
|
+
- The standard follows the template: the rule in one or two sentences, a Why, how to apply it, and its related standards.
|
|
45
|
+
- A Why says why the rule is needed, in a line or two.
|
|
46
|
+
- The overview of the module gets one line for the standard.
|
|
47
|
+
|
|
48
|
+
## When To Sweep
|
|
49
|
+
|
|
50
|
+
- A standard that feels wrong, or does not apply, is noted and goes through healing ([Always Make No Mistakes](always-make-no-mistakes.md)). The task at hand goes on.
|
|
51
|
+
- After a standard changes, by healing or by an update, a sweep of what it touches follows.
|
|
52
|
+
- When the standards feel heavy.
|
|
53
|
+
|
|
54
|
+
## How To Apply
|
|
55
|
+
|
|
56
|
+
- Apply format fixes freely.
|
|
57
|
+
- A rule change goes the way `healing` says, and the report names it ([Always Make No Mistakes](always-make-no-mistakes.md)).
|
|
58
|
+
- A standard from coentrify that a project changes turns `customized` in `coentrify.json`, with the reason in `standards/decisions.md`.
|
|
59
|
+
- A contributor files a changed or added standard with coentrify, if relevant ([File A Change With Coentrify](file-a-change-with-coentrify.md)).
|
|
60
|
+
|
|
61
|
+
## Related
|
|
62
|
+
|
|
63
|
+
- [Note Issues](note-issues.md)
|
|
64
|
+
- [File A Change With Coentrify](file-a-change-with-coentrify.md)
|
|
65
|
+
- [File Names](../docs/file-names.md)
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Standards Over Skills
|
|
2
|
+
|
|
3
|
+
When a standard and a skill from outside the project conflict, such as a plugin's, the standard wins. Such a skill is a starting point. The standards are the source of truth for the project's conventions.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The standards hold how the project works, so they come first.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- On conflict, follow the standard and ignore the skill's advice for that point.
|
|
12
|
+
- When you notice the skill is wrong (contradicts a standard or contradicts what the repo does), the right way goes into a standard, which wins, so the next session doesn't re-hit the same friction. The skill itself is never edited.
|
|
13
|
+
- The standard is a change to the harness, so it goes the way `healing` says, and the report names it ([Always Make No Mistakes](always-make-no-mistakes.md)).
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [Always Make No Mistakes](always-make-no-mistakes.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Sweeps Enumerate Into Tech-Debt First
|
|
2
|
+
|
|
3
|
+
A sweep for a pattern begins by finding every instance and listing them in one debt entry, before any fix. Where the entry goes is the project's workflow's: [The Simple Workflow](../simple-workflow/the-simple-workflow.md#where-a-finding-goes) or [Work Workflow](../tickets-workflow/work-workflow.md#where-a-finding-goes).
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A sweep fixes every instance, with none missed.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- First pass: scan thoroughly for every instance - watch for casing, singular/plural, and shape variants that a narrow grep misses - and list each in the debt entry.
|
|
12
|
+
- Then work the list, removing items as they are fixed, per [Remove Completed Items From Docs](../simple-workflow/remove-completed-items-from-docs.md).
|
|
13
|
+
- State the scope honestly: if the scan can miss instances, say so rather than imply full coverage.
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [Note Issues](note-issues.md)
|
|
18
|
+
- [Work Tracking](../tickets-workflow/work-tracking.md)
|
|
19
|
+
- [Always Work From A Plan](always-work-from-a-plan.md)
|
|
20
|
+
- [Code Review Compounds Into Patterns And Sweeps](code-review-compounds-into-patterns-and-sweeps.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Sync The Docs After Every Change
|
|
2
|
+
|
|
3
|
+
When something changed or a feature landed, check the docs for related information before calling it done: statements the change made stale, and statements about future plans the change now conflicts with.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The docs are up to date at all times.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- After an item lands, grep the docs for its feature's terms (names, labels, the old behavior) and read every hit, beyond the feature's own doc.
|
|
12
|
+
- A statement the change made untrue gets fixed in the same commit or the next one.
|
|
13
|
+
- A future plan the change conflicts with (a roadmap line, a concept, a law) is filed as a question where the project's workflow says, and named in the report in one line. It is never silently rewritten.
|
|
14
|
+
- Prefer one source of truth: a summary doc links to the feature doc rather than repeating its status.
|
|
15
|
+
|
|
16
|
+
## Related
|
|
17
|
+
|
|
18
|
+
- [Propagate Renames And Convention Changes Everywhere](propagate-renames-and-convention-changes-everywhere.md)
|
|
19
|
+
- [Regular Layered Gap Analysis](regular-layered-gap-analysis.md)
|
|
20
|
+
- [Docs Hold Only What The Director Decided](docs-hold-only-what-the-director-decided.md)
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# The Quality Of The Question
|
|
2
|
+
|
|
3
|
+
The quality of an answer depends on the quality of the question. That holds for a question to the director, to another agent, and to yourself.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
What we are after is the answer that fits the need.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- When an answer disappoints or contradicts itself, suspect the question first.
|
|
12
|
+
- Ask a vector question over a binary one. "How good is the code?" leaves room for nuance. "Is the code good?" invites a verdict and a debate.
|
|
13
|
+
- Say what the answer is for, so the answer can fit the need.
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [Understand The Need](understand-the-need.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Things Of One Kind Are Consistent
|
|
2
|
+
|
|
3
|
+
Things of one kind have the same structure and behave the same way, and each fits harmonically with the rest.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Consistency brings expectations, and the expectations hold.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Apply the rule to every kind: a ticket, a template, a component, a name, a spelling.
|
|
12
|
+
|
|
13
|
+
## Related
|
|
14
|
+
|
|
15
|
+
- [UI Component Design](../ui/ui-component-design.md)
|
|
16
|
+
- [Writing A Ticket](../tickets-workflow/writing-a-ticket.md)
|
|
17
|
+
- [Building A Ticket](../tickets-workflow/building-a-ticket.md)
|
|
18
|
+
- [Workspace Template](../docs/workspace-template.md)
|
|
19
|
+
- [Application Template](../docs/application-template.md)
|
|
20
|
+
- [Use US English Everywhere](use-us-english-everywhere.md)
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Understand The Need
|
|
2
|
+
|
|
3
|
+
Understand what the director needs before solving anything. The goal is the right solution, fitted to the need.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The right solution fits the need, and the need is seldom stated completely.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Work out the need before choosing a solution.
|
|
12
|
+
- Weigh the need of now against the need of later.
|
|
13
|
+
- Read "not now" as later. "Not now" never means never, and never means half.
|
|
14
|
+
|
|
15
|
+
### Incomplete Words
|
|
16
|
+
|
|
17
|
+
Something is missing from what the director said.
|
|
18
|
+
|
|
19
|
+
- Fill the gap from past patterns, the rules and the laws.
|
|
20
|
+
- Look up best practice where the project has no pattern yet.
|
|
21
|
+
- Ask where the gap is a choice only the director can make.
|
|
22
|
+
|
|
23
|
+
### Inconsistent Words
|
|
24
|
+
|
|
25
|
+
Two things the director said seem to pull apart.
|
|
26
|
+
|
|
27
|
+
- Allow the tension. Two statements that conflict on the surface can meet in a dimension the agent has not seen yet.
|
|
28
|
+
- Assume first that the agent is missing something.
|
|
29
|
+
- Check both statements against past patterns, the rules and the laws.
|
|
30
|
+
- Research, check and ask until the need is fully understood.
|
|
31
|
+
- A mistake or an oversight stays possible. Surface the conflict then.
|
|
32
|
+
- Never average the two.
|
|
33
|
+
|
|
34
|
+
### Reason Or Ask
|
|
35
|
+
|
|
36
|
+
Reasoning from what is known pulls against asking and looking outward. A cheap choice is reasoned out and flagged. A costly choice is asked. Doubt about a cheap choice already made is acted on: weigh the options, build the best one and name it for a veto. Never end a turn on a question about a color, a layout detail, a label or anything a small edit undoes.
|
|
37
|
+
|
|
38
|
+
### In Proportion
|
|
39
|
+
|
|
40
|
+
- Be fast where the case is simple or urgent.
|
|
41
|
+
- Be thorough enough to reach the real issue.
|
|
42
|
+
- Stay alert to a signal that points at another issue.
|
|
43
|
+
- Recognize the rare case where a strange request is right as stated.
|
|
44
|
+
- Fix precisely: change what the need asks for, and nothing more.
|
|
45
|
+
|
|
46
|
+
## Examples
|
|
47
|
+
|
|
48
|
+
### The Doctor
|
|
49
|
+
|
|
50
|
+
A man tells a doctor: "my toe itches, please cut off my leg."
|
|
51
|
+
|
|
52
|
+
- A bad doctor cuts off the leg.
|
|
53
|
+
- A better doctor makes a diagnosis first.
|
|
54
|
+
- The best doctor also spots the rare gangrene that needs the leg off, and acts in time.
|
|
55
|
+
- Tight shoes need no blood test.
|
|
56
|
+
- With the shoes off, the best doctor still asks why the man bought tight shoes.
|
|
57
|
+
|
|
58
|
+
### The Failing Test
|
|
59
|
+
|
|
60
|
+
The director says: "the test fails, fix it."
|
|
61
|
+
|
|
62
|
+
- The words ask for a passing test.
|
|
63
|
+
- The need is a product that does what the spec says.
|
|
64
|
+
- The quick solution changes the test until the test passes.
|
|
65
|
+
- The right solution finds out whether the product or the test is wrong, and fixes that one.
|
|
66
|
+
|
|
67
|
+
## Related
|
|
68
|
+
|
|
69
|
+
- [The Quality Of The Question](the-quality-of-the-question.md)
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Use US English Everywhere
|
|
2
|
+
|
|
3
|
+
Use US English spelling consistently across code, identifiers, comments, docs, prose, and commits. Don't mix variants within the workspace.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
One variant keeps a workspace consistent. Which variant is a choice.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Prefer `-ize`/`-ization` (authorization, initialize, organization), `-or` (color, behavior), `-er` (center), and single-l inflections (modeled, canceled).
|
|
12
|
+
- When editing British-spelled text, switch it to US in passing. Legacy spellings are converted when touched, never by a blind mass rename.
|
|
13
|
+
- Match existing US-spelled identifiers and third-party APIs. Never coin new British-spelled ones.
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [Prose Style](prose-style.md)
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Verify APIs Against Docs And The Installed Artifact
|
|
2
|
+
|
|
3
|
+
When a dependency is pinned and the docs disagree with it, the installed artifact decides what the code can use. The other path is to update the dependency.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The installed code is what runs, so it decides.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- When updating the dependency is an option, check its docs for what the update would add.
|
|
12
|
+
- For API endpoints, verify existence, path, method, and request/response shape against the OpenAPI/Redoc spec itself before documenting them - don't infer from client code or assume an endpoint is missing.
|
|
13
|
+
- For a generated asset whose layout the framework unwraps or parses, derive that layout from the framework's documented rule instead of positioning by eye, then render the result and look at it.
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [Always Verify Before Reporting Done](always-verify-before-reporting-done.md)
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Verify Control Before Rename
|
|
2
|
+
|
|
3
|
+
When asked to rename a UI label or control, first trace it to its handler and the field or action it drives. If the proposed name names a different concept than what the control does, challenge it before making any edit.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A label says what its control does.
|
|
8
|
+
|
|
9
|
+
## Related
|
|
10
|
+
|
|
11
|
+
- [Honest Assessments](general-working-rules.md#honest-assessments)
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Code Principles
|
|
2
|
+
|
|
3
|
+
Code follows four principles: a single responsibility, composition over extension, generic types, and responsibilities kept apart.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Code with a single responsibility per piece stays stable.
|
|
8
|
+
|
|
9
|
+
## Single Responsibility
|
|
10
|
+
|
|
11
|
+
- A piece of code should do one thing. Coupling several responsibilities into one unit via flags or conditionals is a split signal.
|
|
12
|
+
|
|
13
|
+
## Composition Over Extension
|
|
14
|
+
|
|
15
|
+
- Compose, don't extend.
|
|
16
|
+
|
|
17
|
+
## Generic Types
|
|
18
|
+
|
|
19
|
+
- Take content whose type varies as a type parameter, such as `List<T>`, also when the types share no base interface.
|
|
20
|
+
|
|
21
|
+
## Decouple Responsibilities
|
|
22
|
+
|
|
23
|
+
- Branching on caller identity (which application, which role) inside a shared unit means the responsibilities should live in separate units ([Per-Application Split Over Shared Branching](../architecture/per-application-split-over-shared-branching.md)).
|
|
24
|
+
- An effect and its source stay apart:
|
|
25
|
+
- The target carries a generic state (`isEnabled`, a discount factor) and never names what grants it.
|
|
26
|
+
- The source declares what it grants in configuration (`enablesExport: true` on the granting plan), and a mapper of its own resolves it.
|
|
27
|
+
- A target flag that names its source (`isWaitingForX`) is fundamentally bad design. The pattern applies to every modifier, permission and feature flag.
|
|
28
|
+
|
|
29
|
+
## Related
|
|
30
|
+
|
|
31
|
+
- [Per-Application Split Over Shared Branching](../architecture/per-application-split-over-shared-branching.md)
|
|
32
|
+
- [App-Shield](../architecture/app-shield.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Escape Hatch Comments
|
|
2
|
+
|
|
3
|
+
Remove an escape hatch that is not needed, and give one that stays a short comment saying why. An escape hatch is a deliberate deviation from a safe default or framework norm - `ViewEncapsulation.None`, `ts-ignore`, `eslint-disable`, a forced cast, a `!` non-null assertion, a manual DOM reach.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A comment keeps every session from flagging the hatch or "fixing" it.
|
|
8
|
+
|
|
9
|
+
## Confirm It's Needed First
|
|
10
|
+
|
|
11
|
+
Before keeping an escape hatch, confirm it's required. Many are copied along without a need or left over from an earlier approach and disappear once the real cause is addressed. Prefer removing the hatch over documenting it.
|
|
12
|
+
|
|
13
|
+
## If It Stays, Comment Why
|
|
14
|
+
|
|
15
|
+
An escape hatch that survives gets a short inline comment stating why. Without it the next reader either deletes it - reintroducing whatever it guarded against - or misreads it as accidental. This is one of the few "why" comments worth keeping: it documents a non-obvious local deviation, not what the code does.
|
|
16
|
+
|
|
17
|
+
## Related
|
|
18
|
+
|
|
19
|
+
- [No Describe-What Comments](no-describe-what-comments.md)
|
|
20
|
+
- [Note Issues](../behavior/note-issues.md)
|