agentleFS
MostAshrafMostAshraf/ai-sdlc-harness/skills/story-workflow/SKILL.md

story-workflow

Skill20 starsChanged 3 months agoMITView on GitHub

Refine, analyze, improve, and groom user stories / work items for quality — readiness reports, template restructuring, adaptive gap-filling, and codebase-aware technical grooming. USER-ENTRY and HUMAN-ONLY — invoke only when the user explicitly runs /story-workflow <command>; never autonomously from conversation, never from a subagent (guard-enforced). Distinct from the /dev-workflow pipeline: this shapes the story itself, it does not build it.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. haowjy/creative-writing-skills★ 590same name
    2. bpappin/skills★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

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

    Every harness call is ${CLAUDE_PLUGIN_ROOT}/bin/harness <verb> … — the full path, run by you via Bash (a bare harness is not on PATH, and …

    line 19
  2. Distinctive:

    Never invent business requirements.

    line 70
  3. Distinctive:

    If a story is already well-formed, say so.

    line 75

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

story-workflow — story-quality refinement (PO-facing)

Improves work-item quality through four commands. Read-mostly: it fetches a work item, helps shape it, and — only with the user's consent — posts the result back as a comment. It never starts a dev run and never touches ai/<run>/ run state.

Every harness call is ${CLAUDE_PLUGIN_ROOT}/bin/harness <verb> … — the full path, run by you via Bash (a bare harness is not on PATH, and shell variables set in one Bash call do not persist to the next). Non-zero exit = refused; read the JSON error and act on it.

Usage

/story-workflow <command> <work-item-id> [session-notes…]

<command> is one of analyze, refine, improve, groom. <work-item-id> is whatever the configured provider uses — a number (ADO / GitHub / GitLab), a key (PROJ-123, Jira), or, for local-markdown, the story's id (the file stem inside provider.stories_dir, e.g. WORK-7 for WORK-7.md — not a path). Any trailing tokens are session notes, passed through to improve and refine.

Routing

commandfileone-line
improvecommands/improve.mdadaptive single-pass: assess → gap-fill → draft (the recommended default)
analyzecommands/analyze.mdstandalone readiness report with flags
refinecommands/refine.mdslow, section-by-section interactive restructure
groomcommands/groom.mdcodebase-aware per-repo technical notes

Parse $ARGUMENTS: the first token is the command, the second is the work-item id, the rest are notes. If the command is missing or unknown, print the usage line plus the table above and stop — do not guess. If the id is missing, ask for it — never proceed without one. Then read the one matching command file and follow it (context economy: load a single command file, not all four).

Before routing

  1. Confirm the workspace is bootstrapped: .claude/context/provider.yaml must exist. If it doesn't, /init-workspace never ran — send the user there and stop. The active provider is resolved from config by the harness; you never hand-pick it.
  2. The recipe for fetching a work item and posting a result back — for every provider and both transports — lives once in shared/provider-io.md. Read it; the commands cite it instead of repeating it.
  3. Domain and convention context (for improve and groom) lives once in shared/context.md.

Guardrails (all four commands)

  • On a remote provider, never edit the item's Description or Acceptance-Criteria fields — post back as a comment only. The single exception is a local-markdown story the user explicitly asks you to rewrite in place; see shared/provider-io.md.
  • Never invent business requirements. A gap is a question for the human, not an assertion of what "should" be there.
  • Mirror the user's domain language; don't rename their "platform" to "system".
  • Files in templates/ are read-only references — don't modify them while a command runs.
  • If a story is already well-formed, say so. "This looks ready" is a valid, valuable outcome — don't manufacture flags or questions to look busy.

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.