cursor_gen/docs/superpowers/specs/2026-05-14-build-skill-design.md

# Design Spec: /build Skill — Universal Feature Implementation Command

**Date:** 2026-05-14  
**Status:** Draft — Awaiting user review  
**Scope:** A single Cursor slash command that orchestrates the full feature development lifecycle

---

## 1. Problem Statement

Today, implementing any feature (notifications, auth, payments, etc.) requires the user to manually:
- Specify TDD in the prompt
- Remember to include integration test scenarios
- Know which external services need configuring
- Know which files to touch for their specific stack
- Invoke the right skills in the right order

This leads to inconsistent implementations, missed test scenarios, and forgotten native setup steps.

**Goal:** One command — `/build implement [anything]` — that handles everything from research through PR, following every rule, skill, hook, and architecture pattern defined in the project.

---

## 2. Decision

**Form:** Cursor slash command skill file (`.md.tmpl` inside the generator's template system)  
**Scope:** Universal + context-aware (reads `project-brief.yaml` to adapt behavior)  
**Integration test gate:** Auto-generate `integration_test/` files + pause for device run

---

## 3. Architecture

### 3.1 File Placement

```
flutter-cursor-templates/
  generator/
    templates/
      skills/
        build/
          SKILL.md.tmpl          ← The skill (single new file)
    test/
      golden/
        bloc-clean-firebase/skills/build/SKILL.md
        riverpod-ff-supabase/skills/build/SKILL.md
        getx-mvc-rest/skills/build/SKILL.md
```

The generator renders this to `.cursor/skills/build/SKILL.md` in the user's project — same pattern as every other skill.

### 3.2 Template Variables

| Placeholder | Source in project-brief.yaml |
|---|---|
| `{{PROJECT_NAME}}` | `project.name` |
| `{{ARCHITECTURE}}` | `stack.architecture` |
| `{{STATE_MANAGEMENT}}` | `stack.state_management` |
| `{{ROUTING}}` | `stack.routing` |
| `{{BACKEND}}` | `stack.backend` |
| `{{PLATFORMS_LIST}}` | `stack.platforms` |
| `{{CODEGEN_LIST}}` | `stack.codegen` |
| `{{TESTING_DEPTH}}` | `testing.depth` |
| `{{E2E_TOOL}}` | `testing.e2e_tool` |
| `{{FEATURES_LIST}}` | `features.modules` |
| `{{SPECIAL_FEATURES}}` | `features.special` |
| `{{FLAVORS_LIST}}` | `environments.flavors` |
| `{{CICD_TOOL}}` | `environments.cicd` |
| `{{PACKAGE_ID}}` | `project.package` |

Conditional blocks: `{{#if backend_firebase}}`, `{{#if platforms_ios}}`, `{{#if platforms_android}}`, `{{#if codegen_freezed}}`, `{{#if codegen_injectable}}`, `{{#if special_push_notifications}}`, `{{#if special_deep_linking}}`

---

## 4. The 7 Phases

### Phase 1: Context Loading
1. Read `project-brief.yaml` — extract stack, platforms, existing features
2. Parse user's request → match against FEATURE_REGISTRY keywords
3. Print context summary table (feature type, stack, platforms, rules loaded)
4. If feature already in `features.modules`, confirm extending vs. rebuilding

### Phase 2: Deep Research
1. Enumerate required packages + correct versions for current Flutter stable
2. Build complete file manifest: new files (by architecture pattern) + modified files
3. List all external service configuration required per platform
4. Print research results before touching any file

### Phase 3: TDD Implementation
**Invokes: `superpowers:test-driven-development`**

- **Red:** Write all failing unit + widget tests from FEATURE_REGISTRY scenarios. Run to confirm red. Show actual output.
- **Green:** Implement domain → data → presentation layers. Run tests to green. Show actual output.
- **Refactor:** Clean up per `flutter-core.mdc`. Run `flutter analyze`. Show output.

### Phase 4: Integration Test Generation
1. Create `integration_test/[feature_type]/` directory
2. Generate one test file per logical scenario cluster
3. Each file: standard boilerplate with `IntegrationTestWidgetsFlutterBinding` (or Patrol if `{{E2E_TOOL}} = patrol`)
4. Generate `integration_test/[feature]/README.md` — test matrix with run commands

**PAUSE GATE:** Print table of all integration test files, what they cover, whether hardware is required, and the exact `flutter test` commands. Wait for user to paste device output before Phase 6.

### Phase 5: External Setup Checklist
- Grouped by service/platform (Firebase, iOS, Android, backend)
- iOS/Android: table format — Step | Where | What | How to Verify
- Console steps: numbered checklist with exact menu paths and URLs

### Phase 6: Verification Gate
**Invokes: `superpowers:verification-before-completion`**

Required evidence (real output pasted by user):
- `flutter test test/features/[feature]/ --no-pub` → all tests pass
- `flutter analyze` → no issues
- Integration test device output from Phase 4
- `lefthook run pre-commit` → all hooks pass

If any failure: invoke `superpowers:systematic-debugging` before retrying.

### Phase 7: PR Preparation
**Invokes: `superpowers:finishing-a-development-branch`**

- Conventional commit: `feat([feature_type]): implement [feature] end-to-end`
- PR description: what built, test count, integration test matrix, external setup status
- CI/CD advice for `{{CICD_TOOL}}` (secret scoping per flavor)

---

## 5. FEATURE_REGISTRY

Seven feature types with full metadata:

| Feature Type | Keywords (sample) | Packages | Integration Test Scenarios |
|---|---|---|---|
| `notifications` | notification, push, FCM, APNs | firebase_messaging, flutter_local_notifications | foreground/background/killed receipt, tap redirect in all 3 states, payload parsing |
| `auth` | login, sign in, biometric, OAuth, JWT | firebase_auth, local_auth, flutter_secure_storage | full login flow, biometric + fallback, token refresh, cold start with session |
| `payments` | payment, Stripe, IAP, checkout | flutter_stripe, purchases_flutter | test-card checkout, 3DS, Apple/Google Pay, subscription restore |
| `deep_links` | deep link, universal link, app link | app_links, go_router | cold/background/foreground link handling, auth-guarded routes |
| `analytics` | analytics, event, tracking, screen view | firebase_analytics, mixpanel_flutter | event triggered on action, screen view on nav, opt-out disables tracking |
| `storage` | file upload, Firebase Storage, Hive, Isar | firebase_storage, isar, drift | upload + retrieve, offline cache, background upload restore |
| `camera_media` | camera, photo, QR, barcode, video | camera, image_picker, mobile_scanner | photo capture, gallery pick, QR decode, permission denied UI |

Each entry also specifies: `rules_to_load`, `files_to_touch` (new + modified), `external_setup` (per service/platform), `unit_test_scenarios`, `widget_test_scenarios`.

---

## 6. Integration Test Template Structure

```dart
// integration_test/[feature]/[scenario]_test.dart
// Generated by /build — {{PROJECT_NAME}}
// Run: flutter test integration_test/[feature]/[scenario]_test.dart -d <device_id>

import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';
import 'package:{{PACKAGE_ID}}/main.dart' as app;

void main() {
  IntegrationTestWidgetsFlutterBinding.ensureInitialized();

  group('[FeatureType] — [Scenario Name]', () {
    setUp(() async { /* seed state / reset storage */ });
    tearDown(() async { /* cleanup */ });

    testWidgets(
      'given [precondition], when [action], then [expected outcome]',
      (tester) async {
        app.main();
        await tester.pumpAndSettle();
        // test body
      },
    );
  });
}
```

For `{{E2E_TOOL}} = patrol`: imports swap to `package:patrol`, uses `$` Patrol selector syntax.

---

## 7. Skill File Sections (exact headings)

```
# Build — {{PROJECT_NAME}}
## Usage
## FEATURE_REGISTRY
## Phase 1: Context Loading
## Phase 2: Deep Research
## Phase 3: TDD Implementation
## Phase 4: Integration Test Generation
## Phase 5: External Setup Checklist
## Phase 6: Verification Gate
## Phase 7: PR Preparation
## Rules applied every phase
## Code generation notes
```

---

## 8. Cross-Skill Orchestration

The `/build` skill orchestrates existing skills internally:
- Invokes `/scaffold-feature` patterns to create the initial file skeleton (Phase 3b)
- Borrows `/generate-tests` naming and structure conventions (Phase 3a)
- Invokes `/generate-api-client` if `api_docs.format != none` and feature needs API (Phase 2)
- References `/deploy` checklist for flavor-scoped secret handling (Phase 7)

---

## 9. Rules Applied Every Phase

Always active (no conditional):
- `.cursor/rules/flutter-core.mdc`
- `.cursor/rules/security-standards.mdc`
- `.cursor/rules/project-context.mdc`
- Feature-type rules from `FEATURE_REGISTRY.rules_to_load`

---

## 10. Enhancements / Out of Scope for V1

- Reference project URL fetching and pattern extraction (Phase 1) — included in V1
- Multi-feature requests spanning 2+ feature types — detect and prompt decomposition
- Automatic CI secret rotation advice — Phase 7, advisory only
- Web platform integration test support — flagged as TODO in generated README
- Visual companion for architecture diagrams — post-V1

---

## 11. Verification

End-to-end test of the skill:

1. Run `cursor_gen --wizard` on a test project → choose `bloc/clean/firebase` stack
2. Confirm `.cursor/skills/build/SKILL.md` is generated
3. In Cursor, type `/build implement notification module end-to-end`
4. Verify Phase 1 prints correct context table from project-brief.yaml
5. Verify Phase 3 tests are red before implementation, green after
6. Verify Phase 4 generates `integration_test/notifications/` with 10 test files
7. Verify Phase 5 checklist lists Firebase Console + APNs steps
8. Verify Phase 6 requires real output before proceeding
9. Run golden tests: `dart test test/generator_test.dart` — all stacks must match golden SKILL.md