Repository navigation
Agent flow + goals: change placement, drawn explainer, comment/todo policy - #431
Merged
Merged
Conversation
Contributor
Author
|
Second follow-up commit pushed (
All three docs sit in sync globs deliberately — #597 is what makes them permanent for every child. |
…s goals - docs/agents/change-placement.md: one branch per need — bug, missing capability, pattern improvement, improving the flow itself. First rule encodes the session's learning: sync-owned files are a contribution channel, not a fence — edit there AND file upstream in the same PR. - docs/agents/how-it-fits.md: human-facing drawn tour of the runtime (authored → published → resolved → served; mounts/core-wins; generated types; where source lives; framework-internals pointers). /teach builds lessons from it. - CODING_STANDARDS.md: write-once / type-safety-as-drift-killer / workaround goals added as review-time rules with concrete citations; comments policy — none in implementation, `KEEP:` earns one, `TODO(<ticket>)` points at tracked work; deletions-first for comments and tests. No script: review enforces it from the diff. - AGENTS.md + README: pointers to the flow, the explainer, the standards.
…ing rules - how-it-fits.md: "Read the runtime's own state" — the .bos surfaces table (generated map, resolved-config vs published comparison, logs as last-resort truth, platform manifest, deploy-state, sync-backup, regression caches) plus the clean-at-source rule with TODO(#596) citing the upstream log-retention issue; teach-from-state principle added. - change-placement.md: classify via resolved-config comparison; clean-up-at- source rule; new "Branching and stacking" section (default one-branch-per- ticket; stack only on unmerged-own dependencies, branching from the named base; never branch from the working tree HEAD — cite the #429 absorption; parallel independent work coordinates via conflict comments, #416 model). - docs/agents/testing.md (new): when to test, the three layers, the parent-coverage boundary (compose/hydrate/mounts assumed upstream, npm ships no tests; verify-runtime-map as the cheap claim check; upstream #593 the future home), fitting the regression setup (boot economics, cookie cache, serial-by-design, watchdog), and how to write a good regression test. - tests/README.md + AGENTS.md: pointers to the doctrine; everything-dev-app skill: stack-on-named-base line in Work the frontier. All doc paths land in sync globs so the promotion ticket carries them upstream.
elliotBraem
force-pushed
the
docs/agent-flow-and-goals
branch
from
October 24, 2026 21:05
0213213 to
ecb9a4c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #428. Follow-up from the 2026-10-24 retro.
What
docs/agents/change-placement.md— one branch per need: bug (reproduce → classify local vs pinned platform → fix or upstream), missing capability (search first → smallest reference implementation → upstream with it attached → sync-safe interim + cleanup ticket), pattern improvement (child ADR vs upstream ADR), improving the flow itself. First rule encodes the retro's learning: sync-owned files are a contribution channel, not a fence — edit them here and file upstream in the same PR, becausebos upgraderegenerates those paths (and the whole authored half of AGENTS.md) from the template.docs/agents/how-it-fits.md— the human teach layer: drawn tour of the runtime (authored → published → resolved → served; mounts/core-wins; generated types; where source lives) plus framework-internals pointers for the dig./teachbuilds lessons from it; README links it.CODING_STANDARDS.md— the goals as review-time rules with concrete citations: write code once (fix once/feature once, everyone gets it; local-only fix = fork), type safety as the drift killer (infer from schemas/clients, never restate, generated beats hand-maintained), workaround protocol (upstream issue + cleanup ticket + upgrade-safe wiring), comments policy — none in implementation,KEEP:earns one,TODO(<ticket>)references tracked work, bare TODO is a violation; deletions-first for superfluous tests.Deliberately not here
No comment-lint script — review-time enforcement from the diff is the mechanism (retro decision); the discipline is covered by the
KEEP/TODOcontract in the standards.Upstream counterparts (same-PR pairing)
types genowns the composition inventory (removes the child script + its upgrade hazard)@shadcn/lint(dep ships, nothing runs it)Verification
Docs-only:
pnpm run lintgreen; mermaid blocks render on GitHub; links target-checked.