specflow-execute

name	specflow-execute
description	Use when stories are planned and the user wants to implement them. Orchestrates implementation, updates artifact statuses, and creates test artifacts.

Freeform Input Handling

This skill accepts freeform user input alongside the command. Interpret the user's message to determine scope and depth:

• No additional context → run the standard workflow (deterministic core only)
• A question or concern → run the deterministic core, then address the question directly using the results
• A request for depth ("go deep", "be thorough", "all lenses") → run deterministic core + full LLM analysis
• A specific focus ("focus on REQ-003", "check compliance only") → narrow scope to the request, still run deterministic core first

Always run the deterministic core regardless of input. It costs zero tokens and provides the foundation for any analysis.

---

SpecFlow Execute

Orchestrate the implementation of planned stories and update tracking artifacts.

Workflow

Step 1: Implementation-Readiness Gate (mandatory)

The planning-to-executing phase gate IS the readiness check. Run it unconditionally before any implementation work — never skip it, never treat it as advisory.

1. Run the deterministic gate:

   uv run specflow artifact-lint --type gate --gate planning-to-executing
   

   • Exit 1 → at least one automated blocking item failed (missing ARCH, broken links, etc.). Stop. Do not proceed. Report the failures verbatim and ask the user to address them. Re-run the gate after fixes.
   • Exit 0 → automated checks pass; LLM-judged items show as ○ (skipped by the deterministic runner).

2. Evaluate the LLM-judged items yourself. Read .specflow/checklists/phase-gates/planning-to-executing.yaml. For every item with automated: false, scope artifact reads narrowly:

   • Use _index.yaml files in _specflow/work/stories/ and _specflow/specs/architecture/ to enumerate IDs, statuses, and link metadata without opening every artifact body.
   • Open full artifact bodies only for the subset that needs LLM judgement (e.g., the STORYs in the current wave, ARCHs referenced by those STORYs). At 100+ stories, sample by wave or by suspect/recently-modified flags rather than reading every file.
   • Then answer the llm_prompt against the scoped subset and report findings as:
     • blocking severity items → these MUST be addressed before proceeding.
     • warning severity items → present them and ask the user whether to proceed anyway. Do not proceed silently.

3. Identify the in-scope STORY set. Use uv run specflow go --dry-run to compute the next wave; that's the read-set for this run. Avoid reading STORYs outside the upcoming wave unless an LLM-judged item explicitly requires cross-story analysis.

4. Check suspect: true flags on linked artifacts in the in-scope set. If upstream specs are suspect, surface this to the user before proceeding.

5. Run uv run specflow status silently for the state overview.

Why this is mandatory: the gate verifies the task is sufficiently specified to start coding (ARCH exists, links resolve, AC are clear, interfaces defined, test strategy specified, dependencies approved). Skipping it lets implementation start against draft specs and produces rework.

6. Load execution-phase best practices as context for implementation:

   uv run specflow handbook generate execute-impl
   

   Read the output with uv run specflow handbook show execute-impl. The generated BPs provide domain-specific guidance on what good implementation and testing look like for this project's domain. They also appear automatically in artifact review prompts. If no API key is configured, this step is skipped gracefully.

Step 2: Wave Planning

1. Run uv run specflow go --dry-run to compute the execution wave plan.
2. Review the wave groupings -- stories in the same wave can run in parallel.
3. If the wave plan looks wrong, check story dependencies (derives_from, shared specified_by).
4. Read references/wave-computation.md for algorithm details.

Step 3: Implementation

For each story (or wave of stories):

1. Run uv run specflow go to execute all waves, or implement manually: a. Load context: Read the story, its linked REQ, ARCH, and DDD artifacts. b. Implement the code per the detailed design in DDD artifacts. c. Follow the acceptance criteria -- implement each criterion from the story. d. Quick thinking check (from references/thinking-techniques.md): before writing each function, ask "what's the most unexpected input?" and "does this share state with another STORY in this wave?"

Step 4: Status Updates

After implementation, update artifact statuses:

uv run specflow update STORY-001 --status implemented

If the linked DDD/ARCH artifacts should reflect implementation:

uv run specflow update DDD-001 --status implemented

Execution state is machine-managed. specflow go writes per-artifact locks to .specflow/locks/*.json while waves run and tracks progress in .specflow/execution-state.yaml. Do not edit these by hand -- the CLI releases locks on completion and uses execution-state.yaml to resume interrupted runs.

Step 5: Test Creation

For each implemented spec artifact, create its V-model verification test -- all three levels, not just unit tests:

Spec type	Test type	Link role
REQ	QT (qualification test)	verified_by
ARCH	IT (integration test)	verified_by
DDD	UT (unit test)	verified_by

Use specflow generate-tests to create stubs deterministically:

# Generate test stubs for all implemented specs missing verification
uv run specflow generate-tests

# Generate for a specific artifact
uv run specflow generate-tests --from DDD-001

# Preview what would be created
uv run specflow generate-tests --dry-run

Alternatively, create manually:

uv run specflow create \
  --type unit-test \
  --title "Test <DDD function>" \
  --links "[{\"target\": \"DDD-001\", \"role\": \"verified_by\"}]" \
  --body "<test cases>"

Read references/test-pairing.md when you are unsure which test level a given change needs.

Step 5.5: Human-Review Summary

Before running full validation, present a structured summary so the user can catch silent implementation decisions:

## Summary for Human Review

### Key Decisions Made
- Implementation choices not pre-specified by DDD (library/framework picks, file layout)
- Test strategy: how QT / IT / UT are split per story, and where you stopped
- Any deviation from the linked ARCH/DDD and why

### Assumptions That Need Validation
- External dependencies assumed available in test (stubs, fixtures, network) -- risk if wrong: tests pass locally but fail in CI
- Performance/latency assumptions baked into code -- risk if wrong: NFRs silently violated
- Any STORY that was implemented without a linked DDD -- risk if wrong: future changes lack a specification anchor

### Please Review
- For each STORY: does every acceptance criterion map to at least one of UT / IT / QT?
- Any STORY marked `implemented` whose linked ARCH/DDD is still `approved` (not `implemented`)?
- Any code file written that is NOT referenced by a test artifact?

Wait for user acknowledgement before proceeding.

Step 6: Validation

Run full validation after all changes:

uv run specflow artifact-lint

Report results and fix any issues.

Exit message: Report the count of stories marked implemented and tests created (UT/IT/QT). Recommend the next skill -- /specflow-artifact-review.

Step 7: Phase Closure (Optional)

1. After all stories are implemented and validated, offer phase closure: "All planned stories are implemented. Would you like to close this phase and extract prevention patterns?" (Recommended: Not yet, if more work remains, or Yes if the sprint/wave is complete).
2. If the user declines ("not yet", "skip"), do not force closure.
3. If accepted, run uv run specflow done. Options:
   • --no-patterns -- skip prevention-pattern extraction.
   • --auto -- accept defaults without interactive prompts.
4. Engage in a conversational review:
   • Summarize the accomplishments (count of stories, tests).
   • Review any extracted prevention patterns with the user to ensure they are actionable.
   • Recommend archiving or cleaning up any temporary context files from the implementation phase.

Final Exit message: If the phase was closed, recommend the next logical skill: /specflow-ship.

Rules

• Always update status and modified timestamp via specflow update -- never edit artifact files directly.
• Link tests to what they verify using verified_by role.
• Run uv run specflow artifact-lint after status changes.
• When unsure about valid status transitions, read references/status-lifecycle.md.
• When unsure about V-model test pairing, read references/test-pairing.md.

References

• references/status-lifecycle.md -- Valid status transitions for all artifact types.
• references/test-pairing.md -- V-model verification test pairing rules.
• references/wave-computation.md -- Wave computation algorithm and context isolation.
• references/thinking-techniques.md -- Quick execution-stage thinking checks.