RFC-0040: Shared-library-first guidance for Craft apps (#62)

This commit is contained in:
Dylan M. Taylor authored and GitHub committed 2026-11-16 21:57:39 -05:00
1 parent cd77f54561
commit 937c37449f
3 files changed
+60

No files matched your search

+2
View File
@@ -1,5 +1,7 @@
# RFC-0006: A shared section for coding agents (`AGENTS.md`)
Updated by: [RFC-0040](0040-shared-library-first-guidance.md)
Related: storytold/craft-libs#37, storytold/craft-libs#38.
## Summary
@@ -0,0 +1,57 @@
# RFC-0040: Shared-library-first guidance for Craft apps
Updates: [RFC-0006](0006-coding-agents.md)
## Summary
Add one app-scoped rule to the canonical core house rules: before implementing
reusable formats, codecs, protocols or UI, check craft-libs and relevant open
work, then reuse or extend the shared API instead of keeping another app-local
implementation. App-specific policy and model mapping remain in the app.
## Motivation
Separate guidance paragraphs in app AGENTS.md files can drift or contradict
existing rules. One canonical rule, copied by the existing generated-block
mechanism, makes the shared-library direction consistent without treating a
new instruction as evidence that any existing cutover is complete.
## Decision
Add point 16 to `standards/house-rules-core.md`. Its scope is Craft apps even
though the core block is also present in shared repositories. It preserves
behavior, hostile-input/resource limits, attribution, layering and regression
coverage. It does not authorize sibling-application crate dependencies, alter
license/source allowlists or change platform requirements.
Existing maintainer-approved exceptions remain explicit local instructions.
For example, an app-local parser selected by an accepted ADR is not silently
replaced by this guidance; changing it requires the separate decision, code
change and parity verification appropriate to that repository. A documented
exception is not a reason to silently drop behavior during a cutover.
This changes contributor guidance, not application code or dependency pins.
It does not declare any app or format migrated. The existing runtime-migration
proposal [RFC-0036](https://github.com/storytold/craft-contrib/pull/56) addresses
specific copies and their test suites; this RFC neither accepts its inventory
nor replaces its migration decisions.
## Rollout
After the canonical change is merged, regenerate each app's applicable shared
blocks from the merged source revision using the existing house-rules tool.
Do not hand-edit generated blocks or stamp an unmerged source revision.
Update existing guidance PRs rather than creating duplicate synchronization
PRs. Remove redundant app-local copies of the common paragraph, while
preserving local exceptions and app-specific restrictions.
Use the house-rules integrity check on each regenerated app file and review
its full diff for unintended changes. No runtime validation is implied by the
documentation check; code cutovers still need their own tests and reviews.
## Process
This adds a rule to the living document named by RFC-0006 and therefore follows
[RFC-0013](0013-amending-rfcs.md), including this RFC-0006 back-link. Under
RFC-0000 the normal comment period is three days; the maintainer/owner process
remains unchanged.
+1
View File
@@ -17,3 +17,4 @@ These apply in every Craft repository. A later rule may be stricter, not weaker.
13. **Instructions must be readable by everyone.** No notes about one machine, and no links to files a reader cannot open. `craftrules` is retired. Do not link to it.
14. **Keep pull requests moving.** Concurrent pull requests are fine; unanswered actionable feedback is not. Respond in 7 days, a reminder at 14, closure eligible at 30, from when an actionable request waits on the author. Suggestions and unconfirmed bot findings do not start the clock. A fix, explanation or agreed plan resets it; unrelated activity does not. Waiting on a reviewer or maintainer pauses it and does not count against the author. A maintainer decides closure; it is never automatic. Reuse search results, do not poll, and stop at a rate limit.
15. **No agent attribution.** A pull request does not say an agent wrote it. A repository rule may not require that.
16. **Shared libraries first for Craft apps.** Before adding or changing reusable file-format, codec, protocol or UI code, check `storytold/craft-libs` and relevant open pull requests. Reuse its public APIs or extend the appropriate shared library instead of duplicating an implementation in an app. Keep app-specific policy and model mapping local; preserve behavior, security and resource limits, attribution, layering and regression coverage. Document API gaps and maintainer-approved exceptions rather than silently dropping behavior. This does not authorize dependencies on sibling application crates or override existing platform, licensing or dependency-source requirements.