coentrify 0.0.2 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +18 -0
- package/README.md +2 -1
- package/bin/coentrify.js +83 -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/0.1.1.md +27 -0
- package/src/changelog/overview.md +14 -0
- package/src/coentrify-json.md +74 -0
- package/src/commands.md +50 -0
- package/src/glossary.md +132 -0
- package/src/how-it-works.md +51 -0
- package/src/onboarding.md +141 -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 +107 -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 +25 -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 +64 -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 +114 -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,28 @@
|
|
|
1
|
+
# Folder Concerns
|
|
2
|
+
|
|
3
|
+
Inside any folder, sub-folders are either all **domain** (functional, by-feature) or all **technical** (categorical, by-artifact-type), never a mix. Keep the tree as flat as possible.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Every level of the tree answers exactly one question.
|
|
8
|
+
|
|
9
|
+
## Examples
|
|
10
|
+
|
|
11
|
+
Domain (functional) - sub-folders are entities, features, or apps:
|
|
12
|
+
|
|
13
|
+
- `apps/` -> `admin/`, `client/`, `supplier/`.
|
|
14
|
+
- `components/` -> `button/`, `icon/`, `card/`.
|
|
15
|
+
|
|
16
|
+
Technical (categorical) - sub-folders are types of artifact:
|
|
17
|
+
|
|
18
|
+
- `ui/` -> `components/`, `types/`, `generics/`.
|
|
19
|
+
- `admin/` -> `pages/`, `dialogs/`, `routes/`.
|
|
20
|
+
|
|
21
|
+
## How To Apply
|
|
22
|
+
|
|
23
|
+
When adding a sub-folder, match the kind of its existing siblings. If it would be the other kind, refactor first: insert a level above to separate the concerns, or rethink the structure.
|
|
24
|
+
|
|
25
|
+
## Related
|
|
26
|
+
|
|
27
|
+
- [App-Shield](app-shield.md)
|
|
28
|
+
- [One Component Per Folder, Flat](../angular/one-component-per-folder-flat.md)
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Overview
|
|
2
|
+
|
|
3
|
+
The Architecture standards: patterns that cut across a codebase.
|
|
4
|
+
|
|
5
|
+
- [Adopt, Configure, Override](adopt-configure-override.md) - anything made for reuse comes in three layers: defaults that just work with no choices, configs to choose a flavor, overrides to customize. The default does everything relevant by itself and asks only what is the person's to decide
|
|
6
|
+
- [App-Shield](app-shield.md) - five layers ui/app/data/core/config, one-way deps, all presentation in dumb ui components
|
|
7
|
+
- [Converge Only Once Proven](converge-only-once-proven.md) - apps may diverge. Fold into shared code only once proven
|
|
8
|
+
- [Folder Concerns](folder-concerns.md) - sibling folders are all domain or all technical, flat over nested
|
|
9
|
+
- [Per-Application Split Over Shared Branching](per-application-split-over-shared-branching.md) - split per application instead of branching on app flags, whitelist gates
|
|
10
|
+
- [Separation Before Layer Standards](separation-before-layer-standards.md) - clean up layer placement before per-layer standards
|
|
11
|
+
- [Unique Where It Counts](unique-where-it-counts.md) - unique in what makes the project that project, best practice for the rest
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Per-Application Split Over Shared Branching
|
|
2
|
+
|
|
3
|
+
Prefer per-application components over shared components that branch on application flags. Duplication is acceptable. Visibility gates are opt-in whitelists.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A shared component stays simple, free of every application's branches.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Visibility gates list the applications that should see the feature, never the ones that shouldn't.
|
|
12
|
+
- No application-specific branch in a shared component, not even one: split or otherwise decouple the component, or note the split as tech debt when it is out of the change's scope ([Note Issues](../behavior/note-issues.md)).
|
|
13
|
+
- A negation gate leaks a feature when a new application lands or the backend returns an unexpected status, so an application silently inherits actions it shouldn't have. A whitelist fails closed.
|
|
14
|
+
|
|
15
|
+
## Example
|
|
16
|
+
|
|
17
|
+
A branch on the application, even one, is the signal to split:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
@if (isAdminApp) { <admin-only-badge /> } // stop - extract per-application components instead
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Related
|
|
24
|
+
|
|
25
|
+
- [Note Issues](../behavior/note-issues.md)
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Separation Before Layer Standards
|
|
2
|
+
|
|
3
|
+
When cleaning up the codebase, getting [App-Shield](app-shield.md) layer separation clean comes first: every file should sit in its correct layer (ui / app / data / core / config) before any per-layer standards work begins. This is the top cleanup priority.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Layer placement is the foundation that the work on each layer stands on.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Land layer-placement moves first, for example domain data-access out of core into its proper data or app layer.
|
|
12
|
+
- Then go layer by layer against each one's standards (ui: content projection over props, data: mappers / types / DTOs, core: generic infra only, and so on).
|
|
13
|
+
|
|
14
|
+
## Related
|
|
15
|
+
|
|
16
|
+
- [App-Shield](app-shield.md)
|
|
17
|
+
- [Always Work From A Plan](../behavior/always-work-from-a-plan.md)
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Unique Where It Counts
|
|
2
|
+
|
|
3
|
+
A project is unique in what makes it that project. The rest follows best practice.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
What every project has is a commodity, and reinventing it takes the work away from what sets the project apart.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Name what sets the project apart. The invention goes there.
|
|
12
|
+
- Everything else takes the best practice.
|
|
13
|
+
- A web shop never reinvents the checkout, unless the checkout is what sets it apart.
|
|
14
|
+
- What counts as a commodity shifts: generating an asset is one now.
|
|
15
|
+
|
|
16
|
+
## Related
|
|
17
|
+
|
|
18
|
+
- [Adopt, Configure, Override](adopt-configure-override.md)
|
|
19
|
+
- [Game Design Laws: Own Style](../gamedev/game-design-laws-own-style.md)
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# A Go Before Work Elsewhere
|
|
2
|
+
|
|
3
|
+
Work elsewhere - another project, or a session that outlives this one - begins only on the director's explicit go for exactly that. A sub-agent for the task at hand needs no go, and neither does automatic healing. "Next is X" names only the next topic to talk about.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The director decides where work starts, and can follow all of it.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- When the next topic is work elsewhere, first propose it in a line or two: which projects, how, in what order. Then wait for the go.
|
|
12
|
+
- Take the projects from the director's words. Never infer them from recent folders or what exists on disk. When it is unclear which projects are meant, ask.
|
|
13
|
+
- One go covers what it names, nothing wider.
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [Work Workflow](../tickets-workflow/work-workflow.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# A Maybe Is A Trigger To Investigate
|
|
2
|
+
|
|
3
|
+
When the director phrases an idea with uncertainty, such as a maybe, look into it in the same pass. Listing it in the report as not done, with an offer to build it on a yes, is the wrong outcome.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A maybe gets attention at once, whatever comes of it.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Think it through while processing the message. It ends in one of four outcomes.
|
|
12
|
+
- Clear and cheap: file it as an item in the project's workflow and name it for a veto ([Flag Every Addition Of Your Own](flag-every-addition-of-your-own.md)).
|
|
13
|
+
- One fact missing: ask only that.
|
|
14
|
+
- Looks wrong: give the reason, once ([Honest Assessments](general-working-rules.md#honest-assessments)).
|
|
15
|
+
- Too big for now: note it, or make it a spike for later.
|
|
16
|
+
|
|
17
|
+
## Related
|
|
18
|
+
|
|
19
|
+
- [Flag Every Addition Of Your Own](flag-every-addition-of-your-own.md)
|
|
20
|
+
- [Honest Assessments](general-working-rules.md#honest-assessments)
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# A Name Describes Its Unit
|
|
2
|
+
|
|
3
|
+
A name describes the unit it names, clearly and precisely: neither too broad nor too narrow.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A reader knows what is inside from the name alone.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Apply the rule to every name: a title, a summary, a file, a piece of work, an identifier.
|
|
12
|
+
|
|
13
|
+
## Related
|
|
14
|
+
|
|
15
|
+
- [Commits](../commits/commits.md)
|
|
16
|
+
- [Work Item Names](../tickets-workflow/work-item-names.md)
|
|
17
|
+
- [File Names](../docs/file-names.md)
|
|
18
|
+
- [Name By Concept, Not Copy](../code/name-by-concept-not-copy.md)
|
|
19
|
+
- [No Abbreviated Names](../code/no-abbreviated-names.md)
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# A Quiet Tree While A Suite Runs
|
|
2
|
+
|
|
3
|
+
Make no source edits while a browser suite runs against a watching dev server.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Tests should run in a stable environment.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- While a suite runs, work on what the server does not watch: docs, standards, the plan, reading code.
|
|
12
|
+
- Start the next code edit after the result is in.
|
|
13
|
+
- A run that overlapped with edits is invalid. Rerun it before reading anything into it.
|
|
14
|
+
- With a conductor, a suite may run on a copy of the tree while the real one is edited. The copy is cleaned up after.
|
|
15
|
+
|
|
16
|
+
## Related
|
|
17
|
+
|
|
18
|
+
- [Always Verify Before Reporting Done](always-verify-before-reporting-done.md)
|
|
19
|
+
- [Gate Commits On Exit Codes](../commits/gate-commits-on-exit-codes.md)
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Always Make No Mistakes
|
|
2
|
+
|
|
3
|
+
Use your standards on every task. Mistakes happen, and that is expected. What matters is the response: catch it, correct it, and strengthen the harness, so the system heals itself and keeps learning.
|
|
4
|
+
|
|
5
|
+
The harness is the standards, checks and tools an agent works within.
|
|
6
|
+
|
|
7
|
+
## Why
|
|
8
|
+
|
|
9
|
+
A mistake is a gap in the instructions and context, never a personal failing of the agent. Owning it means fixing the harness. Self-blame and a promise to try harder fix nothing.
|
|
10
|
+
|
|
11
|
+
## How To Apply
|
|
12
|
+
|
|
13
|
+
### Before The Work
|
|
14
|
+
|
|
15
|
+
- Read the relevant standards before acting, not after being corrected.
|
|
16
|
+
|
|
17
|
+
### When A Mistake Surfaces
|
|
18
|
+
|
|
19
|
+
- Own it plainly and fix it.
|
|
20
|
+
- Don't paper over it or justify around it.
|
|
21
|
+
- Find the rule, standard or check that was missing or too weak.
|
|
22
|
+
- Strengthen it: sharpen the rule, add a check or lint, close the loophole that let it through.
|
|
23
|
+
- A rule you can rationalize around is too weak.
|
|
24
|
+
|
|
25
|
+
### A Rule Or A Check
|
|
26
|
+
|
|
27
|
+
- An instruction is preferred over a check: prevention is cheaper.
|
|
28
|
+
- An instruction that is easy to get wrong gets a check beside it.
|
|
29
|
+
- The harness change is judged outside the context of the task at hand, the way `healing` in `coentrify.json` says.
|
|
30
|
+
- Automatic, the default: a subagent makes the change, logs it in the [Healing Log](../records/healing-log.md), and the report names it for a veto.
|
|
31
|
+
- Review: the change is filed in the project's workflow, like any other ticket, for the director.
|
|
32
|
+
- A sub-agent never heals on its own. It tells its conductor, who starts the healing subagent, or files the change under review.
|
|
33
|
+
|
|
34
|
+
### The Cost Of A Rule
|
|
35
|
+
|
|
36
|
+
- A tighter rule can cost more than the mistake it prevents.
|
|
37
|
+
- Some rules are considerations, and some tension between rules never fully resolves.
|
|
38
|
+
- Resolving it anyway overcomplicates the rules, which costs more.
|
|
39
|
+
- A deliberate concession leaves the tension in place, and is mitigated with a written exception or consideration.
|
|
40
|
+
- Most of the time, strengthen the harness.
|
|
41
|
+
|
|
42
|
+
## Related
|
|
43
|
+
|
|
44
|
+
- [Code Review Compounds Into Patterns And Sweeps](code-review-compounds-into-patterns-and-sweeps.md)
|
|
45
|
+
- [Honest Assessments](general-working-rules.md#honest-assessments)
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Always Verify Before Reporting Done
|
|
2
|
+
|
|
3
|
+
The verification step always applies. The mechanism varies by what was changed.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Done means it works, and only the matching check shows that.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Pick the verification surface that matches the change: browser preview for UI, e2e run for spec edits, type check for type changes, unit run for logic, lint for style-rule fixes, build for tooling.
|
|
12
|
+
- Run it before declaring done. "I read the diff" never substitutes for "I ran the check" when a check exists.
|
|
13
|
+
- If no automated check exists for the change, name what is being skipped and why, so the director can decide whether to verify manually.
|
|
14
|
+
- Never frame the absence of a browser preview as a reason to skip verification.
|
|
15
|
+
|
|
16
|
+
## Related
|
|
17
|
+
|
|
18
|
+
- [Review Changes Before Reporting Done](review-changes-before-reporting-done.md)
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Always Work From A Plan
|
|
2
|
+
|
|
3
|
+
Work that survives the session, or grows out of its scope, gets a written plan. For product features, the plan is step 1 of the [Feature Workflow](feature-workflow.md).
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A plan in a file lets any other session or agent continue from where the previous one stopped.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
### Where The Plan Lives
|
|
12
|
+
|
|
13
|
+
- In a project, all work follows the project's workflow.
|
|
14
|
+
- Read the workflow before starting any project work, every session.
|
|
15
|
+
- Outside a project, the plan is a file of its own.
|
|
16
|
+
|
|
17
|
+
### Working From The Plan
|
|
18
|
+
|
|
19
|
+
- Work from the plan, even one you wrote.
|
|
20
|
+
- Read it before starting and update it as you go.
|
|
21
|
+
- A plan holds what was asked and decided. A doubt goes to the director, never into the plan as a gate.
|
|
22
|
+
- It shrinks toward empty per [Plans Vs Persistent Files](../simple-workflow/plans-vs-persistent-files.md).
|
|
23
|
+
- Plans are documentation. Follow the same markdown conventions as persistent docs (see [Documentation Philosophy](../docs/documentation-philosophy.md)), even though plans are temporary.
|
|
24
|
+
|
|
25
|
+
## Related
|
|
26
|
+
|
|
27
|
+
- [Feature Workflow](feature-workflow.md)
|
|
28
|
+
- [Plans Vs Persistent Files](../simple-workflow/plans-vs-persistent-files.md)
|
|
29
|
+
- [Documentation Philosophy](../docs/documentation-philosophy.md)
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Anchor Edits After Formatting
|
|
2
|
+
|
|
3
|
+
When a formatter or a commit hook rewrites files, write nothing while a commit hook runs, and edit by content once the formatter ran. Write a batch of anchored edits only after every anchor in it matches.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A change lands whole and in the right place.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Never write files while a commit hook is running, since lint-staged stashes and restores the working tree, and a concurrent write can be lost.
|
|
12
|
+
- In a batch of anchored edits across several files, check every anchor first and write only when all of them match. A batch that aborts halfway leaves the first files changed, and the next attempt fights the formatter on the half that landed.
|
|
13
|
+
- Never delete or edit by a line number after a formatter ran, since it may have shifted the lines. Edit by content, and gate the commit on the type check's exit code ([Gate Commits On Exit Codes](../commits/gate-commits-on-exit-codes.md)).
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [Review Changes Before Reporting Done](review-changes-before-reporting-done.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Backward-Trace Missing Prerequisites
|
|
2
|
+
|
|
3
|
+
When the next step in the [Feature Workflow](feature-workflow.md) needs infrastructure that doesn't exist - no e2e harness, no spec template, no mock for the area, no tests for the affected area - file the prerequisite above the current item, and build it on its go.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A gap is closed once, for every feature after it.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- File the prerequisite as work of its own, ahead of the current item, where the project's workflow says: [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
|
+
- Recurse when the prerequisite has a missing prerequisite of its own.
|
|
13
|
+
- Resume only after the prerequisite is committed and verified.
|
|
14
|
+
- Never fold prerequisite work into the current feature's diff. Never write a throw-away bypass to get past the gap.
|
|
15
|
+
|
|
16
|
+
## Related
|
|
17
|
+
|
|
18
|
+
- [Feature Workflow](feature-workflow.md)
|
|
19
|
+
- [The Simple Workflow](../simple-workflow/the-simple-workflow.md)
|
|
20
|
+
- [Work Workflow](../tickets-workflow/work-workflow.md)
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Code Review Compounds Into Patterns And Sweeps
|
|
2
|
+
|
|
3
|
+
A code-review finding is rarely a one-off. When something surfaces in review, check whether it is a pattern - it usually is - and turn the single catch into a durable defense across the codebase.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A pattern captured once protects the whole codebase and every later session.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- On any finding, look for sibling instances before treating it as isolated.
|
|
12
|
+
- When it is a pattern:
|
|
13
|
+
- It goes to healing, the way `healing` says: a review check so future reviews catch it ([Pre-Empt Recurring Code-Review Nits](../code/pre-empt-recurring-code-review-nits.md)), or a standard on how to do it properly ([Always Make No Mistakes](always-make-no-mistakes.md)). When unsure of the correct approach, the director is asked before it is codified.
|
|
14
|
+
- File a sweep for the existing instances as debt, enumerated per [Sweeps Enumerate Into Tech-Debt First](sweeps-enumerate-into-tech-debt-first.md).
|
|
15
|
+
- Run code-review sweeps on occasion, not only when asked, to keep the codebase healthy.
|
|
16
|
+
- When an issue recurs that already has a rule, the rule was too weak: strengthen it ([Always Make No Mistakes](always-make-no-mistakes.md)).
|
|
17
|
+
|
|
18
|
+
## Related
|
|
19
|
+
|
|
20
|
+
- [Regular Layered Gap Analysis](regular-layered-gap-analysis.md)
|
|
21
|
+
- [Note Issues](note-issues.md)
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Communication Boundary
|
|
2
|
+
|
|
3
|
+
Agents never reach out to anyone outside the work. The director speaks to users and testers, and agents track and plan.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The director owns relationships, tone and timing.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Don't contact users or testers directly.
|
|
12
|
+
- Don't send messages on the director's behalf or say "I'll let X know."
|
|
13
|
+
- A follow-up only the director can do, such as asking a colleague or a client, a demo or a talk, goes on `docs/development/director-tasks.md`: an optional, short, flat list of one-liners outside the workflow's lists. The agent adds a line and names it in the report, and the director clears it. The project chooses whether git keeps the file.
|
|
14
|
+
- If the director asks for a draft, draft it. The director sends it.
|
|
15
|
+
|
|
16
|
+
## Related
|
|
17
|
+
|
|
18
|
+
- [Note Issues](note-issues.md)
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Dev Tiers
|
|
2
|
+
|
|
3
|
+
Work goes in a recommended order, higher tiers first: CI/CD and build, then bugs, then tech debt, then features, each tier counting only what hurts the current phase's goal. The director decides the order, and the agent names what is still open in a higher tier whenever a pick skips it.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Work builds on a stable foundation, and open bugs and debt are the first thing forgotten.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Before starting a feature, check the build, the bugs and the debt of the current phase, where the project's workflow keeps them.
|
|
12
|
+
- A broken build comes first, before anything else lands.
|
|
13
|
+
- The director may pick a feature over open bugs or debt.
|
|
14
|
+
- A pick that skips an open tier gets one line in the report, every time: `Still open in this phase: 3 bugs, 2 debt`.
|
|
15
|
+
- Only bugs that hurt the current phase's goal take the bug tier: early on, a bug in a core feature or one that stops the product from being used from start to finish. Every other bug is filed for a later phase where the project's workflow says, such as under the epic it belongs to there in the tickets workflow ([Work Tracking](../tickets-workflow/work-tracking.md#phases)).
|
|
16
|
+
- Only debt that hurts the current phase's goal takes the debt tier: it slows the current work, causes a bug, or blocks a check. Every other debt is noted all the same and filed for a later phase, where work that touches its code often resolves it on the way.
|
|
17
|
+
- Bugs and debt may blur into each other, which is fine.
|
|
18
|
+
- Debt in code that will not reach the product, a prototype or a throwaway probe, is never scheduled ahead of the work that decides whether the code stays.
|
|
19
|
+
- A bug the director wants to keep may stay on purpose. Then it is documented as a feature, and leaves the bugs.
|
|
20
|
+
|
|
21
|
+
## Related
|
|
22
|
+
|
|
23
|
+
- [Note Issues](note-issues.md)
|
|
24
|
+
- [Feature Workflow](feature-workflow.md)
|
|
25
|
+
- [Project Lifecycle](project-lifecycle.md)
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Docs Hold Only What The Director Decided
|
|
2
|
+
|
|
3
|
+
The director decides what a project's docs say. Project docs (laws, features, roadmap, tickets) should contain only what the director said or approved.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The director trusts the docs as the record of what was decided. A contribution is welcome, and it is recorded, so the director can veto it.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Parse requests freely: fix spelling, reword carefully, turn prose into flat lists, give things names. Keep the essence and add nothing.
|
|
12
|
+
- A specific the director did not say (a list, an order, a number, a name, a mechanism) is an extension, even when it feels like the obvious reading of a short line. Content is written and named for a veto, and an impactful change is discussed first ([Flag Every Addition Of Your Own](flag-every-addition-of-your-own.md)).
|
|
13
|
+
- Run the agent's own ideas by the director in chat, apart from the deliverable. They land in a doc only once the director picks them up, and are dropped otherwise.
|
|
14
|
+
- A decision an agent makes inside a ticket, including a specific it fills in to make the ticket workable, stands under the ticket's Veto, so the director sees it before it spreads. The docs carry it from its build on, and land with the story. The director's feedback on it comes back as rework.
|
|
15
|
+
- The request log records who decided what.
|
|
16
|
+
- A knowledge page states the decision plainly ([Docs State Knowledge](../docs/docs-state-knowledge.md)).
|
|
17
|
+
- When restructuring moves a statement (a feature idea lifted out of a rule, say), name the move in the report.
|
|
18
|
+
- Restructuring and cleanup that follow the templates and the director's stated goal do not count as the agent's own ideas: splitting an overloaded page, renaming a file to its title, moving copy to its right home within a section, picking between two readings the templates already decide. Do it without asking, say what was done, and ask for a review of the pages. A change to the wiki's tree, such as a new top-level section or pages moving between sections, is workshopped with the director first.
|
|
19
|
+
|
|
20
|
+
## Related
|
|
21
|
+
|
|
22
|
+
- [Request Log](../records/request-log.md)
|
|
23
|
+
- [Honest Assessments](general-working-rules.md#honest-assessments)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Don't Filter Data Without A Spec
|
|
2
|
+
|
|
3
|
+
Never drop or filter out data - client-side or server-side - unless that exclusion is explicitly specified: documented as intended behavior and covered by a test.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Unexpected data surfaces, so someone sees it and decides.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Before adding any filter - a `.filter()`, a narrowing request param, a guard that skips records - confirm the exclusion is specified. If it isn't, surface the data and get it specced first.
|
|
12
|
+
- When the exclusion is wanted, document it (feature doc or spec) and add a test that asserts it.
|
|
13
|
+
- Default to surfacing unexpected data as a distinct state or error over quietly removing it.
|
|
14
|
+
|
|
15
|
+
## Related
|
|
16
|
+
|
|
17
|
+
- [Never Obscure Information The User Needs](../ui/never-obscure-information-the-user-needs.md)
|
|
18
|
+
- [Communicate State](../ui/communicate-state.md)
|
|
19
|
+
- [Verify APIs Against Docs And The Installed Artifact](verify-apis-against-docs-and-the-installed-artifact.md)
|
|
20
|
+
- [Note Issues](note-issues.md)
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Don't Introduce Tech Debt
|
|
2
|
+
|
|
3
|
+
Code you write or extend should follow the established conventions, whatever the surrounding file happens to do.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Any work should add value. Debt detracts from it.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Before extending a type, const, or file, check it against the relevant conventions (as-const + `Enum` over bare unions, one artifact per file, barrel imports). New or extended code conforms even when its neighbors don't.
|
|
12
|
+
- The code a change edits, the function or the scope it works in, follows the conventions, the older code in it included.
|
|
13
|
+
- What the agent's own change introduced is fixed in the same pass, never filed as new debt: a leftover alias, a probe gone blind, a helper bypassed.
|
|
14
|
+
- A violation that was already there, in a file the change touches, is fixed in the same pass when it is small and obvious, and named for a veto ([Flag Every Addition Of Your Own](flag-every-addition-of-your-own.md)).
|
|
15
|
+
- One that is complex, or outside the change's scope, is noted as debt and left as it is ([Note Issues](note-issues.md)).
|
|
16
|
+
- A green build and passing tests do not mean no debt was added. The compiler does not enforce these conventions.
|
|
17
|
+
- In the tickets workflow, a ticket lands right ([Building A Ticket](../tickets-workflow/building-a-ticket.md#a-ticket-lands-right)).
|
|
18
|
+
|
|
19
|
+
## Related
|
|
20
|
+
|
|
21
|
+
- [No Magic Values](../typescript/no-magic-values.md)
|
|
22
|
+
- [One Artifact Per File](../typescript/one-artifact-per-file.md)
|
|
23
|
+
- [Barrel Imports](../typescript/barrel-imports.md)
|
|
24
|
+
- [Note Issues](note-issues.md)
|
|
25
|
+
- [General Working Rules](general-working-rules.md)
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Feature Workflow
|
|
2
|
+
|
|
3
|
+
Every new product feature follows this pipeline. Identify the next step, verify its prerequisite, run it, commit.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A feature is built on intent and context, never on guesses.
|
|
8
|
+
|
|
9
|
+
## The Pipeline
|
|
10
|
+
|
|
11
|
+
- Plan ([Always Work From A Plan](always-work-from-a-plan.md)).
|
|
12
|
+
- Functional doc at `docs/features/<feature>.md` ([Feature Template](../docs/feature-template.md)).
|
|
13
|
+
- The laws a project adopted are checked against the feature, in a step of their own.
|
|
14
|
+
- Spec at `docs/features/<feature>.spec.md` ([Feature Spec Template](../docs/feature-spec-template.md)).
|
|
15
|
+
- E2E tests, failing first ([E2E Test Conventions](../e2e/e2e-test-conventions.md)).
|
|
16
|
+
- Implement use case by use case, in mock state ([Develop Against Mocks](../tooling/develop-against-mocks.md)).
|
|
17
|
+
- Regression-test the affected area.
|
|
18
|
+
- Proof: a screenshot, a video, a test run or whatever fits, that tells the director the feature is done and lets the director verify it. Proof the director cannot check is no proof ([Reels And Video Proof](../reporting/reels-and-video-proof.md)).
|
|
19
|
+
|
|
20
|
+
Small steps keep the focus.
|
|
21
|
+
|
|
22
|
+
Doc, spec and e2e steps are observation only - no production-code edits ([Non-Destructive Documenting And Test Automation](non-destructive-documenting-and-test-automation.md)).
|
|
23
|
+
|
|
24
|
+
Commit at each step boundary on the work's branch ([Commits](../commits/commits.md)). Never blend steps. The steps land on main together, green ([Main Stays Green, Work Stays Clean](../commits/main-stays-green-work-stays-clean.md)). If a prerequisite is missing, park and recurse ([Backward-Trace Missing Prerequisites](backward-trace-missing-prerequisites.md)).
|
|
25
|
+
|
|
26
|
+
## Related
|
|
27
|
+
|
|
28
|
+
- [Always Work From A Plan](always-work-from-a-plan.md)
|
|
29
|
+
- [Non-Destructive Documenting And Test Automation](non-destructive-documenting-and-test-automation.md)
|
|
30
|
+
- [Backward-Trace Missing Prerequisites](backward-trace-missing-prerequisites.md)
|
|
31
|
+
- [Main Stays Green, Work Stays Clean](../commits/main-stays-green-work-stays-clean.md)
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# File A Change With Coentrify
|
|
2
|
+
|
|
3
|
+
A project that is a contributor files a harness change with coentrify, where the change holds beyond the project.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
What one project learns reaches every project.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- A project files only when its `coentrify.json` says `contributor: true`. Any project can be a contributor, and the setting is the director's standing go to file at the source.
|
|
12
|
+
- `filing` in `coentrify.json` says who files. With `review`, the default, the director looks at the issue first, and that look is the go for it. With `automatic`, the subagent that `healing` starts files it on its own ([Always Make No Mistakes](always-make-no-mistakes.md#a-rule-or-a-check)).
|
|
13
|
+
- A change is filed as an issue at the source that `coentrify.json` names. Creating the issue is the filing, so the agent creates it there itself once the go is in, without asking again.
|
|
14
|
+
- A session that cannot create an issue at the source asks for that access once, and keeps the drafts ready meanwhile.
|
|
15
|
+
- A change to a module with a source of its own is filed with coentrify only when it is generic, as an addition of the module or the standard that coentrify lacks.
|
|
16
|
+
- An issue holds one point, so issues close one by one.
|
|
17
|
+
- Before filing, search the open issues.
|
|
18
|
+
- A point that is filed already gets an addition on that issue, or a thumbs up.
|
|
19
|
+
- An issue states the trigger, the proposal and the check: what happened, the rule to add, change or loosen and the standards it touches, and whether code could catch it instead, and which.
|
|
20
|
+
- The source is public, and it expects issues from the projects that use it. An issue holds no project details for that reason.
|
|
21
|
+
|
|
22
|
+
## Related
|
|
23
|
+
|
|
24
|
+
- [Standards Maintenance](standards-maintenance.md)
|
|
25
|
+
- [Always Make No Mistakes](always-make-no-mistakes.md)
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Flag Every Addition Of Your Own
|
|
2
|
+
|
|
3
|
+
A decision of the agent's own, one that no law, rule or content guideline settles, is named for the director's veto. Judgment calls that fill a gap count, and so do placeholders.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The director decides on everything that goes in. A decision that moves into the agent's work unseen pulls the outcome toward the agent, and costs rework, time and tokens.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Flag no choice that a standard, a law or a content guideline decides, since it is no addition.
|
|
12
|
+
- Easy-to-change content (names, numbers, a look) is decided and flagged, never asked.
|
|
13
|
+
- An impactful change is discussed before it is made: one that adds scope, or drops, loosens or moves a rule or a decision away from the director.
|
|
14
|
+
- In a ticket, the flag is a line in its Veto section, holding only what the director could want undone, in a few words ([The Done Part](../tickets-workflow/the-done-part.md)).
|
|
15
|
+
- Outside a ticket, the report names each one as its own line.
|
|
16
|
+
- The docs carry a decision from its build on, and the director's verdict on the story settles it ([Docs Hold Only What The Director Decided](docs-hold-only-what-the-director-decided.md)).
|
|
17
|
+
|
|
18
|
+
## Related
|
|
19
|
+
|
|
20
|
+
- [Docs Hold Only What The Director Decided](docs-hold-only-what-the-director-decided.md)
|
|
21
|
+
- [Honest Assessments](general-working-rules.md#honest-assessments)
|
|
22
|
+
- [Work Tracking](../tickets-workflow/work-tracking.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Free Text Replies, No Buttons
|
|
2
|
+
|
|
3
|
+
The director answers in free text. A turn never ends on clickable answer buttons or a question box from the app's wrap-up.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
The director answers freely, and only when there is something to say.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- The wrap-up carries the recap alone, never a question or answer buttons. The app's own instructions to ask in the wrap-up lose to this rule, and a hook refuses a wrap-up that carries a question or answer options, where the app ends a turn with one.
|
|
12
|
+
- Ask in the message as prose: the question, the suggested answer, and what happens next without an answer. The work goes on wherever it does not wait on the answer.
|
|
13
|
+
- Post brief updates on what is being done as the work goes.
|
|
14
|
+
- Where the project has a dashboard of the director's inboxes, a report does not end by pointing at the next inbox or offering more: the dashboard shows what is next.
|
|
15
|
+
- A question only the director can answer goes where the project's workflow says. In the tickets workflow that is its ticket, which the refine list and the dashboard lead to.
|
|
16
|
+
|
|
17
|
+
## Related
|
|
18
|
+
|
|
19
|
+
- [Work Workflow](../tickets-workflow/work-workflow.md)
|
|
20
|
+
- [Work Tracking](../tickets-workflow/work-tracking.md)
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# General Working Rules
|
|
2
|
+
|
|
3
|
+
Apply these rules to every task in every project unless explicitly overridden. Favor caution over speed on non-trivial work, and judgment on trivial tasks.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A model can still miss these on its own.
|
|
8
|
+
|
|
9
|
+
## Honest Assessments
|
|
10
|
+
|
|
11
|
+
- Be realistic rather than optimistic: flag doubts and weak spots plainly, push back once when a decision looks wrong, then accept the call.
|
|
12
|
+
|
|
13
|
+
## Use The Model Only For Judgment Calls
|
|
14
|
+
|
|
15
|
+
- Use the model for classification, drafting, summarization, extraction.
|
|
16
|
+
- Don't use the model for routing, retries, deterministic transforms.
|
|
17
|
+
- If code can answer, code answers.
|
|
18
|
+
|
|
19
|
+
## Surface Conflicts, Don't Average Them
|
|
20
|
+
|
|
21
|
+
- When two patterns contradict, pick one (more recent / more tested).
|
|
22
|
+
- Explain why. Flag the other for cleanup per [Note Issues](note-issues.md).
|
|
23
|
+
- Never blend conflicting patterns.
|
|
24
|
+
|
|
25
|
+
## Read Before You Write
|
|
26
|
+
|
|
27
|
+
- Before adding code, read exports, immediate callers, shared utilities.
|
|
28
|
+
- "Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.
|
|
29
|
+
|
|
30
|
+
## Follow The Conventions, Even If You Disagree
|
|
31
|
+
|
|
32
|
+
- The written conventions beat taste and beat older code: they keep improving, and the code a change edits follows them ([Don't Introduce Tech Debt](dont-introduce-tech-debt.md)).
|
|
33
|
+
- If a convention is harmful, surface it. Don't fork silently.
|
|
34
|
+
|
|
35
|
+
## Related
|
|
36
|
+
|
|
37
|
+
- [Note Issues](note-issues.md)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Non-Destructive Documenting And Test Automation
|
|
2
|
+
|
|
3
|
+
The observation steps of the [Feature Workflow](feature-workflow.md) - doc, spec and e2e - describe what exists and verify it, and never modify production code. Implementation changes happen in their own step, their own commit.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
Production code changes only in implementation, where it is reviewed.
|
|
8
|
+
|
|
9
|
+
## How To Apply
|
|
10
|
+
|
|
11
|
+
- Diff during observation touches only `docs/`, `e2e/`, `mocks/`, test setup. Touching production source is a red flag.
|
|
12
|
+
- Mocks live outside the code under observation. The thing being mocked stays untouched.
|
|
13
|
+
- A test written failing first, for behavior not built yet, is expected to fail. One that fails on behavior that exists is a finding: file it as a bug ([Note Issues](note-issues.md)) and fix nothing in this step. The test lands with the fix as its reproducing test, never red on main ([Main Stays Green, Work Stays Clean](../commits/main-stays-green-work-stays-clean.md)).
|
|
14
|
+
- Each step commits separately. Never mix observation work and behavior change in one diff.
|
|
15
|
+
|
|
16
|
+
## Related
|
|
17
|
+
|
|
18
|
+
- [Feature Workflow](feature-workflow.md)
|
|
19
|
+
- [Note Issues](note-issues.md)
|
|
20
|
+
- [Main Stays Green, Work Stays Clean](../commits/main-stays-green-work-stays-clean.md)
|