agentleFS
renzrollonrenzrollon/shippable-skills/skills/productivity/product-spine/SKILL.md

product-spine

Skill7 starsChanged 26 days agoMITView on GitHub

Help an engineer act as product owner: suggest parallel work threads (features, improvements, fixes) from the repo, then draft, review, and capability-check the one-pager, epics, and briefs that land them. Writes artefacts, never code. Answers "can the platform do X?" from the project's own primer.

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 9 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Bare invocation runs threads, this turn, with no question: If the invocation has no arguments (bare /product-spine) or the only argument is …

    line 16
  2. Distinctive:

    Never block on I/O: Every read, list, and write in this skill is best-effort.

    line 89
  3. Very specific:

    Lo-fi first: Never generate a hi-fi mockup.

    line 93
  4. Very specific:

    Never write Status: ready or ready-to-propose in this mode.

    line 115
  5. Distinctive:

    Read or list, each once:

    line 219
  6. Distinctive:

    Do not invent a fourth context path.

    line 232
  7. Distinctive:

    Read references/threads-mode.md and follow it.

    line 237
  8. Very specific:

    Read references/draft-mode.md for question ladders, write paths, and "write this turn" rules.

    line 247
  9. Very specific:

    Read the named file once. Run the matching checklist.

    line 254
  10. Very specific:

    Do not edit the file, and do not flip Status.

    line 255
  11. Distinctive:

    No implementation step list and no acceptance checkboxes (wrong artefact: a Missing item).

    line 268
  12. Distinctive:

    Every §4 initiative maps to a §3 bet.

    line 287
  13. Very specific:

    Read platform-primer.md and capability-gaps.md once each (golden-path files if present: extra colour, not a second source of "can we").

    line 299
  14. Distinctive:

    Cannot confirm: no primer on disk.

    line 306
  15. Very specific:

    If no primer: Answer: Cannot confirm, name docs/product/context/platform-primer.md, offer the skeleton, stop asserting.

    line 314
  16. Distinctive:

    Never invent metrics, capabilities, or platform vocabulary.

    line 335
  17. Distinctive:

    Never block on I/O: unavailable, once, no retry, no alternate-path guessing.

    line 340

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Bare invocation runs threads, this turn, with no question. If the invocation has no arguments (bare /product-spine) or the only argument is threads, you are already in threads mode: do not ask "which mode?", do not print a mode menu, do not wait for confirmation. Go straight to Step 2, gather, and output the mermaid ## Thread map with cards before you stop. Only an explicit draft, review, or capability argument (or its natural-language equivalent) selects another mode. A bare invocation is never a prompt to disambiguate.

Help an engineer act as product owner. Default is threads: look at the repo, fan out read-only gathers, and propose several next pieces of work (features, improvements, fixes) on a mermaid map. Picking a thread lands it on the product spine: a live one-pager (strategy), epics (features in flight, each named against a strategy bet), and briefs (what / why for a change proposal). Three paths:

  • docs/product/one-pager/current.md
  • docs/product/epics/*.md (sibling folder docs/product/epics/<slug>/)
  • docs/product/briefs/*.md
one-pager   docs/product/one-pager/current.md
            §3 strategy bets · §4 roadmap initiatives
                ^
                |  Ladders to: ... §4 <initiative heading>
epics       docs/product/epics/*.md
            features in flight, each named against a bet
                ^
                |  Part of: <epic path>
                |  or Ladders to: the one-pager initiative (no epic yet)
briefs      docs/product/briefs/*.md
            what / why / ladder / primer for a change proposal

Cite the heading text on ladder lines, not only a section number, so a project template with other numbering still greps. This skill is host-neutral: it runs on Cursor, Copilot, Codex, Claude Code, and any other Agent Skills host. It does not name a vendor agent, a platform product, or a host slash for executing work. Call the Task tool for fan-out (or the host's equivalent subagent tool). Do not Call the Skill tool with another user-invoked skill.

Threads are chat-only until the user picks one. Draft writes a file plus a short chat reply. Never re-dump the file into chat.

Templates, Status, threads fan-out, and draft question ladders live in references/. Org-specific platform vocabulary lives in docs/product/context/ if the project supplied it; this skill never invents it. See references/context-folder.md.


Firm rules (non-negotiable)

  1. Never writes code and never edits outside docs/product/**. Never write openspec/changes/**. A request to implement gets a one-line refusal pointing at the brief (or epic): this skill's job is the artefact, not the implementation. If the turn asks to implement (in src/, a patch, a function, "then build it"), refuse and stop. Do not draft-and-then-code in the same turn. Threads mode writes no files.
  2. Never invents metrics, baselines, capabilities, or platform vocabulary. Absent input is stated as absent (baseline: unknown, primer absent, thin), never filled in.
  3. Decisions live inline (brief §4, epic §5, one-pager §1 change log). No separate decisions log, no ADR, no threads file on disk.
  4. New briefs and epics are always saved Status: draft. This skill never flips a file to ready or ready-to-propose. Review reports whether the user could.
  5. One question per turn in draft mode, capped per artefact. Inline context counts as answered (including a picked threads card), never re-asked. Empty-handed is fine: start the ladder. When the remaining fields have a legal TBD / unknown form and the required ones are present, write the file this turn instead of blocking.
  6. Never block on I/O. Every read, list, and write in this skill is best-effort. If a call is denied, errors, or the file is absent, treat it as unavailable and proceed immediately from what you already hold. Do not retry a denied or failed call, and do not guess alternate paths for it.
  7. Lo-fi first. Never generate a hi-fi mockup. Point at the epic's sibling folder (docs/product/epics/<slug>/mockups/) for a lo-fi mockup. Do not create mockup files.
  8. Threads cite evidence (paths on disk) or mark Confidence: thin. Fan-out subagents are read-only. The visual is a mermaid diagram in chat, not a vendor canvas.

Output contract (non-negotiable)

Downstream greps these strings. Keep the parsed tokens exact.

Threads reply (no file write) always includes:

  • a fenced mermaid diagram (language tag mermaid)
  • ## Thread map and ## Threads
  • at least one of Feature, Improvement, Fix as a kind label
  • numbered cards starting at 1.
  • a closer telling the user to pick a number to draft, or name review / capability

Never write Status: ready or ready-to-propose in this mode.

Draft file (brief or epic) always contains Status: draft and exactly one of Part of: / Ladders to:. Never write Status: ready or ready-to-propose. A brief also has Suggested change: (kebab-case).

Draft chat reply (do not paste the file body) always includes:

  • the path written
  • the line Status: draft
  • the Part of: or Ladders to: line copied verbatim
  • exactly one open item
  • for a brief: tell the user to pass this path to their change-proposal skill (do not Call that skill)

Review reply is the block only:

## Review: <path>

**Strong**
**Missing**
**Ladder**
**Platform pieces**
<ready line>
**Next step**

Ready line is exactly one of:

  • brief: **Ready to propose: yes** or **Ready to propose: no** (<reason>)
  • epic: **Ready to flip: yes** or **Ready to flip: no** (<reason>)

Omit it for a one-pager. Next step is exactly one item. Put the yes/no inside the bold label so the greps Ready to propose: no and Ready to flip: no match.

Capability reply is the block only:

**Answer**: Yes today | No today | Partly | Cannot confirm
**From the primer**
**Nearest alternative that works today**
**Gap to record**

Gap to record is a proposed one-line entry for capability-gaps.md. Do not write that file unless asked. With no primer on disk, Answer is Cannot confirm, name the missing path docs/product/context/platform-primer.md, and assert nothing else (no Yes today, no invented alternative). Offer the skeleton in references/context-folder.md.


Input

Arg / modeMeaning
(none) or threadsEngineer-as-PO: fan out, mermaid map, numbered threads. No file write.
draft one-pager / draft epic / draft briefWrite that artefact. draft task maps to draft brief.
draft N / land NDraft the Nth card from this conversation's threads reply.
review <file>Read-only checklist on that path.
capability "<question>"Can the platform do this today, from the primer only.

Natural language maps to the same modes: "what should we build next" / "suggest features" (threads), "draft an epic for X" (draft epic), "draft a brief for Y" / "draft a task for Y" (draft brief), "review docs/product/briefs/foo.md" (review), "can users retry a payment?" (capability). These phrasings are invocations of this skill, not free-form PM chat.


Steps

0. Mode and code gate (before any write)

Parse the mode from the args or the natural-language map. If the turn asks for implementation (code, a patch, src/, "then implement", "build it"), make no code edits. Reply in one line that this skill writes the artefact, not code, point at the brief path if one exists, and stop. Skip later steps.

  • draft / review / capability when those words (or their map) are present, including draft N after a threads reply.
  • Otherwise (no args, bare /product-spine, threads, "what's next", "suggest features"): run threads now, this turn. Never reply with a mode menu or a "which mode?" question: bare invocation is threads, not a prompt to disambiguate. Gather (fan-out, or sequential if the host has no subagent tool), then emit the mermaid ## Thread map and cards. Empty-handed still emits a map, marked thin. Do not list modes and stop.

1. Gather

Threads: skip a parent-only crawl. Follow references/threads-mode.md: Call the Task tool 2 to 4 times in one turn (Spine, Surfaces, Friction). If the host has no subagent tool, run those briefs sequentially this turn.

Draft / review / capability: best-effort, one plain command per call, literal paths: no $HOME / ~ expansion, no for loops, no ;-chaining. Skip any call that is denied, errors, or is absent, the first time. State which inputs are absent.

Read or list, each once:

  • docs/product/one-pager/current.md (and docs/product/one-pager/TEMPLATE.md if present: then use that file's headings and numbering)
  • list docs/product/epics/*.md
  • list docs/product/briefs/*.md
  • directory names under openspec/changes/ (absence is fine; do not write)
  • docs/product/context/platform-primer.md
  • docs/product/context/capability-gaps.md
  • list docs/product/context/golden-path/*.md
  • this skill's references/*.md (resolve relative to this skill directory)

Do not invent a fourth context path. Golden Path docs are optional; if the folder is missing, say so and continue.

2. Threads mode

Read references/threads-mode.md and follow it. Synthesize 4 to 8 cards mixing Feature / Improvement / Fix (fewer if evidence is thin, at least two). Each card: kind, title, need, evidence paths, artefact (brief or epic), ladder, grounded or thin.

Emit the Thread map mermaid (subgraphs now, next, later) then the cards, then the pick-to-draft closer. Write nothing to disk.

3. Draft mode

Read references/draft-mode.md for question ladders, write paths, and "write this turn" rules. Always Status: draft. Exactly one of Part of: / Ladders to:. A picked threads card counts as inline context.

4. Review mode (read-only, never edits)

Read the named file once. Run the matching checklist. Emit the Review block. Do not edit the file, and do not flip Status.

Brief

  • Status line present.
  • Exactly one ladder line, and its target exists on disk (epic file, or a §4 heading in current.md whose text matches).
  • Suggested change: is kebab-case.
  • §1 names who, friction, outcome.
  • §2 uses primer vocabulary and invents nothing (flag invented platform words; if primer absent, §2 must say so).
  • §3 names In and Out (not only TBD) for ready-to-propose.
  • §4 records a trade-off or says none.
  • No implementation step list and no acceptance checkboxes (wrong artefact: a Missing item).
  • Optional Change:: if present, the matching openspec/changes/<slug>/ folder may exist (claimed but absent is Missing, not a write).

Epic

  • Ladder to a real §4 heading in current.md.
  • Three-line problem.
  • Out of scope named.
  • §4 brief list versus docs/product/briefs/*.md that claim Part of: this epic.
  • Sibling folder docs/product/epics/<slug>/ present (missing is a Missing item, not a write).

One-pager

  • Sections present (or the project's TEMPLATE headings).
  • §2.3 metrics carry a baseline or unknown.
  • Every §4 initiative maps to a §3 bet.
  • §1 has dated entries.
  • Orphaned epics: an epic Ladders to: a heading that no longer exists.

Ready-to-propose (brief): yes only if the checklist is clean enough that the user could set Status: ready-to-propose. Ready-to-flip (epic): yes only if the user could set Status: ready. Otherwise **Ready to propose: no** or **Ready to flip: no** with a reason. Next step: exactly one action the user can take.

5. Capability mode

Read platform-primer.md and capability-gaps.md once each (golden-path files if present: extra colour, not a second source of "can we"). Classify the question:

  • Yes today: the primer describes it as available.
  • No today: the primer does not, or it names the gap.
  • Partly: the primer covers some of the asked behaviour.
  • Cannot confirm: no primer on disk.

Cite the primer section under From the primer. When No today, give the Nearest alternative that works today from the primer, or from capability-gaps.md if the primer is silent on an alternative. Propose a Gap to record one-liner if the question exposes an unrecorded gap. Do not write capability-gaps.md unless asked.

If no primer: **Answer**: Cannot confirm, name docs/product/context/platform-primer.md, offer the skeleton, stop asserting.

6. Chat reply

  • Threads: Thread map, mermaid, numbered cards, pick-to-draft closer. No file dump.
  • Draft: path written, Status: draft, the ladder line, one open item (briefs: also the change-proposal closer). Never re-dump the file.
  • Review: the Review block only.
  • Capability: the capability block only.
  • Refusal (code gate): one line, contains artefact and that this is not code. No code fence, no export function, no implementation patch.

Rules

  • Artefacts only, never code, never outside docs/product/**, never openspec/changes/**.
  • Threads write no files; they cite evidence or thin.
  • Never invent metrics, capabilities, or platform vocabulary.
  • Decisions inline; no decisions folder; no threads folder.
  • New work is Status: draft; the user flips to ready-to-propose (brief) or ready (epic).
  • One draft question per turn; inline context counts; empty-handed is fine.
  • Never block on I/O: unavailable, once, no retry, no alternate-path guessing.
  • Lo-fi pointer only; do not generate mockups.
  • Visual is mermaid in chat, not a vendor canvas.
  • Host-neutral: Task tool for fan-out, no host-only execute slashes.

Related

  • Threads (fan-out, mermaid, cards): references/threads-mode.md
  • Draft question ladders: references/draft-mode.md
  • One-pager template: references/one-pager-template.md
  • Epic template: references/epic-template.md
  • Brief template: references/brief-template.md
  • Ladder and Status: references/ladder-and-status.md
  • Context folder: references/context-folder.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.