@goondocks/myco 0.1.0

package/hooks/hooks.json

@@ -0,0 +1,60 @@
+{
+  "description": "Myco capture pipeline — session lifecycle hooks for knowledge capture and context injection",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/src/hooks/session-start.js",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/src/hooks/user-prompt-submit.js",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/src/hooks/post-tool-use.js",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/src/hooks/stop.js",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/src/hooks/session-end.js",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@goondocks/myco",
+  "version": "0.1.0",
+  "description": "Collective agent intelligence — Claude Code plugin",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "myco": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/",
+    "commands/",
+    "skills/",
+    "hooks/",
+    ".claude-plugin/",
+    "CONTRIBUTING.md"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/goondocks-co/myco.git"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.78.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "better-sqlite3": "^12.8.0",
+    "chokidar": "^5.0.0",
+    "gray-matter": "^4.0.3",
+    "sqlite-vec": "^0.1.0",
+    "yaml": "^2.4.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.5.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.0"
+  }
+}

package/skills/myco/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: myco
+description: Use when making design decisions, debugging non-obvious issues, encountering gotchas, wondering why code is structured a certain way, or when you need context about prior work on the same feature or component. Myco captures the reasoning, trade-offs, and lessons behind the codebase — things the code itself doesn't show. Also use when the user mentions vault, memories, sessions, team knowledge, institutional memory, or prior decisions.
+---
+
+# Myco — Collective Agent Intelligence
+
+The codebase shows you **what** exists. Myco shows you **why** it exists — why this approach was chosen over alternatives, what broke along the way, what's non-obvious. When you're wondering *why* something is the way it is, or *whether* something was already tried, Myco has the answers.
+
+## When to Use Myco
+
+Use Myco tools proactively in these situations — don't wait to be asked:
+
+- **Before making a design decision** — search for prior reasoning on the same component. Someone may have already evaluated the approach you're considering, or documented why an alternative was rejected.
+- **When debugging a non-obvious issue** — search for the error message, component name, or symptom. A prior session may have hit the same problem and documented the root cause.
+- **When wondering why code is structured a certain way** — decisions and trade-offs behind the architecture are captured as memories.
+- **When continuing work on a feature** — check session history and plan progress for context on what's been done and what's pending.
+- **After discovering a gotcha, making a key decision, or fixing a tricky bug** — save it so future sessions benefit from the knowledge.
+- **When starting work on a branch** — context is injected automatically at session start, but you can call `myco_recall` for deeper context on specific files.
+
+## What's Automatic
+
+Myco works in the background without explicit tool calls:
+
+- **Session start**: relevant context is injected based on your git branch and active plans
+- **During the session**: tool calls, prompts, and responses are buffered as events
+- **Session stop**: the daemon extracts observations, writes session notes, detects parent sessions, and captures artifacts
+- **Lineage**: parent-child session relationships are detected automatically (clear context, same branch, semantic similarity)
+
+The MCP tools below are for going deeper than the automatic context injection provides.
+
+## Setup
+
+If the vault isn't configured, run `/myco-init` to set up. To change LLM providers, run `/myco-setup-llm`. To check health, run `/myco-status`.
+
+## MCP Tools Reference
+
+### myco_search — Find knowledge across the vault
+
+Combined semantic + full-text search across sessions, plans, and memories.
+
+```json
+{ "query": "why did we choose JWT over session cookies", "type": "memory", "limit": 5 }
+```
+
+**When to use**: searching for prior decisions, debugging context, or understanding rationale. The `type` filter narrows results — use `"memory"` for decisions/gotchas, `"session"` for session history, `"plan"` for plans, or omit for all.
+
+**Example**: before choosing an authentication approach, search for prior decisions:
+```json
+{ "query": "authentication approach JWT session", "type": "memory" }
+```
+
+### myco_recall — Get context for current work
+
+Automatic context retrieval based on git branch and files you're working on.
+
+```json
+{ "branch": "feature/auth-redesign", "files": ["src/auth/middleware.ts"] }
+```
+
+**When to use**: starting work on a feature or wanting deeper context than what was injected at session start. This is the "what do I need to know?" tool.
+
+### myco_remember — Save an observation
+
+Store a noteworthy observation for future sessions. Only save things that aren't obvious from reading the code.
+
+```json
+{ "content": "better-sqlite3 WASM build fails on Node 22 ARM — must use native build", "type": "gotcha", "tags": ["sqlite", "build"] }
+```
+
+**Observation types:**
+- `gotcha` — non-obvious pitfall, constraint, or workaround
+- `bug_fix` — root cause of a bug and what fixed it
+- `decision` — why an approach was chosen over alternatives
+- `discovery` — significant insight about the codebase, tooling, or domain
+- `trade_off` — what was sacrificed and what was gained
+
+**What makes a good observation:**
+- Specific: file names, function names, actual error messages, concrete values
+- Non-obvious: wouldn't be clear from just reading the code
+- Valuable: a teammate encountering the same situation would benefit
+- Durable: not specific to a transient state or one-off debugging session
+
+**Bad**: "the auth system is complex"
+**Good**: "bcrypt.compare() silently returns false (not an error) on hash format mismatch — spent 2h debugging; the hash column was VARCHAR(50) but bcrypt outputs 60 chars"
+
+### myco_plans — Check plan status
+
+List active plans and their progress.
+
+```json
+{ "status": "active" }
+```
+
+Use `{ "id": "plan-name" }` to read a specific plan's content.
+
+### myco_sessions — Browse session history
+
+Query past sessions with filters.
+
+```json
+{ "branch": "feature/auth", "limit": 5 }
+```
+
+Filter by `plan`, `branch`, `user`, or `since` (ISO timestamp). Useful for understanding what work has been done on a feature before continuing it.
+
+### myco_graph — Traverse vault connections
+
+Follow wikilink connections between notes — find related sessions, memories, and plans.
+
+```json
+{ "note_id": "session-abc123", "direction": "both", "depth": 2 }
+```
+
+**When to use**: exploring how a decision connects to sessions and other memories, or understanding the lineage of a feature's development across multiple sessions.
+
+### myco_orphans — Find disconnected notes
+
+Find vault notes with no incoming or outgoing wikilinks — potentially stale or unconnected knowledge.
+
+```json
+{}
+```
+
+### myco_team — See teammate activity
+
+See what teammates have been working on, filtered by files or plan.
+
+```json
+{ "plan": "auth-redesign" }
+```
+
+### myco_logs — Debug the daemon
+
+View daemon logs for debugging when sessions aren't being captured, observations are missing, or embeddings fail.
+
+```json
+{ "level": "warn", "component": "processor", "limit": 20 }
+```
+
+Components: `daemon`, `processor`, `hooks`, `lifecycle`, `embeddings`, `lineage`, `watcher`.
+
+### myco_supersede — Mark a memory as replaced
+
+When a newer observation makes an older one obsolete, supersede it. The old memory stays in the vault (data is never deleted) but is marked `status: superseded`.
+
+```json
+{ "old_memory_id": "decision-abc123", "new_memory_id": "decision-def456", "reason": "Migrated from bcrypt to argon2" }
+```
+
+**When to use**: a decision was reversed, a gotcha was fixed, a discovery turned out to be wrong, or the codebase changed and an observation no longer applies.
+
+### myco_consolidate — Merge memories into wisdom
+
+When multiple memories describe aspects of the same insight, consolidate them into a single comprehensive note. Source memories are marked superseded with links to the new wisdom note.
+
+```json
+{
+  "source_memory_ids": ["gotcha-aaa111", "gotcha-bbb222", "gotcha-ccc333"],
+  "consolidated_content": "# SQLite Operational Gotchas\n\n1. WAL mode requires shared memory...\n2. Single writer lock...\n3. FTS5 tokenization...",
+  "observation_type": "gotcha",
+  "tags": ["sqlite", "infrastructure"]
+}
+```
+
+**When to use**: 3+ memories share a root cause, describe the same pattern from different angles, or would be more useful as a single comprehensive reference.
+
+For detailed patterns on when and how to consolidate, read `references/wisdom.md`.
+
+## Wisdom — Keeping the Vault Clean
+
+Memories are injected into every prompt via the `UserPromptSubmit` hook. Each injected memory includes its ID (e.g., `[decision-abc123]`). When you see an injected memory that contradicts what you just did or know to be outdated, **supersede it immediately** — don't wait to be asked. This is how the vault stays accurate.
+
+**Proactive superseding during normal work:**
+
+- You just changed how the stop hook works → an injected memory says it works the old way → `myco_supersede` with the old ID and a new `myco_remember` capturing the current behavior
+- You see two injected memories that say conflicting things → supersede the older one
+- An injected gotcha references code that was refactored → supersede it
+
+**Other signals to act on:**
+
+- **Recurring gotchas**: the same problem keeps being recorded → `myco_consolidate` into one definitive note
+- **Overlapping content**: a `myco_remember` would duplicate an existing memory → `myco_supersede` with updated content instead
+- **Stale decisions**: a decision references a deleted component or reversed approach → supersede it
+
+The vault should get sharper over time, not just bigger. Every session should leave the vault more accurate than it found it.
+
+## Patterns
+
+### Starting work on an existing feature
+
+1. `myco_recall` with your branch and key files
+2. `myco_sessions` filtered by branch to see prior session summaries
+3. `myco_plans` to check if there's an active plan
+
+### After fixing a tricky bug
+
+```json
+{ "content": "Race condition in session stop: the unregister hook can fire before the stop hook processes the buffer. Fixed by checking buffer existence before deletion.", "type": "bug_fix", "tags": ["daemon", "hooks", "race-condition"] }
+```
+
+### Before making an architectural decision
+
+1. `myco_search` for prior decisions on the same component
+2. If you find relevant context, factor it into your recommendation
+3. After the decision is made, `myco_remember` the rationale

package/skills/myco/references/wisdom.md

@@ -0,0 +1,61 @@
+# Wisdom Consolidation Patterns
+
+When you notice patterns in vault memories — recurring themes, conflicting advice, outdated observations — use these tools to keep the vault clean and its knowledge sharp.
+
+## Supersede
+
+Use `myco_supersede` when a newer memory replaces an older one.
+
+**Signals:**
+- A decision was reversed in a later session
+- A gotcha was fixed and is no longer relevant
+- A discovery turned out to be wrong or incomplete
+- The codebase changed and an observation no longer applies
+
+**Example flow:**
+1. You find memory `decision-abc123` saying "we chose bcrypt for password hashing"
+2. A newer memory `decision-def456` says "migrated from bcrypt to argon2 for better side-channel resistance"
+3. Supersede the old one:
+```json
+{
+  "old_memory_id": "decision-abc123",
+  "new_memory_id": "decision-def456",
+  "reason": "Auth migrated from bcrypt to argon2"
+}
+```
+
+The old memory stays in the vault (data is never deleted) but its frontmatter is marked `status: superseded` with a link to the replacement. Search results deprioritize superseded memories.
+
+## Consolidate
+
+Use `myco_consolidate` when multiple memories describe aspects of the same insight and would be more useful as a single comprehensive note.
+
+**Signals:**
+- Three gotchas about the same subsystem that share a root cause
+- Multiple discoveries about the same library that, together, form a complete picture
+- A bug fix and a gotcha that describe the same issue from different angles
+- Several trade-off memories about the same architectural decision
+
+**Example flow:**
+1. You find three related gotchas:
+   - `gotcha-aaa111`: "SQLite WAL mode requires shared memory — fails in Docker"
+   - `gotcha-bbb222`: "SQLite locks on concurrent writes from multiple processes"
+   - `gotcha-ccc333`: "SQLite FTS5 tokenizer doesn't handle CamelCase"
+2. Consolidate them into a wisdom note:
+```json
+{
+  "source_memory_ids": ["gotcha-aaa111", "gotcha-bbb222", "gotcha-ccc333"],
+  "consolidated_content": "# SQLite Operational Gotchas\n\nThree key constraints when using SQLite in production:\n\n1. **WAL mode + Docker**: WAL requires shared memory (mmap). Containers with `--tmpfs` or read-only root filesystems break this. Mount the database directory as a named volume.\n\n2. **Concurrent write access**: SQLite serializes all writes through a single writer lock. Multiple processes writing concurrently will get SQLITE_BUSY. Use a single long-lived process (the daemon) for all writes.\n\n3. **FTS5 tokenization**: The default tokenizer splits on non-alphanumeric characters, so CamelCase identifiers like `getUserById` are indexed as one token. Use the `unicode61` tokenizer with `tokenchars` to handle this.",
+  "observation_type": "gotcha",
+  "tags": ["sqlite", "infrastructure"]
+}
+```
+
+The source memories are marked `status: superseded` with links to the wisdom note. The wisdom note has `consolidated_from` in its frontmatter linking back to its sources.
+
+## When NOT to act
+
+- **Don't consolidate unrelated memories** that happen to share tags — they should remain separate observations
+- **Don't supersede a memory just because it's old** — age alone isn't a reason; the content must be outdated or replaced
+- **Don't force consolidation for fewer than 3 sources** — two related memories are fine as separate notes; consolidation adds value when there's a pattern across 3+
+- **Don't consolidate across observation types** unless they truly describe the same insight from different angles (e.g., a bug_fix and a gotcha about the same issue is fine)

package/skills/rules/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: rules
+description: >-
+  Use when creating, auditing, or improving project rules files (CLAUDE.md,
+  AGENTS.md). Helps write specific, enforceable rules that agents actually
+  follow. Also triggered proactively when Myco detects recurring patterns
+  that should become project rules.
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob
+user-invocable: true
+---
+
+# Rules — Project Rules File Management
+
+Write, audit, and improve project rules files (CLAUDE.md, AGENTS.md) so agents follow them consistently. Rules files are the project's system prompt — they define invariants every agent must follow every time.
+
+## When to Use
+
+- **Creating a new rules file** for a project that doesn't have one
+- **Auditing an existing rules file** that agents seem to ignore
+- **Adding a rule** when you identify a pattern that should be standardized
+- **Proactively** when Myco detects recurring observations that suggest a missing rule
+
+## What Belongs in a Rules File
+
+Rules files contain **project invariants** — things every agent must follow every time, regardless of context.
+
+| Belongs in Rules File | Does NOT Belong |
+|----------------------|-----------------|
+| Hard constraints: "All API routes go through `src/routes/`" | Situational context (use Myco context injection) |
+| Golden paths: step-by-step standard procedures | Decision rationale (use Myco memory) |
+| Quality gates: specific commands that must pass | Code documentation (that's the codebase) |
+| Non-goals: what the project is NOT | Anything starting with "try to" or "when possible" |
+
+**The test:** If it's an invariant that applies to every session on every branch, it's a rule. If it depends on what you're working on, it's context — let Myco inject it.
+
+## Rule Writing Principles
+
+These principles apply whether you're writing new rules or auditing existing ones.
+
+### Every rule must be specific enough to violate
+
+- Bad: "Write clean code"
+- Good: "Functions MUST NOT exceed 50 lines"
+
+### Use RFC 2119 language
+
+| Keyword | Meaning | Example |
+|---------|---------|---------|
+| **MUST** | Absolute requirement, no exceptions | "All endpoints MUST validate input with Zod" |
+| **SHOULD** | Strong recommendation, exceptions need justification | "Services SHOULD be stateless" |
+| **MAY** | Optional, recognized pattern | "Teams MAY use dependency injection" |
+
+Anything weaker than MAY is not a rule. Remove it or strengthen it.
+
+### Anchor to real paths
+
+- Bad: "Put tests near the code"
+- Good: "Tests MUST be at `tests/<module>.test.ts` mirroring `src/<module>.ts`"
+
+### Define deviation lanes for SHOULD rules
+
+- "Functions SHOULD NOT exceed 50 lines. Exception: generated code in `src/generated/`."
+
+### No loopholes
+
+These phrases give agents permission to skip the rule: "when possible", "try to", "consider", "if needed", "as appropriate". Remove them or rephrase as SHOULD with explicit exceptions.
+
+## Required Sections
+
+A well-formed rules file has these sections. Not all are required for every project, but the skill checks for their absence.
+
+### 1. Project Identity
+
+What this project is, in one sentence. The anchor everything else hangs on.
+
+### 2. Non-Goals
+
+What this project is NOT. Prevents agents from "improving" things outside scope. Example: "This is NOT a general-purpose framework. Do not add extensibility points or plugin systems."
+
+### 3. Architecture Invariants
+
+Hard rules about project structure, anchored to real file paths. Example: "All database queries MUST go through `src/db/queries.ts`. No raw SQL in route handlers."
+
+### 4. Golden Paths
+
+Step-by-step standard procedures for common operations: add a feature, fix a bug, add a test. Not vibes — a checklist an agent can follow literally. Point to a canonical file to copy.
+
+### 5. Quality Gates
+
+Specific commands that must pass before work is done. Example: "Before committing: `npm run lint && npm test && npx tsc --noEmit`"
+
+## Audit Workflow
+
+### Step 1: Discover existing rules files
+
+Scan the project root and subdirectories for:
+- `CLAUDE.md` (root and subdirectories)
+- `AGENTS.md` (root)
+
+Report what exists and what doesn't. If neither exists, offer to create CLAUDE.md.
+
+### Step 2: Run audit checks
+
+For each rules file found, check:
+
+| Check | What It Catches | Severity |
+|-------|----------------|----------|
+| Missing sections | No non-goals, no quality gates, etc. | Important |
+| Vague rules | "Follow best practices", "keep it clean", "when possible" | Critical |
+| Unanchored rules | References to structure without real file paths | Important |
+| Contradictions | Two rules that conflict with each other | Critical |
+| Bloat | Rules duplicating what linter/tsconfig/CI already enforces | Minor |
+| Missing golden path | Common operations with no documented standard way | Important |
+| Stale anchors | Rules referencing files/paths that no longer exist | Critical |
+
+Detect missing golden paths by checking project signals: `package.json` → should have "add dependency" path, `src/routes/` → should have "add endpoint" path, test framework → should have "add test" path. Also ask the developer what common operations they perform.
+
+### Step 3: Check Myco observations (if available)
+
+Query `myco_search` for recurring observations related to the project. Look for:
+- Gotchas that recur 3+ times (same mistake across sessions)
+- Decisions that state "we should always/never do X"
+- Bug fixes where the root cause was violating an unwritten convention
+
+These are rule candidates. Surface them to the developer.
+
+### Step 4: Present findings
+
+Report findings ranked by severity (critical first). For each finding:
+- What the problem is
+- Why agents exploit it
+- Specific fix text (the exact rule to add, modify, or remove)
+
+The developer approves fixes individually or in batch.
+
+### Step 5: Apply approved fixes
+
+Edit the rules file with approved changes. Never auto-commit — the developer reviews the diff.
+
+## Add Rule Workflow
+
+### From a developer request
+
+1. Developer describes the rule they want
+2. Craft the rule: specific, anchored, RFC 2119 language
+3. Determine placement:
+   - **CLAUDE.md** — Rules specific to Claude Code (tool patterns, commit conventions, test commands)
+   - **AGENTS.md** — Universal rules any agent should follow (architecture, golden paths, conventions)
+   - If only one file exists, put it there
+   - If neither exists, create CLAUDE.md
+   - If CLAUDE.md contains agent-agnostic rules (architecture, golden paths), suggest creating AGENTS.md and moving them there
+4. Find the correct section (invariant, golden path, quality gate, etc.)
+5. Insert the rule
+6. Developer reviews the diff
+
+### Rule Crafting Example
+
+Raw observation: "better-sqlite3 WASM build fails on Node 22 ARM — must use native build"
+
+Bad rule: "Be careful with sqlite builds"
+
+Good rule: "better-sqlite3 MUST be installed with native bindings, not WASM. The WASM build fails on Node 22 ARM. Run `npm install better-sqlite3 --build-from-source` if the default install produces WASM artifacts."
+
+### From a Myco observation
+
+1. Myco surfaces a pattern: "Your team has hit 3 gotchas about X. Should this become a rule?"
+2. If the developer approves:
+   - Craft the rule from the observation
+   - The rule states the **what** — the observation (in Myco memory) stores the **why**
+   - Place it in the correct file and section
+3. If the developer dismisses: the observation stays as context, not a rule
+
+### What stays as memory, NOT a rule
+
+Reject promotion for:
+- One-off gotchas unlikely to recur (< 3 occurrences)
+- Decision rationale (the rule states what; memory stores why)
+- Branch-specific or time-limited knowledge
+- Anything that would only matter during a specific initiative
+
+## References
+
+For examples of well-written and poorly-written rules files:
+- `references/rules-good-example.md` — All five sections done right
+- `references/rules-bad-example.md` — Every anti-pattern annotated with fixes

package/skills/rules/references/rules-bad-example.md

@@ -0,0 +1,106 @@
+# Rules File — Bad Example
+
+This is an example of a poorly written CLAUDE.md. Every section contains anti-patterns that cause agents to freestyle, skip rules, or misinterpret intent. Each problem is annotated below.
+
+---
+
+# Patchwork
+
+A deployment tool. Use best practices and write clean code.
+
+Try to follow SOLID principles and keep things simple. Use TypeScript patterns when appropriate.
+We want good test coverage. Avoid hardcoded values when possible.
+
+Architecture:
+
+- Routes
+- Services
+- Database
+
+When adding features, follow the existing patterns and make sure things work.
+Try to add tests for important functionality. Keep the codebase clean.
+
+---
+
+## What's Wrong (and How Agents Exploit It)
+
+### 1. "Use best practices" — vague and unenforceable
+
+**Problem:** Every agent interprets "best practices" differently. One agent adds dependency injection, another uses functional patterns, a third invents its own service layer.
+
+**Why agents exploit it:** It's permission to do whatever they think is best. They always think their approach is a best practice.
+
+**Fix:** Specify the practice. "All request input MUST be validated with Zod schemas in `src/schemas/`."
+
+### 2. No non-goals — unlimited scope
+
+**Problem:** Without explicit boundaries, agents will "improve" anything they touch. They'll add caching layers, restructure folders, create abstraction hierarchies — all unrequested.
+
+**Why agents exploit it:** Agents default to being helpful. Without boundaries, everything looks like an opportunity to improve.
+
+**Fix:** Add explicit non-goals: "Patchwork is NOT a deployment orchestrator, NOT a monitoring system, NOT a CI/CD pipeline."
+
+### 3. "When appropriate" and "when possible" — loophole generators
+
+**Problem:** "Use TypeScript patterns when appropriate" and "avoid hardcoded values when possible" give agents a built-in excuse to skip the rule. They'll decide it's "not appropriate" or "not possible" whenever the rule is inconvenient.
+
+**Why agents exploit it:** The qualifying phrase is a release valve. Agents will always find a reason the exception applies.
+
+**Fix:** Make it absolute or define the exceptions: "No literal strings or numbers outside of `src/constants.ts`. Exception: test fixture data in `tests/fixtures/`."
+
+### 4. No anchors — agents invent patterns
+
+**Problem:** "Follow existing patterns" doesn't say which patterns or where to find them. Agents scan the codebase, find three different approaches, and pick whichever they prefer — or invent a fourth.
+
+**Why agents exploit it:** Without a canonical example to copy, agents rely on their training data, which includes thousands of different patterns.
+
+**Fix:** Point to specific files: "Copy `src/routes/patches.ts` for new endpoints."
+
+### 5. "Try to add tests" — permission to skip
+
+**Problem:** "Try to" means "do it if you feel like it." Agents will skip tests for "simple changes" or "obvious code."
+
+**Why agents exploit it:** Agents optimize for speed. If tests are optional, they're the first thing cut.
+
+**Fix:** Make it a gate: "ALL changes MUST include tests. Run `npm test` before committing."
+
+### 6. "Keep things clean" — means nothing
+
+**Problem:** What does "clean" mean? Short functions? No comments? Lots of comments? Alphabetized imports? Every agent has a different opinion.
+
+**Why agents exploit it:** It's a vibes-based instruction. Agents will refactor code to match their idea of "clean," often introducing unnecessary changes.
+
+**Fix:** Be specific about what clean means in this project: "Functions MUST NOT exceed 50 lines. Files MUST NOT exceed 300 lines. Imports MUST be grouped: node: built-ins, external packages, internal modules."
+
+### 7. Architecture section is just labels
+
+**Problem:** "Routes, Services, Database" describes what exists but says nothing about the rules. Can a route call the database directly? Can a service import from routes? Who knows.
+
+**Why agents exploit it:** Without layering rules, agents take the shortest path. If the database is faster to call from a route, they'll do it.
+
+**Fix:** Define the invariants: "Route handlers delegate to services. Services MUST NOT import from routes. Database access MUST go through `src/db/client.ts`."
+
+### 8. No quality gates — "make sure things work" is not a gate
+
+**Problem:** "Make sure things work" has no verification step. There's no command to run, no coverage threshold, no lint check.
+
+**Why agents exploit it:** If there's no specific command to run, agents won't run anything. They'll eyeball the code and claim it works.
+
+**Fix:** List exact commands: "`npm run lint && npm run typecheck && npm test` — ALL must pass before committing."
+
+---
+
+## The Pattern
+
+Bad rules files share these characteristics:
+
+| Anti-Pattern | Example | Why Agents Exploit It |
+|-------------|---------|----------------------|
+| Vague verbs | "should", "try to", "prefer" | Not enforceable — agents treat them as suggestions |
+| No examples | "follow good patterns" | Agents invent patterns from training data |
+| No metrics | "keep coverage high" | Subjective — agents set their own threshold (usually 0%) |
+| Loopholes | "when possible", "if needed" | Built-in excuse to skip the rule |
+| Missing scope | (no non-goals section) | Agents "improve" everything they touch |
+| No gates | "add tests" | No way to verify compliance |
+| Just labels | "Routes, Services, Database" | Describes structure without enforcing rules about it |
+| Aspirational | "keep things clean" | Means whatever the agent wants it to mean |