feat(build): add /build skill — universal TDD-first feature implementation command
Adds a Cursor slash command that implements any feature end-to-end: deep research → TDD (Red/Green/Refactor) → integration test generation with device pause gate → external setup checklist → verified PR. Includes a FEATURE_REGISTRY covering 7 feature types (notifications, auth, payments, deep links, analytics, storage, camera/media) with per-type test scenarios, external setup steps, and files-to-touch. Stack-aware: adapts to architecture, state management, backend, platforms, and e2e tool from project-brief.yaml. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,242 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user