diff --git a/CLAUDE.md b/CLAUDE.md index a1d9c60..4144145 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,21 @@ 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. 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. + +**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. + +**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:** +- `open-paws-strategy/ecosystem/repos.md` — structured-coding-with-ai entry with full breakdown +- `open-paws-strategy/closed-decisions.md` — 2026-04-01 external contribution safety decision +- `open-paws-strategy/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: @@ -18,18 +33,19 @@ See README.md for copy commands for all 12 tools. ## Architecture ``` -claude-code/ 15 files — CLAUDE.md + scoped rules + skills + hooks template -cursor/ 14 files — .cursorrules + .mdc files (4 activation modes) -github-copilot/ 22 files — copilot-instructions + prompts + chat modes + skills -windsurf/ 14 files — .windsurf/rules/ (4 trigger types, 6K/12K char limits) -kilo-code/ 21 files — mode files + Memory Bank + concerns + skills -cline/ 14 files — .clinerules/ (Plan/Act paradigm) -roo-code/ 19 files — .roomodes JSON + mode rules + concerns + skills -augment-code/ 14 files — .augment/rules/ -aider/ 1 file — CONVENTIONS.md (all-in-one) -gemini-cli/ 1 file — GEMINI.md (all-in-one) -jetbrains-junie/ 1 file — .junie/guidelines.md (all-in-one) -agents-md/ 1 file — AGENTS.md (vendor-neutral, 20+ tools) +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. @@ -41,7 +57,9 @@ agents-md/ 1 file — AGENTS.md (vendor-neutral, 20+ tools) | `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 | -| `agents-md/AGENTS.md` | Universal fallback for any unsupported tool | +| `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 @@ -51,8 +69,78 @@ All 12 tools cover the same 7 concerns and 6 process skills: **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 -- **Editing content:** Each tool was independently authored for its format -- changes to one do not auto-propagate to others +- **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). + +```bash +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 (graze-cli bundling, 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 "livestock" +- **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 diff --git a/augment-code/CLAUDE.md b/augment-code/CLAUDE.md new file mode 100644 index 0000000..f5ff146 --- /dev/null +++ b/augment-code/CLAUDE.md @@ -0,0 +1,38 @@ +# Augment Code — Animal Advocacy Instructions + +Augment Code instruction files for animal advocacy development. Copy this directory into any Open Paws project root. + +## Usage + +```bash +cp -r .augment your-project/ +``` + +The `.augment/rules/` files are loaded by Augment Code based on filename context. + +## .augment/rules/ Contents + +| File | What it covers | When to read | +|------|---------------|--------------| +| `main.md` | Always-active baseline: advocacy domain, security constraints, 10-point checklist | Augment loads this automatically | +| `accessibility.md` | Internationalization, low-bandwidth, offline-first, low-literacy design | Accessibility work | +| `advocacy-domain.md` | Ubiquitous language dictionary, bounded contexts, anti-corruption layers | Any advocacy feature work | +| `code-review.md` | Five-layer review pipeline (automated → AI → Ousterhout → AI failures → advocacy) | PR review | +| `cost-optimization.md` | Model routing, token budget discipline, vendor lock-in as movement risk | LLM integration work | +| `emotional-safety.md` | Progressive disclosure, content warnings, burnout prevention | Content-displaying features | +| `external-contribution-safety.md` | Two-state identity: advocacy mode vs neutral mode for external repos | Any external repo work | +| `geo-seo.md` | SEO and GEO optimization rules | Public-facing pages | +| `git-workflow.md` | Atomic commits, ephemeral branches, PR curation | Git operations | +| `plan-first.md` | Read → plan → code → verify workflow | Before any implementation | +| `privacy.md` | Activist identity protection, real deletion, zero-knowledge architecture | Any data handling | +| `requirements-interview.md` | Six-phase stakeholder interview | Requirements gathering | +| `security-audit.md` | 10-step advocacy security audit | Security reviews | +| `security.md` | Three-adversary threat model, zero-retention APIs, device seizure preparation | Any security-sensitive work | +| `testing-strategy.md` | Spec-first, mutation testing, five anti-patterns | Test writing | +| `testing.md` | Testing concerns and quality gates | Test setup | + +## Cross-References + +- For Claude Code format, see `../claude-code/` +- For Cursor MDC format, see `../cursor/` +- For universal vendor-neutral instructions, see `../agents-md/AGENTS.md` diff --git a/claude-code/CLAUDE.md b/claude-code/CLAUDE.md index 5866b26..38df9b3 100644 --- a/claude-code/CLAUDE.md +++ b/claude-code/CLAUDE.md @@ -1,7 +1,19 @@ -# Animal Advocacy Platform +# Claude Code — Animal Advocacy Instructions 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. +## Usage + +Copy this directory into any Open Paws project root: + +```bash +cp CLAUDE.md your-project/ +cp hooks-template.md your-project/ +cp -r .claude your-project/ +``` + +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. + ## Workflow 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. @@ -45,6 +57,18 @@ See `hooks-template.md`. Hooks execute shell commands before/after agent actions See `.claude/rules/desloppify.md` for desloppify setup and usage. +## External Contribution Safety + +When working in a repository that is NOT part of the Open Paws organization, switch to neutral mode: +- Match the target repo's commit style — read the last 5 commits first +- Do not mention Open Paws, advocacy context, or movement terminology in commits, PRs, or comments +- Do not include Co-Authored-By trailers or "Generated with" attribution +- Write PR descriptions proportional to diff size, human-style + +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). + +See `.claude/rules/external-contribution-safety.md` for the full two-state identity model. + ## MCP Servers 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. diff --git a/cline/CLAUDE.md b/cline/CLAUDE.md new file mode 100644 index 0000000..bee7610 --- /dev/null +++ b/cline/CLAUDE.md @@ -0,0 +1,38 @@ +# Cline — Animal Advocacy Instructions + +Cline instruction files for animal advocacy development using the Plan/Act paradigm. Copy this directory into any Open Paws project root. + +## Usage + +```bash +cp -r .clinerules your-project/ +``` + +The `.clinerules/` directory contains flat files. Cline loads all of them and applies them contextually. + +## .clinerules/ Contents + +| File | What it covers | When to read | +|------|---------------|--------------| +| `main.md` | Always-active baseline: advocacy domain, security constraints, 10-point checklist | Cline loads this automatically | +| `accessibility.md` | Internationalization, low-bandwidth, offline-first, low-literacy design | Accessibility work | +| `advocacy-domain.md` | Ubiquitous language dictionary, bounded contexts, anti-corruption layers | Any advocacy feature work | +| `code-review.md` | Five-layer review pipeline (automated → AI → Ousterhout → AI failures → advocacy) | PR review | +| `cost-optimization.md` | Model routing, token budget discipline, vendor lock-in as movement risk | LLM integration work | +| `emotional-safety.md` | Progressive disclosure, content warnings, burnout prevention | Content-displaying features | +| `external-contribution-safety.md` | Two-state identity: advocacy mode vs neutral mode for external repos | Any external repo work | +| `geo-seo.md` | SEO and GEO optimization rules | Public-facing pages | +| `git-workflow.md` | Atomic commits, ephemeral branches, PR curation | Git operations | +| `plan-first.md` | Read → plan → code → verify workflow | Before any implementation | +| `privacy.md` | Activist identity protection, real deletion, zero-knowledge architecture | Any data handling | +| `requirements-interview.md` | Six-phase stakeholder interview | Requirements gathering | +| `security-audit.md` | 10-step advocacy security audit | Security reviews | +| `security.md` | Three-adversary threat model, zero-retention APIs, device seizure preparation | Any security-sensitive work | +| `testing-strategy.md` | Spec-first, mutation testing, five anti-patterns | Test writing | +| `testing.md` | Testing concerns and quality gates | Test setup | + +## Cross-References + +- For Claude Code format, see `../claude-code/` +- For Cursor MDC format, see `../cursor/` +- For universal vendor-neutral instructions, see `../agents-md/AGENTS.md` diff --git a/cursor/CLAUDE.md b/cursor/CLAUDE.md new file mode 100644 index 0000000..b5179aa --- /dev/null +++ b/cursor/CLAUDE.md @@ -0,0 +1,45 @@ +# Cursor — Animal Advocacy Instructions + +Cursor MDC instruction files for animal advocacy development. Copy this directory into any Open Paws project root. + +## Usage + +```bash +cp .cursorrules your-project/ +cp -r .cursor your-project/ +``` + +The `.cursorrules` file is the always-active baseline. `.cursor/rules/` files use MDC frontmatter activation modes (always, auto, agent-requested, manual). + +## Files + +| File | What it covers | When to read | +|------|---------------|--------------| +| `.cursorrules` | Always-active baseline rules: advocacy domain, security, 10-point checklist | Cursor loads this automatically | +| `.cursor/rules/README.md` | MDC activation mode guide | When adding new rules | + +## .cursor/rules/ Contents + +| File | What it covers | When to read | +|------|---------------|--------------| +| `accessibility.mdc` | Internationalization, low-bandwidth, offline-first, low-literacy design | Accessibility work | +| `advocacy-domain.mdc` | Ubiquitous language dictionary, bounded contexts, anti-corruption layers | Any advocacy feature work | +| `code-review.mdc` | Five-layer review pipeline (automated → AI → Ousterhout → AI failures → advocacy) | PR review | +| `cost-optimization.mdc` | Model routing, token budget discipline, vendor lock-in as movement risk | LLM integration work | +| `emotional-safety.mdc` | Progressive disclosure, content warnings, burnout prevention | Content-displaying features | +| `external-contribution-safety.mdc` | Two-state identity: advocacy mode vs neutral mode for external repos | Any external repo work | +| `geo-seo.mdc` | SEO and GEO optimization rules | Public-facing pages | +| `git-workflow.mdc` | Atomic commits, ephemeral branches, PR curation | Git operations | +| `plan-first.mdc` | Read → plan → code → verify workflow | Before any implementation | +| `privacy.mdc` | Activist identity protection, real deletion, zero-knowledge architecture | Any data handling | +| `requirements-interview.mdc` | Six-phase stakeholder interview | Requirements gathering | +| `security-audit.mdc` | 10-step advocacy security audit | Security reviews | +| `security.mdc` | Three-adversary threat model, zero-retention APIs, device seizure preparation | Any security-sensitive work | +| `testing-strategy.mdc` | Spec-first, mutation testing, five anti-patterns | Test writing | +| `testing.mdc` | Testing concerns and quality gates | Test setup | + +## Cross-References + +- For Claude Code format, see `../claude-code/` +- For the canonical advocacy rules source, see `../claude-code/.claude/rules/` +- For universal vendor-neutral instructions, see `../agents-md/AGENTS.md` diff --git a/github-copilot/CLAUDE.md b/github-copilot/CLAUDE.md new file mode 100644 index 0000000..a779d7d --- /dev/null +++ b/github-copilot/CLAUDE.md @@ -0,0 +1,64 @@ +# GitHub Copilot — Animal Advocacy Instructions + +GitHub Copilot instruction files for animal advocacy development. Copy this directory into any Open Paws project root. + +## Usage + +```bash +cp -r .github your-project/ +``` + +The `.github/` directory contains Copilot's instruction format: persistent instructions, context instructions, prompt files, skills, and chat modes. + +## .github/ Contents + +| File | What it covers | When to read | +|------|---------------|--------------| +| `copilot-instructions.md` | Always-active baseline instructions for Copilot | Copilot loads this automatically | + +## .github/instructions/ Contents + +Context-specific instruction files loaded when Copilot detects relevant file patterns: + +| File | What it covers | When to read | +|------|---------------|--------------| +| `accessibility.md` | Internationalization, low-bandwidth, offline-first, low-literacy design | Accessibility work | +| `advocacy-domain.md` | Ubiquitous language dictionary, bounded contexts, anti-corruption layers | Any advocacy feature work | +| `cost-optimization.md` | Model routing, token budget discipline, vendor lock-in as movement risk | LLM integration work | +| `emotional-safety.md` | Progressive disclosure, content warnings, burnout prevention | Content-displaying features | +| `external-contribution-safety.md` | Two-state identity: advocacy mode vs neutral mode for external repos | Any external repo work | +| `geo-seo.md` | SEO and GEO optimization rules | Public-facing pages | +| `privacy.md` | Activist identity protection, real deletion, zero-knowledge architecture | Any data handling | +| `security.md` | Three-adversary threat model, zero-retention APIs, device seizure preparation | Any security-sensitive work | +| `testing.md` | Testing concerns and quality gates | Test setup | + +## .github/prompts/ Contents + +Reusable prompt files invoked from Copilot chat: + +| File | What it covers | When to read | +|------|---------------|--------------| +| `code-review.prompt.md` | Five-layer code review pipeline | PR review | +| `geo-seo-audit.prompt.md` | SEO and GEO audit workflow | Public pages audit | +| `git-workflow.prompt.md` | Atomic commits, ephemeral branches, PR curation | Git operations | +| `plan-first.prompt.md` | Read → plan → code → verify workflow | Before implementation | +| `requirements-interview.prompt.md` | Six-phase stakeholder interview | Requirements gathering | +| `security-audit.prompt.md` | 10-step advocacy security audit | Security reviews | +| `testing-strategy.prompt.md` | Spec-first, mutation testing, five anti-patterns | Test writing | + +## .github/chat-modes/ Contents + +| File | What it covers | When to read | +|------|---------------|--------------| +| `advocacy-reviewer.yml` | Chat mode for code review with advocacy focus | PR review mode | +| `requirements-interviewer.yml` | Chat mode for structured requirements gathering | Requirements sessions | + +## .github/skills/ Contents + +Each subdirectory is a Copilot skill (code-review, geo-seo-audit, git-workflow, plan-first-development, requirements-interview, security-audit, testing-strategy). + +## Cross-References + +- For Claude Code format, see `../claude-code/` +- For Cursor MDC format, see `../cursor/` +- For universal vendor-neutral instructions, see `../agents-md/AGENTS.md` diff --git a/kilo-code/CLAUDE.md b/kilo-code/CLAUDE.md new file mode 100644 index 0000000..e760877 --- /dev/null +++ b/kilo-code/CLAUDE.md @@ -0,0 +1,48 @@ +# Kilo Code — Animal Advocacy Instructions + +Kilo Code instruction files for animal advocacy development. Uses mode-based architecture with Memory Bank for persistent context. Copy this directory into any Open Paws project root. + +## Usage + +```bash +cp -r .kilocode your-project/ +``` + +Kilo Code loads rules from `.kilocode/rules/` based on active mode. Skills are loaded on demand from `.kilocode/skills/`. + +## .kilocode/rules/ Contents + +| File | What it covers | When to read | +|------|---------------|--------------| +| `architect-mode.md` | System design and architecture review rules | Architect mode | +| `ask-mode.md` | Question-answering and explanation rules | Ask mode | +| `code-mode.md` | Implementation rules: advocacy constraints, 10-point checklist | Code mode (default) | +| `debug-mode.md` | Debugging and error investigation rules | Debug mode | +| `orchestrator-mode.md` | Multi-agent orchestration rules | Orchestrator mode | +| `accessibility.md` | Internationalization, low-bandwidth, offline-first, low-literacy design | Accessibility work | +| `advocacy-domain.md` | Ubiquitous language dictionary, bounded contexts, anti-corruption layers | Any advocacy feature work | +| `cost-optimization.md` | Model routing, token budget discipline, vendor lock-in as movement risk | LLM integration work | +| `emotional-safety.md` | Progressive disclosure, content warnings, burnout prevention | Content-displaying features | +| `external-contribution-safety.md` | Two-state identity: advocacy mode vs neutral mode for external repos | Any external repo work | +| `geo-seo.md` | SEO and GEO optimization rules | Public-facing pages | +| `privacy.md` | Activist identity protection, real deletion, zero-knowledge architecture | Any data handling | +| `security.md` | Three-adversary threat model, zero-retention APIs, device seizure preparation | Any security-sensitive work | +| `testing.md` | Testing concerns and quality gates | Test setup | + +## .kilocode/rules/memory-bank/ Contents + +| File | What it covers | When to read | +|------|---------------|--------------| +| `brief.md` | Project brief template for Memory Bank | Initialize new project context | +| `context.md` | Running context template | Ongoing session context | +| `history.md` | Decision history template | Track architectural decisions | + +## .kilocode/skills/ Contents + +Skill subdirectories: code-review, geo-seo-audit, git-workflow, plan-first-development, requirements-interview, security-audit, testing-strategy. + +## Cross-References + +- For Claude Code format, see `../claude-code/` +- For Cursor MDC format, see `../cursor/` +- For universal vendor-neutral instructions, see `../agents-md/AGENTS.md` diff --git a/roo-code/CLAUDE.md b/roo-code/CLAUDE.md new file mode 100644 index 0000000..6ec014e --- /dev/null +++ b/roo-code/CLAUDE.md @@ -0,0 +1,51 @@ +# Roo Code — Animal Advocacy Instructions + +Roo Code instruction files for animal advocacy development. Uses JSON-based mode definitions with per-mode rule files. Copy this directory into any Open Paws project root. + +## Usage + +```bash +cp .roomodes your-project/ +cp -r .roo your-project/ +``` + +`.roomodes` defines the available modes (code, architect, ask, debug, review, interview). `.roo/rules/` contains rule files loaded per mode. + +## Files + +| File | What it covers | When to read | +|------|---------------|--------------| +| `.roomodes` | Mode definitions (JSON): code, architect, ask, debug, review, interview | Configure available modes | + +## .roo/rules/ Contents + +Mode-specific rule files: + +| File | What it covers | When to read | +|------|---------------|--------------| +| `rules-architect.md` | Architecture mode: system design, bounded contexts, advocacy constraints | Architect mode | +| `rules-code.md` | Code mode: implementation rules, 10-point checklist, advocacy domain | Code mode (default) | +| `rules-debug.md` | Debug mode: error investigation without compromising security | Debug mode | +| `rules-interview.md` | Interview mode: structured requirements gathering | Interview mode | +| `rules-review.md` | Review mode: five-layer code review pipeline | Review mode | +| `accessibility.md` | Internationalization, low-bandwidth, offline-first, low-literacy design | Accessibility work | +| `advocacy-domain.md` | Ubiquitous language dictionary, bounded contexts, anti-corruption layers | Any advocacy feature work | +| `code-review.md` | Five-layer review pipeline (automated → AI → Ousterhout → AI failures → advocacy) | PR review | +| `cost-optimization.md` | Model routing, token budget discipline, vendor lock-in as movement risk | LLM integration work | +| `emotional-safety.md` | Progressive disclosure, content warnings, burnout prevention | Content-displaying features | +| `external-contribution-safety.md` | Two-state identity: advocacy mode vs neutral mode for external repos | Any external repo work | +| `geo-seo.md` | SEO and GEO optimization rules | Public-facing pages | +| `git-workflow.md` | Atomic commits, ephemeral branches, PR curation | Git operations | +| `plan-first.md` | Read → plan → code → verify workflow | Before any implementation | +| `privacy.md` | Activist identity protection, real deletion, zero-knowledge architecture | Any data handling | +| `requirements-interview.md` | Six-phase stakeholder interview | Requirements gathering | +| `security-audit.md` | 10-step advocacy security audit | Security reviews | +| `security.md` | Three-adversary threat model, zero-retention APIs, device seizure preparation | Any security-sensitive work | +| `testing-strategy.md` | Spec-first, mutation testing, five anti-patterns | Test writing | +| `testing.md` | Testing concerns and quality gates | Test setup | + +## Cross-References + +- For Claude Code format, see `../claude-code/` +- For Cursor MDC format, see `../cursor/` +- For universal vendor-neutral instructions, see `../agents-md/AGENTS.md` diff --git a/windsurf/CLAUDE.md b/windsurf/CLAUDE.md new file mode 100644 index 0000000..d77a261 --- /dev/null +++ b/windsurf/CLAUDE.md @@ -0,0 +1,38 @@ +# Windsurf — Animal Advocacy Instructions + +Windsurf instruction files for animal advocacy development. Copy this directory into any Open Paws project root. + +## Usage + +```bash +cp -r .windsurf your-project/ +``` + +Windsurf loads rules from `.windsurf/rules/` based on trigger type. Rule files respect 6K character (always-active) and 12K character (agent-requested) limits. + +## .windsurf/rules/ Contents + +| File | What it covers | When to read | +|------|---------------|--------------| +| `main.md` | Always-active baseline: advocacy domain, security constraints, 10-point checklist | Windsurf loads this always | +| `accessibility.md` | Internationalization, low-bandwidth, offline-first, low-literacy design | Accessibility work | +| `advocacy-domain.md` | Ubiquitous language dictionary, bounded contexts, anti-corruption layers | Any advocacy feature work | +| `code-review.md` | Five-layer review pipeline (automated → AI → Ousterhout → AI failures → advocacy) | PR review | +| `cost-optimization.md` | Model routing, token budget discipline, vendor lock-in as movement risk | LLM integration work | +| `emotional-safety.md` | Progressive disclosure, content warnings, burnout prevention | Content-displaying features | +| `external-contribution-safety.md` | Two-state identity: advocacy mode vs neutral mode for external repos | Any external repo work | +| `geo-seo.md` | SEO and GEO optimization rules | Public-facing pages | +| `git-workflow.md` | Atomic commits, ephemeral branches, PR curation | Git operations | +| `plan-first.md` | Read → plan → code → verify workflow | Before any implementation | +| `privacy.md` | Activist identity protection, real deletion, zero-knowledge architecture | Any data handling | +| `requirements.md` | Six-phase stakeholder interview for requirements gathering | Requirements sessions | +| `security-audit.md` | 10-step advocacy security audit | Security reviews | +| `security.md` | Three-adversary threat model, zero-retention APIs, device seizure preparation | Any security-sensitive work | +| `testing-strategy.md` | Spec-first, mutation testing, five anti-patterns | Test writing | +| `testing.md` | Testing concerns and quality gates | Test setup | + +## Cross-References + +- For Claude Code format, see `../claude-code/` +- For Cursor MDC format, see `../cursor/` +- For universal vendor-neutral instructions, see `../agents-md/AGENTS.md`