SSDET Workflow Framework

Getting Started

Development Workflows

Set up the development pipeline and run your first structured workflow.

What Is This?

The development pipeline turns Claude Code into a systematic engineering agent that executes structured, multi-phase delivery from ticket to tested PR — with every decision traced and every phase verified.

After setup, you'll have slash commands for three development workflows: /bug-fix, /feature-enhance, /feature-build — plus a smart classifier (/sdet) that picks the right one for you.

Prerequisites

  • Claude Code CLI installed and authenticated
  • A repository with build and test tooling (the generator detects these automatically)
  • Optional: Jira MCP integration (enables Jira ticket classification in /sdet; text-based classification works without it)

Setup

1

Copy the framework into your repo

Copy the .claude folder into the root of your repository. This folder contains:

  • commands/generate-development-workflows.md — dev workflow generator
  • workflow-generator/ — dev workflow phases and 35+ templates
bash
# From the framework source
cp -r .claude /path/to/your-repo/.claude
2

Open Claude Code in your repo

Navigate to your repository root and launch Claude Code. It will automatically detect the .claude/commands/ directory and make the generators available as slash commands.

bash
cd /path/to/your-repo
claude
3

Generate development workflows

The dev generator scans your repo — language, test runner, build tools, Jira, feature flags — and produces tailored workflow files.

bash
/generate-development-workflows

The generator runs a 3-phase process:

  1. aSURVEY — Deep investigation of your repo: reads manifests, build configs, entry points, and test configs fully (no truncation). Traces the initialization chain, maps cross-package dependencies for blast-radius analysis, detects override/extensibility mechanisms, and catalogs every module by name. Works with any tech stack.
  2. bGENERATE — Uses the deep survey data to fill templates and produce all workflow files. Also generates CODEBASE_INSIGHTS.md — the enterprise context document that gives every workflow agent full situational awareness of the repo.
  3. cVALIDATE — Cross-references all generated files for completeness: no leftover {{slots}}, all signals handled, all phase prompts present. Also runs a quality check on CODEBASE_INSIGHTS.md.

What gets created

After generation, your .claude/ folder will have new commands/ entries (bug-fix.md, feature-enhance.md, feature-build.md, and companions) plus bug-fix/, feature-enhance/, feature-build/ directories. Each workflow directory contains 3 core files: RULES.md (universal rules), KEY_PATHS.md (directory map for code-tracing phases), and TEST_HELPERS.md (E2E lifecycle & test-ring mapping for test phases). The orchestrator selectively loads only the files each phase needs.

What the survey investigates

The SURVEY phase deeply investigates your repo — reading config files fully (not truncating), tracing entry points, and mapping dependencies. It works with any tech stack (JS, TS, Python, Go, .NET, Java, Rust, Ruby, PHP):

  • Language, framework, package manager, monorepo structure
  • Build & bundle config — path aliases, shared dependencies, entry points
  • Initialization chain — providers, middleware, DI in execution order
  • Override/extensibility mechanism and resolution order
  • Cross-package dependency graph for blast-radius analysis
  • Test infrastructure — full config, commands, path mappings, coverage thresholds
  • Feature flags, Jira integration, analytics, i18n
  • All modules/components/hooks listed by name (never just counts)

CODEBASE_INSIGHTS.md — enterprise context for workflow agents

The generator produces a deeply investigated CODEBASE_INSIGHTS.md — the enterprise context document that gives every workflow agent full situational awareness. It's shared across all workflows (bug-fix, feature-enhance, feature-build) and each section is purpose-built for what the agents actually need:

  • Architecture overview — framework with versions, build system details, path aliases, shared dependency boundaries
  • App/package descriptions — every component, hook, and service listed by name (not counts)
  • Entry points & bootstrap — complete initialization chain with every provider/middleware listed by name
  • Test infrastructure — full config details (path mappings, coverage thresholds, commands)
  • Dependency graph & blast radius — which packages depend on which, most-imported shared files
  • 8–12 real import examples — covering hooks, contexts, components, utils, config, and base framework

Every workflow's RECALL phase reads this file so it doesn't have to re-discover your repo's structure. The LEARN phase writes back new discoveries so the file gets richer with every run. Run /refresh-insights to re-survey and regenerate without re-running the full generator.

4

Start using development workflows

You now have slash commands for all development workflows. Here are the most common commands:

Universal entry point

bash
/sdet "Login button returns 500 error"
/sdet PROJ-123 --pr
/sdet PROJ-123 --jira-check
/bug-fix --qe-review          # audit test coverage after discovery
/feature-build --qe-run       # re-run full QE gauntlet after implementation
/bug-fix --pr-only            # create commit + PR from a completed workflow

Pick a workflow directly

bash
/bug-fix "Login button returns 500"
/feature-enhance "Add dark mode to settings"
/feature-build "Implement SSO authentication"

What Happens During a Workflow

When you run a workflow command, Claude Code executes a multi-phase state machine. Each phase reads upstream documents, does its work, writes an output document, and emits a signal to advance. You'll see files appear in your repo as it progresses:

State fileBUG_FIX_STATE.md

Tracks current phase, attempt number, and history. This is the single source of truth for progress.

Phase documentsbug-fix-docs/

One document per completed phase (INTAKE.md, DIAGNOSIS.md, etc.). Each captures decisions and outputs.

Knowledge storesKNOWLEDGE_BASE.md

Updated at the end of each workflow. Captures patterns and insights so future workflows are smarter.

Final output--pr

The CLOSE phase posts an implementation summary to Jira and creates a QE Review sub-task. With --pr, it auto-commits (selective staging) and raises a pull request.

Companion Commands

While a workflow is running (or paused), use the unified companions — they auto-detect which workflow is active, so you don't need to remember the prefix. Workflow-specific companions (e.g., /bug-fix-status) are also available.

CommandPurpose
/sdet-statusAuto-detect active workflow and show current phase, attempt count, and completed phases
/sdet-guideInject guidance into the active workflow's HUMAN_GUIDANCE.md
/sdet-retryRe-run a phase in the active workflow (resets attempt counter)
/sdet-unblockResolve a BLOCKED_NEEDS_HUMAN situation in the active workflow and continue
/refresh-insightsRe-survey the repo and regenerate CODEBASE_INSIGHTS.md (backs up previous version first)

Workflow-specific companions (/bug-fix-status, /feature-enhance-guide, /feature-build-retry, etc.) still work if you prefer to be explicit.

Generated File Structure

After running the dev generator, your .claude/ folder will contain:

Show full file tree
text
.claude/
├── commands/
│   ├── generate-development-workflows.md  # Dev workflow generator
│   ├── bug-fix.md             # Main orchestrator
│   ├── bug-fix-status.md      # Check current phase
│   ├── bug-fix-guide.md       # Show workflow guide
│   ├── bug-fix-retry.md       # Retry current phase
│   ├── bug-fix-unblock.md     # Handle blockers
│   ├── feature-enhance.md     # + status, guide, retry, unblock
│   ├── feature-build.md       # + status, guide, retry, unblock
│   ├── sdet.md                # Universal entry point (always generated)
│   ├── sdet-status.md         # Unified status (auto-detects workflow)
│   ├── sdet-guide.md          # Unified guide (auto-detects workflow)
│   ├── sdet-retry.md          # Unified retry (auto-detects workflow)
│   ├── sdet-unblock.md        # Unified unblock (auto-detects workflow)
│   └── refresh-insights.md    # Re-survey + regenerate CODEBASE_INSIGHTS
├── bug-fix/
│   ├── RULES.md               # Universal rules (loaded every phase)
│   ├── KEY_PATHS.md           # Directory map (loaded for +PATHS phases)
│   ├── TEST_HELPERS.md        # E2E lifecycle (loaded for +TEST phases)
│   ├── APPROACH.md            # Bug-fix methodology
│   ├── SYSTEM_CONTEXT.md      # Repo-specific context
│   └── prompts/               # 16 phase prompts
├── feature-enhance/
│   ├── RULES.md / KEY_PATHS.md / TEST_HELPERS.md
│   ├── APPROACH.md / SYSTEM_CONTEXT.md
│   └── prompts/               # 17 phase prompts
├── feature-build/
│   ├── RULES.md / KEY_PATHS.md / TEST_HELPERS.md
│   ├── APPROACH.md / SYSTEM_CONTEXT.md
│   └── prompts/               # 20+ phase prompts
├── KNOWLEDGE_BASE.md          # Cross-workflow learning
├── CODEBASE_INSIGHTS.md       # Enterprise context for all agents
└── TOOL_RETRO.md              # Command successes/failures

Architecture deep dive

Every development workflow is powered by the same core architecture: LISA (Layered Information State Architecture) organizes information into three layers — state file, phase documents, and knowledge stores. Ralph Loops make every phase idempotent and crash-safe with automatic retries. Read the full Architecture page →

Next steps

Explore the individual workflow pages to understand phase details: Bug-Fix, Feature-Enhance, Feature-Build, or the Smart Classifier.