Skip to content

CLAUDE.md

Latest commit

 

History

History
148 lines (105 loc) · 8.56 KB

CLAUDE.md

File metadata and controls

148 lines (105 loc) · 8.56 KB

Structured Coding with AI

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.

Organizational Context

Role in flywheel: This repo is the canonical source for AI coding methodology across all Open Paws projects. Its primary downstream consumer is desloppify, which generates agent skill files from this content. It is also curriculum content for the bootcamp — developers learn these 7 concerns and 6 process skills through the training pipeline.

Layer: 1 — Strengthen. Lever: Strengthen.

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.

Clean-room agent architecture rollout (2026-04-09): The clean-room reuse pattern (closed decision 2026-04-01) is being rolled out across the ecosystem using instruction files from this repo. Status: PCC#13 merged, platform#42 merged, docs#7 merged. Tools-Platform#1 repo verification is still pending — do not mark the rollout complete until that PR is verified.

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.

Strategy references:

  • context/ecosystem/repos.md — structured-coding-with-ai entry with full breakdown
  • context/decisions.md — 2026-04-01 external contribution safety decision
  • context/programs/developer-training-pipeline/guild/operations.md — bootcamp curriculum context

Quick Start

No build step. Pick a tool directory, copy its files into your project:

# Example: Claude Code
cp claude-code/CLAUDE.md your-project/
cp claude-code/hooks-template.md your-project/
cp -r claude-code/.claude your-project/

See README.md for copy commands for all 12 tools.

Architecture

claude-code/       CLAUDE.md + hooks-template.md + .claude/ (rules/ + skills/)
cursor/            .cursorrules + .cursor/rules/ (.mdc files)
github-copilot/    .github/ (copilot-instructions.md + instructions/ + prompts/ + skills/ + chat-modes/)
windsurf/          .windsurf/rules/ (trigger-type rules, 6K/12K char limits)
kilo-code/         .kilocode/ (rules/ mode files + Memory Bank + skills/)
cline/             .clinerules/ (Plan/Act paradigm — all rules as flat files)
roo-code/          .roomodes + .roo/rules/ (JSON modes + mode rules)
augment-code/      .augment/rules/ (concern rules + process skills)
aider/             CONVENTIONS.md (all-in-one)
gemini-cli/        GEMINI.md (all-in-one)
jetbrains-junie/   README.md (references .junie/guidelines.md pattern)
agents-md/         AGENTS.md (vendor-neutral, 20+ tools)
scripts/           check-unicode-integrity.py (instruction file integrity checker)

137 files total across 12 tool directories.

Key Files

File Purpose
README.md Full tool comparison, copy commands, content coverage
claude-code/CLAUDE.md Claude Code root instruction file
claude-code/hooks-template.md Pre-commit/post-edit/pre-push hook setup guide
claude-code/.claude/rules/external-contribution-safety.md Two-state identity model for external repos
agents-md/AGENTS.md Universal vendor-neutral fallback for any unsupported tool
scripts/check-unicode-integrity.py Detects hidden Unicode in instruction files (Rules File Backdoor defense)

Content Coverage

All 12 tools cover the same 7 concerns and 6 process skills:

Concerns: Testing, Security, Privacy, Cost optimization, Advocacy domain, Accessibility, Emotional safety

Skills: git-workflow, testing-strategy, requirements-interview, plan-first-development, code-review, security-audit

Each tool also includes: external-contribution-safety (two-state identity model for external repos).

Development

  • No dependencies — pure markdown/JSON instruction files
  • 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
  • Editing content: Each tool was independently authored for its format — changes to one do not auto-propagate to others
  • Integrity check: Run python scripts/check-unicode-integrity.py before committing any instruction file edits
  • CI: Unicode integrity check runs on all PRs via GitHub Action

Development Standards

10-Point Review Checklist (ranked by AI violation frequency)

Apply to every PR:

  1. DRY — AI clones code at 4x the human rate. Search before writing anything new
  2. Deep modules — Reject shallow wrappers and pass-through methods. Interface must be simpler than implementation (Ousterhout)
  3. Single responsibility — Each function does one thing at one level of abstraction
  4. Error handling — Never catch-all. AI suppresses errors and removes safety checks. Every catch block must handle specifically
  5. Information hiding — Don't expose internal state. Mask API keys (last 4 chars only)
  6. Ubiquitous language — Use movement terminology consistently. Never let AI invent synonyms for domain terms
  7. Design for change — Abstraction layers and loose coupling. Tools must outlast individual campaigns
  8. Legacy velocity — AI code churns 2x faster. Use characterization tests before modifying existing code
  9. Over-patterning — Simplest structure that works. Three similar lines of code is better than a premature abstraction
  10. Test quality — Every test must fail when the covered behavior breaks. Mutation score over coverage percentage

Quality Gates

Desloppify — Target score: ≥ 85 (all other repos).

pip install "git+https://github.com/Open-Paws/desloppify.git#egg=desloppify[full]"
desloppify scan --path .
desloppify next

Speciesist language — Run semgrep --config semgrep-no-animal-violence.yaml on all .md edits.

Instruction file integrity — Run python scripts/check-unicode-integrity.py before pushing. CI also runs this automatically.

Two-failure rule — After two failed fixes on the same problem, stop and restart with a better approach.

Plan-First Development

Read existing files → identify what changes → write specification → break into subtasks → implement and verify each → commit per subtask

Structured Coding Reference

For tool-specific AI coding instructions, copy the corresponding directory from this repo into your project root. This repo IS the reference.

Seven Concerns — repo-specific implications

All 7 always apply. Critical for this repo:

  1. Testing — Content changes must not break the downstream consumers (desloppify skill generation). Verify content renders correctly in the target tool's format
  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
  3. Privacy — No activist data or operational details in example code or sample prompts
  4. Cost — Instruction files are loaded into every AI session that uses them. Keep them lean — every token counts at scale across the bootcamp
  5. Advocacy domain — This repo IS the canonical source for advocacy domain language. Never introduce synonyms for established terms
  6. Accessibility — Instruction files must work in editors with no syntax highlighting, screen readers, and plain-text terminals
  7. Emotional safety — Sample prompts and example scenarios must not include graphic investigation content

Advocacy Domain Language

Use these terms consistently. Never introduce synonyms:

  • Campaign — organized advocacy effort (not "project" or "initiative")
  • Investigation — covert documentation (not "research" or "audit")
  • Coalition — multi-org alliance
  • Sanctuary — permanent animal care facility (not "shelter" or "foster")
  • Farmed animal — not the industry commodity term
  • Factory farm — not "farm" or "facility"
  • Ag-gag — laws criminalizing undercover agricultural investigation
  • Companion animal — not "pet"
  • Direct action — physical intervention with specific legal status