Data-WiseData-Wise/craft/CLAUDE.md

craft

CLAUDE.md4 starsChanged 12 days agoMITView on GitHub

48 commands · 41 skills · 2 agents · Docs · GitHub /craft:finish — renamed from /craft:done (ADR-006, v4.2.0, breaking) · orchestrate:drive — spec-driven autonomous /goal loop · prompt-refiner skill + --refine flag (9 commands) · /craft:restore — combined git+.STATUS recap Current Version: v4.8.2 | Tests: full suite via python3 -m pytest tests/ · tiers via /craft:test <unit|e2e|dogfood> For project details, see plugin.json description and scripts/validate-counts.sh Override local hook: ask "unprotect dev" / "bypass branch guard" (dev/git skill, Operation 10…

In this repository42 other files it gives its agents.
- AGENTS.mdAGENTS.md
- system-architectSkill
- project-detectorSkill
- audit-routerSkill
- command-skill-token-efficiencySkill
- plugin-auditSkill
- sync-featuresSkill
- backend-designerSkill
- devops-helperSkill
- frontend-designerSkill
- git-workflowSkill
- dist-extrasSkill
- distribution-strategistSkill
- homebrew-formula-expertSkill
- homebrew-multi-formulaSkill
- homebrew-setup-wizardSkill
- homebrew-workflow-expertSkill
- architecture-decision-recordsSkill
- changelog-automationSkill
- claude-md-lifecycleSkill
- guard-auditSkill
- hooksSkill
- insights-applySkill
- mode-controllerSkill
- drive-engineSkill
- plan-orchestratorSkill
- repo-triageSkill
- session-stateSkill
- task-analyzerSkill
- workflow-engineSkill
- orchestrator-resilienceSkill
- project-plannerSkill
- preflight-checkSkill
- releaseSkill
- test-generatorSkill
- test-strategistSkill
- adhd-workflowSkill
- brainstorm-insightsSkill
- brainstormSkill
- grillSkill
- prompt-refinerSkill
- background-task-managerSkill

The file

We split this CLAUDE.md into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
CRITICAL: Always start work from dev branch (git checkout dev)
line 25
Distinctive:
Never: commit directly to main
line 26
Very specific:
Never: write feature code on dev
line 27
Distinctive:
Always: verify branch: git branch --show-current
line 28

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 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

CLAUDE.md - Craft Plugin

Active Work

48 commands · 41 skills · 2 agents · Docs · GitHub

/craft:finish — renamed from /craft:done (ADR-006, v4.2.0, breaking) · orchestrate:drive — spec-driven autonomous /goal loop · prompt-refiner skill + --refine flag (9 commands) · /craft:restore — combined git+.STATUS recap

Current Version: v4.8.2 | Tests: full suite via python3 -m pytest tests/ · tiers via /craft:test <unit|e2e|dogfood>

For project details, see plugin.json description and scripts/validate-counts.sh

Git Workflow

main (protected) ← PR only, never direct commits
  ↑
dev (integration) ← Plan here, branch from here
  ↑
feature/* (worktrees) ← All implementation work

Constraints

CRITICAL: Always start work from dev branch (git checkout dev)
Never commit directly to main
Never write feature code on dev
Always verify branch: git branch --show-current

Branch Protection

Branch	Code Files	.md Files	Git Operations
`main`	BLOCKED	BLOCKED	Commit/push BLOCKED
`dev`	New: noted once (allowed), Existing: allowed	ALLOWED	Commit/push allowed
`feature/*`	ALLOWED	ALLOWED	All allowed

Override local hook: ask "unprotect dev" / "bypass branch guard" (dev/git skill, Operation 10 — session-scoped, auto-expires).

GitHub-side: main is protected (PR only). Since 2026-09-23 dev has a deletion-only ruleset (protect-dev-from-deletion, id 23890849 — no push/PR/review rules, so commits to dev are still policed only by the local hook) and the repo auto-deletes merged head branches. The ruleset is load-bearing: release PRs use dev as head, and auto-delete removes an unprotected head branch on merge, so dropping it would delete dev at the next dev→main release.

Quick Commands

Task	Command
Run unit tests	`python3 tests/test_craft_plugin.py` or `/craft:test unit`
E2E tests	`python3 -m pytest tests/test_plugin_e2e.py -v`
Dogfood tests	`python3 -m pytest tests/test_plugin_dogfood.py -v`
Integration tests	`python3 tests/test_integration_*.py`
Dependency tests	`bash tests/test_dependency_management.sh`
Validate counts	`./scripts/validate-counts.sh`
Pre-release check	`./scripts/pre-release-check.sh <version>`
Post-release sweep	`./scripts/post-release-sweep.sh` or `--fix`
Docs staleness check	`./scripts/docs-staleness-check.sh` or `--fix`
Build docs	`mkdocs build`
Apply GitHub-side protection	ask "apply GitHub branch protection [--repo OWNER/REPO]" (`dev/git` skill, Operation 9)
Smart routing	`/craft:do <task>`
Pre-flight check	`/craft:check`
Lint code	`/craft:code:lint`
Release pipeline	`/release` or `/release -n`
Brainstorm	`/craft:brainstorm`
Orchestrate	`/craft:orch`
Plugin evals (costs money)	`./scripts/run-evals.sh --dry-run`, `--single-arm --case 'trigger-*'` — see `docs/guide/eval-harness.md`

Execution Modes

Canonical definitions live in skills/modes/SKILL.md (the mode-controller skill) — see it for the full time-budget/use-case/behavior table. Quick reference: default (<10s, quick tasks) · debug (<120s, verbose) · optimize (<180s, performance) · release (<300s, thorough). Example: /craft:code:lint debug.

Troubleshooting

Issue	Fix
Unit tests failing	`python3 tests/test_craft_plugin.py`
Integration tests failing	`python3 tests/test_integration_<name>.py`
Broken links	`python3 tests/test_craft_plugin.py -k "broken_links"`
Outdated counts	`./scripts/validate-counts.sh`
Stale docs	`./scripts/docs-staleness-check.sh` or `--fix`
Stale worktree	`git worktree remove <path> --force`
Plugin not loading	Check `.claude-plugin/plugin.json` — no unrecognized keys (strict schema)
Command not found	Verify file in `commands/` with valid frontmatter

Project Structure

Directory	Purpose
`commands/`	48 commands (auto-discovered, one `.md` per command)
`skills/`	41 skills (`SKILL.md` pattern)
`agents/`	2 agent definitions
`tests/`	Unit, e2e, dogfood, and integration test suites
`scripts/`	Release, validation, and maintenance scripts
`utils/`	Python utilities (`claude_md_sync`, `validate-counts`, etc.)
`.claude-plugin/`	Plugin manifest + hot-reload validators

Testing

Tier	Command	Scope
Unit	`python3 -m pytest tests/test_craft_plugin.py`	Core plugin logic
E2E	`python3 -m pytest tests/test_plugin_e2e.py`	End-to-end command flows
Dogfood	`python3 -m pytest tests/test_plugin_dogfood.py`	Self-usage patterns
Full	`python3 -m pytest tests/`	All tiers
Tiered	`/craft:test <unit\|e2e\|dogfood>`	Via craft command

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.

Check your setup, free