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

// 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)

Generated alongside /build (same cursor_gen bundle) for lifecycle support:

• /debug (debug-issue skill) — structured BugReport + evidence before fixes; use when Phase 6 checks fail with unclear errors or weak reproduction.
• /verify (verify-change skill) — pasted-evidence gate for tests/analyze/hooks without walking the full seven-phase build doc; use for small PRs or post-fix sanity checks.
• /explain (explain-code skill) — read-only walkthrough of code paths; use when research needs human answers about runtime or native behavior before implementation.

The generated build skill template also cross-links Phase 3 (TDD loop) and Phase 6 (verification failures) to /debug and /verify so agents escalate without re-reading the full seven-phase doc.

---

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