@anthropologies/claudestory 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropologies/claudestory",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "exports": {
     ".": {
@@ -13,6 +13,7 @@
   },
   "files": [
     "dist",
+    "src/skill",
     "README.md"
   ],
   "engines": {

package/src/skill/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: story
+description: Cross-session context persistence for AI coding projects. Load project context, manage sessions, guide setup.
+---
+
+# /story — Project Context & Session Management
+
+claudestory tracks tickets, issues, roadmap, and handovers in a `.story/` directory so every AI coding session builds on the last instead of starting from zero.
+
+## How to Handle Arguments
+
+`/story` is one smart command. Parse the user's intent from context:
+
+- `/story` → full context load (default, see Step 2 below)
+- `/story handover` → draft a session handover. Summarize the session's work, then call `claudestory_handover_create` with the drafted content and a descriptive slug
+- `/story snapshot` → save project state (call `claudestory_snapshot` MCP tool)
+- `/story export` → export project for sharing. Ask the user whether to export the current phase or the full project, then call `claudestory_export` with either `phase` or `all` set
+- `/story status` → quick status check (call `claudestory_status` MCP tool)
+- `/story help` → show all capabilities (read `~/.claude/skills/story/reference.md`)
+
+If the user's intent doesn't match any of these, use the full context load.
+
+## Step 0: Check Setup
+
+Check if the claudestory MCP tools are available by looking for `claudestory_status` in your available tools.
+
+**If MCP tools ARE available** → proceed to Step 1.
+
+**If MCP tools are NOT available:**
+
+1. Check if the `claudestory` CLI is installed: run `claudestory --version` via Bash
+2. If NOT installed:
+   - Check `node --version` and `npm --version` — both must be available
+   - If Node.js is missing, tell the user to install Node.js 20+ first
+   - Otherwise, with user permission, run: `npm install -g @anthropologies/claudestory`
+   - Then run: `claude mcp add claudestory -s user -- claudestory --mcp`
+   - Tell the user to restart Claude Code and run `/story` again
+3. If CLI IS installed but MCP not registered:
+   - With user permission, run: `claude mcp add claudestory -s user -- claudestory --mcp`
+   - Tell the user to restart Claude Code and run `/story` again
+
+**Important:** Always use `npm install -g`, never `npx`, for the CLI. The MCP server needs the global binary.
+
+**If MCP tools are unavailable and user doesn't want to set up**, fall back to CLI mode:
+- Run `claudestory status` via Bash
+- Run `claudestory recap` via Bash
+- Run `claudestory handover latest` via Bash
+- Read `RULES.md` and `WORK_STRATEGIES.md` if they exist in the project root
+- Run `git log --oneline -10`
+- Then continue to Step 3 below
+
+## Step 1: Check Project
+
+- If `.story/` exists in the current working directory (or a parent) → proceed to Step 2
+- If no `.story/` but the directory looks like a real project (has package.json, Cargo.toml, go.mod, pyproject.toml, .git, etc.) → offer to initialize: "Want me to set up claudestory? It creates a .story/ directory for tracking tickets, issues, and session handovers." With permission, run `claudestory init --name <project-name>`
+- If not a project directory → explain what claudestory is and suggest navigating to a project
+
+## Step 2: Load Context (Default /story Behavior)
+
+Call these in order:
+
+1. **Project status** — call `claudestory_status` MCP tool
+2. **Session recap** — call `claudestory_recap` MCP tool (shows changes since last snapshot)
+3. **Recent handovers** — call `claudestory_handover_latest` MCP tool with `count: 3` (last 3 sessions' context — ensures reasoning behind recent decisions is preserved, not just the latest session's state)
+4. **Development rules** — read `RULES.md` if it exists in the project root
+5. **Lessons learned** — read `WORK_STRATEGIES.md` if it exists in the project root
+6. **Recent commits** — run `git log --oneline -10`
+
+## Step 3: Present Summary
+
+After loading context, present a concise summary:
+
+- Project progress (X/Y tickets complete, current phase)
+- What changed since last snapshot (from recap)
+- What the last session accomplished (from handover)
+- Next ticket to work on
+- Any high-severity issues or blockers
+- Key process rules (from WORK_STRATEGIES.md if it exists)
+
+For collaborative sessions, `claudestory_recommend` provides context-aware suggestions mixing tickets and issues. For autonomous sessions, `claudestory_ticket_next` provides queue-based next ticket.
+
+Then ask: **"What would you like to work on?"**
+
+## Session Lifecycle
+
+- **Snapshots** save project state for diffing. They may be auto-taken before context compaction.
+- **Handovers** are session continuity documents. Create one at the end of significant sessions.
+- **Recaps** show what changed since the last snapshot — useful for understanding drift.
+
+**Never modify or overwrite existing handover files.** Handovers are append-only historical records. Always create new handover files — never edit, replace, or write to an existing one. If you need to correct something from a previous session, create a new handover that references the correction. This prevents accidental data loss during sessions.
+
+Before writing a handover at the end of a session, run `claudestory snapshot` first. This ensures the next session's recap can show what changed. If `setup-skill` has been run, a PreCompact hook auto-takes snapshots before context compaction.
+
+## Ticket and Issue Discipline
+
+**Tickets** are planned work — features, tasks, refactors. They represent intentional, scoped commitments.
+
+**Ticket types:**
+- `task` — Implementation work: building features, writing code, fixing bugs, refactoring.
+- `feature` — A user-facing capability or significant new functionality. Larger scope than a task.
+- `chore` — Maintenance, publishing, documentation, cleanup. No functional change to the product.
+
+**Issues** are discovered problems — bugs, inconsistencies, gaps, risks found during work. If you're not sure whether something is a ticket or an issue, make it an issue. It can be promoted to a ticket later.
+
+When working on a task and you encounter a bug, inconsistency, or improvement opportunity that is out of scope for the current ticket, create an issue using `claudestory issue create` (CLI) with a clear title, severity, and impact description. Don't fix it in the current task, don't ignore it — log it. This keeps the issue tracker growing organically and ensures nothing discovered during work is lost.
+
+When starting work on a ticket, update its status to `inprogress`. When done, update to `complete` in the same commit as the code change.
+
+## Managing Tickets and Issues
+
+Ticket and issue create/update operations are available via both CLI and MCP tools. Delete remains CLI-only.
+
+CLI examples:
+- `claudestory ticket create --title "..." --type task --phase p0`
+- `claudestory ticket update T-001 --status complete`
+- `claudestory issue create --title "..." --severity high --impact "..."`
+
+MCP examples:
+- `claudestory_ticket_create` with `title`, `type`, and optional `phase`, `description`, `blockedBy`, `parentTicket`
+- `claudestory_ticket_update` with `id` and optional `status`, `title`, `order`, `description`, `phase`, `parentTicket`
+- `claudestory_issue_create` with `title`, `severity`, `impact`, and optional `components`, `relatedTickets`, `location`, `phase`
+- `claudestory_issue_update` with `id` and optional `status`, `title`, `severity`, `impact`, `resolution`, `components`, `relatedTickets`, `location`
+
+Read operations (list, get, next, blocked) are available via both CLI and MCP.
+
+## Notes
+
+**Notes** are unstructured brainstorming artifacts — ideas, design thinking, "what if" explorations. Use notes when the content doesn't fit tickets (planned work) or issues (discovered problems).
+
+Create notes via CLI: `claudestory note create --content "..." --tags idea`
+
+Create notes via MCP: `claudestory_note_create` with `content`, optional `title` and `tags`.
+
+List, get, and update notes via MCP: `claudestory_note_list`, `claudestory_note_get`, `claudestory_note_update`. Delete remains CLI-only: `claudestory note delete <id>`.
+
+## Command & Tool Reference
+
+For the full list of CLI commands and MCP tools, read `reference.md` in the same directory as this skill file.

package/src/skill/reference.md

@@ -0,0 +1,338 @@
+# claudestory Reference
+
+## CLI Commands
+
+### init
+Initialize a new .story/ project
+
+```
+claudestory init [--name <name>] [--type <type>] [--language <lang>] [--force] [--format json|md]
+```
+
+### status
+Project summary: phase statuses, ticket/issue counts, blockers
+
+```
+claudestory status [--format json|md]
+```
+
+### ticket list
+List tickets with optional filters
+
+```
+claudestory ticket list [--status <s>] [--phase <p>] [--type <t>] [--format json|md]
+```
+
+### ticket get
+Get ticket details by ID
+
+```
+claudestory ticket get <id> [--format json|md]
+```
+
+### ticket next
+Suggest next ticket(s) to work on
+
+```
+claudestory ticket next [--count N] [--format json|md]
+```
+
+### ticket blocked
+List blocked tickets with their blocking dependencies
+
+```
+claudestory ticket blocked [--format json|md]
+```
+
+### ticket create
+Create a new ticket
+
+```
+claudestory ticket create --title <t> --type <type> [--phase <p>] [--description <d>] [--blocked-by <ids>] [--parent-ticket <id>] [--format json|md]
+```
+
+### ticket update
+Update a ticket
+
+```
+claudestory ticket update <id> [--status <s>] [--title <t>] [--phase <p>] [--order <n>] [--description <d>] [--blocked-by <ids>] [--parent-ticket <id>] [--format json|md]
+```
+
+### ticket delete
+Delete a ticket
+
+```
+claudestory ticket delete <id> [--force] [--format json|md]
+```
+
+### issue list
+List issues with optional filters
+
+```
+claudestory issue list [--status <s>] [--severity <sev>] [--format json|md]
+```
+
+### issue get
+Get issue details by ID
+
+```
+claudestory issue get <id> [--format json|md]
+```
+
+### issue create
+Create a new issue
+
+```
+claudestory issue create --title <t> --severity <s> --impact <i> [--components <c>] [--related-tickets <ids>] [--location <locs>] [--format json|md]
+```
+
+### issue update
+Update an issue
+
+```
+claudestory issue update <id> [--status <s>] [--title <t>] [--severity <sev>] [--impact <i>] [--resolution <r>] [--components <c>] [--related-tickets <ids>] [--location <locs>] [--format json|md]
+```
+
+### issue delete
+Delete an issue
+
+```
+claudestory issue delete <id> [--format json|md]
+```
+
+### phase list
+List all phases with derived status
+
+```
+claudestory phase list [--format json|md]
+```
+
+### phase current
+Show current (first non-complete) phase
+
+```
+claudestory phase current [--format json|md]
+```
+
+### phase tickets
+List tickets in a specific phase
+
+```
+claudestory phase tickets --phase <id> [--format json|md]
+```
+
+### phase create
+Create a new phase
+
+```
+claudestory phase create --id <id> --name <n> --label <l> --description <d> [--summary <s>] [--after <id>] [--at-start] [--format json|md]
+```
+
+### phase rename
+Rename/update phase metadata
+
+```
+claudestory phase rename <id> [--name <n>] [--label <l>] [--description <d>] [--summary <s>] [--format json|md]
+```
+
+### phase move
+Move a phase to a new position
+
+```
+claudestory phase move <id> [--after <id>] [--at-start] [--format json|md]
+```
+
+### phase delete
+Delete a phase
+
+```
+claudestory phase delete <id> [--reassign <phase-id>] [--format json|md]
+```
+
+### handover list
+List handover filenames (newest first)
+
+```
+claudestory handover list [--format json|md]
+```
+
+### handover latest
+Content of most recent handover
+
+```
+claudestory handover latest [--format json|md]
+```
+
+### handover get
+Content of a specific handover
+
+```
+claudestory handover get <filename> [--format json|md]
+```
+
+### handover create
+Create a new handover document
+
+```
+claudestory handover create [--content <md>] [--stdin] [--slug <slug>] [--format json|md]
+```
+
+### blocker list
+List all roadmap blockers
+
+```
+claudestory blocker list [--format json|md]
+```
+
+### blocker add
+Add a new blocker
+
+```
+claudestory blocker add --name <n> [--note <note>] [--format json|md]
+```
+
+### blocker clear
+Clear (resolve) a blocker
+
+```
+claudestory blocker clear --name <n> [--note <note>] [--format json|md]
+```
+
+### note list
+List notes with optional status/tag filters
+
+```
+claudestory note list [--status <s>] [--tag <t>] [--format json|md]
+```
+
+### note get
+Get a note by ID
+
+```
+claudestory note get <id> [--format json|md]
+```
+
+### note create
+Create a new note
+
+```
+claudestory note create --content <c> [--title <t>] [--tags <tags>] [--format json|md]
+```
+
+### note update
+Update a note
+
+```
+claudestory note update <id> [--content <c>] [--title <t>] [--tags <tags>] [--clear-tags] [--status <s>] [--format json|md]
+```
+
+### note delete
+Delete a note
+
+```
+claudestory note delete <id> [--format json|md]
+```
+
+### validate
+Reference integrity + schema checks on all .story/ files
+
+```
+claudestory validate [--format json|md]
+```
+
+### snapshot
+Save current project state for session diffs
+
+```
+claudestory snapshot [--quiet] [--format json|md]
+```
+
+### recap
+Session diff — changes since last snapshot + suggested actions
+
+```
+claudestory recap [--format json|md]
+```
+
+### export
+Self-contained project document for sharing
+
+```
+claudestory export [--phase <id>] [--all] [--format json|md]
+```
+
+### recommend
+Context-aware work suggestions
+
+```
+claudestory recommend [--count N] [--format json|md]
+```
+
+### reference
+Print CLI command and MCP tool reference
+
+```
+claudestory reference [--format json|md]
+```
+
+### setup-skill
+Install the /story skill globally for Claude Code
+
+```
+claudestory setup-skill
+```
+
+## MCP Tools
+
+- **claudestory_status** — Project summary: phase statuses, ticket/issue counts, blockers
+- **claudestory_phase_list** — All phases with derived status
+- **claudestory_phase_current** — First non-complete phase
+- **claudestory_phase_tickets** (phaseId) — Leaf tickets for a specific phase
+- **claudestory_ticket_list** (status?, phase?, type?) — List leaf tickets with optional filters
+- **claudestory_ticket_get** (id) — Get a ticket by ID
+- **claudestory_ticket_next** (count?) — Highest-priority unblocked ticket(s)
+- **claudestory_ticket_blocked** — All blocked tickets with dependencies
+- **claudestory_issue_list** (status?, severity?) — List issues with optional filters
+- **claudestory_issue_get** (id) — Get an issue by ID
+- **claudestory_handover_list** — List handover filenames (newest first)
+- **claudestory_handover_latest** — Content of most recent handover
+- **claudestory_handover_get** (filename) — Content of a specific handover
+- **claudestory_handover_create** (content, slug?) — Create a handover from markdown content
+- **claudestory_blocker_list** — All roadmap blockers with status
+- **claudestory_validate** — Reference integrity + schema checks
+- **claudestory_recap** — Session diff — changes since last snapshot
+- **claudestory_recommend** (count?) — Context-aware ranked work suggestions
+- **claudestory_snapshot** — Save current project state snapshot
+- **claudestory_export** (phase?, all?) — Self-contained project document
+- **claudestory_note_list** (status?, tag?) — List notes
+- **claudestory_note_get** (id) — Get note by ID
+- **claudestory_note_create** (content, title?, tags?) — Create note
+- **claudestory_note_update** (id, content?, title?, tags?, status?) — Update note
+- **claudestory_ticket_create** (title, type, phase?, description?, blockedBy?, parentTicket?) — Create ticket
+- **claudestory_ticket_update** (id, status?, title?, order?, description?, phase?, parentTicket?) — Update ticket
+- **claudestory_issue_create** (title, severity, impact, components?, relatedTickets?, location?, phase?) — Create issue
+- **claudestory_issue_update** (id, status?, title?, severity?, impact?, resolution?, components?, relatedTickets?, location?) — Update issue
+
+## Common Workflows
+
+### Session Start
+1. `claudestory status` — project overview
+2. `claudestory recap` — what changed since last snapshot
+3. `claudestory handover latest` — last session context
+4. `claudestory ticket next` — what to work on
+
+### Session End
+1. `claudestory snapshot` — save state for diffs
+2. `claudestory handover create --content <md>` — write session handover
+
+### Project Setup
+1. `npm install -g @anthropologies/claudestory` — install CLI
+2. `claudestory setup-skill` — install /story skill for Claude Code
+3. `claudestory init --name my-project` — initialize .story/ in your project
+
+## Troubleshooting
+
+- **MCP not connected:** Run `claude mcp add claudestory -s user -- claudestory --mcp`
+- **CLI not found:** Run `npm install -g @anthropologies/claudestory`
+- **Stale data:** Run `claudestory validate` to check integrity
+- **/story not available:** Run `claudestory setup-skill` to install the skill