agentleFS
alexnodelandalexnodeland/principled/.claude/CLAUDE.md

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

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
  1. Very specific:

    All eight first-party plugins are installed via .claude/settings.json.

    line 7
  2. Very specific:

    Run bash plugins/principled-docs/skills/scaffold/scripts/check-template-drift.sh to verify zero drift.

    line 27
  3. Very specific:

    Every plugin now uses the lib/ pattern (ADR-018) — one copy, no propagation:

    line 32
  4. Very specific:

    Run bash scripts/check-skill-references.sh to verify every reference still resolves.

    line 42
  5. Very specific:

    Unknown budgets must fail closed: When gh is unavailable the counts are unknown, and dispatch refuses.

    line 105
  6. Very specific:

    Test both paths. tests/manifest-checkpoint.bats runs each operation with jq and with a PATH that genuinely lacks it, then validates the …

    line 124
  7. Very specific:

    Every hook in it mirrors a step in .github/workflows/ci.yml.

    line 129
  8. Very specific:

    When adding a plugin to plugins/ or external_plugins/, remember to add its entry to .claude-plugin/marketplace.json.

    line 148
  9. Very specific:

    Run /lint or pre-commit run --all-files to check formatting and lint

    line 153
  10. Very specific:

    Run /validate --root to check root structure (plugin skill, from dogfooding)

    line 154
  11. Very specific:

    If you modified shared code in a lib/, run just refs to confirm references resolve

    line 155
  12. Very specific:

    If you modified a drift-checked template (principled-docs scaffolding, or the cross-plugin check-gh-cli.sh), propagate copies first and run …

    line 156
  13. Very specific:

    Run just test for the bats suite

    line 158

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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.sh is a shared dependency. Changes to it affect both check-adr-immutability.sh and check-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-templates or copy manually.
  • Run bash plugins/principled-docs/skills/scaffold/scripts/check-template-drift.sh to 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}.sh
  • plugins/principled-implementation/lib/templates/claude-task.md
  • plugins/principled-tasks/lib/task-db.sh
  • plugins/principled-agent/lib/agent-memory.sh
  • plugins/principled-agent/lib/agent-governance.sh

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 exist = CI failure. This is what caught spawn/SKILL.md invoking a parse-plan.sh that was never copied into spawn.

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/ and plugins/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 review and gh pr merge commands.

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 tag commands (excludes git tag -l and git 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, then agent — 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_path and 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.sh uses 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 gh is 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.bats asserts that --status never prints 0/5 for 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 to check-skill-references.sh and must be maintained by convention. If the path changes, /orchestrate must 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)

  • checkpoint and acceptance_criteria are 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, so sed -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. Use awk into a temp file and mv, which behaves identically on both platforms.
  • Test both paths. tests/manifest-checkpoint.bats runs 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 a local hook against npx prettier for this reason.
  • Scope shell hooks with files: \.sh$. CI lints *.sh only. Unscoped, pre-commit also lints .bats files 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.sh scripts 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.sh and the guard scripts that consume it.

Marketplace Manifest

  • When adding a plugin to plugins/ or external_plugins/, remember to add its entry to .claude-plugin/marketplace.json.
  • CI validates that every source path in the manifest exists on disk.

Before Committing

  1. Run /lint or pre-commit run --all-files to check formatting and lint
  2. Run /validate --root to check root structure (plugin skill, from dogfooding)
  3. If you modified shared code in a lib/, run just refs to confirm references resolve
  4. If you modified a drift-checked template (principled-docs scaffolding, or the cross-plugin check-gh-cli.sh), propagate copies first and run just drift
  5. Run just test for the bats suite

Dev Skills

These supplement the 48 plugin skills available via dogfooding:

SkillCommandWhat It Does
lint/lintFull lint suite (ShellCheck + shfmt + markdownlint + Prettier)
test-hooks/test-hooksSmoke-test enforcement hooks with known inputs
propagate-templates/propagate-templatesCopy canonical templates/scripts to consuming skills
check-ci/check-ciRun the full CI pipeline locally

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.