A Claude Code plugin that turns "figure out what to build" into a structured process. Describe a problem and storytime assembles a team of domain-expert personas who discuss it, investigate the code, debate tradeoffs, and produce a plan — grounded in your actual codebase.
The output is a plan with code citations (file:line), ASCII diagrams,
numbered decisions with rationale, non-goals, measurable success criteria, and
effort estimates (Complexity + Scale, never time).
Storytime makes the spec process interactive, code-grounded, and fast.
Domain-expert lenses, not characters. They provide structured perspectives that ensure the plan considers all relevant dimensions.
| Archetype | Perspective | What they ask |
|---|---|---|
| OWNER | Wrote the code, knows where everything lives | "This touches X, which depends on Y..." |
| OPERATOR | Runs it in prod, wants observability | "What's the kill switch? How do I monitor this?" |
| DOMAIN | Deep expertise in the problem area | "The standard approach for this is..." |
| SYSTEMS | Knows the runtime, infra, failure modes | "At scale, this will bottleneck at..." |
| PLATFORM | Knows the product, users, business case | "Users expect... The business needs..." |
| SKEPTIC | Challenges assumptions | "Do we actually need this? What if we don't?" |
| CRITIC | Code quality, DRY, optimization | "This duplicates X — extract a shared abstraction" |
| EDUCATOR | Knowledge gaps, comprehension, audience | "A reader won't know what X means — let me unpack that" |
The default core is OWNER, OPERATOR, CRITIC — what you get if you don't specify. Defaults, not mandates — collapsible like everything else. Team size is sized to the project, not fixed. Tiny problem → tiny team. Bias small. Hard ceiling 12 (override required). Duplicate archetypes are allowed — two SYSTEMS personas can cover different facets (one on database perf, one on networking). They should complement, not echo. Productive tension between same-archetype personas is a feature.
Cohort personas persist across sessions — they accumulate context and remember past decisions. Specialists are temporary, recruited for a specific problem.
Personas should have texture: background quirks that inform their perspective,
opinions and biases that make them useful lenses, a communication style you'd
recognize. Codenames are non-human by default — concept words like
anchor, lattice, kestrel, ember, forge. Personas are lenses, not
people; codenames keep the lens primary. Human names only when you pick them.
When you see @critic [lattice] you should already know the flavor of what's coming.
At every leg of the process — phase, breakout, buildout slice — one persona drives. The driver writes the artifact and owns the recommendation. The other personas are in the room but stay silent unless their perspective is both useful AND non-distortive: they catch a missing constraint, ground a loose claim, correct a factual error. Otherwise, silence is the right answer. Round-robin commentary is the failure mode this rule prevents. Supporters who never spoke up are still recorded — their silence means the driver's lens covered the territory cleanly.
@operator is this safe to deploy without a kill switch?
@critic [forge] can we reuse the existing retry logic here?
@critic:architecture is the boundary here correct?
@team what did we decide about the cache TTL?@role is a lens directive, not just a skill trigger. Use it inline
in any conversation — the model applies the role’s perspective without
launching a formal skill. For context-loaded answers that need persona
history + decision log lookup, use /storytime-qa explicitly.
You are a persona too. @user [codename] is a first-class lens with its own
cohort/_user.md file, accumulated context, and lens distribution tracked over
sessions. You can drive decisions, be a supporter, originate prompt-yield
documents (complex asks the cohort hydrates into structured artifacts), and
have your own intent history at .storytime/intents.md. Storytime doesn't
treat your input as instructions to a tool — it treats your input as one
voice in the room.
# Permanent install
$ claude install-plugin ~/workspace/storytime
# Or per-session
$ claude --plugin-dir ~/workspace/storytime/storytime "our public API has no rate limiting, scrapers are hammering /search at 200 req/s"Be specific. Context drives quality. See a full walkthrough →
SURVEY — explores codebase, presents artifact inventory.
ASSEMBLE — proposes 3-7 personas. You can adjust.
ICEBREAKER — team discusses status quo, identifies sub-problems.
BREAKOUT — parallel deep dives with 2-3 personas each.
PAUSE — summary cards per breakout. Proceed, dig in, revise, or add more.
CONVERGE — full team merges findings into a plan.
REVIEW — plan presented to you. Challenge, revise, or approve.
BUILDOUT — implement the plan. Persona-driven pair programming with trace docs.
Invoke with /storytime-buildout after plan approval.
Storytime is a continuity system. The spec workflow is one surface on a deeper consolidation loop: context → consolidation events → document structure → continuity across compactions, sessions, and time.
Consolidation fires at six scales: phase (phase boundary), commit (LLM-drafted + user-confirmed), nap (model detects 1 degradation signal), shift (2+ signals or framing loss), session (DONE or walk-away), compact (approaching context budget).
Remembrance (/storytime-remember) is the handoff mechanism.
A workday-shaped wakeup document + consolidation prompt, staged before
/compact and loaded as the first action post-compact. It tells the
re-engaging model exactly what to load and where the work was.
Decisions are not narrative bullets — they're nodes in a typed DAG.
Each decision (e.g., RATE-001) lives in its topic's _thread.md, pins to
the commit that sealed it, and can carry edges to other decisions via
parent:, tensions:, and cross-topic Callout-> / Callout<- sigils.
Cross-topic references use callouts so a decision in auth-refactor can
reference one in rate-limiting without copying content. Forward callouts
(Callout->) are authoritative; reverse callouts (Callout<-) are
lint-cached. Closed 5-kind vocabulary: depends-on, affects,
supersedes, superseded-by, related.
The graph is queryable via shell scripts — no graph DB, just grep over existing artifacts:
# All sealed decisions across topics
./scripts/intent-graph-query.sh list_nodes
# Decisions sealed but not yet realized in code
./scripts/intent-graph-query.sh get_unrealized
# Walk the parent chain from any decision
./scripts/intent-graph-query.sh get_path RATE-003
# Decisions referenced as parent but missing from any thread
./scripts/intent-graph-query.sh get_orphans
# Sealed-vs-realized grid per topic
./scripts/intent-adherence.sh rate-limitingThe graph is read-side in v1.0.1. Write-side mutations are still hand-edits to frontmatter. Composition (distillation, naming — surfacing unnamed parent intents from clusters of children) lands in v1.2+.
Sessions are episodes of an ongoing story. The thread
(_thread.md) is the continuity ledger — decisions, consolidation
log, open questions. When you revisit a topic, remembrance or warm-start
carries the context forward.
# See recent threads, auto-resume incomplete ones
/storytime
# Or go directly to a topic
/storytime rate-limitingThreads auto-checkpoint at every phase boundary and consolidation event.
If your session is interrupted or /compact fires, the next invocation
picks up from the checkpoint. No explicit save needed.
Every technical claim must be grounded. Personas use the strongest available evidence:
| Source | Format | When |
|---|---|---|
| Code | src/auth.ts:32 | Runtime behavior |
| Repo files | docs/api-design.md:15 | Project intent |
| Library docs | [redis.io/commands/...] | External system behavior |
| Git | commit abc123 | What changed and when |
| Standards | RFC 6585 §4 | Protocols and specs |
| Web | [url] | Benchmarks, CVEs, blog posts |
Evidence hierarchy: Code > Git > Repo files > Library docs > Standards > Web. Ungrounded claims get challenged: "can you ground that?"
Complexity (how hard) uses a Fibonacci scale. Scale (how big) uses 1-5. Both always stated with prose. Never time estimates.
| Complexity | What it means | Human analog |
|---|---|---|
| 1 | Single-file, single-concept | Quick fix |
| 2 | Few files, one system | Straightforward |
| 3 | Multiple files, one system | A morning |
| 5 | Cross-system | Solid day |
| 8 | Architectural | Multi-day |
| 13+ | Foundational | Must decompose |
Scale: 1 (file) → 2 (module) → 3 (services) → 4 (users) → 5 (ecosystem)
Full workflow. Use for features, architecture decisions, investigations.
Focused investigation: one driver + 1-2 silent supporters.
Merge breakout results into a unified plan.
Implement the plan. Persona-driven pair programming with trace docs.
Suggests /storytime-retro at completion to close the feedback loop.
Reconvene team: plan vs what was built. Includes evaluation scorecard.
Formal queries to personas with context + decision-log loading. For casual
@role lens directives, the model responds inline without this skill.
One-shot spawning-pool voice. Ephemeral — no files, no state.
Team handles PR review comments with proposed responses.
Manage personas: list, hire, fire, bench, evolve, promote.
Stage remembrance for /compact. Tiers: nap (quick), shift (frame change),
compact (full handoff). Model-invoked or explicit.
Mechanical + reasoning-tier validation against process rules. Two tiers: scripts for grep, estimator agent for prose parsing.
Standalone codebase survey with artifact inventory and fingerprint.
Dashboard: cohort, threads, decisions, tutorial progress, citations.
Initialize .storytime/. Storytime-native, adapt-in-place, or export-only.
Organize, archive, roll up documents, backfill timestamps.
Team reads and discusses existing docs or code.
Convert output to ADRs, GitHub issues, Linear tickets, Kiro specs.
Revert at any granularity: phase, episode, thread, specific file.
/storytime and resume./storytime-remember before expected /compact. Remembrance carries state forward.@role inline. It's a lens directive, not a formal skill trigger.Full rules, formats, and config: Reference →