conventions.md claims every skill and workflow follows it, and is @-included by one skill of twenty-three #67

New issue

Closed

opened 2026-07-28 17:41:28 +00:00 by crenshawdev · 0 comments

crenshawdev commented

2026-07-28 17:41:28 +00:00

(Migrated from github.com)

What happened

cadence-core/references/conventions.md opens by claiming a reach it does not have:

# cadence-core/references/conventions.md:1-3
# Cadence conventions

Shared rules every skill and workflow follows. Referenced, not repeated.

It is @-included by exactly one file:

$ grep -rn '@.*conventions\.md' skills/ cadence-core/workflows/ agents/
skills/cad-pause/SKILL.md:22:@${CLAUDE_PLUGIN_ROOT}/cadence-core/references/conventions.md

Every other citation is prose. 5 skills and 13 workflows name the file without loading it, and no agent mentions it at all. So its 99 lines of rules, covering paths, config resolution, parallel work, state, subagents and reviews, reporting style, and authoring style, reach the model only when something happens to read the file.

This is not a missing mechanism. Skills use @${CLAUDE_PLUGIN_ROOT} 27 times for other things, so the include works and is in active use. Workflows use it zero times.

What you expected

Either the header's claim is true, or the header does not make it. "Referenced, not repeated" describes an architecture that was designed and then not wired, and the file states it as fact.

The practical consequence is worse than an unenforced rule. 18 files point at a contract that loads by accident, so each of them either restates the rule locally or quietly diverges from it, and nothing distinguishes the two. That is how contradictory guidance across layers gets manufactured, which is the failure mode Anthropic names directly in the new rules of context engineering: overlapping and conflicting instructions cost the model reasoning before it can act.

Reproduction

head -3 cadence-core/references/conventions.md
grep -rn '@.*conventions\.md' skills/ cadence-core/workflows/ agents/ | wc -l   # 1
grep -rln 'conventions\.md' skills/ | wc -l                                     # 5
grep -rln 'conventions\.md' cadence-core/workflows/ | wc -l                      # 13
grep -rn '@\${CLAUDE_PLUGIN_ROOT}' cadence-core/workflows/ | wc -l               # 0

Environment

Claude Code version: 2.1.220
node --version: v26.4.0
OS: Linux (CachyOS, 7.1.5-1-cachyos)
Cadence: v1.4.0 at fba5879

Notes

Two ways to close it, and the choice is a real one.

Make the claim true: @-include conventions.md from every skill and workflow. This costs resident context in every session that loads any of them, for rules most invocations never need.

Make the claim honest: soften the header to what is actually true, that the file is a reference workflows cite when a rule applies, and let progressive disclosure do its job. This is the two-line fix and it is the one that matches how the file is really used.

The second is probably right, but it should be decided rather than defaulted into. Whatever gets chosen, decide it before any new rule is added to this file, because a rule landing here inherits whatever reach the file actually has.

## What happened `cadence-core/references/conventions.md` opens by claiming a reach it does not have: ``` # cadence-core/references/conventions.md:1-3 # Cadence conventions Shared rules every skill and workflow follows. Referenced, not repeated. ``` It is `@`-included by exactly one file: ``` $ grep -rn '@.*conventions\.md' skills/ cadence-core/workflows/ agents/ skills/cad-pause/SKILL.md:22:@${CLAUDE_PLUGIN_ROOT}/cadence-core/references/conventions.md ``` Every other citation is prose. 5 skills and 13 workflows name the file without loading it, and no agent mentions it at all. So its 99 lines of rules, covering paths, config resolution, parallel work, state, subagents and reviews, reporting style, and authoring style, reach the model only when something happens to read the file. This is not a missing mechanism. Skills use `@${CLAUDE_PLUGIN_ROOT}` 27 times for other things, so the include works and is in active use. Workflows use it zero times. ## What you expected Either the header's claim is true, or the header does not make it. "Referenced, not repeated" describes an architecture that was designed and then not wired, and the file states it as fact. The practical consequence is worse than an unenforced rule. 18 files point at a contract that loads by accident, so each of them either restates the rule locally or quietly diverges from it, and nothing distinguishes the two. That is how contradictory guidance across layers gets manufactured, which is the failure mode Anthropic names directly in [the new rules of context engineering](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models): overlapping and conflicting instructions cost the model reasoning before it can act. ## Reproduction ``` head -3 cadence-core/references/conventions.md grep -rn '@.*conventions\.md' skills/ cadence-core/workflows/ agents/ | wc -l # 1 grep -rln 'conventions\.md' skills/ | wc -l # 5 grep -rln 'conventions\.md' cadence-core/workflows/ | wc -l # 13 grep -rn '@\${CLAUDE_PLUGIN_ROOT}' cadence-core/workflows/ | wc -l # 0 ``` ## Environment - Claude Code version: 2.1.220 - `node --version`: v26.4.0 - OS: Linux (CachyOS, 7.1.5-1-cachyos) - Cadence: v1.4.0 at `fba5879` ## Notes Two ways to close it, and the choice is a real one. Make the claim true: `@`-include `conventions.md` from every skill and workflow. This costs resident context in every session that loads any of them, for rules most invocations never need. Make the claim honest: soften the header to what is actually true, that the file is a reference workflows cite when a rule applies, and let progressive disclosure do its job. This is the two-line fix and it is the one that matches how the file is really used. The second is probably right, but it should be decided rather than defaulted into. Whatever gets chosen, decide it before any new rule is added to this file, because a rule landing here inherits whatever reach the file actually has.