feat(skills): naming firewall + conventions contract + coherence sweep#3
Merged
Conversation
Parallel fan-out is where coherence breaks: each subagent sees only its own issue and contract rows, names and structures locally, and the merged feature reads as written by a committee. The plugin already pinned wire contracts up front, handed them down, and re-checked them — but did none of that for naming and structural conventions. Separately, organizing labels (Flow N) leaked from issue titles into specs and on into code identifiers. - references/naming-and-coherence.md: single source of truth for the conventions contract, the naming firewall (organizing labels never become identifiers), and "coherence is a signal". The four skills reference it. - planning-a-feature: §6 pins a ## Conventions block alongside ## Contracts; §2 fences the firewall at spec authoring; anti-patterns + red flags added. - writing-github-issues: §Title hygiene (clean prefix, no trailing "(Flow N)" parenthetical, no decorative arrows) + §The naming firewall; anti-patterns and red flags. - fanning-out-with-worktrees: conventions block is now mandatory dispatch context; a naming/layout-divergence watch category; per-sub-PR review checks the diff against the conventions; anti-pattern + red flag. - reviewing-feature-progress: new Step 3 cross-PR coherence sweep (renumbers 4-7), a Coherence findings bullet in the synthesis, anti-patterns + red flags so "contracts + criteria + CI green" can no longer be called "all clean". Verified RED->GREEN with subagents: baseline leaked Flow 2 into fixture dir / test name / marker and declared the drifted branch "all clean → open the integration PR"; with the skills, the label stays out of code and the checkpoint routes the drift to a convergence sub-PR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a “naming firewall” and an explicit “conventions contract” to the feature-dev workflow skills so parallel fan-out produces coherent, consistently named output (and so orchestration checkpoints can detect and correct cross-PR drift).
Changes:
- Introduces
references/naming-and-coherence.mdas the single source of truth for conventions, the naming firewall, and coherence rationale. - Updates planning + fan-out skills to require and propagate a plan
## Conventionsblock alongside contracts. - Updates issue-writing and progress-review skills to enforce title hygiene, prevent organizing-label leakage into identifiers, and add a cross-PR coherence sweep step.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/writing-github-issues/SKILL.md | Adds title hygiene guidance and codifies the naming firewall in issue authoring. |
| skills/reviewing-feature-progress/SKILL.md | Adds a cross-PR coherence sweep and requires reporting coherence findings at checkpoints. |
| skills/planning-a-feature/SKILL.md | Requires pinning a ## Conventions section in plans and establishes the naming firewall early. |
| skills/fanning-out-with-worktrees/SKILL.md | Makes the ## Conventions block mandatory dispatch context and adds naming/layout divergence to watch for. |
| references/naming-and-coherence.md | New reference doc defining the conventions contract, naming firewall, and coherence-as-signal framing. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
These skill sources were hand-wrapped at ~80-100 columns (no formatter enforces it — the repo has none), which the user never asked for and which reads as ragged short lines in diffs. Join soft-wrapped prose and list-item continuations into one line per paragraph; a genuine paragraph break stays a blank line. Tables, fenced code, headings, and frontmatter are byte-identical (verified). Covers the five markdown files this PR owns; the rest of the repo's markdown is unwrapped in a sibling PR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The only anti-wrap guidance in the plugin was scoped to published issue/PR bodies and explicitly called hard-wrapping skill SOURCE files "a source-file convention." That carve-out is what produced the wrapped sources and trained the habit — and after the prose reflow it was self-contradictory (the document claimed to be hard-wrapped while no longer being so). Generalize the rule: one line per paragraph in everything authored — bodies and source files alike. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The rule cited an "80-100 column guide" / "~90 columns" as if a cap existed to respect. It doesn't — the point is to never insert a wrap newline at all. State it without a number: one line per paragraph, the renderer soft-wraps.
- Spelling: artefact → artifact (repo uses the US spelling everywhere; writing-github-issues + references/naming-and-coherence). - Grammar: reword the plural-subject "two schemes ... is the signal" in the coherence sweep. - List rendering: the prose-unwrap reflow had three bugs in writing-github-issues — the literal `<!-- -->` in Step 2A item 1 tripped the comment-skip and split the item mid-sentence; and continuations after the heredoc code blocks (Steps 2A.3, 2B.5) and the blockquote (2C.2) lost their list indentation, so they rendered as top-level paragraphs. Rejoin item 1 and re-indent the three continuations so the ordered lists render intact. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
sourcehawk
added a commit
that referenced
this pull request
May 29, 2026
The prose reference to `<!-- -->` guidance tripped the unwrap's comment-skip, leaving the paragraph split across two physical lines. It renders as one paragraph (adjacent lines join), but it's an incomplete unwrap — join it. Same defect class the PR #3 review caught in writing-github-issues.
Dispatch (Step 2) and the anti-patterns treat the plan's ## Conventions block as required, but the "When to invoke" prerequisites only named ## Contracts. Add ## Conventions to the gate so the requirement and the prerequisite list agree.
…coherence skill The reference doc was mis-cast: it's a pattern/discipline, not lookup material, and broader than "naming" (the conventions contract + coherence-as-signal span structure, interfaces, layering, vocabulary, and idiom — naming is one dimension). Promote it to skills/maintaining-architectural-coherence/, expanded to name all the coherence dimensions, with the naming firewall as a sub-rule. De-duplicate: reviewing-feature-progress Step 3 no longer restates the dimensions/firewall/signal — it invokes the skill as a REQUIRED SUB-SKILL and keeps only the checkpoint-gate behaviour (run the sweep, classify findings, feed the gap list). planning, fanning-out, and writing-github-issues now cite the skill instead of the deleted reference, dropping their inline copies of the firewall and the conventions-dimension list. README skills table updated. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
"GitHub renders fenced ` ```mermaid ` blocks" put three backticks inside a single-backtick code span, which terminates the span early and renders wrong. Reword to `mermaid`.
sourcehawk
added a commit
that referenced
this pull request
May 29, 2026
…#4) * chore(skills): unwrap markdown prose to one line per paragraph These sources were hand-wrapped at ~80-100 columns (no formatter enforces it — the repo has none), which reads as ragged short lines in diffs and was never an intentional convention. Join soft-wrapped prose and list-item continuations into one line per paragraph; a genuine paragraph break stays a blank line. Tables, fenced code, headings, and frontmatter are byte-identical (verified). Covers every markdown file except the four SKILL.md being reworked in the naming-coherence PR (which carries their unwrap, to keep zero file overlap). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(templates): stop restating skill-taught rules in project-CLAUDE The template's operational-rules block duplicated discipline the skills already teach when invoked (TDD, verify-before-done, PR-title hygiene, the spec/plan/state lifecycle). A rule stated in both the template and a skill drifts — the state-dir move had to be edited in both places. Keep only what a skill reads from here (the commit convention) or can't enforce alone (the two git/GitHub safety rules); delete the rest and say why. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(skills): join paragraph split by the reflow's <!-- --> false-trigger The prose reference to `<!-- -->` guidance tripped the unwrap's comment-skip, leaving the paragraph split across two physical lines. It renders as one paragraph (adjacent lines join), but it's an incomplete unwrap — join it. Same defect class the PR #3 review caught in writing-github-issues. * fix(templates): restore feature-state.md YAML frontmatter The prose reflow only treated frontmatter as verbatim when it starts at line 1. feature-state.md opens with an HTML comment block before its `---` frontmatter, so the reflow joined the YAML fields onto one line — invalid, unparseable frontmatter. Restore the multi-line block; keep the one valid list-item unwrap the reflow also made. * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Comment on lines
+63
to
+65
| ## Don't hard-wrap markdown prose | ||
|
|
||
| Write each paragraph as a single line and put a blank line between paragraphs. Write each list item as a single line too. GitHub renders issue bodies far wider than an editor's 80–100 column guide, so a body hard-wrapped at ~90 columns reflows into ragged short lines in the GitHub view — the line breaks you inserted become visible noise the reader didn't ask for. Let GitHub do the wrapping. | ||
| Write each paragraph as a single line and put a blank line between paragraphs. Write each list item as a single line too. This applies to everything you author: the issue/PR body you publish AND markdown source files (these skills, their templates, READMEs, docs). There is no column cap to respect — GitHub and editors soft-wrap on their own, so any newline you insert mid-paragraph just reflows into ragged short lines in the rendered view and in every diff. Let the renderer wrap. Tables, fenced code, and YAML frontmatter keep their own line structure. |
Comment on lines
+31
to
+35
| **Spec.** Capture the brainstorm's conclusions in a spec at `docs/superpowers/specs/YYYY-MM-DD-<slug>-design.md`. The spec is the feature's design record — WHAT we're building and WHY, with goals, non-goals, design choices, risks, alternatives considered. It does **not** enumerate PRs, commits, or parallelism contracts (those live in the plan, see step 6). Slug is short ("multi-tenant-profiles", not "implement-multi-tenant-profile-system"); date is the conception date. | ||
|
|
||
| The spec's section headings may use the decomposition's organizing labels (`Flow 1`, `Flow 2`, …) to index the work — that's navigational. But nothing downstream (fixture names, ids, functions, files, marker strings) may inherit those labels as identifiers — the naming firewall in `feature-dev-workflow:maintaining-architectural-coherence`. | ||
|
|
||
| **ADR (only if the brainstorm surfaced a project-wide architectural decision).** A spec captures feature-scoped design. An ADR captures **cross-cutting** decisions that affect multiple features — choosing one architectural approach over another for reasons that future readers will need. Examples of ADR-worthy decisions: introducing a new IPC channel, picking a state-of-the-art pattern over the project's current default, rejecting a tempting alternative. Examples of NOT ADR-worthy: feature-specific design (that's the spec), operational conventions (CLAUDE.md), file naming (CLAUDE.md). |
Comment on lines
56
to
58
| | `opening-a-pull-request` | About to `gh pr create`/`edit`. Draft and ready body templates, issue-linking keywords. | | ||
| | `maintaining-architectural-coherence` | Work split across PRs/agents/waves must read as one author. Invoked when agreeing conventions before parallel work, and when reviewing the merged union for structural, interface, naming, and vocabulary drift. | | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Parallel fan-out is where coherence breaks: each subagent sees only its own issue and contract rows, so it names and structures locally, and the merged feature reads as written by a committee. The plugin already pinned wire contracts up front, handed them down, and re-checked them — but did none of that for naming and structural conventions. Separately, organizing labels (
Flow N) leaked from issue titles into specs and on into code identifiers. This adds the missing half.Changes
references/naming-and-coherence.md: single source of truth for the conventions contract, the naming firewall (organizing labels never become identifiers), and "coherence is a signal." The four skills reference it.planning-a-feature: pins a## Conventionsblock alongside## Contracts; fences the firewall at spec authoring.writing-github-issues: title hygiene (cleanFlow N:prefix, no trailing(e2e Flow 1), no decorative arrows) + the naming firewall.fanning-out-with-worktrees: the conventions block is mandatory dispatch context; a naming/layout-divergence watch category; per-sub-PR review checks the diff against the conventions.reviewing-feature-progress: a new cross-PR coherence sweep step + a Coherence-findings synthesis bullet, so "contracts + criteria + CI green" can no longer be declared "all clean."Testing
Verified RED→GREEN with subagents per
superpowers:writing-skills. Baseline (skills unchanged): an agent leakedFlow 2into a fixture dir, a test name, and a marker string, and the checkpoint declared a visibly-drifted branch "all clean → open the integration PR." With the changes: the label stays out of code (resumable-investigation,TestInvestigationSessionHappyPath), and the checkpoint runs the coherence sweep and routes the drift to a convergence sub-PR. No executable code in this repo; the skills are markdown.