Skip to content

docs(agents): define repository workflow conventions - #962

Merged
tobyhede merged 1 commit into
mainfrom
docs/agent-workflow-conventions
Sep 2, 2026
Merged

docs(agents): define repository workflow conventions#962
tobyhede merged 1 commit into
mainfrom
docs/agent-workflow-conventions

Conversation

@tobyhede

@tobyhede tobyhede commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

Summary

Define the repository-wide conventions used by agent skills for issue tracking,
triage labels, and domain documentation.

Changes

  • Route active EQL work to cipherstash/stack rather than the historical EQL repository.
  • Add the repository context map and initial EQL glossary.
  • Document the multi-context domain/ADR layout used by domain-modeling workflows.
  • Map canonical agent triage roles to this repository's GitHub labels.
  • Add concise pointers from CLAUDE.md instead 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.

@tobyhede
tobyhede requested a review from a team as a code owner September 2, 2026 00:02
@changeset-bot

changeset-bot Bot commented Sep 2, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: ec590a0

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@freshtonic freshtonic left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 in packages/eql/AGENTS.md where 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.md is honest about lazy creation ("if these files do not exist, proceed silently; do not propose empty placeholders") — the example layout naming packages/stack/CONTEXT.md etc. is aspiration, and the doc says so. The docs/adr/ convention coexists sensibly with docs/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/*.md files ride through.

Create (or caveat) the labels and this is an approve.

@tobyhede
tobyhede requested a review from freshtonic September 2, 2026 01:39

@freshtonic freshtonic left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@tobyhede
tobyhede merged commit be4d114 into main Sep 2, 2026
25 checks passed
@tobyhede
tobyhede deleted the docs/agent-workflow-conventions branch September 2, 2026 04:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants