storybloq/plugin-archive/go

/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 auto -> start autonomous mode (read autonomous-mode.md in the same directory as this skill file; if not found, tell user to run claudestory setup-skill)
• /story auto T-183 T-184 ISS-077 -> start targeted autonomous mode with ONLY those items in order (read autonomous-mode.md; pass the IDs as targetWork array in the start call)
• /story review T-XXX -> start review mode for a ticket (read autonomous-mode.md in the same directory as this skill file; if not found, tell user to run claudestory setup-skill)
• /story plan T-XXX -> start plan mode for a ticket (read autonomous-mode.md in the same directory as this skill file; if not found, tell user to run claudestory setup-skill)
• /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 settings -> manage project settings (see Settings section below)
• /story design -> evaluate frontend design (read design/design.md in the same directory as this skill file; if not found, tell user to run claudestory setup-skill)
• /story design <platform> -> evaluate for specific platform: web, ios, macos, android (read design/design.md in the same directory as this skill file)
• /story review-lenses -> run multi-lens review on current diff (read review-lenses/review-lenses.md in the same directory as this skill file; if not found, tell user to run claudestory setup-skill). Note: the autonomous guide invokes lenses automatically when reviewBackends includes "lenses" -- this command is for manual/debug use.
• /story help -> show all capabilities (read reference.md in the same directory as this skill file; if not found, tell user to run claudestory setup-skill)

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

1. 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 if it exists in the project root
• Run claudestory lesson digest via Bash
• 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 project indicators exist (code, manifest, .git) -> read setup-flow.md in the same directory as this skill file and follow the AI-Assisted Setup Flow (if not found, tell user to run claudestory setup-skill)
• If no .story/ and no project indicators -> 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 -- call claudestory_lesson_digest MCP tool
6. Recent commits -- run git log --oneline -10

Step 2b: Empty Scaffold Check

After claudestory_status returns, check in order:

1. Integrity guard -- if the response starts with "Warning:" and contains "item(s) skipped due to data integrity issues", this is NOT an empty scaffold. Tell the user to run claudestory validate. Continue Step 2/3 normally.
2. Scaffold detection -- check BOTH: output contains "## Getting Started" AND shows Tickets: 0/0 complete + Handovers: 0. If met AND the project has code indicators (git history, package manifest, source files), read setup-flow.md in the same directory as this skill file and follow the AI-Assisted Setup Flow (section 1b). After setup completes, restart Step 2 from the top (the project now has data to load).
3. Empty without code -- if scaffold detected but no code indicators (truly empty directory), continue to Step 3 which will show: "Your project is set up but has no tickets yet. Would you like me to help you create your first phase and tickets?"

Step 3: Present Summary

After loading context, present a summary with two parts: a conversational intro (2-3 sentences catching the user up), then structured tables showing actionable data.

Part 1: Conversational intro (2-3 sentences)

Open with the project name and progress. Mention what the last session accomplished in one sentence. Note anything important (no git repo, open issues, blockers). Keep it brief -- the tables carry the detail.

Part 2: Structured tables (REQUIRED -- always show these, do not fold into prose)

You MUST show the following tables after the prose intro. Do not summarize them in paragraph form.

Ready to Work table -- call claudestory_recommend for context-aware suggestions. Always render as a markdown table:

## Ready to Work
| Ticket | Title                              | Phase      |
|--------|-----------------------------------|------------|
| T-001  | Project setup                     | foundation |
| T-011  | Rate agreement conditions schema  | foundation |
| T-012  | Audit trail infrastructure        | foundation |

Show up to 5 unblocked tickets. If more exist, note "(+N more unblocked)".

Decisions Pending (show only if there are TBD items in CLAUDE.md or undecided tech choices):

## Decisions Pending
- PDF generation: managed service vs pure-JS (affects T-030)
- Background jobs: Inngest vs Trigger.dev vs Vercel Cron (affects T-001)

Open Issues (show only if issues exist with status "open"):

## Open Issues
| Issue    | Title                  | Severity |
|----------|------------------------|----------|
| ISS-001  | Auth token expiry bug  | high     |

Key Rules (from lessons digest or RULES.md -- brief one-line callout, not a full list):

Example: "Rules: integer cents for money, billing engine is pure logic, TDD for billing."

First session guide (show only when handover count is 0 or 1):

Tip: You can also use these modes anytime:
  /story auto T-XXX ISS-YYY  Autonomous mode scoped to specific tickets/issues
  /story review T-XXX        Review code you already wrote
  /story plan T-XXX          Plan a ticket with review rounds
  /story design              Evaluate frontend against platform best practices
  /story review-lenses       Run multi-lens review on current plan or diff

Show this once or twice, then never again.

Part 3: AskUserQuestion

End with AskUserQuestion:

• question: "What would you like to do?"
• header: "Next"
• options:
• "Work on [first recommended ticket ID + title] (Recommended)" -- the top ticket from the Ready table
• "Something else" -- I'll ask what you have in mind
• "Autonomous mode" -- I'll pick tickets, plan, review, build, commit, and loop until done
• (Other always available for free-text input)

Autonomous mode is last -- most users want to collaborate, not hand off control.

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.

Lessons capture non-obvious process learnings that should carry forward across sessions. At the end of a significant session, review what you learned and create lessons via claudestory_lesson_create for:

• Patterns that worked (or failed) and why
• Architecture decisions with non-obvious rationale
• Tool/framework quirks discovered during implementation
• Process improvements (review workflows, testing strategies)

Don't duplicate what's already in the handover -- lessons are structured, tagged, and ranked. Handovers are narrative. Use claudestory_lesson_digest to check existing lessons before creating duplicates. Use claudestory_lesson_reinforce when an existing lesson proves true again.

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.