2.8 KiB
Rule:
Committed in main, branch deleted means the work is done. Having code uncommitted or committed in a branch or worktree means you failed to deliver. Pushing is not a thing we really care about.
Rule:
MDs dont have hard wraps. IF you come across one make it soft wrapping
Rule:
In documentations so not write bloat like:
The obvious objection, answered before it's asked. "They just open a new session." Yes. That's friction, not a wall, and it's meant to be.
Instead, write more concise, more technical English, e.g. :
One objection is that they just open a new session. Yet, this friction is by design because ...
Bad Example:
Could we verify them first to save the human a step? Only if the receiving system will accept our verification. If it re-authenticates anyway we've added a step to save none — worth asking in a real deployment, not worth assuming.
Good example:
We should only verify them first, if the receiving system will accept our verification? Otherwise it double work for the customer.
Rule:
The package is app, following the boilerplate: the deploy kit, APP_CONFIG, APP_PASSWORD and APP_DATA assume that name. The domain noun is role, so "job" only ever means queued work.
Rule:
pipeline/, auth/, llm/ and deploy/ are downstream copies of ../boilerplate, taken whole with git archive; the generic modules of desk/ (modeltask, notices, config, tools/*) are copies of ../news's, taken file by file; desk/sources/* and desk/models.py are roledesk's own. A fix to a copy lands upstream first, otherwise the next refresh reverts it. The drift check is diff -rq --strip-trailing-cr -x __pycache__ <folder> ../boilerplate/<folder>.
Rule:
Phone and UI patterns come from ../news (frontend/src/app.css, a React page since October 2026) and ../health (webapp/static/app.css), which went through the phone fixes already; the boilerplate's are in its frontend/src/app.css and its Kit tab. roledesk's page is Jinja templates and plain JS: copy their CSS fragments and layout rules, do not write new ones, and do not port components.
Rule:
A larger rework is planned first, as a doc in docs/ committed on main with work packages that own disjoint files, then built by Opus and Sonnet agents in parallel worktrees and merged into main by the planner. The plan is folded into decisions.md and deleted when the work lands.
Rule:
documentation/ holds the owner's ADRs (ADR Fetch prep and score.md, ADR Plugins.md): the target design and its key decisions, with no description of today's code. Each stands alone and may refer only to the other ADRs, never to docs/ or the code's files. What is built is tested against them. Change them only when the owner makes a key decision; the way there goes into a plan in docs/, the detailed reasoning into decisions.md.