averello/compound-engineering-plugin-mirror
1
0
Fork 0
mirror of https://github.com/EveryInc/compound-engineering-plugin.git synced 2026-06-19 15:41:46 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs(skill-authoring): drop inaccurate Codex/Gemini claim from skill prose

Browse Source 
Three skill files claimed that on non-Claude targets the `:-.` fallback
'yields the bare relative path those harnesses expect.' A Codex
investigation (converter source + live runtime) disproved this: the
converter preserves ${CLAUDE_SKILL_DIR:-.} verbatim and the var is unset
at runtime, so it expands to a project-CWD-relative ./scripts/... that
does NOT resolve to the bundled script (it lives in the platform's skill
store). The claim is the same overclaim corrected in the repo-root
AGENTS.md.

Per the plugin's Rationale Discipline (portability meta-commentary
belongs in commits/docs, not the runtime skill body), remove the false
clause rather than expand it. The `:-.` form is kept — it is correct on
Claude Code and harmless elsewhere — with a short, accurate note that it
only keeps the command syntactically valid where the var is unset.

ce-compound and ce-compound-refresh carry the duplicated validate-
frontmatter step, so both copies are edited in the same commit per the
plugin's duplicate-reference sync rule.
This commit is contained in:
Trevin Chow
2026-06-14 16:24:05 -07:00
parent 6d738573e8
commit fc80d8d3a2
3 changed files with 3 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/compound-engineering/skills/ce-compound-refresh/references/per-action-flows.md
+1 -1
View File
@@ -62,7 +62,7 @@ Do not let replacement subagents invent frontmatter fields, enum values, or sect
- The target path and category (same category as the old learning unless the category itself changed)
- The relevant contents of the three support files listed above
2. The subagent writes the new learning using the support files as the source of truth: `references/schema.yaml` for frontmatter fields and enum values, `references/yaml-schema.md` for category mapping and YAML-safety rules for array items, and `assets/resolution-template.md` for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
3. **Run `python3 "${CLAUDE_SKILL_DIR:-.}/scripts/validate-frontmatter.py" <new-learning-path>`** to catch silent-corruption parser-safety issues that the prose rules miss: malformed `---` delimiter lines, unquoted ` #` in scalar values (silent comment truncation), and unquoted `: ` in scalar values (silent mapping confusion). Exit 0 means the doc is parser-safe; exit 1 means the script's stderr names the offending field(s) and what to fix — quote the value(s), re-write the doc, and re-run until exit 0. Do not declare success while validation fails. The script does not enforce schema rules and does not flag YAML reserved-indicator characters (those produce loud parser errors downstream rather than silent corruption — out of scope). Uses Python 3 stdlib only (no PyYAML or other deps). The validator ships **inside the skill bundle**, not the user's repo, and the runtime Bash tool's CWD is the project root — so a bare `scripts/validate-frontmatter.py` resolves against `<project>/scripts/`, finds nothing, and this guard is silently skipped (the parser-safety protection never runs). `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory on Claude Code (marketplace-cached installs and `--plugin-dir` local dev); on other targets it is unset and the `:-.` fallback yields the bare relative path those harnesses expect.
3. **Run `python3 "${CLAUDE_SKILL_DIR:-.}/scripts/validate-frontmatter.py" <new-learning-path>`** to catch silent-corruption parser-safety issues that the prose rules miss: malformed `---` delimiter lines, unquoted ` #` in scalar values (silent comment truncation), and unquoted `: ` in scalar values (silent mapping confusion). Exit 0 means the doc is parser-safe; exit 1 means the script's stderr names the offending field(s) and what to fix — quote the value(s), re-write the doc, and re-run until exit 0. Do not declare success while validation fails. The script does not enforce schema rules and does not flag YAML reserved-indicator characters (those produce loud parser errors downstream rather than silent corruption — out of scope). Uses Python 3 stdlib only (no PyYAML or other deps). The validator ships **inside the skill bundle**, not the user's repo, and the runtime Bash tool's CWD is the project root — so a bare `scripts/validate-frontmatter.py` resolves against `<project>/scripts/`, finds nothing, and this guard is silently skipped (the parser-safety protection never runs). `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory on Claude Code (marketplace-cached installs and `--plugin-dir` local dev); the `:-.` fallback keeps the command valid where it is unset.
4. After the subagent completes, the orchestrator deletes the old learning file. The new learning's frontmatter may include `supersedes: [old learning filename]` for traceability, but this is optional — the git history and commit message provide the same information.
**When evidence is insufficient:**
plugins/compound-engineering/skills/ce-compound/SKILL.md
+1 -1
View File
@@ -251,7 +251,7 @@ The orchestrating agent (main conversation) performs these steps:
5. Validate YAML frontmatter against `references/schema.yaml`, including the YAML-safety quoting rule for array items (see `references/yaml-schema.md` > YAML Safety Rules)
6. Create directory if needed: `mkdir -p docs/solutions/[category]/`
7. Write the file: either the updated existing doc or the new `docs/solutions/[category]/[filename].md`
8. **Run `python3 "${CLAUDE_SKILL_DIR:-.}/scripts/validate-frontmatter.py" <output-path>`** to catch silent-corruption parser-safety issues that the prose rules miss: malformed `---` delimiter lines, unquoted ` #` in scalar values (silent comment truncation), and unquoted `: ` in scalar values (silent mapping confusion). Exit 0 means the doc is parser-safe; exit 1 means the script's stderr names the offending field(s) and what to fix — quote the value(s), re-write the doc, and re-run until exit 0. Do not declare success while validation fails. The script does not enforce schema rules and does not flag YAML reserved-indicator characters (those produce loud parser errors downstream rather than silent corruption — out of scope). Uses Python 3 stdlib only (no PyYAML or other deps). The validator ships **inside the skill bundle**, not the user's repo, and the runtime Bash tool's CWD is the project root — so a bare `scripts/validate-frontmatter.py` resolves against `<project>/scripts/`, finds nothing, and this guard is silently skipped (the parser-safety protection never runs). `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory on Claude Code (marketplace-cached installs and `--plugin-dir` local dev); on other targets it is unset and the `:-.` fallback yields the bare relative path those harnesses expect.
8. **Run `python3 "${CLAUDE_SKILL_DIR:-.}/scripts/validate-frontmatter.py" <output-path>`** to catch silent-corruption parser-safety issues that the prose rules miss: malformed `---` delimiter lines, unquoted ` #` in scalar values (silent comment truncation), and unquoted `: ` in scalar values (silent mapping confusion). Exit 0 means the doc is parser-safe; exit 1 means the script's stderr names the offending field(s) and what to fix — quote the value(s), re-write the doc, and re-run until exit 0. Do not declare success while validation fails. The script does not enforce schema rules and does not flag YAML reserved-indicator characters (those produce loud parser errors downstream rather than silent corruption — out of scope). Uses Python 3 stdlib only (no PyYAML or other deps). The validator ships **inside the skill bundle**, not the user's repo, and the runtime Bash tool's CWD is the project root — so a bare `scripts/validate-frontmatter.py` resolves against `<project>/scripts/`, finds nothing, and this guard is silently skipped (the parser-safety protection never runs). `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory on Claude Code (marketplace-cached installs and `--plugin-dir` local dev); the `:-.` fallback keeps the command valid where it is unset.
When creating a new doc, preserve the section order from `assets/resolution-template.md` unless the user explicitly asks for a different structure.
plugins/compound-engineering/skills/ce-worktree/SKILL.md
+1 -1
View File
@@ -15,7 +15,7 @@ Create a worktree under `.worktrees/<branch>` with branch-specific setup that `g
## Creating a worktree
Invoke the bundled script via the runtime Bash tool. On Claude Code, `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory across both marketplace-cached installs and `claude --plugin-dir` local development; the runtime Bash tool's CWD is the user's project, not the skill directory, so a bare `bash scripts/worktree-manager.sh` fails. On other targets (Codex, Gemini, Pi, etc.) `${CLAUDE_SKILL_DIR}` is unset and the `:-.` fallback yields the bare relative path those harnesses expect.
Invoke the bundled script via the runtime Bash tool. On Claude Code, `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory across both marketplace-cached installs and `claude --plugin-dir` local development; the runtime Bash tool's CWD is the user's project, not the skill directory, so a bare `bash scripts/worktree-manager.sh` fails. The `:-.` fallback keeps the command syntactically valid where `${CLAUDE_SKILL_DIR}` is unset.
```bash
bash "${CLAUDE_SKILL_DIR:-.}/scripts/worktree-manager.sh" create <branch-name> [from-branch]