principled
CLAUDE.md4 starsChanged 4 months agoMITView on GitHub
This file supplements the root CLAUDE.md with development-specific guidance for contributors working on the principled marketplace and its plugins. All eight first-party plugins are installed via .claude/settings.json. See root CLAUDE.md § Dogfooding for the full list of available skills and active hooks. Every plugin now uses the lib/ pattern (ADR-018) — one copy, no propagation: Edit in place. Skills reference them as ${CLAUDE_PLUGIN_ROOT}/lib/<name>. - Run bash scripts/check-skill-references.sh to verify every reference still resolves. - Referencing a file that does not…
- Commits and pushes
In this repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- check-ciSkill
- lintSkill
- propagate-templatesSkill
- test-hooksSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
13 rules. About 0 are common, 0 are distinctive, and 13 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
All eight first-party plugins are installed via .claude/settings.json.
- Very specific: line 27
Run bash plugins/principled-docs/skills/scaffold/scripts/check-template-drift.sh to verify zero drift.
- Very specific: line 32
Every plugin now uses the lib/ pattern (ADR-018) — one copy, no propagation:
- Very specific: line 42
Run bash scripts/check-skill-references.sh to verify every reference still resolves.
- Very specific: line 105
Unknown budgets must fail closed: When gh is unavailable the counts are unknown, and dispatch refuses.
- Very specific: line 124
Test both paths. tests/manifest-checkpoint.bats runs each operation with jq and with a PATH that genuinely lacks it, then validates the …
- Very specific: line 129
Every hook in it mirrors a step in .github/workflows/ci.yml.
- Very specific: line 148
When adding a plugin to plugins/ or external_plugins/, remember to add its entry to .claude-plugin/marketplace.json.
- Very specific: line 153
Run /lint or pre-commit run --all-files to check formatting and lint
- Very specific: line 154
Run /validate --root to check root structure (plugin skill, from dogfooding)
- Very specific: line 155
If you modified shared code in a lib/, run just refs to confirm references resolve
- Very specific: line 156
If you modified a drift-checked template (principled-docs scaffolding, or the cross-plugin check-gh-cli.sh), propagate copies first and run …
- Very specific: line 158
Run just test for the bats suite
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Development Context
This file supplements the root CLAUDE.md with development-specific guidance for contributors working on the principled marketplace and its plugins.
Dogfooding
All eight first-party plugins are installed via .claude/settings.json. See root CLAUDE.md § Dogfooding for the full list of available skills and active hooks.
Common Pitfalls
Editing Hook Scripts (principled-docs)
- Hook scripts read JSON from stdin. Always test with
echo '{"tool_input":{"file_path":"..."}}' | bash plugins/principled-docs/hooks/scripts/<script>.sh - Exit code 0 = allow, exit code 2 = block. Never use exit code 1 (reserved for script errors).
parse-frontmatter.shis a shared dependency. Changes to it affect bothcheck-adr-immutability.shandcheck-proposal-lifecycle.sh.
Editing Hook Scripts (principled-implementation)
- Same stdin JSON format:
echo '{"tool_input":{"file_path":"..."}}' | bash plugins/principled-implementation/hooks/scripts/check-manifest-integrity.sh - Advisory only — always exits 0. Never blocks.
- Uses jq with grep fallback for JSON parsing.
Modifying Templates (principled-docs)
- Always edit the canonical version first (in
plugins/principled-docs/skills/scaffold/templates/) - Then propagate to all copies. Use
/propagate-templatesor copy manually. - Run
bash plugins/principled-docs/skills/scaffold/scripts/check-template-drift.shto verify zero drift. - Forgetting to propagate = CI failure.
Modifying Shared Code (lib/)
Every plugin now uses the lib/ pattern (ADR-018) — one copy, no propagation:
plugins/principled-implementation/lib/{task-manifest,parse-plan,run-checks}.shplugins/principled-implementation/lib/templates/claude-task.mdplugins/principled-tasks/lib/task-db.shplugins/principled-agent/lib/agent-memory.shplugins/principled-agent/lib/agent-governance.sh
Edit in place. Skills reference them as ${CLAUDE_PLUGIN_ROOT}/lib/<name>.
- Run
bash scripts/check-skill-references.shto verify every reference still resolves. - Referencing a file that does not exist = CI failure. This is what caught
spawn/SKILL.mdinvoking aparse-plan.shthat was never copied intospawn.
Editing Hook Scripts (principled-github)
- Uses stdin JSON with
tool_input.command:echo '{"tool_input":{"command":"gh pr create ..."}}' | bash plugins/principled-github/hooks/scripts/check-pr-references.sh - Advisory only --- always exits 0. Never blocks.
Modifying check-gh-cli.sh (cross-plugin)
This is the only script still duplicated across plugins. principled-github,
principled-quality, principled-release and principled-agent install independently, so
${CLAUDE_PLUGIN_ROOT} cannot reach across the boundary and each needs its own copy.
Four copies, down from fifteen.
- Canonical:
plugins/principled-github/lib/check-gh-cli.sh - Propagate to
plugins/principled-quality/lib/,plugins/principled-release/lib/andplugins/principled-agent/lib/(or run/propagate-templates). - Verify with
bash scripts/check-cross-plugin-drift.sh. - Forgetting to propagate = CI failure.
Within a single plugin, shared code lives in lib/ with one copy — nothing to
propagate. Copying a lib/ script into a skill directory is a regression against
ADR-018.
Editing Hook Scripts (principled-quality)
- Uses stdin JSON with
tool_input.command:echo '{"tool_input":{"command":"gh pr review 42"}}' | bash plugins/principled-quality/hooks/scripts/check-review-checklist.sh - Advisory only --- always exits 0. Never blocks.
- Triggers on
gh pr reviewandgh pr mergecommands.
Editing Hook Scripts (principled-release)
- Uses stdin JSON with
tool_input.command:echo '{"tool_input":{"command":"git tag v1.0.0"}}' | bash plugins/principled-release/hooks/scripts/check-release-readiness.sh - Advisory only --- always exits 0. Never blocks.
- Triggers on
git tagcommands (excludesgit tag -landgit tag -d).
Editing Hook Scripts (principled-architecture)
- Uses stdin JSON with
tool_input.file_path:echo '{"tool_input":{"file_path":"src/index.ts"}}' | bash plugins/principled-architecture/hooks/scripts/check-boundary-violation.sh - Advisory only --- always exits 0. Never blocks.
- Triggers on Write of source files (
.ts,.tsx,.js,.jsx,.py,.go,.rs,.java). - Checks for module dependency direction violations by scanning imports against the module type system (ADR-003, ADR-014).
Editing Hook Scripts (principled-agent)
- Injection reads an agent id from stdin JSON, trying
agent_id,subagent_type,agent_type, thenagent— the field name has varied across Claude Code versions:echo '{"agent_id":"impl-worker"}' | bash plugins/principled-agent/hooks/scripts/inject-agent-memory.sh - Integrity uses
tool_input.file_pathand only reacts to paths under.agents/. - Both always exit 0. Injection runs on
SubagentStart, so a non-zero exit would block agent spawning outright. - Never make injection truncate. An agent handed a silently halved memory file has a confidently incomplete picture and no way to notice. Oversized memory is reported by the integrity hook; it is never trimmed on the way in.
Editing Governance Code (principled-agent)
agent-governance.shuses exit 3 for a refusal and exit 1 for an error. Never collapse them: a caller that conflates them either ignores a real refusal or halts on a transient fault.- Unknown budgets must fail closed. When
ghis unavailable the counts are unknown, and dispatch refuses. Treating unknown as zero would silently disable the safety layer exactly when the environment is already misbehaving.tests/agent-governance.batsasserts that--statusnever prints0/5for an unknown count. - The halt switch is a file path contract (
.agents/HALT) shared with principled-implementation. Plugins cannot call each other (ADR-018), so this coupling is invisible tocheck-skill-references.shand must be maintained by convention. If the path changes,/orchestratemust change with it. - The dispatch workflow is a template, not an active workflow. Do not add it to
.github/workflows/in this repository (ADR-023).
Editing the Manifest Schema (principled-implementation)
checkpointandacceptance_criteriaare additive and optional (ADR-021). Every consumer must tolerate their absence and ignore unknown fields.- Do not use
sed -i. BSD sed reads the next argument as a backup suffix, sosed -i <expr> <file>misparses on stock macOS. The no-jq fallback was broken this way for the second task onward and for every status update. Useawkinto a temp file andmv, which behaves identically on both platforms. - Test both paths.
tests/manifest-checkpoint.batsruns each operation with jq and with a PATH that genuinely lacks it, then validates the result with the real jq.
Changing .pre-commit-config.yaml
Every hook in it mirrors a step in .github/workflows/ci.yml. Keep them in step, or the
local gate stops predicting CI — which is the only reason to run it.
- Do not use
pre-commit/mirrors-prettier. It pins its own prettier, which disagrees with the repo's devDependency on Markdown tables containing|inside code spans: the mirror rewrites files that CI's prettier reports as clean. Prettier runs as alocalhook againstnpx prettierfor this reason. - Scope shell hooks with
files: \.sh$. CI lints*.shonly. Unscoped, pre-commit also lints.batsfiles and fails on style CI never checks. - Removing a script means removing the hook that calls it. Four hooks kept invoking
per-plugin
check-template-drift.shscripts that ADR-018 had deleted; each failed with exit 127, and CI never noticed because CI had already dropped those steps.
Changing Frontmatter Schema
- Any changes to frontmatter field names or status values must be reflected in
plugins/principled-docs/hooks/scripts/parse-frontmatter.shand the guard scripts that consume it.
Marketplace Manifest
- When adding a plugin to
plugins/orexternal_plugins/, remember to add its entry to.claude-plugin/marketplace.json. - CI validates that every
sourcepath in the manifest exists on disk.
Before Committing
- Run
/lintorpre-commit run --all-filesto check formatting and lint - Run
/validate --rootto check root structure (plugin skill, from dogfooding) - If you modified shared code in a
lib/, runjust refsto confirm references resolve - If you modified a drift-checked template (principled-docs scaffolding, or the
cross-plugin
check-gh-cli.sh), propagate copies first and runjust drift - Run
just testfor the bats suite
Dev Skills
These supplement the 48 plugin skills available via dogfooding:
| Skill | Command | What It Does |
lint | /lint | Full lint suite (ShellCheck + shfmt + markdownlint + Prettier) |
test-hooks | /test-hooks | Smoke-test enforcement hooks with known inputs |
propagate-templates | /propagate-templates | Copy canonical templates/scripts to consuming skills |
check-ci | /check-ci | Run the full CI pipeline locally |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

