Goal
Consolidate the issue-branch-worktree workflow, "Pre-Edit Workflow Gate," and
superseded-PR closure procedure to a single canonical document, with other
files linking to it instead of restating it.
Background
A documentation review of the process/CI/agent docs found the same workflow
content independently restated across many files, which is a real drift risk
(one copy has already partially drifted — see the companion GitHub Project
Initiative-duplicate issue for a concrete example of restated content going
stale):
- The "Pre-Edit Workflow Gate" paragraph is restated almost verbatim in three
files: AGENTS.md:25-39, docs/github-workflow.md:7-20, and
.ai-context/WORKFLOWS.md:3-16.
- The superseded-PR closure procedure is fully restated four separate times:
AGENTS.md:85-98, skills.md:40-56, docs/github-workflow.md:461-508,
and .ai-context/WORKFLOWS.md:134-139.
- The full issue/branch/worktree workflow (labels, branch shape, Project
status transitions) is independently restated across six files:
CONTRIBUTING.md:14-71, AGENTS.md:23-101, skills.md:6-38,
STANDARDS.md:661-691, all of docs/github-workflow.md, and
.ai-context/WORKFLOWS.md:18-104. Only docs/github-workflow.md needs the
full detail; the rest should point to it.
skills.md:16 narrows the auto-assign rule to "Codex-created issues" while
every other file (AGENTS.md:47-49, STANDARDS.md:668-669,
docs/github-workflow.md:79-80, .ai-context/WORKFLOWS.md:31) uses
tool-neutral "agent-created"/"automation" language — an example of the
restated copies already diverging in wording.
Scope
AGENTS.md
CONTRIBUTING.md
skills.md
STANDARDS.md
docs/github-workflow.md
.ai-context/WORKFLOWS.md
Acceptance Criteria
Validation
git diff --check; manual read-through confirming each file still makes
sense standalone with the trimmed summary + link.
Non-Goals
- Changing the actual workflow policy — this is a consolidation/DRY issue,
not a policy change.
Project Metadata
- Priority: P3
- Size: L
- Area: Docs
- Initiative: Contract Hardening
- Agent Assignment: Human first (requires editorial judgment on what to keep
as a local summary vs. trim entirely in each of six files)
Goal
Consolidate the issue-branch-worktree workflow, "Pre-Edit Workflow Gate," and
superseded-PR closure procedure to a single canonical document, with other
files linking to it instead of restating it.
Background
A documentation review of the process/CI/agent docs found the same workflow
content independently restated across many files, which is a real drift risk
(one copy has already partially drifted — see the companion GitHub Project
Initiative-duplicate issue for a concrete example of restated content going
stale):
files:
AGENTS.md:25-39,docs/github-workflow.md:7-20, and.ai-context/WORKFLOWS.md:3-16.AGENTS.md:85-98,skills.md:40-56,docs/github-workflow.md:461-508,and
.ai-context/WORKFLOWS.md:134-139.status transitions) is independently restated across six files:
CONTRIBUTING.md:14-71,AGENTS.md:23-101,skills.md:6-38,STANDARDS.md:661-691, all ofdocs/github-workflow.md, and.ai-context/WORKFLOWS.md:18-104. Onlydocs/github-workflow.mdneeds thefull detail; the rest should point to it.
skills.md:16narrows the auto-assign rule to "Codex-created issues" whileevery other file (
AGENTS.md:47-49,STANDARDS.md:668-669,docs/github-workflow.md:79-80,.ai-context/WORKFLOWS.md:31) usestool-neutral "agent-created"/"automation" language — an example of the
restated copies already diverging in wording.
Scope
AGENTS.mdCONTRIBUTING.mdskills.mdSTANDARDS.mddocs/github-workflow.md.ai-context/WORKFLOWS.mdAcceptance Criteria
docs/github-workflow.mdis the single canonical source for the fullissue/branch/worktree workflow, Pre-Edit Workflow Gate, and
superseded-PR closure procedure.
AGENTS.md,CONTRIBUTING.md,skills.md,STANDARDS.md, and.ai-context/WORKFLOWS.mdeach keep only the minimum summary neededfor their own audience and link to
docs/github-workflow.mdfor fulldetail, instead of restating it.
skills.md's "Codex-created" wording is aligned with the tool-neutral"agent-created" language used elsewhere.
Validation
git diff --check; manual read-through confirming each file still makessense standalone with the trimmed summary + link.
Non-Goals
not a policy change.
Project Metadata
as a local summary vs. trim entirely in each of six files)