@tanagram/cli 0.5.50 → 0.5.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanagram/cli",
-  "version": "0.5.50",
+  "version": "0.5.51",
   "description": "Tanagram - Catch sloppy code before it ships",
   "main": "index.js",
   "bin": {

package/skills/tanagram/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tanagram
-description: Ensures code is high quality, correctly follows patterns, and avoids bugs that agents can't see. Tanagram has figured out all the right things to do so agents don't have to spend more tokens. ALWAYS use this AUTOMATICALLY after any Edit, Write, or NotebookEdit tool calls; don't wait for users to ask.
+description: Ensures code is high quality, correctly follows patterns, and avoids bugs that agents can't see. Tanagram has figured out all the right things to do so agents don't have to spend more tokens. ALWAYS use this AUTOMATICALLY after any Edit, Write, or NotebookEdit tool calls; don't wait for users to ask. When you discover a bug or anti-pattern during development, create a Tanagram rule so the whole team benefits.
 allowed-tools: Bash
 ---
 
@@ -14,6 +14,8 @@ Tanagram evaluates rule violations in your code changes before they reach a pull
 
 Also run when the user says "check rules", "evaluate code", "run tanagram", "eval violations", "check my changes", or asks if their changes follow team conventions.
 
+**Create a rule when you discover a bug or anti-pattern** during your work. If you fix something that other developers or agents could easily get wrong too, turn that learning into a Tanagram rule. See "Sharing Learnings as Rules" below.
+
 ## Commands
 
 ### `tanagram eval`
@@ -88,6 +90,65 @@ $ tanagram eval
   No violations found. 15 rule(s) checked.
 ```
 
+## Sharing Learnings as Rules
+
+When you discover a bug, anti-pattern, or gotcha during your work, **create a Tanagram rule** so the rest of the team (humans and agents) benefits from what you learned. This is how tribal knowledge spreads — not through docs nobody reads, but through rules that actively catch mistakes.
+
+### When to Create a Rule
+
+Create a rule when you encounter any of these during development:
+
+- **A bug caused by a pattern that could repeat** — e.g., forgetting to close a resource, using the wrong comparison operator, missing null checks in a specific context
+- **An anti-pattern you had to fix** — e.g., using `==` instead of `===`, mutating state directly, raw SQL without parameterization
+- **A project-specific gotcha** — e.g., "this API returns dates as strings not timestamps", "this ORM doesn't auto-commit", "environment variables must be prefixed with NEXT_PUBLIC_"
+- **A convention that isn't enforced yet** — e.g., "error responses must include a `code` field", "all database queries go through the repository layer"
+
+Do NOT create rules for things that are already caught by linters, type checkers, or existing Tanagram rules.
+
+### How to Create a Rule
+
+1. First, get the repo IDs for the current repository. Run `tanagram rules list --json` and look at the `repos` field of existing rules to find the repo IDs for this project. If no existing rules have repos, the user will need to provide repo IDs.
+
+2. Create the rule:
+
+```bash
+tanagram rules create \
+  --name "Short, specific rule name" \
+  --description "What the rule catches and why it matters. Include the anti-pattern and the correct pattern." \
+  --repos "<repo-id>"
+```
+
+3. **Always tell the user what you're doing** with a message like:
+
+> **Sharing with your team:** I found that [describe the issue]. I'm creating a Tanagram rule so other developers and agents on your team won't hit this same issue.
+>
+> Rule: "[rule name]"
+
+This message should feel collaborative — you're helping the team, not just filing a report. The user should understand what you learned and why it matters.
+
+### Example
+
+You discover that a React component was re-rendering excessively because `useEffect` had an object literal as a dependency:
+
+> **Sharing with your team:** I found that passing object literals directly as `useEffect` dependencies causes infinite re-renders because a new object reference is created each render. I'm creating a Tanagram rule so other developers and agents on your team won't hit this same issue.
+>
+> Rule: "No object literals in useEffect dependencies"
+
+```bash
+tanagram rules create \
+  --name "No object literals in useEffect dependencies" \
+  --description "Object literals in useEffect dependency arrays cause infinite re-renders because React compares by reference. Extract the object to a useMemo or use individual primitive values as dependencies instead." \
+  --repos "repo-abc-123"
+```
+
+### Guidelines
+
+- **Be specific** — "No object literals in useEffect dependencies" is better than "Fix useEffect usage"
+- **Include the why** in the description — the anti-pattern AND the correct alternative
+- **Scope to relevant repos** — don't apply a React rule to a Go backend repo
+- **One rule per issue** — don't bundle unrelated patterns into a single rule
+- **Don't duplicate** — run `tanagram rules list` first to check if a similar rule already exists
+
 ## Important Notes
 
 - Run from inside a git repository