You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
chore: update CLAUDE.md hierarchy with current org strategy context (#14)
- Update root CLAUDE.md with Organizational Context section, architecture details, external-contribution-safety coverage, and Development Standards
- Update claude-code/CLAUDE.md: add Usage section, External Contribution Safety section, rename title for clarity
- Add CLAUDE.md to 6 tool directories missing them: cursor, augment-code, cline, github-copilot, windsurf, kilo-code, roo-code
- All new subdirectory CLAUDE.md files list every non-config file with descriptions and cross-references
Generated by /generate-context skill from open-paws-strategy
Ready-to-use AI coding instruction files for 12 tools, tailored for animal advocacy software. Copy a tool directory into any project root and the AI assistant immediately understands advocacy-domain constraints, security threat models, testing standards, and process workflows. Part of the Open Paws developer pipeline.
4
4
5
+
## Organizational Context
6
+
7
+
**Role in flywheel:** This repo is the canonical source for AI coding methodology across all Open Paws projects. It feeds two downstream consumers: `graze-cli` bundles selected guides into its binary, and `desloppify` generates agent skill files from the same content. It is also curriculum content for the bootcamp — developers learn these 7 concerns and 6 process skills through the training pipeline.
8
+
9
+
**Layer:** 1 — Strengthen. Lever: Strengthen.
10
+
11
+
**External contribution safety (2026-04-01):** All 12 tool directories now include `external-contribution-safety.md` (or equivalent for the tool's format). This file teaches the two-state identity model: advocacy mode for Open Paws repos, neutral mode (org identity suppressed, commit hygiene enforced) for external repos. The `agents-md/AGENTS.md` is the vendor-neutral version of the same. This was implemented in PR #13.
12
+
13
+
**Unicode integrity (CI):** A CI action checks all instruction files for hidden Unicode characters (Rules File Backdoor attack). The `scripts/check-unicode-integrity.py` script is the underlying tool.
14
+
15
+
**Strategy references:**
16
+
-`open-paws-strategy/ecosystem/repos.md` — structured-coding-with-ai entry with full breakdown
Each tool also includes: external-contribution-safety (two-state identity model for external repos).
73
+
54
74
## Development
55
75
56
-
-**No dependencies** -- pure markdown/JSON instruction files
57
-
-**Adding a new tool:** Create `tool-name/` directory, implement the 7 concerns + 6 skills in the tool's native format
58
-
-**Editing content:** Each tool was independently authored for its format -- changes to one do not auto-propagate to others
76
+
-**No dependencies** — pure markdown/JSON instruction files
77
+
-**Adding a new tool:** Create `tool-name/` directory, implement the 7 concerns + 6 skills in the tool's native format, add external-contribution-safety content
78
+
-**Editing content:** Each tool was independently authored for its format — changes to one do not auto-propagate to others
79
+
-**Integrity check:** Run `python scripts/check-unicode-integrity.py` before committing any instruction file edits
80
+
-**CI:** Unicode integrity check runs on all PRs via GitHub Action
81
+
82
+
## Development Standards
83
+
84
+
### 10-Point Review Checklist (ranked by AI violation frequency)
85
+
86
+
Apply to every PR:
87
+
88
+
1.**DRY** — AI clones code at 4x the human rate. Search before writing anything new
89
+
2.**Deep modules** — Reject shallow wrappers and pass-through methods. Interface must be simpler than implementation (Ousterhout)
90
+
3.**Single responsibility** — Each function does one thing at one level of abstraction
91
+
4.**Error handling** — Never catch-all. AI suppresses errors and removes safety checks. Every catch block must handle specifically
**Speciesist language** — Run `semgrep --config semgrep-no-animal-violence.yaml` on all `.md` edits.
110
+
111
+
**Instruction file integrity** — Run `python scripts/check-unicode-integrity.py` before pushing. CI also runs this automatically.
112
+
113
+
**Two-failure rule** — After two failed fixes on the same problem, stop and restart with a better approach.
114
+
115
+
### Plan-First Development
116
+
117
+
Read existing files → identify what changes → write specification → break into subtasks → implement and verify each → commit per subtask
118
+
119
+
### Structured Coding Reference
120
+
121
+
For tool-specific AI coding instructions, copy the corresponding directory from this repo into your project root. This repo IS the reference.
122
+
123
+
### Seven Concerns — repo-specific implications
124
+
125
+
All 7 always apply. Critical for this repo:
126
+
127
+
1.**Testing** — Content changes must not break the downstream consumers (graze-cli bundling, desloppify skill generation). Verify content renders correctly in the target tool's format
128
+
2.**Security** — Instruction file integrity is a first-class concern. Hidden Unicode in instruction files is the Rules File Backdoor attack. Every PR runs the Unicode check
129
+
3.**Privacy** — No activist data or operational details in example code or sample prompts
130
+
4.**Cost** — Instruction files are loaded into every AI session that uses them. Keep them lean — every token counts at scale across the bootcamp
131
+
5.**Advocacy domain** — This repo IS the canonical source for advocacy domain language. Never introduce synonyms for established terms
132
+
6.**Accessibility** — Instruction files must work in editors with no syntax highlighting, screen readers, and plain-text terminals
133
+
7.**Emotional safety** — Sample prompts and example scenarios must not include graphic investigation content
134
+
135
+
### Advocacy Domain Language
136
+
137
+
Use these terms consistently. Never introduce synonyms:
138
+
-**Campaign** — organized advocacy effort (not "project" or "initiative")
139
+
-**Investigation** — covert documentation (not "research" or "audit")
140
+
-**Coalition** — multi-org alliance
141
+
-**Sanctuary** — permanent animal care facility (not "shelter" or "foster")
Copy file name to clipboardExpand all lines: claude-code/CLAUDE.md
+25-1Lines changed: 25 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,19 @@
1
-
# Animal Advocacy Platform
1
+
# Claude Code — Animal Advocacy Instructions
2
2
3
3
Software for animal liberation and advocacy. This is a high-risk domain: investigation data is subpoena-target evidence, activists face legal prosecution, and system compromise endangers lives. See `.claude/rules/advocacy-domain.md` for ubiquitous language — NEVER introduce synonyms for established domain terms.
4
4
5
+
## Usage
6
+
7
+
Copy this directory into any Open Paws project root:
8
+
9
+
```bash
10
+
cp CLAUDE.md your-project/
11
+
cp hooks-template.md your-project/
12
+
cp -r .claude your-project/
13
+
```
14
+
15
+
The `.claude/rules/` files are scoped by filename and activate contextually. The `.claude/skills/` files are invoked by slash commands or agent prompts. See `hooks-template.md` for pre-commit/post-edit/pre-push hook setup.
16
+
5
17
## Workflow
6
18
7
19
Read existing code before writing anything. Plan before code: read, plan, code, verify. Never create files or functions that duplicate existing ones — search first. Write a specification before implementation. Write a failing test before writing code. After two failed fix attempts, stop and re-approach with a better prompt rather than compounding errors.
See `.claude/rules/desloppify.md` for desloppify setup and usage.
47
59
60
+
## External Contribution Safety
61
+
62
+
When working in a repository that is NOT part of the Open Paws organization, switch to neutral mode:
63
+
- Match the target repo's commit style — read the last 5 commits first
64
+
- Do not mention Open Paws, advocacy context, or movement terminology in commits, PRs, or comments
65
+
- Do not include Co-Authored-By trailers or "Generated with" attribution
66
+
- Write PR descriptions proportional to diff size, human-style
67
+
68
+
Repo classification: `git remote get-url origin` — if the owner is `Open-Paws`, use advocacy mode. Otherwise, neutral mode. Absent positive confirmation, default to neutral (safe).
69
+
70
+
See `.claude/rules/external-contribution-safety.md` for the full two-state identity model.
71
+
48
72
## MCP Servers
49
73
50
74
Any MCP server handling sensitive advocacy data MUST be self-hosted. MCP extends agent capabilities but also extends the attack surface — audit each server's data access, network calls, and retention policy before enabling.
Cursor MDC instruction files for animal advocacy development. Copy this directory into any Open Paws project root.
4
+
5
+
## Usage
6
+
7
+
```bash
8
+
cp .cursorrules your-project/
9
+
cp -r .cursor your-project/
10
+
```
11
+
12
+
The `.cursorrules` file is the always-active baseline. `.cursor/rules/` files use MDC frontmatter activation modes (always, auto, agent-requested, manual).
0 commit comments