/project:scaffold#

Stage 4.5: Scaffold — Scaffolds full-stack code via Mason bricks (co-bricks), generates BDD .feature files from PRD Acceptance Criteria, and auto-generates widget + patrol test files via co-test-gen.

Triggers#

• When scaffolding full-stack code structure after Design stage completion
• When generating BDD test scaffolding from PRD Acceptance Criteria
• When bootstrapping a new feature module with Clean Architecture layers

Usage#

/project:scaffold
/project:scaffold --feature community --entity Post
/project:scaffold --skip-bdd
/project:scaffold --skip-tests

Options#

Prerequisites#

• Design stage completed (Solutioning Gate passed)
• Architecture Doc (docs/architecture-{slug}.md) exists
• UX Spec (docs/ux-spec-{slug}.md) exists
• PRD (docs/prd-{slug}.md) with Acceptance Criteria exists

Execution Flow#

Phase 1: Feature Extraction#

Source: cc-pipeline (internal)

1. Parse Architecture Doc (docs/architecture-{slug}.md)

   • Extract feature list from architecture layer definitions
   • Identify primary/secondary entity per feature
   • Map feature → Clean Architecture layers (domain, data, presentation)

2. Parse UX Spec (docs/ux-spec-{slug}.md)

   • Extract screen list per feature (list, detail, form, etc.)
   • Identify screen-to-feature mapping

3. Parse PRD (docs/prd-{slug}.md)

   • Extract Acceptance Criteria per feature
   • Map AC → Gherkin-ready scenario descriptions

4. Build Feature Manifest

       features:
     - name: community          # snake_case
       primary_entity: Post      # PascalCase
       secondary_entity: Comment # PascalCase (optional)
       screens: [list, detail, form]
       acceptance_criteria:
         -  " User can view post list " 
          -  " User can create new post " 
          -  " User can add comment to post " 
        brick_match: feature-community  # Auto-matched from 27 app bricks
   

Phase 2: Brick Scaffolding#

Source: cc-bricks-feature

For each feature in the manifest:

1. Brick matching — Match feature name to closest available brick from 27 app bricks + 29 console bricks

   • Exact match: community → feature-community
   • Keyword match: messaging → feature-chat
   • Fallback: use generic feature structure

2. Run Mason brick per feature

       mason make feature-{brick_name} \
     --project_name {project_name} \
     --org_name {org_name} \
     --org_tld {org_tld} \
     --feature_name {feature_name}
   

3. Verify scaffolded output

       feature/application/{feature_name}/
   ├── lib/src/
   │   ├── domain/        # Entity, UseCase, Repository Interface
   │   ├── data/          # Repository impl, Cache, OpenAPI Mixin
   │   ├── presentation/  # BLoC, Page, Widgets
   │   ├── route/         # GoRouter TypedRoute
   │   └── di/            # Dependency Injection
   └── test/src/          # Test directory structure
   
   backend/{project}_server/feature/{feature_name}/
   ├── model/             # .spy.yaml models
   ├── endpoint/          # CRUD handlers
   ├── service/           # Business logic
   ├── exception/         # Domain exceptions
   └── validation/        # Input validation
   

4. Commit: "feat({scope}): scaffold {feature_name} via mason brick"

Phase 3: BDD Scenario Generation#

Source: cc-flutter-dev (bdd-scenario-agent)

For each feature with screens:

1. Generate .feature files from PRD Acceptance Criteria

       /bdd:generate {feature_name} \
     --entity-name {PrimaryEntity} \
     --screens  " {screen_list} "   \
     --builder dual \
     --run-build true
   

2. co-test-gen build_runner generates dual test files

       dart run build_runner build --delete-conflicting-outputs
   

   Output per feature:

   • test/src/bdd/{feature}.feature — Gherkin scenarios
   • test/src/bdd/{feature}.widget_test.dart — Auto-generated (DO NOT MODIFY)
   • test/src/bdd/{feature}.patrol_test.dart — Auto-generated (DO NOT MODIFY)
   • test/src/bdd/step/ — Step function stubs (to be implemented in Development)

3. Step stub generation — Create skeleton step functions with TestDriver API

   /// Usage: Given I am on the post list page
   /// Purpose: Navigate to post list page
   Future<void> iAmOnThePostListPage(TestDriver driver) async {
     // TODO: Implement step - scaffold generated stub
     throw UnimplementedError('Step not yet implemented');
   }
   

4. Commit: "test({scope}): generate BDD scenarios and test stubs for {feature_name}"

Phase 4: Scaffold Gate#

Scaffold Gate verification per feature:

Gate fails if any check does not pass. Scaffold is revised with feedback.

Artifacts#

feature/application/{feature_name}/     # Scaffolded feature code (per feature)
backend/{project}_server/feature/{name}/ # Scaffolded backend code (per feature)
test/src/bdd/{feature}.feature           # BDD feature files
test/src/bdd/{feature}.widget_test.dart  # Auto-generated widget tests
test/src/bdd/{feature}.patrol_test.dart  # Auto-generated patrol tests
test/src/bdd/step/                       # Step function stubs

After Completion#

• Verify Scaffold Gate passed
• Update .pipeline/{slug}.yaml state
• Present context-clear handoff:

✅ Scaffold stage complete (Scaffold Gate PASSED).
  - {N} features scaffolded via Mason bricks
  - {M} .feature files generated
  - {K} widget + patrol test files auto-generated
  - {S} step function stubs created (to be implemented in Development)

**Option 1 (Recommended)**: Clear context and continue to Epic Creation
  /clear
  Then run: /project:epic

**Option 2**: Continue in current context
  Proceed directly to /project:epic

Notes#

• Step function stubs are intentionally unimplemented (throw UnimplementedError) — they become the DoD for each Story in the Development stage
• The BDD Coverage Gate (Step 8.3 in /dev:run) will enforce that all step stubs are implemented before PR creation
• Brick selection uses a best-match heuristic; use --brick to override if the auto-match is incorrect
• For features without a matching brick, the scaffold phase creates a minimal Clean Architecture directory structure