Skill: Spec-Driven Development

When to Use

Trigger when planning non-trivial Power Platform projects that need structured requirements, component specifications, dependency ordering, and coordinated multi-agent builds. Also trigger when the user mentions "spec", "specification", "master spec", "component spec", "requirements document", or "design document".

Philosophy

Spec before code. Every build has three parts:

• Spec (what) — the requirement and design document
• Agent (who) — Laura plans, Sean designs, Scott builds, Razor reviews
• Skill (how) — the technical knowledge loaded for the task

Without a spec, agents build what they assume. With a spec, agents build what was agreed.

Master Spec Structure

The master specification is the single source of truth for a project. Laura generates it during the planning phase, Sean refines the technical sections.

# [Project Name] — Master Specification

## 1. Project Overview
- Business problem being solved
- Target users and their roles
- Success criteria (measurable outcomes)
- Constraints (timeline, budget, licensing, compliance)

## 2. Functional Requirements
| ID | Requirement | Priority | Acceptance Criteria |
|----|-------------|----------|---------------------|
| FR-001 | [Requirement description] | Must | Given [context], When [action], Then [outcome] |
| FR-002 | ... | Should | ... |

## 3. Non-Functional Requirements
- Performance targets (page load, query response, concurrent users)
- Accessibility standard (WCAG 2.2 AA minimum)
- Browser/device support matrix
- Data retention and archival policy
- Availability target (uptime SLA)

## 4. Data Model
- Entity Relationship Diagram (Mermaid erDiagram)
- Table descriptions with ownership type and key columns
- Relationship descriptions with cascade behavior
- Option set definitions (with specific values)

## 5. Security Model
- User roles and permission levels
- Row-level security strategy (BU hierarchy, team ownership)
- Column-level security (sensitive fields)
- App-level security (Conditional Access, Managed Environments)

## 6. Integration Points
- External systems and data flow direction
- Authentication method per integration
- Error handling and retry strategy
- Data transformation requirements

## 7. ALM Strategy
- Environment topology (dev/test/UAT/prod)
- Solution segmentation (single vs multi-solution)
- CI/CD pipeline approach
- Deployment approval gates

## 8. Component Inventory
| Component | Type | Agent | Spec File | Dependencies |
|-----------|------|-------|-----------|--------------|
| [Tables + Columns] | Dataverse schema | Scott | spec-tables.md | None |
| [Views + Forms] | Customizations | Scott | spec-views-forms.md | Tables |
| [App Module] | MDA | Scott | spec-app.md | Views, Forms |
| [Flows] | Power Automate | Scott | spec-flows.md | Tables |
| ... | ... | ... | ... | ... |

Component Spec Splitting

The master spec is split into buildable component specs. Each component spec is a self-contained document that Scott can execute without referring back to the master spec.

Standard Component Specs

Component Spec Template

# Component Spec: [Component Name]

## Overview
[What this component does and why it exists]

## Dependencies
- Requires: [list of components that must exist before this one]
- Required by: [list of components that depend on this one]

## Detailed Requirements

### [Requirement Group 1]
[Specific implementation details — exact column names, data types, values]

### [Requirement Group 2]
[...]

## Acceptance Criteria
- [ ] [Specific, testable criterion]
- [ ] [...]

## Notes
[Edge cases, constraints, decisions made during design]

Dependency Ordering

Build Order (Sequential)

Components must be built in dependency order. The standard order is:

Phase 1: Foundation (sequential, blocking)
  1. Publisher + Solution
  2. Tables (all tables, no columns beyond primary name)
  3. Columns (all columns for all tables)
  4. Relationships (all relationships — tables must exist first)

Phase 2: UI Components (can be parallelized per table)
  5. Views (reference columns — columns must exist)
  6. Forms (reference columns — columns must exist)
  7. Business rules (reference columns)

Phase 3: App Shell (sequential)
  8. App module
  9. Sitemap
  10. PublishAllXml

Phase 4: Independent Components (fully parallel)
  11. Web resources
  12. PCF controls
  13. Plugin assemblies
  14. Power BI reports
  15. Connection references
  16. Environment variables

Phase 5: Dependent Components (after schema + app exist)
  17. Flows (need tables + connection refs)
  18. Security roles (need tables)
  19. Dashboards

Identifying Parallel Work

Ask these questions for each component:

1. Does it reference a table or column? -> Must wait for schema (Phase 1)
2. Does it reference a form or view? -> Must wait for UI (Phase 2)
3. Does it reference the app module? -> Must wait for app shell (Phase 3)
4. Does it have no schema dependencies? -> Can run in parallel (Phase 4)

Spec-to-Build Handoff

What Laura Passes to Scott

1. The component spec file (complete, with all details)
2. The solution unique name and publisher prefix
3. The environment URL and auth method
4. Any decisions flagged as "PERMANENT" (table names, column types, ownership)

What Scott Needs Before Starting

• Component spec is marked as "APPROVED" by Sean
• All dependency components are built (check dependency list)
• Solution exists in the target environment
• Authentication is working (Azure CLI token or service principal)

What Scott Delivers

• All components created via Web API (with MSCRM.SolutionUniqueName header)
• PublishXml called for any UI customizations
• Self-review checklist completed
• Ready for Razor review

Verification

How Razor Validates Implementation Against Spec

For each component spec, Razor checks:

1. Completeness — Every item in the spec exists in the environment
2. Correctness — Column types, relationship cascade configs, view filters match spec
3. Solution membership — All components are in the correct solution (not Default)
4. Naming compliance — All logical names follow naming conventions
5. Security — Roles and column security match the security model
6. Publishability — All customizations are published and accessible

Verification queries (Web API)

# Check all components in solution
GET /api/data/v9.2/solutioncomponents
  ?$filter=_solutionid_value eq [solution-guid]
  &$select=componenttype,objectid

# Check table exists with correct columns
GET /api/data/v9.2/EntityDefinitions(LogicalName='prefix_tablename')
  ?$expand=Attributes($select=LogicalName,AttributeType,RequiredLevel)

# Check views exist
GET /api/data/v9.2/savedqueries
  ?$filter=returnedtypecode eq 'prefix_tablename'
  &$select=name,fetchxml,layoutxml

Anti-Patterns

• Building without a spec — "Just start coding" leads to rework when requirements were ambiguous
• Monolithic spec — One giant document that no agent can fully consume. Split into component specs.
• Spec without acceptance criteria — If you can't test it, you can't verify it
• Skipping dependency ordering — Creating views before columns exist causes silent failures
• Not marking permanent decisions — Table names and column types need explicit user confirmation
• Spec drift — Spec says one thing, implementation does another. Razor catches this.

Executable Master Spec Template

Copy-paste this template to start a new project specification:

# [Project Name] -- Master Specification

## Project Overview
- **Business problem:** [What pain point does this solve?]
- **Target users:** [Role 1 (X users), Role 2 (Y users)]
- **Success criteria:** [Measurable outcome 1], [Measurable outcome 2]
- **Timeline:** [Target go-live date]
- **Licensing:** [Power Apps Premium / per-app / existing entitlements]

## Stakeholders
| Name | Role | Responsibility | Sign-off authority? |
|---|---|---|---|
| [Name] | Product Owner | Requirements, UAT approval | Yes |
| [Name] | IT Admin | Environment, licensing, DLP | Yes |
| [Name] | End User Rep | Acceptance testing | No |

## Functional Requirements
| ID | User Story | Priority | Acceptance Criteria |
|---|---|---|---|
| FR-001 | As a [role], I want to [action], so that [outcome] | Must | Given [context], When [action], Then [outcome] |
| FR-002 | ... | Should | ... |
| FR-003 | ... | Could | ... |

## Non-Functional Requirements
- **Performance:** Page load < 3s, query response < 2s, support X concurrent users
- **Accessibility:** WCAG 2.2 AA compliance
- **Browser support:** Edge, Chrome (latest 2 versions)
- **Data retention:** [X years, then archive/delete]
- **Availability:** [99.9% during business hours]

## Data Model Summary
[Mermaid erDiagram or table list with key columns, relationships, ownership type]

## Integration Points
| System | Direction | Method | Auth | Error Handling |
|---|---|---|---|---|
| [System A] | Inbound | Custom Connector / HTTP | OAuth 2.0 | Retry 3x, then queue |
| [System B] | Outbound | Power Automate flow | Service Principal | Dead letter table |

## Security Requirements
- Roles: [Role 1 -- CRUD on own records], [Role 2 -- Read all, Create own]
- Row-level security: [BU hierarchy / Team ownership / None]
- Column security: [SSN, salary columns restricted to Role X]
- Authentication: [Entra ID, conditional access required]

## Build Order (Dependency Graph)
1. Publisher + Solution
2. Tables (schema only, primary name columns)
3. Columns (all columns for all tables)
4. Relationships (lookups, N:N)
5. Option sets (global and local)
6. Views + Forms
7. Security roles + column security profiles
8. Flows (after tables + connection references exist)
9. App module + sitemap
10. PublishAllXml

## Acceptance Criteria Summary
[Each FR maps to a testable Given/When/Then that Ava uses for UAT scripts]

Worked Example: Case Management

A simplified spec showing how the template maps to real requirements.

Project Overview

• Business problem: Support team tracks cases in spreadsheets. No visibility, no SLAs, no escalation.
• Target users: Support Agents (15), Support Managers (3), Customers (external portal)
• Success criteria: 90% of cases resolved within SLA, manager dashboard shows real-time status

User Stories (3 examples)

Data Model (4 tables)

Build Order

1. Publisher (contoso) + Solution (CaseManagement)
2. Tables: contoso_case, contoso_category, contoso_caseactivity
3. Columns: all columns per table
4. Relationships: case->contact, case->category, caseactivity->case
5. Views: "Active Cases", "My Cases", "SLA At Risk", "Cases by Category"
6. Forms: Case main form (3 tabs), Category quick create
7. Security roles: "Support Agent" (CRUD own cases), "Support Manager" (Read all, manage team)
8. Flows: "Set SLA Deadline on Create", "Escalate SLA Breach", "Notify Customer on Update"
9. App module: "Case Management" with sitemap
10. PublishAllXml

Agent Delegation

Spec-to-Acceptance-Criteria Mapping

Every functional requirement in the spec maps to a testable Given/When/Then statement that Ava uses to generate UAT scripts.

Mapping Pattern

Spec Requirement (FR-XXX)
  -> Given/When/Then (acceptance criteria)
    -> UAT Script Step (Ava generates)
      -> Pass/Fail (Ava records during UAT)

Example Mappings

Ava's UAT Script Format

## UAT Script: FR-001 -- Log New Case

**Preconditions:**
- Logged in as user with "Support Agent" role
- At least 1 contact record exists

**Steps:**
1. Navigate to Case Management app
2. Click "+ New Case"
3. Fill: Title = "Test Case 001", Description = "Test description"
4. Set Priority = "High", Customer = [existing contact]
5. Click Save

**Expected Results:**
- [ ] Case record is created
- [ ] Case Number is auto-generated (format: CASE-XXXXX)
- [ ] Status = "New"
- [ ] SLA Deadline is set to [now + category SLA hours]
- [ ] Created By = current user
- [ ] Owner = current user

Related Skills

• dataverse-web-api -- Primary build tool for executing specs
• architecture -- Sean's skill for designing the architecture that specs describe
• alm -- ALM strategy section of the master spec
• security -- Security model section of the master spec
• testing -- Test plans derived from acceptance criteria