| name | spec-driven-dev |
| description | Spec-driven development pattern for Power Platform. Use when: planning non-trivial projects, writing master specifications, splitting component specs, defining build order, requirements documents, design documents, specification templates. |
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
| Spec File | Contains | Built By |
|---|
spec-tables.md | Tables, columns, relationships, option sets, alternate keys | Scott (Web API) |
spec-views-forms.md | System views, main forms, quick view forms | Scott (Web API) |
spec-app.md | App module, sitemap, navigation | Scott (Web API) |
spec-flows.md | Cloud flows, triggers, actions, error handling | Scott (Power Automate) |
spec-plugins.md | Plugin steps, messages, stages, logic | Scott (C# + registration) |
spec-code-app.md | React components, hooks, routes, state management | Scott (pac code) |
spec-pcf.md | PCF control manifest, properties, rendering | Scott (pac pcf) |
spec-security.md | Security roles, column security profiles, BU structure | Scott (Web API) |
spec-web-resources.md | Form scripts, ribbon customizations, HTML web resources | Scott (Web API) |
spec-integration.md | Custom connectors, Azure Functions, webhooks | Scott |
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:
- Does it reference a table or column? -> Must wait for schema (Phase 1)
- Does it reference a form or view? -> Must wait for UI (Phase 2)
- Does it reference the app module? -> Must wait for app shell (Phase 3)
- Does it have no schema dependencies? -> Can run in parallel (Phase 4)
Spec-to-Build Handoff
What Laura Passes to Scott
- The component spec file (complete, with all details)
- The solution unique name and publisher prefix
- The environment URL and auth method
- Any decisions flagged as "PERMANENT" (table names, column types, ownership)
What Scott Needs Before Starting
What Scott Delivers
Verification
How Razor Validates Implementation Against Spec
For each component spec, Razor checks:
- Completeness — Every item in the spec exists in the environment
- Correctness — Column types, relationship cascade configs, view filters match spec
- Solution membership — All components are in the correct solution (not Default)
- Naming compliance — All logical names follow naming conventions
- Security — Roles and column security match the security model
- 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)
| ID | User Story | Priority | Acceptance Criteria |
|---|
| FR-001 | As a support agent, I want to log a new case with customer details and description | Must | Given I am on the case form, When I fill required fields and save, Then a case record is created with status "New" and auto-numbered case ID |
| FR-002 | As a support manager, I want to see all cases approaching SLA breach | Must | Given cases have an SLA deadline, When I open the "SLA At Risk" view, Then I see cases where deadline is within 4 hours and status is not "Resolved" |
| FR-003 | As a customer, I want to check my case status on a portal | Should | Given I am logged into the portal, When I navigate to "My Cases", Then I see my open cases with status and last update date |
Data Model (4 tables)
| Table | Ownership | Key Columns | Relationships |
|---|
| contoso_case | User | case_number (autonumber), title, description, status, priority, sla_deadline | Lookup to contact, lookup to contoso_category |
| contoso_category | Organization | name, sla_hours, escalation_team | 1:N to contoso_case |
| contoso_caseactivity | User | activity_type, notes, created_by | Lookup to contoso_case |
| contact | User | (standard) | 1:N to contoso_case |
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
| Phase | Agent | Skills Loaded |
|---|
| Planning | Laura | architecture, spec-driven-dev |
| Architecture | Sean | architecture, dataverse, security, power-pages |
| Build (schema) | Scott | dataverse-web-api |
| Build (UI) | Scott | dataverse-web-api (customizations) |
| Build (flows) | Scott | power-automate |
| Build (portal) | Scott | power-pages |
| Review | Razor | dataverse, power-automate, security, power-pages |
| Infrastructure | Parvez | alm, env-strategy |
| UAT | Ava | testing |
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
| Spec Requirement | Given | When | Then |
|---|
| FR-001: Log new case | Agent is on case form | Agent fills title, description, priority, customer and saves | Case record created with status "New", auto-number assigned, SLA deadline calculated |
| FR-002: SLA at-risk view | 3 cases exist: 1 within SLA, 1 within 4 hours of breach, 1 already breached | Manager opens "SLA At Risk" view | Only the 2 at-risk/breached cases appear; case within SLA is not shown |
| FR-003: Portal case status | Customer has 2 open cases and 1 closed case | Customer logs into portal and opens "My Cases" | 2 open cases shown with status and last update; closed case not shown |
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 specsarchitecture -- Sean's skill for designing the architecture that specs describealm -- ALM strategy section of the master specsecurity -- Security model section of the master spectesting -- Test plans derived from acceptance criteria
