Recipe: Adding a New Feature

This recipe walks through the complete SDD workflow for adding a new feature to an existing project. We'll use "adding Stripe payment integration" as the running example.

Prerequisites

• SpecForge installed and configured (Getting Started)
• Project initialized (init_project already run, you have a projectId)

---

Step 1 — Clarify Requirements

Before writing anything, surface the ambiguities.

Prompt:

Use specforge to clarify requirements for adding Stripe payment integration to project proj_abc123

What to expect: A list of 5–10 targeted questions such as:

• Should we support one-time payments, subscriptions, or both?
• What currencies need to be supported?
• Do we need invoice generation?
• How should failed payments be handled — retry logic? notifications?
• What's the refund policy and who can initiate refunds?

Answer these questions in the conversation. SpecForge will incorporate the answers into the spec.

---

Step 2 — Create the Spec

Prompt:

Create a spec for Stripe payment integration in project proj_abc123.
Requirements: one-time payments only, USD and EUR, email receipt on success,
webhook for payment events, admin refund capability.

What to expect: A complete HU.md saved in your project's spec storage with:

• 8–15 acceptance criteria covering the happy path, error cases, and edge cases
• Database schema for payments and payment_events tables
• UI contract for the checkout form component
• ADR hint about idempotency keys for Stripe API calls
• PLAN.md with implementation steps

SpecForge assigns this spec an ID like SPEC-004. Note it.

---

Step 3 — Review and Adjust

Read the generated spec and refine if needed.

Prompt:

Summarize spec SPEC-004 for project proj_abc123

If something is missing or wrong:

Prompt:

Add a criterion to SPEC-004 for project proj_abc123:
"The system must validate card details client-side before sending to Stripe to minimize failed charges"

---

Step 4 — Stress-Test the Spec

Prompt:

Challenge spec SPEC-004 for project proj_abc123

What to expect: SpecForge will probe for:

• What happens if the Stripe webhook arrives before the API response?
• What if the user refreshes during payment? (idempotency)
• What if EUR conversion rate service is unavailable?
• Concurrency: two tabs completing payment simultaneously

Address any gaps found before proceeding.

---

Step 5 — Check Readiness

Prompt:

Check if spec SPEC-004 is ready for implementation in project proj_abc123

This validates:

• All criteria are testable and unambiguous
• No blocking dependencies (e.g., SPEC-001 auth must be done first)
• Constitution compliance

If it passes, you'll see DoR: PASSED. If not, fix what's flagged.

---

Step 6 — Estimate Effort

Prompt:

Estimate spec SPEC-004 for project proj_abc123

What to expect:

Effort: 8–13 story points
Time: 2–4 days (solo dev) / 1–2 days (pair)
Cost: $640–$1,040 at $80/hr
AI token estimate: ~45k tokens
Risk factors: Stripe webhook reliability, idempotency complexity

---

Step 7 — Security Check

Since this spec involves payments:

Prompt:

Run a security check on spec SPEC-004 for project proj_abc123

What to check: OWASP Top 10 mapping, PCI DSS surface area, webhook signature validation, Stripe API key handling.

---

Step 8 — Generate the Execution Plan

Prompt:

Generate an execution plan for spec SPEC-004 in project proj_abc123

This generates a PLAN.md with RED/GREEN/VERIFY steps:

## Phase 1: Foundation (can parallelize 1a, 1b, 1c)
- [ ] 1a: Database migration — create payments + payment_events tables
- [ ] 1b: Define TypeScript interfaces for Stripe payloads
- [ ] 1c: Write failing tests for PaymentService (RED)

## Phase 2: Core Implementation
- [ ] 2a: Implement PaymentService.createCheckoutSession
- [ ] 2b: Implement webhook handler with signature validation
- [ ] 2c: Implement AdminRefundService

## Phase 3: Frontend
- [ ] 3a: Build CheckoutForm component with Stripe Elements
- [ ] 3b: Implement payment status polling/webhook SSE

## Phase 4: Verify
- [ ] 4a: Run full test suite (GREEN + VERIFY)
- [ ] 4b: Test with Stripe test cards
- [ ] 4c: Update spec SPEC-004 status to review

---

Step 9 — Generate Tests

Prompt:

Generate tests for spec SPEC-004 in project proj_abc123

This produces test stubs mapped to each acceptance criterion — ready to be filled in or used as a starting point for TDD.

---

Step 10 — Update Status to In Progress

Prompt:

Update status of spec SPEC-004 to in_progress in project proj_abc123

---

Step 11 — Implement

Use the PLAN.md as your implementation guide. Your AI agent will follow the RED/GREEN/VERIFY cycle. The spec acts as the contract — every acceptance criterion must be met.

---

Step 12 — Validate Implementation

Prompt:

Validate spec SPEC-004 against the code at /Users/me/my-app/src for project proj_abc123

What to expect:

Criterion 1: Payment creation ✅ covered
Criterion 2: Webhook handling ✅ covered
Criterion 3: Refund flow ✅ covered
Criterion 4: Email receipt ⚠️ partially covered — tests missing for failure case
Criterion 5: Currency validation ✅ covered

Coverage: 90% (1 criterion needs attention)

Fix the gap, then re-validate.

---

Step 13 — Mark as Done

Prompt:

Mark spec SPEC-004 as done in project proj_abc123

SpecForge validates the DoD checklist before accepting the transition. Once done, the spec is part of the project's permanent record.

---

Time Summary

Step	Typical time
Clarify + Create	5–15 min
Challenge + Readiness check	5 min
Estimate + Security	3 min
Generate plan + tests	5 min
Implementation	Varies by spec
Validate + Mark done	5 min

The SDD overhead is 20–30 minutes. The payoff is a production-ready spec, a security-checked design, and validation that the implementation matches what was agreed.