Glossary
Every file the framework creates or uses — what it does and why it exists.
Command Files
Slash commands that appear in your agentic coding assistant after generation. Located in .claude/commands/.
| File | Command | What it does |
|---|---|---|
| generate-development-workflows.md | /generate-development-workflows | Development workflow generator. Routes to modular phase files: SURVEY (deep repo investigation), GENERATE (template filling + CODEBASE_INSIGHTS), VALIDATE (quality checks). Produces /bug-fix, /feature-enhance, /feature-build. |
| generate-story-workflows.md | /generate-story-workflows | Story readiness workflow generator. Surveys Jira structure, DoR practices, and test infrastructure. Produces /story-draft (PO), /story-engineer (Dev), /story-qa (QE). |
| bug-fix.md | /bug-fix | Main orchestrator for the bug-fix workflow. Runs the 16-phase state machine from INTAKE to LEARN. |
| feature-enhance.md | /feature-enhance | Main orchestrator for the feature-enhance workflow. Runs the 17-phase state machine including FIGMA_CONTEXT and DESIGN. |
| feature-build.md | /feature-build | Main orchestrator for the feature-build workflow. Runs 20+ phases with per-slice iteration and integration testing. |
| sdet.md | /sdet | Universal entry point. Accepts text descriptions or Jira tickets, detects active workflows, classifies input as bug-fix/feature-enhance/feature-build, and delegates. Use --jira-check to validate ticket readiness without starting a workflow. Always generated. |
| sdet-status.md | /sdet-status | Unified status — auto-detects which workflow is active and shows its phase, attempt count, blockers, and documents. |
| sdet-guide.md | /sdet-guide | Unified guide — auto-detects active workflow and appends guidance to its HUMAN_GUIDANCE.md. |
| sdet-retry.md | /sdet-retry | Unified retry — auto-detects active workflow, shows valid phases for that workflow type, and re-runs a specific phase. |
| sdet-unblock.md | /sdet-unblock | Unified unblock — auto-detects active workflow, resolves a blocker in BLOCKERS.md, and continues. |
| refresh-insights.md | /refresh-insights | Re-surveys the repo and regenerates CODEBASE_INSIGHTS.md. Backs up the previous version, re-runs survey steps, rewrites using the same generation logic, and validates quality. |
| story-draft.md | /story-draft | PO workflow: creates/enriches epics and stories with ACs, scope boundaries, edge cases, and dependencies. Validates against DoR. 6 phases: INTAKE → CONTEXT → SPECIFY → DECOMPOSE → VALIDATE_DOR → PUBLISH. |
| story-engineer.md | /story-engineer | Developer workflow: adds technical refinement to stories — architecture, affected components, API contracts, risks, sub-tasks. 5 phases: INTAKE → ANALYZE → REFINE → VALIDATE → PUBLISH. |
| story-qa.md | /story-qa | QE workflow: adds test plan across 5 layers (unit, integration, E2E, security, performance), test data requirements, and coverage targets. 6 phases: INTAKE → ASSESS → PLAN_TESTS → PLAN_DATA → VALIDATE → PUBLISH. |
| bug-fix-status.md | /bug-fix-status | Shows current phase, attempt count, and completed phases for an active bug-fix workflow. |
| bug-fix-guide.md | /bug-fix-guide | Explains what the current phase expects — what inputs it needs, what output it produces, and how to help. |
| bug-fix-retry.md | /bug-fix-retry | Resets the attempt counter for the current phase and re-runs it. Use when a phase failed due to a transient issue. |
| bug-fix-unblock.md | /bug-fix-unblock | Resolves a BLOCKED_NEEDS_HUMAN situation. Reads BLOCKERS.md, applies the human-provided resolution, and continues. |
The status, guide, retry, and unblock companions exist for all three workflows (feature-enhance-status, feature-build-guide, etc.).
Workflow Configuration Files
Each workflow gets its own directory with rules, approach, context, and phase prompts. Located in .claude/bug-fix/, .claude/feature-enhance/, .claude/feature-build/.
| File | What it does | Why it exists |
|---|---|---|
| RULES.md | 17+ universal rules that govern every phase (verify actions, no vague language, 3-attempt limit, never pause on happy path, etc.) | Loaded at the start of every orchestrator loop. Ensures consistent behavior regardless of which phase is running. |
| KEY_PATHS.md | Directory map — source code paths, test paths, feature flag locations, routes, DI mechanism, monorepo package paths. | Only loaded by phases marked +PATHS (CODE_TRACE, BLAST_RADIUS_MAP, DIAGNOSIS/DESIGN/ARCHITECTURE, SCAFFOLD). Keeps non-tracing phases lightweight. |
| TEST_HELPERS.md | E2E test lifecycle script (start → health check → run → stop), test-ring mapping (Ring 1-4), and health check reference. | Only loaded by phases marked +TEST (BASELINE, IMPLEMENT/FIX, VERIFY, INTEGRATION, VERIFY_ALL, BLAST_RADIUS_RUN). Avoids loading test boilerplate in discovery phases. |
| APPROACH.md | Workflow-specific methodology — how this workflow approaches its type of work (debugging vs design vs architecture). | Gives the agent the right mental model. A bug-fix approach is fundamentally different from a feature approach. |
| SYSTEM_CONTEXT.md | Repo-specific context — language, framework, test runner, build commands, directory structure, conventions. | Generated during SURVEY. Means the agent knows your repo without re-scanning every time a workflow runs. |
| prompts/*.md | One prompt file per phase (16-22 files). Each contains the exact instructions, inputs, outputs, and signal logic for that phase. | Each phase is a self-contained unit. The orchestrator loads the right prompt based on STATE_FILE, so the agent always knows exactly what to do. |
Runtime State Files
Created during workflow execution. These track progress and enable resume-from-interruption.
| File | What it does | Why it exists |
|---|---|---|
| BUG_FIX_STATE.md | Current phase, subphase, attempt counter, completed phases with timestamps, auto_pr flag. | The single source of truth for workflow progress. Rewritten in full on every phase transition (never edited). Enables resume after crash or interruption. |
| HUMAN_GUIDANCE.md | Human-provided overrides, preferences, and corrections. Read at the start of every phase. | Lets engineers steer the agent without breaking the workflow. Override a diagnosis, skip a known-good area, provide context the agent can't discover. |
| BLOCKERS.md | Created when a phase hits BLOCKED_NEEDS_HUMAN. Describes the blocker, what was tried, and what's needed. | Structured handoff to the human. Instead of a vague failure, the agent documents exactly what's blocking and what resolution looks like. |
State files follow the pattern: ENHANCE_STATE.md, FEATURE_STATE.md for other workflows.
Phase Documents
One document per completed phase, stored in bug-fix-docs/ (or feature-enhance-docs, feature-build-docs). These form the document chain — each phase reads upstream docs and produces exactly one output.
| Document | Produced by | What it captures | Why it exists |
|---|---|---|---|
| INTAKE.md | INTAKE | Structured problem/request statement, ticket ID, parsed Jira fields, initial scope. | The anchor document. Everything downstream traces back to this. Fetches Jira ticket data if a ticket ID is provided. |
| TICKET_GATE.md | TICKET_GATE | Checklist results (PRESENT/PARTIAL/MISSING per field), verdict (READY/NEEDS_REVIEW/INSUFFICIENT), impact analysis mapping gaps to downstream phases, dependency maturity table for linked stories. | Validates the Jira ticket has the right info BEFORE discovery burns time. Workflow-specific checklists: 6 required for bug-fix, 6 for enhance, 8+5 for feature. For features: fetches linked stories to check status maturity, interface contracts, and transitive blockers. Auto-passes if no Jira ticket. Re-fetches on retry. Use --jira-check flag on any command to run this check standalone — drafts suggested fixes and can update the ticket directly. |
| FIGMA_CONTEXT.md | FIGMA_CONTEXT | Design specs, mockups, UI requirements from Figma. | Brings design intent into the workflow so code matches the design. Non-blocking — if unavailable, documents assumptions instead. |
| LANDSCAPE.md | LANDSCAPE | Current state of the feature/system — what exists today, how it works, its structure. | You can't change what you don't understand. For bug-fix this is REPRODUCE.md (proving the bug exists with actual output). |
| RECALL.md | RECALL | Relevant patterns, pitfalls, and insights from KNOWLEDGE_BASE.md. | Prevents re-discovering known patterns. If a similar bug was fixed before, the approach and pitfalls are surfaced here. |
| API_SURVEY.md | API_SURVEY | All external APIs, services, and dependencies the feature needs. | Feature workflow only. Catalogs every external dependency so DEPENDENCY_GATE can evaluate each one before coding starts. |
| CODE_TRACE.md | CODE_TRACE | Specific files, functions, and lines involved in the bug/feature/enhancement. | Narrows the search space from 'the whole repo' to 'these exact code paths'. Everything downstream uses this as the map. |
| BLAST_RADIUS_MAP.md | BLAST_RADIUS | Every file, test, and component that could be affected by changes. | Runs BEFORE code changes. Means you know the impact zone upfront — not after a reviewer spots a surprise regression in the PR. |
| REQUIREMENTS.md | REQUIREMENTS | Specific pass/fail acceptance criteria for 'done'. | The single source of truth for scope. TEST_GEN writes tests against these criteria. VERIFY checks them. No ambiguity about what 'fixed' or 'done' means. |
| TEST_INVENTORY.md | TEST_INVENTORY | All existing tests in the affected area — what they cover, where they live. | Feeds BASELINE (what to run before changes) and TEST_GEN (what gaps to fill). Prevents duplicate test creation. |
| DEPENDENCY_GATE.md | DEPENDENCY_GATE | Status of each external dependency: READY, MOCKED, or BLOCKED. | Feature workflow only. Ensures no blocked dependency surprises mid-sprint. BLOCKED deps stop the workflow and escalate. |
| DIAGNOSIS.md | DIAGNOSIS | Root cause analysis synthesized from all discovery documents. | Bug-fix only. The pivotal document — everything before it is gathering evidence, everything after acts on this conclusion. Versioned (v1, v2) on loopback. |
| DESIGN.md | DESIGN | Enhancement approach and category classification (AUGMENT/EXTEND/MODIFY/OPTIMIZE/INTEGRATE). | Enhance only. Determines how to change the feature AND whether a feature flag is required. Versioned on REDESIGN loopback. |
| ARCHITECTURE.md | ARCHITECTURE | Full system design — components, data models, API contracts, integration patterns. | Feature only. The blueprint that SLICE_PLAN decomposes into deliverable pieces. Versioned on REARCHITECT loopback. |
| FIX_PLAN.md | FIX_PLAN | Specific code changes planned at the file/function level. | Bug-fix only. No code is written until this plan exists. TEST_GEN and FIX both follow it. Versioned on loopback. |
| ENHANCE_PLAN.md | ENHANCE_PLAN | Implementation plan including feature flag decisions. | Enhance only. Includes whether the change needs a feature flag based on the category from DESIGN. |
| SLICE_PLAN.md | SLICE_PLAN | Feature broken into independently deliverable vertical slices. | Feature only. Each slice gets its own build-test-verify cycle. Prevents 50-file mega-PRs. |
| BASELINE.md | BASELINE | Test suite results BEFORE any code changes. | Establishes the health baseline. If tests are already failing, that's documented here — not blamed on your changes later. |
| TEST_GEN.md | TEST_GEN | Auto-generated unit + E2E tests (Category A) for the change. | Zero manual test writing. Tests are generated from REQUIREMENTS and the plan. They should FAIL before changes and PASS after. |
| VERIFY.md | VERIFY | Test results for new (A) and updated (B) tests after changes. | Confirms the fix/enhancement/feature works. Failure triggers a loopback signal (REDIAGNOSE/REDESIGN/REARCHITECT). |
| BLAST_RADIUS_RUN.md | BLAST_RADIUS_RUN | Full regression suite results compared against BASELINE. | Catches regressions in areas you didn't intend to change. The final safety net before CLOSE. |
| INTEGRATION.md | INTEGRATION | Cross-slice interaction test results. | Feature only. After all slices pass individually, this verifies they work together. Failure triggers RESLICE. |
| VERIFY_ALL.md | VERIFY_ALL | Full test suite with feature flag ON and OFF. | Feature only. Both flag states must pass. Failure triggers REARCHITECT. |
| CLOSE.md | CLOSE | Complete workflow summary, changes made, test results, decisions. Jira comment with implementation summary. QE Review sub-task with test inventory and manual QE areas. | The final record. Posts results back to Jira and creates a QE sub-task so nothing falls through the cracks. With --pr, becomes the PR description (selective staging — no workflow artifacts). Without --pr, serves as the handoff document. |
| LEARN.md | LEARN | Patterns, pitfalls, and insights extracted from this workflow. | Written to KNOWLEDGE_BASE.md so future workflows benefit. This is how the system gets smarter over time. |
Knowledge Stores
Persistent files that live across workflows and accumulate intelligence over time. Located in .claude/.
| File | What it captures | Written by | Read by | Why it exists |
|---|---|---|---|---|
| KNOWLEDGE_BASE.md | Diagnostic patterns, architecture patterns, slice strategies, pitfalls, and proven approaches. | LEARN phase | RECALL phase | Long-term memory. Every workflow writes what it learned; future workflows read it to avoid repeating mistakes. |
| CODEBASE_INSIGHTS.md | Enterprise context document: architecture with versions, every module/hook/service by name, initialization chain in order, test config (path mappings, coverage, commands), dependency graph with blast-radius rules, override mechanism, 8–12 real import examples. LEARN appends fragile areas, component consumers, API quirks. | /generate-workflows (deeply investigated) + LEARN phase (grows) + /refresh-insights (re-surveys) | RECALL phase (all workflows) | The most important shared file — gives every workflow agent full situational awareness. Quality-validated by VALIDATE phase (named lists, import examples, test commands, blast-radius data). Gets richer with every run. Use /refresh-insights to regenerate after significant codebase changes. |
| STORY_KNOWLEDGE.md | Story readiness patterns: DoR patterns that work, common AC mistakes, technical refinement patterns per module, test data patterns per service, stories sent back and why. | PUBLISH phase (story-draft, story-engineer, story-qa) | CONTEXT (story-draft), ANALYZE (story-engineer), ASSESS (story-qa) | Cross-workflow learning for story readiness. Each workflow writes what worked; future story workflows read it to avoid repeating mistakes. |
| TOOL_RETRO.md | Seeded with known-working commands from survey (dev server, test runners, build). LEARN appends commands that failed and workarounds. | /generate-workflows (seeded) + LEARN phase (grows) | RECALL phase (all workflows) | Prevents the agent from re-trying known-broken commands. Downstream phases use proven alternatives instead of discovering failures the hard way. |