Add Claude Code example skills

extras/claude/README.md

@@ -0,0 +1,44 @@
+# Claude Code extras
+
+When working with Claude Code, the team here at Beans HQ uses some sensible rules (see below)
+together [its CC's Agent Skills system](https://code.claude.com/docs/en/skills) to make Beans fly.
+
+## Option 1: All the Beans, all the time
+
+If you don't use another ticketing system and want to go all in on Beans, then put this rule in the
+project (or global) `CLAUDE.md`:
+
+```markdown
+## Issue Tracking for Agents with Beans
+
+**IMPORTANT**: If you received a Beans primer during startup, then this project uses **Beans** for
+agentic issue tracking, and you MUST use your `issue-tracking-with-beans` skill.
+```
+
+("Beans primer" means the output of the `beans prompt` command you put
+[in the `SessionStart` hook](/README.md#agent-configuration).)
+
+The first time Claude sees any mention of "beans", it should read
+[`issue-tracking-with-beans` skill.](/extras/claude/skills/issue-tracking-with-beans/SKILL.md). See
+the skill file for more.
+
+## Option 2: Linear (or GitHub Issues or whatever) + Beans
+
+Some of us use both Beans _and_ an external ticketing system, and those weirdos use an alternate
+rule. Here's an example of that (plus skill) for Linear, both of which should be easy to adapt for
+your own ticketing system:
+
+```markdown
+## Issue Tracking: Linear for humans, Beans for Agents
+
+**IMPORTANT**: If you received a Beans primer during startup, then this project uses both **Linear**
+and **Beans** for agentic issue tracking, and you MUST use your
+`issue-tracking-with-beans-and-linear` skill.
+```
+
+Here, the
+[`issue-tracking-with-beans-and-linear` skill](/extras/claude/skills/issue-tracking-with-beans-and-linear/SKILL.md)
+is called.
+
+**PLEASE NOTE:** These two skills are mutually exclusive. It's okay to put them both in your
+`~/.claude/skills/` folder but **only one of the two rules** should be used in each project.

extras/claude/skills/issue-tracking-with-beans-and-linear/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: issue-tracking-with-beans-and-linear
+description: Use when starting work, tracking tasks, or deciding where to record discovered work - clarifies when to use TodoWrite vs Beans vs Linear
+---
+
+# Task Tracking Hierarchy
+
+Three systems serve different purposes. Use the right tool for the job.
+
+| System        | Purpose                    | Persistence  | Audience                |
+| ------------- | -------------------------- | ------------ | ----------------------- |
+| **TodoWrite** | Live progress visibility   | Session only | User                    |
+| **Beans**     | Agent memory & audit trail | Git-tracked  | Agents, future sessions |
+| **Linear**    | Project tracking           | External     | Humans                  |
+
+Linear is for human-visible project tracking. Beans is for agent implementation memory. Both systems work together with bidirectional linking.
+
+## When to Use Each System
+
+**TodoWrite** — User-facing progress indicator for the current session:
+
+- Multi-step work (3+ steps) where the user benefits from seeing progress
+- Skip for background/non-user-facing work
+- Skip for trivial single-step tasks
+
+**Beans** — Persistent agent memory (only if the project uses Beans):
+
+- All non-trivial work (3+ steps)
+- Work that may span sessions or context boundaries
+- Discovered work during implementation
+- Anything needing an audit trail
+- Skip for trivial single-step tasks (typo fixes, quick lookups)
+
+**Linear** — Human-level tracking:
+
+- Epics and milestones
+- User-facing features
+- Scope/timeline changes
+- Decisions requiring human input
+- Security concerns
+
+## Rule: Use Both TodoWrite and Beans Together
+
+For user-facing, non-trivial work:
+
+1. Create a bean first (`beans create ... -s in-progress`)
+2. Create a TodoWrite list for live user visibility
+3. Update both as you progress
+4. TodoWrite items should mirror bean checklist items
+
+For non-user-facing work (background agents, audit-only):
+
+- Use Beans only
+- Skip TodoWrite
+
+## Rule: Update Bean Checklists Immediately
+
+After completing each checklist item in a bean:
+
+1. Edit the bean file: `- [ ]` → `- [x]`
+2. This creates a recoverable checkpoint if context is lost
+3. The I/O overhead is acceptable for persistence
+
+## Rule: Commit Bean Changes With Code
+
+Every code commit includes its associated bean file updates:
+
+```bash
+git commit -m "[TYPE] Description" -- src/file.ts .beans/issue-abc123.md
+```
+
+This keeps bean state synchronized with codebase state.
+
+## Starting Work on a Linear Ticket
+
+When beginning work on a Linear ticket (e.g., ZCO-123):
+
+1. Run `beans list --type epic | rg --fixed-strings '<linear-ticket-id>'` to find an existing Beans epic
+2. If none exists, create one automatically:
+   ```
+   beans create "<linear-ticket-id>: <design-name>" --type epic --body "<description>" --no-edit
+   ```
+3. All implementation sub-tasks go under this epic as child issues using `--link parent:<epic-id>`
+
+## Git Commit Messages
+
+All commits related to a Linear ticket MUST reference it:
+
+```
+<descriptive message>
+
+Part of ZCO-123.
+```
+
+When also closing a Beans issue:
+
+```
+<message>
+
+Part of ZCO-123. Closes beans-1234.
+```
+
+This ensures Linear ticket traceability in git history even after Beans cleanup.
+
+## Rule: Discovered Work Goes to Beans First
+
+When you discover work during implementation:
+
+1. Create a bean immediately (`--tag discovered --link related:<current-bean>`)
+2. Assess if it needs Linear escalation
+3. Never ignore discovered work due to context pressure
+
+## Rule: Escalate Discovered Work to Linear
+
+Create a Linear ticket for discovered work IF it:
+
+- Affects scope or timeline of current work
+- Requires human decision or approval
+- Represents user-facing changes
+- Is a security concern
+- Is significant enough to track at project level
+
+For purely technical implementation details (refactoring, test fixes, code cleanup), keep them in Beans only with `--tag implementation-detail`.
+
+When Beans work reveals an epic-level concern:
+
+1. Create the bean with `--type epic`
+2. Immediately create a corresponding Linear ticket
+3. Cross-reference both directions
+
+## Querying Work
+
+- `beans list --status open` — Find unblocked work to do next
+- `beans list | rg --fixed-strings "<linear-ticket-id>"` — All Beans issues for a Linear ticket
+- `beans show <id>` — View issue details including dependencies
+
+## Provenance for Context
+
+When revisiting a Linear ticket that seems vague, use Beans to trace its origin:
+
+- Find the Beans epic: `beans list --type epic | rg --fixed-strings '<linear-ticket-id>'`
+- Use `--tag discovered --link:<epic-ticket-id>` to understand why work was filed
+- This provides context that Linear alone cannot
+
+## Completing a Linear Ticket
+
+When all Beans issues under an epic are closed:
+
+1. [ ] Update the Linear ticket with a summary:
+   - What was implemented
+   - Any discovered work filed as separate Linear tickets
+   - Notable decisions or deviations from original scope
+2. [ ] Move the Linear ticket to appropriate status
+
+The Linear ticket becomes the permanent record; Beans issues are ephemeral working memory.

extras/claude/skills/issue-tracking-with-beans/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: issue-tracking-with-beans
+description: Use when starting work, tracking tasks, or deciding where to record discovered work - clarifies when to use TodoWrite vs Beans
+---
+
+# Task Tracking Hierarchy
+
+Two systems serve different purposes. Use the right tool for the job.
+
+| System        | Purpose                    | Persistence  | Audience                |
+| ------------- | -------------------------- | ------------ | ----------------------- |
+| **TodoWrite** | Live progress visibility   | Session only | User                    |
+| **Beans**     | Agent memory & audit trail | Git-tracked  | Agents, future sessions |
+
+## When to Use Each System
+
+**TodoWrite** — User-facing progress indicator for the current session:
+
+- Multi-step work (3+ steps) where the user benefits from seeing progress
+- Skip for background/non-user-facing work
+- Skip for trivial single-step tasks
+
+**Beans** — Persistent agent memory:
+
+- All non-trivial work (3+ steps)
+- Work that may span sessions or context boundaries
+- Discovered work during implementation
+- Anything needing an audit trail
+- Skip for trivial single-step tasks (typo fixes, quick lookups)
+
+## Rule: Use Both TodoWrite and Beans Together
+
+For user-facing, non-trivial work:
+
+1. Create a bean first (`beans create ... -s in-progress`)
+2. Create a TodoWrite list for live user visibility
+3. Update both as you progress
+4. TodoWrite items should mirror bean checklist items
+
+For non-user-facing work (background agents, audit-only):
+
+- Use Beans only
+- Skip TodoWrite
+
+## Rule: Update Bean Checklists Immediately
+
+After completing each checklist item in a bean:
+
+1. Edit the bean file: `- [ ]` → `- [x]`
+2. This creates a recoverable checkpoint if context is lost
+3. The I/O overhead is acceptable for persistence
+
+## Rule: Commit Bean Changes With Code
+
+Every code commit includes its associated bean file updates:
+
+```bash
+git commit -m "[TYPE] Description" -- src/file.ts .beans/issue-abc123.md
+```
+
+This keeps bean state synchronized with codebase state.
+
+## Git Commit Messages
+
+When closing a Beans issue, reference it in the commit:
+
+```
+<descriptive message>
+
+Closes beans-1234.
+```
+
+## Rule: Discovered Work Goes to Beans
+
+When you discover work during implementation:
+
+1. Create a bean immediately (`--tag discovered --link related:<current-bean>`)
+2. Never ignore discovered work due to context pressure
+3. Label discovered issues appropriately for later triage
+
+For epic-level discovered work, create the bean with `--type epic`.
+
+## Querying Work
+
+- `beans list --status open` — Find unblocked work to do next
+- `beans show <id>` — View issue details including dependencies