docs(agents): define repository workflow conventions - #962
Conversation
|
freshtonic
left a comment
There was a problem hiding this comment.
Requesting changes on one two-minute item; everything else here is what I asked #961 to split out, done properly, and I'm glad to see it as its own deliberate decision.
The blocker: docs/agents/triage-labels.md maps roles to labels that don't exist. The table says these are "this repository's GitHub labels", but I checked the live label list: of the five, only wontfix exists — needs-triage, needs-info, ready-for-agent, and ready-for-human are not repo labels. An agent following this doc fails immediately (gh issue edit --add-label needs-triage errors on an unknown label). Since this PR's whole purpose is agent-facing conventions that are true, either create the four labels alongside the doc (gh label create ×4 — happy with any colours) or have the doc say they must be created on first use. Same class of note for the wayfinder:map / wayfinder:<type> labels in issue-tracker.md's Wayfinding section — those don't exist either; a one-line "create on first use" there covers it.
Verified clean:
- The repository-ownership routing (file EQL/protect-ffi work in
cipherstash/stack, never the archived upstreams) is accurate, and it's correctly stated once in AGENTS.md for every agent and reinforced inpackages/eql/AGENTS.mdwhere the subtree's own docs would otherwise mislead. - The split of concerns is right: universal facts land in AGENTS.md; Claude-specific skill-consumption glue is pointers in CLAUDE.md to
docs/agents/*, keeping the "AGENTS.md is the single source of truth" contract intact rather than violating it the way the original in-#961 version did. docs/agents/domain.mdis honest about lazy creation ("if these files do not exist, proceed silently; do not propose empty placeholders") — the example layout namingpackages/stack/CONTEXT.mdetc. is aspiration, and the doc says so. Thedocs/adr/convention coexists sensibly withdocs/plans/(decisions vs designs); with this PR as its own decision point, my convention-by-fait-accompli objection on #961 is resolved.packages/eql/CONTEXT.md's glossary is genuinely good — the durable-domain / disposable-machinery / derived-index / non-reconstructable-dependency vocabulary is exactly the language #961's refusal messages need, and the Avoid lines will keep issue titles from drifting.- No changeset is correct: nothing here ships in any tarball.
- CI green, including the EQL docs scans the new
packages/eql/*.mdfiles ride through.
Create (or caveat) the labels and this is an approve.
freshtonic
left a comment
There was a problem hiding this comment.
Approving. The blocker was resolved on the repository side, which is the better fix: all four triage labels (needs-triage, needs-info, ready-for-agent, ready-for-human) now exist on cipherstash/stack — verified against the live label list — and the wayfinding labels (wayfinder:map plus all four wayfinder:<type> values) were created too, which goes beyond what I asked and makes the issue-tracker doc's Wayfinding section true as written rather than caveated. The document set is unchanged from what I already verified (ownership routing accurate, AGENTS.md/CLAUDE.md split of concerns correct, honest lazy-creation language, solid EQL glossary, no changeset correctly). Every claim in these docs now checks out against the live repo. CI green.
Summary
Define the repository-wide conventions used by agent skills for issue tracking,
triage labels, and domain documentation.
Changes
cipherstash/stackrather than the historical EQL repository.CLAUDE.mdinstead of inlining the reference material.Scope
This PR contains only repository agent-workflow and domain-documentation
conventions. The EQL safe-reinstall ADR and implementation are stacked in
PR #961.