SpecFlow OSS

Author: awrobel-gd

.claude/commands/document.md

@@ -0,0 +1,18 @@
+Create comprehensive documentation for a new feature or component:
+
+1. Read `CLAUDE.md` and `agents/IMPLEMENTATION.md` to understand current state
+2. Create feature documentation in `agents/plans/<feature>/`
+3. Include:
+   - **Overview**: Purpose and scope
+   - **Architecture**: How it fits in the system
+   - **State Management**: State machine usage (if applicable)
+   - **API**: Endpoints and schemas (if applicable)
+   - **Database**: Firestore collections and documents (if applicable)
+   - **Testing**: Test strategy and coverage
+   - **Dependencies**: External services or libraries
+   - **Edge Cases**: Known limitations and gotchas
+4. Update `agents/IMPLEMENTATION.md` with implementation status
+5. Use references to code, not code duplication
+6. Keep it concise and scannable (aim for 100-200 lines)
+
+Focus on what developers need to know to work with this feature.

.claude/commands/review-backend.md

@@ -0,0 +1,120 @@
+You are an expert reviewer for this AI SDLC accelerator codebase. Your job is to find real bugs, not style issues.
+
+## Context
+
+This backend uses a strict state machine architecture. The canonical sources of truth are:
+- `backend/app/schemas/estimation_enums.py` — `EstimationStatus`, `EstimationCheckpoint`, `WorkspaceStatus`, `CHECKPOINT_ORDER`
+- `backend/app/state/` — the ONLY place allowed to write status/checkpoint/workspace_phases to Firestore
+- `backend/app/state/transitions.py` — legal transitions
+- `CLAUDE.md` — Steel Commandments (especially I–X)
+
+## Steps
+
+1. If no PR number given, run `gh pr list` and ask which one to review.
+2. Run `gh pr diff <number>` to get the full diff.
+3. Run `gh pr view <number>` for the description.
+
+## What to check — in this exact priority order
+
+### 🔴 CRITICAL — These are production bugs if missed
+
+**1. Enum contract violations (`estimation_enums.py`)**
+- Was `EstimationStatus` modified (values added, removed, renamed, reordered)?
+- Was `EstimationCheckpoint` modified?
+- Was `CHECKPOINT_ORDER` list changed? This controls checkpoint ordering validation — any change breaks `advance_checkpoint()` for all in-flight estimations.
+- Was `WorkspaceStatus` modified?
+- Flag ANY change to this file. Even adding a new value can break running estimations that don't know about it.
+
+**2. Direct Firestore writes outside `backend/app/state/`** (Commandment VII)
+Look for any of these patterns outside `backend/app/state/`:
+- `db.update("estimations", ...)` or `db.set("estimations", ...)` with `status`, `checkpoint`, `workspace_phases`, or `workspace_phases_deployment`
+- `self._esm._db.` accessed from service or workflow files
+- `self.db.update(...)` writing status/checkpoint fields directly
+- String literals like `{"status": "running"}` or `{"checkpoint": "generation_done"}` written directly
+The CI guard (`ci/check_state_writes.sh`) catches most but not all patterns. Review manually too.
+
+**3. Missing checkpoint advancement**
+Every major workflow step that completes a logical phase MUST advance `EstimationCheckpoint` via `estimation_service.update_checkpoint()` or `_esm.advance_checkpoint()`. Check:
+- Does each new workflow step call `update_checkpoint` at the end?
+- Is the checkpoint value from `EstimationCheckpoint` (never a bare string)?
+- Is the checkpoint consistent with `CHECKPOINT_ORDER`? (must go forward)
+- For LOCAL_ONLY vs INTEGRATION_TESTS_READY paths: does each path advance to the correct checkpoint? (e.g. LOCAL_ONLY skips `DEPLOY_AND_E2E_DONE`)
+
+**4. Missing `state_history` append** (Commandment IX)
+Any new state machine method that writes to Firestore must append to `state_history` with: `status`, `at` (UTC), `triggered_by`, `metadata`. Check `_record_phase_progress_for_field`, `init_deployment_phases`, and any new methods added in `backend/app/state/`.
+
+**5. Workspace safety violations** (Commandments I–VI)
+- Does `fail()` or `stuck_detected()` release any workspace? It must NOT — only `failed_at` timestamp side-effect is allowed.
+- Does any code path touch an ALLOCATED workspace from a background job? Only `stuck_detected()` on the estimation is allowed.
+- Does `complete()` still require `outputs_archived == True` AND archive branch confirmed before releasing workspaces?
+- On retry: if `code_archived == False`, does it reuse the same `workspace_ids`? Never fall back to fresh workspaces silently.
+
+### 🟡 HIGH — Logic bugs that cause silent corruption
+
+**6. Brittle status/checkpoint string comparisons**
+Look for:
+- `if status == "running":` — must use `EstimationStatus.RUNNING`
+- `if checkpoint == "generation_done":` — must use `EstimationCheckpoint.GENERATION_DONE`
+- `doc.get("status") == "failed"` — same issue
+- Resume logic using raw dict string keys for status comparisons (using `.get("last_completed_phase", 0)` for data fields is fine; comparing status values is not)
+
+**7. Invalid transition action names in `_validate_transition` / `_require_running`**
+- Is a method using `_validate_transition(doc, "advance_checkpoint", ...)` when it's not actually advancing a checkpoint? The action name appears in error messages and logs — misuse produces misleading diagnostics.
+- New state machine methods that only need a RUNNING guard should use `_require_running(doc, "method_name", generation_id)`.
+
+**8. Checkpoint order violations**
+- Is `advance_checkpoint()` called with a checkpoint that could go backward? (e.g., `GENERATION_DONE` after `ESTIMATION_DONE`)
+- On retry/resume: does the code respect the saved checkpoint and resume forward from it? Does it ever reset checkpoint to an earlier value?
+
+**9. `init_*` methods that aren't idempotent**
+Any init method called before a loop (like `init_deployment_phases`) must be a no-op if already initialized, to survive retries. Check that new init methods guard against overwriting existing progress.
+
+### 🔴 CRITICAL — Graceful failure and audit logging
+
+**12. Hard stoppers in non-essential operations**
+Non-essential operations (P10Y estimation, archiving, notifications, metric collection, telemetry) must NEVER crash the workflow. Check:
+- Does any new non-essential step propagate an unhandled exception that would abort the whole estimation run?
+- Are errors caught, logged with `logger.warning`/`logger.error`, and stored in the relevant Firestore audit fields (e.g. `state_history`, error context on the estimation/workspace doc)?
+- `assert` statements are forbidden outside of tests — they raise `AssertionError` (stripped with `-O`) and produce opaque crashes. Replace with a typed exception and a clear message.
+- Background tasks (archiving, notifications) must catch and log their own exceptions so a failure does not surface to the caller or abort an in-progress estimation.
+
+### 🟠 MEDIUM — Robustness issues
+
+**10. Resume logic correctness**
+For any new phase loop (generation or deployment):
+- Does `last_completed >= total_phases` correctly skip already-done workspaces?
+- Does `last_completed > 0` correctly set `start_phase = last_completed + 1`?
+- Is `total_phases` read from the stored checkpoint data (not recalculated), so a retry with a different plan doesn't corrupt resume?
+
+**11. `workspace_ids` assumptions**
+- Does new code assume `workspace_ids` is always populated? It may be empty before allocation.
+- Is `workspace_ids` ever modified outside of the allocation path?
+
+### 🟡 HIGH — CLAUDE.md coding pattern adherence
+
+**13. Coding pattern violations**
+Check new code against the mandatory patterns from `CLAUDE.md`:
+- **Pydantic/dataclasses/OOP over raw dicts and strings** — new data passed between functions should use typed models, not bare `dict`/`str`.
+- **Enums over string literals** — any new status, type, or category value must be an `Enum` member, not a bare string.
+- **SRP / Open-Closed** — new classes should have a single responsibility; extensions should not require modifying existing classes.
+- **Imports at the top of the file** — no lazy imports inside functions or methods.
+- **Small functions / DRY** — flag functions that duplicate logic already present elsewhere, or that are doing more than one thing.
+- **No raw collections as public API** — functions returning `dict`/`list` for structured data should return a typed model instead.
+- **Model with the right paradigm for clarity** — choose the tool that makes the domain intent obvious at the call site: pure functions for stateless transforms, magic methods for natural domain operations (`current + delta` via `__add__` instead of manual field construction), OOP for encapsulating state and invariants. Flag code that uses a weaker paradigm when a stronger one would eliminate boilerplate and make the intent self-evident.
+
+## What NOT to flag
+
+- Minor inefficiencies (extra dict copy, redundant log line)
+- Test structure preferences
+- Docstring/comment quality on unchanged code
+- The `progress` field — this is explicitly exempt from the state machine write guard (it's owned by the workflow display layer)
+
+## Output format
+
+Group findings by severity. For each finding:
+- File and line number
+- The exact problematic code snippet
+- Why it's a bug (reference the relevant Commandment or rule above)
+- The correct fix
+
+End with a one-line verdict: **APPROVED**, **APPROVED WITH NITS**, or **CHANGES REQUIRED**.

.claude/commands/review-specflow.md

@@ -0,0 +1,16 @@
+Parity: same intent as Cursor `/review` (`.cursor/commands/review.md`). For PR-style `gh` review, use `review-backend.md`.
+
+Review code changes against SpecFlow project standards:
+
+1. Check that state changes go through `backend/app/state/` machines only
+2. Verify no direct Firestore writes for status/checkpoint/workspace_phases
+3. Confirm tests still pass (baseline: 584+)
+4. Check type hints on all function signatures
+5. Verify error handling follows guard clause pattern
+6. Confirm logging includes context (request_id, generation_id, etc.)
+7. Check async/await usage is correct
+8. Verify STEEL COMMANDMENTS compliance (workspace safety)
+9. Check for anti-patterns (see `.cursor/rules/backend-python.mdc`)
+10. Confirm no absolute paths in generated files
+
+Run `make check` and `make unit-tests` to validate.

.claude/commands/state-machine.md

@@ -0,0 +1,69 @@
+Debug or modify state machine logic:
+
+1. Understand state machine architecture:
+   - Read docs/ARCHITECTURE.md (State Machine Layer)
+   - Read backend/app/state/estimation_state_machine.py
+   - Read backend/app/state/workspace_state_machine.py
+   - Read backend/app/state/transitions.py (all valid transitions)
+
+2. Key principles (STEEL COMMANDMENTS):
+   - State machines are ONLY writers of status/checkpoint
+   - No code outside backend/app/state/ may write these fields
+   - CI enforces this: ci/check_state_writes.sh
+   - Every transition logged in state_history
+   - Invalid transitions raise immediately
+   - Checkpoints never go backward
+
+3. Common tasks:
+
+   **Add new transition**:
+   a. Add to ESTIMATION_TRANSITIONS or WORKSPACE_TRANSITIONS in transitions.py
+   b. Add method to EstimationStateMachine or WorkspaceStateMachine
+   c. Method must: validate transition, write status, append state_history
+   d. Add tests to backend/test/test_state/
+   e. Update docs/ARCHITECTURE.md state diagrams
+
+   **Fix invalid transition error**:
+   a. Check current status in Firestore
+   b. Review transitions.py for valid paths
+   c. Check if estimation stuck in FAILED (cannot resume)
+   d. Use retry with workspace reuse if code not archived
+
+   **Debug transition not happening**:
+   a. Check state_history in Firestore document
+   b. Look for InvalidEstimationStateError in logs
+   c. Verify caller using state machine (not direct DB write)
+   d. Check if CI guard would catch it: `./ci/check_state_writes.sh`
+
+4. State machine methods (EstimationStateMachine):
+   - create() - PENDING
+   - begin_allocation() - PENDING → INITIALIZING
+   - allocation_succeeded() - INITIALIZING → RUNNING
+   - allocation_failed() - INITIALIZING → FAILED
+   - advance_checkpoint() - Update progress
+   - fail() - * → FAILED
+   - stuck_detected() - Write failed_at, keep workspaces ALLOCATED
+   - complete() - RUNNING → COMPLETED, archive_and_release()
+
+5. State machine methods (WorkspaceStateMachine):
+   - allocate() - AVAILABLE → ALLOCATED
+   - archive_and_release() - ALLOCATED → CLEANING
+   - allocation_rollback() - INITIALIZING estimation failed
+   - mark_available() - CLEANING → AVAILABLE
+   - force_release() - Operator only, audit trail required
+
+6. Testing state machines:
+   ```bash
+   cd backend && uv run pytest test/test_state/ -v
+   ```
+   - Test all valid transitions
+   - Test invalid transitions raise
+   - Test state_history logging
+   - Test checkpoint ordering
+
+Reference:
+- State machines: backend/app/state/
+- Transitions: backend/app/state/transitions.py
+- Tests: backend/test/test_state/
+- CI guard: ci/check_state_writes.sh
+- STEEL COMMANDMENTS: CLAUDE.md (rules VII-X)

.claude/commands/test.md

@@ -0,0 +1,15 @@
+Run full test suite and validation:
+
+1. Run `make unit-tests` in backend directory
+2. Check test count (baseline: 584+ passing)
+3. Review test output for any warnings or deprecations
+4. If tests fail:
+   - Read test output carefully
+   - Check if changes broke existing functionality
+   - Verify mocks are properly configured
+   - Check async test fixtures
+   - Review state machine transitions
+5. Run `make check` for static analysis (ruff, mypy, vulture)
+6. Format code with `make format` if needed
+
+Expected: All tests pass, no linter errors, 584+ tests passing.

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "pyright-lsp@claude-plugins-official": true
+  }
+}

.claude/skills/backend-quality-gate/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: backend-quality-gate
+description: After substantive edits under backend/app, run static checks and optional Radon complexity (matches Makefile and Cursor post-write hook intent).
+---
+
+# Backend quality gate (SpecFlow)
+
+Use when finishing or reviewing a change that touches `backend/app/**/*.py`.
+
+## Steps
+
+1. From repo root: `make check` (ruff, mypy, vulture as in Makefile).
+2. If the change is non-trivial: `make check-complexity` (summary) or `make check-complexity-diff` against `main` (see `CLAUDE.md` for `METRIC=cc|mi|hal`).
+3. For a single file: `make check-complexity-cc FILE=app/...` and `make check-complexity-mi FILE=app/...`.
+4. Confirm SRP, DRY, and that state/credential rules match `docs/PATTERNS/INDEX.md` and `.cursor/rules/backend-python.mdc`.
+
+**Note:** Cursor may show ruff/radon inline via `.cursor/hooks.json`; that does not replace `make check` or tests.
+
+## Tests
+
+- `make unit-tests` (required before merge for substantive work)

.claude/skills/deploy-requirements/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: deploy-requirements
+description: Generate a customer-specific deployment requirements document from the template. Takes customer name and known infrastructure details as input. Produces a filled-in requirements spec ready for human review before sending to the customer.
+argument-hint: <customer-name> <known details about their infrastructure>
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(ls:*), Bash(mkdir:*)
+---
+
+# Generate Customer Deployment Requirements Spec
+
+You are a GAIN implementation engineer preparing a deployment requirements document for a customer. This document will be sent to the customer's platform/DevOps team as part of presales and implementation.
+
+## Input
+
+The user provided: $ARGUMENTS
+
+Parse this for:
+- **Customer name** (first argument or identifiable from context)
+- **Known infrastructure details** (cloud provider, K8s setup, services, integrations, etc.)
+
+## Process
+
+### Step 1: Read the template
+
+Read the template at `docs/operations/deployment-requirements-template.md`. This is your structural reference — every section must appear in the output.
+
+### Step 2: Fill in what you know
+
+From the user's input, fill in all fields where information was provided. Be precise — use exact values given (account IDs, cluster names, URLs, etc.).
+
+For fields where information was **not** provided:
+- Leave the field blank with a `<!-- TODO: confirm with customer -->` comment
+- If you can make a reasonable inference from context (e.g., AWS implies ECR for registry), fill it in but mark with `<!-- INFERRED: verify with customer -->`
+
+### Step 3: Tailor the document
+
+- Replace all generic references with the customer name
+- Remove options that don't apply (e.g., if customer is AWS, remove GCP/Azure examples from tables)
+- Keep the section numbering and structure intact
+- Preserve the checklist in §9 — update it to reflect customer-specific items
+
+### Step 4: Handle open questions
+
+- Keep §10 (Questions for Customer) but **remove questions that are already answered** by the provided input
+- Add any **new customer-specific questions** that arise from the details given (e.g., if they mention a service mesh, ask which one)
+- Mark unanswered questions with severity: `[BLOCKING]` if estimation can't start without it, `[NICE-TO-HAVE]` otherwise
+
+### Step 5: Write the output
+
+Save the completed document to:
+```
+docs/operations/customers/{customer-name}-deployment-requirements.md
+```
+
+Use kebab-case for the customer name in the filename.
+
+## Output quality rules
+
+- **Tone:** Professional technical document between companies. No casual language.
+- **Completeness:** Every section from the template must appear. Empty sections get a TODO comment, never deleted.
+- **Precision:** Use exact values. Don't paraphrase technical details — account IDs, URLs, namespace patterns must be verbatim.
+- **Open questions are OK:** This document is used to start the conversation. Gaps marked with TODO are expected and useful — they show the customer exactly what GAIN still needs.
+- **No invented details:** If you don't know something, leave it blank with TODO. Never guess account IDs, secret paths, or endpoints.
+
+## Final message
+
+After writing the file, summarize:
+1. How many sections are fully filled vs have TODOs
+2. List all `[BLOCKING]` open questions
+3. The output file path