story-flow

Agentic Development Workflow

This workflow leverages Claude Code to automate and streamline software development, from story planning to fully tested implementation. It helps teams maintain high-quality code, complete BDD coverage, and efficient task execution.

Prerequisite

• Story readiness: The story in your story tracker (e.g. Jira, ClickUp, Azure DevOps) has been groomed, refined, and story-pointed. Acceptance criteria are clearly defined.

  💡 Stories not ready yet? Use design-flow to explore product design, establish a style guide, create UI designs, and break the feature into epics and stories collaboratively with Claude before grooming.

• Team alignment: All scrum team members understand the feature, including edge cases, error handling, and expected outcomes.

• Tool access: Every tool your project uses is installed and logged in before you start. Tools are critical for Claude to produce reliable results: they let it read the real story, design, data, and logs instead of guessing, and verify its work against the running app.

  • MCP servers, e.g. Jira, Figma, Playwright, Sentry, Datadog, Grafana. Add to project's .mcp.json, then run /mcp to log in and verify connection status.
  • CLIs, e.g. gh, glab, az, aws, sqlcmd, psql, mongosh, terraform, kubectl, docker. Confirm each is authenticated (e.g. gh auth status, az account show).

Steps

1. 🤖🧠 Create the technical story markdown
   Prompt in plan mode:
   /draft-story @path/to/story.md PROJ-123 to draft from a story tracker, or
   /draft-story @path/to/story.md "feature description" to draft from a feature description, or
   /draft-story @path/to/story.md to draft according to a plan discussed with Claude.

   The draft is a starting point—your review turns it into the technical design.

   Important:

   • Include a QA task to plan BDD scenarios.
   • Do not specify task dependencies at this stage; they will be analyzed later.
   • Include comprehensive technical details—this allows Claude to produce better, more reliable results without guessing.
   • Think first, code later. Creating the story markdown ensures the technical design exists before a single line of code is written. This reduces rework and enables smooth parallel development.

   Example:

   As a user, I want to update my profile name so that my account details are accurate.
   
   ## Requirements
   
   - Allow the user to edit their display name.
   - The display name is optional and has a maximum length of 100 characters.
   
   ## Tasks
   
   - Use qa-tester subagent to plan BDD scenarios @src/account/docs/update-profile-name.feature.
   - Use backend-developer subagent to add `displayName: String` to the user schema @src/account/schemas/user-schema.js.
   - Use frontend-developer subagent to add a Display Name input field with validation to the profile form @src/account/components/profile-form.jsx and update state management @src/account/redux/profile-slice.js.
   

2. 🤖🧠 Review the story markdown
   Prompt: /review-story @path/to/story.md PROJ-123 starting from plan mode.
   This checks the story markdown, optionally against the story in your story tracker.

   Exit plan mode to discuss the findings one at a time, incorporating or skipping each one, to refine the story markdown into a well-defined and detailed technical design.

3. 🤖 Analyze task dependencies
   Prompt: /analyze-tasks @path/to/story.md starting from plan mode.
   This identifies tasks that can be executed in parallel and updates the story markdown accordingly.

4. 🧠 Create the technical design pull request — the review that matters most
   Open a PR with the story markdown and discuss requirements, planned tasks, and the execution plan with the team before any code is written.

   💡 Why now? Shift-left: a wrong approach caught here costs a review comment; caught after implementation it costs the implementation. Use junior-flow /learn-story-flow technical-design to explore why design PRs reduce rework.

   Important:

   • Don't rush this review or take it lightly. Bounce ideas around and challenge the approach until the team agrees on the design.
   • Include alternatives considered and open questions for reviewers.
   • Designs evolve; update the story markdown when implementation diverges.

5. 🤖 Implement the story
   Prompt: /implement-story @path/to/story.md in auto mode.
   Executes tasks according to the plan in loops until the acceptance criteria are met. Each task is delegated to a subagent running in an isolated context, keeping the orchestrator lightweight so it can handle larger stories without exhausting its context window. Tasks previously analyzed as independent will be implemented in parallel.

6. 🧠 Review implementation
   In parallel with step 7 to save time: review while the scenarios execute.
   Check code, unit tests, and BDD scenarios for:

   • Code quality
     • Zero lint errors or warnings (e.g. ESLint)
     • Zero type errors (e.g. tsc --noEmit, mypy)
     • No function exceeds the project's cyclomatic or cognitive complexity threshold (e.g. ESLint complexity, SonarQube, radon, gocyclo, PMD)
     • No duplicated code blocks (e.g. jscpd, SonarQube)
     • No unused exports, files, or dependencies (e.g. knip, ts-prune)
     • No new high or critical dependency vulnerabilities (e.g. npm audit)
   • 100% test coverage
   • Full BDD coverage (positive, negative, edge cases)
   • Test assertions match their descriptions (tests actually verify what they claim to test)
     • No surviving mutants in changed code: tests fail when the logic is altered (e.g. Stryker, PIT, mutmut, cargo-mutants)

7. 🤖🧠 Execute BDD scenarios
   Prompt: /execute-scenario SCN-01 @path/to/file.feature in auto mode.
   Executes the BDD scenarios directly in the browser without coding. Confirm all scenarios pass, or skip to step 8 to execute and record in one pass if confident about the scenarios.
   The first argument accepts a single scenario, a comma-separated list, an inclusive range such as SCN-01..SCN-10, or all.

8. 🤖 Recommended: Generate a Playwright script
   Prompt: /execute-scenario all @path/to/file.feature --record in auto mode.
   Generates a Playwright test script that can be run efficiently without Claude for regression testing.

   Troubleshoot Recording Issues
   If the recording produces unreliable or incomplete Playwright tests, try the following (in order):

   1. Make BDD steps more specific
      Clarify intent and expected outcomes so Claude doesn’t need to infer behavior.
   2. Add stable UI selectors
      Prefer explicit identifiers such as accessibilityId, data-testid, or similar attributes on key elements.
   3. Add domain knowledge to Claude skills (last resort)
      If ambiguity remains, extend Claude with relevant domain context via custom skills.

   After applying any of the above, simply regenerate the Playwright test cases.

9. 🧠 Create the final pull request
   Share the fully tested implementation with the team.

   Recommended: Prepare the pull request for review
   Prompt in auto mode:
   /prepare-implementation-review to prepare the current branch's PR, or
   /prepare-implementation-review 123 @path/to/story.md to prepare a PR by ID, with an optional story markdown for requirement traceability, or
   /prepare-implementation-review <package PR URL> <app PR URL> to prepare one story split across repositories together.

   Helps reviewers by posting comments and evidence on the pull requests. Run it again after pushing changes: it updates its earlier comments and resolves the ones that no longer apply.

Outside the Workflow

• Triage failed scenarios in recorded Playwright specs
  Prompt in auto mode:
  /triage-failed-scenarios --grep "SCN-01:|SCN-02:" to triage specific scenarios, or
  /triage-failed-scenarios "failed scenarios in <issue URL>" to triage the failures listed in an issue raised by a regression pipeline.

  Keeps the regression suite autonomously maintained: deletes the scenario if the behaviour was removed, updates the steps and re-records if it changed intentionally, re-records if the spec is stale, or reports a defect for human review if the app no longer meets the story.

  Recommended: Run it from a regression pipeline
  Have the pipeline that runs the recorded specs raise an issue listing the failed scenarios and linking the run, then start a triage job when the run fails. The job can launch Claude Code headless with a command that:

  1. Runs /triage-failed-scenarios "failed scenarios in <issue URL>".
  2. Comments the triage summary on the issue, mentioning the team only when a scenario is reported as a defect, and labels the issue as triaged.
  3. Opens a draft pull request referencing the issue when the triage changed any files, so stale scenarios are fixed through review.

• Retrofit BDD scenarios
  For code written without scenarios. Prefer planning them from the story — retrofitted scenarios describe what the code does, bugs included, not what it should do.
  /retrofit-scenarios @path/to/file.feature "feature description", or
  /retrofit-scenarios @path/to/file.feature @path/to/source1 @path/to/source2/*

Extension

Extend the workflow with your own domain knowledge by adding custom skills.
Each skill must follow the exact naming convention so the agent can discover and use it.

Example:

• .claude/skills/review-story-against-ticket/SKILL.md
• .claude/skills/analyze-task-dependencies/SKILL.md
• .claude/skills/implement-story-markdown/SKILL.md
• .claude/skills/plan-bdd-scenarios/SKILL.md
• .claude/skills/execute-bdd-scenario/SKILL.md
• .claude/skills/prepare-implementation-review-comments/SKILL.md

Installation

Add this marketplace to Claude Code:

claude plugin marketplace add Intai/story-flow

Browse and install plugins:

/plugin

Environment Variables

BASE_URL selects the environment to run against. The project's playwright.config.js reads it into use.baseURL with a local default, so scenarios and recorded specs navigate with relative paths (page.goto('/settings')) and one spec runs unchanged against dev, QA, staging or production. Skip starting the local dev server when it points at a remote host:

const baseURL = process.env.BASE_URL ?? 'http://localhost:3000'
const isRemote = !baseURL.includes('localhost')

export default defineConfig({
  use: { baseURL },
  ...(isRemote ? {} : { webServer: [{ command: 'make dev-bg', url: baseURL }] }),
})