---
name: architect-app
description: Architecture review team for Dataverse Model-Driven App projects. Spawns parallel specialist agents (Data Architect, Field Matrix Analyst, Forms/UX Designer, Security Architect) to validate and refine extracted requirements into a buildable specification. Filters OOB entities, validates field types, designs form layouts, and produces a comprehensive build spec + human-reviewable field matrix.
argument-hint: "[project-runs-dir]"
---

# Architecture Review Team

Validate and refine extracted requirements through a multi-perspective Dataverse architecture review. Produces a build-specification.json that precisely defines every artifact to create.

## Arguments

- `$ARGUMENTS[0]` — Path to project runs directory (e.g., `./project-runs/sba-cash-app/`)

## Prerequisites

- `_hierarchy_plan.json` must exist in the project directory (from Phase 1 extraction)
- All `batch-*.json` files must exist (for full requirement details)

## Overview

```
Input: _hierarchy_plan.json + batch-*.json files
  ↓
Parallel specialist agents (4 agents simultaneously)
  ↓
Consolidation lead merges all reviews
  ↓
Output: build-specification.json + field-matrix.md
```

---

## Dataverse OOB Entity Knowledge

These standard entities exist in every Dataverse environment and do NOT need table creation PBIs. However, custom columns/forms/views on these entities DO need PBIs.

### Standard Entities (Do Not Create)

| Logical Name | Display Name | Notes |
|---|---|---|
| `account` | Account | Company/organization records |
| `contact` | Contact | People records |
| `lead` | Lead | Sales leads |
| `opportunity` | Opportunity | Sales opportunities |
| `incident` | Case | Customer service cases |
| `activitypointer` | Activity | Base activity entity |
| `task` | Task | Activity subtype |
| `email` | Email | Activity subtype |
| `phonecall` | Phone Call | Activity subtype |
| `appointment` | Appointment | Activity subtype |
| `annotation` | Note | Attachments/notes |
| `systemuser` | User | Dataverse users |
| `team` | Team | Security teams |
| `businessunit` | Business Unit | Org hierarchy |
| `queue` | Queue | Work routing |
| `knowledgearticle` | Knowledge Article | KB articles |
| `product` | Product | Product catalog |
| `pricelevel` | Price List | Pricing |
| `quote` | Quote | Sales quotes |
| `salesorder` | Order | Sales orders |
| `invoice` | Invoice | Billing |
| `connection` | Connection | Entity relationships |
| `goal` | Goal | Performance goals |
| `metric` | Goal Metric | Goal metrics |

### What This Means for PBI Creation

- **OOB table exists, no customization needed** → No PBI at all
- **OOB table needs custom columns** → PBI: "Add custom fields to [table]" (not "Create [table]")
- **OOB table needs custom form** → PBI: "Create [purpose] form for [table]"
- **OOB table needs custom views** → PBI: "Create [view name] view for [table]"
- **Fully custom table** → PBI: "Create [table] table" (full creation PBI)

---

## Specialist Agent Definitions

### Agent 1: Data Architect

Spawn as a **background subagent**:

> You are a Dataverse Data Architect. Review the extracted requirements hierarchy and validate the data model design.
>
> **Read these files:**
> - `{project_dir}/_hierarchy_plan.json` — Hierarchy of requirements
> - All `{project_dir}/batch-*.json` — Full requirement details
>
> **Your review tasks:**
>
> 1. **OOB Entity Filtering:**
>    - Identify any proposed tables that are standard Dataverse OOB entities (Account, Contact, Lead, Opportunity, Case, Task, Email, etc.)
>    - For OOB entities: Remove "Create table" requirements, KEEP custom column/form/view requirements
>    - Flag each table as `is_oob: true/false`
>
> 2. **Table Design Validation:**
>    - Are table names following conventions? (singular, PascalCase schema names)
>    - Is the primary column choice appropriate for each table?
>    - Are there tables that should be merged (too granular)?
>    - Are there tables that should be split (too broad/doing too many things)?
>    - Is ownership type correct? (User-owned for most, Organization-owned for reference data)
>
> 3. **Relationship Validation:**
>    - Are all 1:N relationships correctly identified? (parent has many children)
>    - Are N:N relationships needed anywhere? (many-to-many)
>    - Are polymorphic lookups needed? (Customer type = Account OR Contact)
>    - Cascade behavior: what happens on delete/assign/share?
>    - Are there circular reference risks?
>    - Are self-referential relationships needed? (e.g., parent Account → child Account)
>
> 4. **Missing Standard Patterns:**
>    - Does every custom table have a clear primary column?
>    - Are status/statecode fields properly planned with custom values?
>    - Are audit requirements captured? (which tables need auditing enabled?)
>    - Are alternate keys needed? (external system IDs, natural keys)
>    - Are there calculated/rollup columns needed?
>
> **Output:** Write to `{project_dir}/_review_data_architect.json`:
> ```json
> {
>   "reviewed_at": "ISO timestamp",
>   "tables": [
>     {
>       "logical_name": "proposed_or_oob_name",
>       "display_name": "Display Name",
>       "is_oob": false,
>       "create_table": true,
>       "ownership_type": "UserOwned",
>       "primary_column": "name field",
>       "notes": "any review notes",
>       "action": "keep|merge_into|split|remove"
>     }
>   ],
>   "relationships": [
>     {
>       "type": "OneToMany",
>       "parent": "table_a",
>       "child": "table_b",
>       "lookup_name": "proposed_lookupid",
>       "cascade_delete": "RemoveLink",
>       "notes": "relationship rationale"
>     }
>   ],
>   "issues": [
>     { "severity": "high|medium|low", "entity": "table_name", "issue": "description", "recommendation": "what to do" }
>   ],
>   "missing_items": [
>     { "category": "Tables|Relationships|Keys", "title": "what's missing", "recommendation": "add this" }
>   ]
> }
> ```
>
> **Rules:**
> - Be opinionated — flag bad patterns, don't just rubber-stamp
> - Every custom table must justify its existence (not just "mentioned in a doc")
> - Think about query performance: heavily filtered tables need proper views
> - Write output to file. Keep text response SHORT (summary + issue count only).

### Agent 2: Field Matrix Analyst

Spawn as a **background subagent**:

> You are a Dataverse Field Matrix Analyst. Review ALL proposed fields across ALL tables and produce a comprehensive field matrix.
>
> **Read these files:**
> - `{project_dir}/_hierarchy_plan.json`
> - All `{project_dir}/batch-*.json`
>
> **Your review tasks:**
>
> 1. **Field Type Validation:**
>    - String: Is max_length appropriate? (100 for names, 200 for descriptions, 2000 for URLs, Memo for long text)
>    - Number: Integer vs Decimal vs Currency vs Float? Precision appropriate?
>    - Choice: Should it be local (table-specific) or global (reused across tables)?
>    - Lookup: Target entity correct? Polymorphic needed?
>    - Date: Date-only vs DateTime? Time zone behavior?
>    - Boolean: Default value appropriate?
>    - Auto-number: Format string defined?
>
> 2. **Option Set Consolidation:**
>    - Identify choice fields across ALL tables that use the same or similar values
>    - Recommend global option sets for any choice reused by 2+ tables
>    - Define complete option value lists with integer values (starting at publisher prefix range)
>    - Validate status/statecode custom values
>
> 3. **Field Completeness Check:**
>    - Does every table have all fields needed by its forms and views?
>    - Are calculated/rollup fields identified with their formulas?
>    - Are required vs optional fields correctly flagged?
>    - Are default values defined where appropriate?
>
> 4. **Naming Convention Validation:**
>    - Schema names: `{prefix}_{FieldName}` in PascalCase
>    - Display names: Title Case with spaces
>    - No abbreviations unless universally understood (ID, URL, etc.)
>
> **Output:** Write to `{project_dir}/_review_field_matrix.json`:
> ```json
> {
>   "reviewed_at": "ISO timestamp",
>   "global_option_sets": [
>     {
>       "schema_name": "{prefix}_StatusCategory",
>       "display_name": "Status Category",
>       "options": [
>         { "label": "Active", "value": 100000000 },
>         { "label": "Inactive", "value": 100000001 }
>       ],
>       "used_by_tables": ["table_a", "table_b"]
>     }
>   ],
>   "tables": [
>     {
>       "logical_name": "table_name",
>       "display_name": "Table Name",
>       "columns": [
>         {
>           "schema_name": "{prefix}_FieldName",
>           "display_name": "Field Name",
>           "type": "String|Integer|Decimal|Currency|Boolean|DateTime|Lookup|Choice|Memo|AutoNumber",
>           "max_length": 100,
>           "required": "Required|Recommended|Optional",
>           "default_value": null,
>           "description": "Purpose of this field",
>           "target_entity": "for lookups only",
>           "option_set": "global_set_name or inline options",
>           "formula": "for calculated/rollup fields",
>           "source_refs": ["batch-001:REQ-005"],
>           "notes": "any review notes"
>         }
>       ]
>     }
>   ],
>   "issues": [
>     { "severity": "high|medium|low", "table": "table_name", "field": "field_name", "issue": "description", "recommendation": "fix" }
>   ]
> }
> ```
>
> **Rules:**
> - Account for EVERY field mentioned in ANY requirement — nothing gets dropped
> - String lengths matter: 100 is tight for full names, 200 is safe, 2000 for URLs/paths
> - Currency fields need precision specified (2 for money, 4 for rates)
> - DateTime fields: specify DateOnly for birth dates, DateAndTime for timestamps
> - Write output to file. Keep text response SHORT.

### Agent 3: Forms & UX Designer

Spawn as a **background subagent**:

> You are a Dataverse Forms & UX Designer. Review the requirements and design form layouts, view configurations, and navigation for the Model-Driven App.
>
> **Read these files:**
> - `{project_dir}/_hierarchy_plan.json`
> - All `{project_dir}/batch-*.json`
>
> **Your review tasks:**
>
> 1. **Form Design:**
>    - Main form for every custom table (and modified OOB tables)
>    - Tab structure: group related fields logically (General, Details, Related, History, etc.)
>    - Section structure: 1-2 column sections, labeled clearly
>    - Field placement: most important fields in the first tab, reference fields in subsequent tabs
>    - Subgrids: where should related entity grids appear? (tab, section, label, columns)
>    - Quick view forms: where should lookup previews appear?
>    - Timeline control: which tables need activity tracking?
>    - Header fields: key status/owner fields in the form header
>
> 2. **View Design:**
>    - Active/Inactive/All views for every custom table
>    - Custom views for common query patterns (e.g., "My Active [Items]", "Pending Approval")
>    - Column selection: most useful columns first, appropriate widths
>    - Default sort order
>    - Filter criteria for custom views
>
> 3. **Navigation / Sitemap:**
>    - Area grouping (e.g., "Operations", "Administration", "Reports")
>    - Group ordering within areas
>    - Which tables appear in which area/group
>    - Dashboards as landing pages
>
> 4. **UX Patterns:**
>    - Are there forms that need conditional visibility (hide/show tabs/sections)?
>    - Are there business rules needed for form behavior (field locking, required on condition)?
>    - Are there inline editable grids needed?
>    - Quick create forms: which tables benefit from quick create?
>
> **Output:** Write to `{project_dir}/_review_forms_ux.json`:
> ```json
> {
>   "reviewed_at": "ISO timestamp",
>   "forms": [
>     {
>       "table_logical_name": "table_name",
>       "form_type": "Main",
>       "name": "Main Form",
>       "tabs": [
>         {
>           "label": "General",
>           "sections": [
>             {
>               "label": "Basic Information",
>               "columns": 2,
>               "fields": ["prefix_field1", "prefix_field2"]
>             }
>           ]
>         }
>       ],
>       "header_fields": ["prefix_status", "ownerid"],
>       "subgrids": [
>         { "tab": "Related", "section": "Child Records", "entity": "child_table", "view": "Active Children", "label": "Related Items" }
>       ],
>       "quick_views": [
>         { "tab": "General", "section": "Lookup Details", "source_entity": "parent_table", "lookup_field": "prefix_parentid", "fields": ["name", "prefix_key_field"] }
>       ],
>       "timeline": true
>     }
>   ],
>   "views": [
>     {
>       "table_logical_name": "table_name",
>       "name": "Active Records",
>       "is_default": true,
>       "columns": [
>         { "name": "prefix_name", "width": 200 },
>         { "name": "prefix_status", "width": 120 }
>       ],
>       "sort": { "field": "createdon", "direction": "desc" },
>       "filter": "statecode eq 0"
>     }
>   ],
>   "quick_create_forms": ["table_a", "table_b"],
>   "sitemap": {
>     "areas": [
>       {
>         "title": "Operations",
>         "groups": [
>           {
>             "title": "Applications",
>             "tables": ["prefix_application", "prefix_payment"]
>           }
>         ]
>       }
>     ]
>   },
>   "issues": [
>     { "severity": "high|medium|low", "table": "table_name", "issue": "description", "recommendation": "fix" }
>   ]
> }
> ```
>
> **Rules:**
> - Every custom table needs at minimum: 1 main form + Active/All views
> - Subgrids are critical for UX — don't skip them for parent-child relationships
> - Sitemap should feel intuitive — group by business function, not by entity type
> - Write output to file. Keep text response SHORT.

### Agent 4: Security Architect

Spawn as a **background subagent**:

> You are a Dataverse Security Architect. Review the requirements and design security roles, field-level security, and access control.
>
> **Read these files:**
> - `{project_dir}/_hierarchy_plan.json`
> - All `{project_dir}/batch-*.json`
>
> **Your review tasks:**
>
> 1. **Security Role Design:**
>    - Identify all user personas/roles mentioned in requirements
>    - Map each role to a Dataverse security role with appropriate privilege levels
>    - Standard privilege levels: None, User, Business Unit, Parent:Child BU, Organization
>    - Standard access types: Create, Read, Write, Delete, Append, AppendTo, Assign, Share
>    - Start restrictive (User level) and expand only where justified
>
> 2. **Privilege Matrix:**
>    - For each security role × each table: define CRUD + Append/AppendTo/Assign/Share privileges
>    - Consider: who creates records? who reads? who updates? who deletes?
>    - Lookup tables (reference data): typically Read-only at Organization level for all roles
>    - Transaction tables: typically User or BU level for create/write/delete
>
> 3. **Field-Level Security:**
>    - Are there sensitive fields that need FLS profiles? (SSN, salary, financial data)
>    - Which roles can read vs update these fields?
>
> 4. **Business Unit Scoping:**
>    - Is a multi-BU structure needed?
>    - How does the BU hierarchy map to the organization structure?
>    - Which tables are BU-scoped vs Organization-scoped?
>
> 5. **Team-Based Access:**
>    - Are there teams needed for shared access patterns?
>    - Owner teams vs Access teams?
>
> **Output:** Write to `{project_dir}/_review_security.json`:
> ```json
> {
>   "reviewed_at": "ISO timestamp",
>   "security_roles": [
>     {
>       "name": "App Administrator",
>       "description": "Full access to all custom tables and configuration",
>       "base_role": "System Administrator",
>       "privileges": [
>         {
>           "table": "prefix_application",
>           "create": "Organization",
>           "read": "Organization",
>           "write": "Organization",
>           "delete": "Organization",
>           "append": "Organization",
>           "append_to": "Organization",
>           "assign": "Organization",
>           "share": "Organization"
>         }
>       ]
>     }
>   ],
>   "field_level_security": [
>     {
>       "profile_name": "Financial Data Access",
>       "description": "Controls access to sensitive financial fields",
>       "fields": [
>         {
>           "table": "prefix_application",
>           "field": "prefix_ssn",
>           "allowed_roles": ["App Administrator"],
>           "can_read": true,
>           "can_update": true,
>           "can_create": true
>         }
>       ]
>     }
>   ],
>   "business_units": [
>     { "name": "Root BU", "children": [] }
>   ],
>   "teams": [
>     { "name": "Processing Team", "type": "Owner", "roles": ["Processor"], "purpose": "Shared access to processing queue" }
>   ],
>   "issues": [
>     { "severity": "high|medium|low", "issue": "description", "recommendation": "fix" }
>   ]
> }
> ```
>
> **Rules:**
> - Principle of least privilege — start restrictive
> - Every custom table must appear in the privilege matrix for every role
> - Admin roles get Organization-level; regular users get User or BU level
> - Write output to file. Keep text response SHORT.

---

## Consolidation Phase

After ALL 4 specialist agents complete, the main orchestrator (you) acts as the **Consolidation Lead**:

### Step 1: Read All Reviews

Read all four `_review_*.json` files.

### Step 2: Resolve Conflicts

Common conflicts to look for:
- Data Architect says merge two tables, but Field Matrix has distinct columns for each → decide based on column count and query patterns
- Forms designer added a subgrid, but the relationship doesn't exist in Data Architect's output → add the relationship
- Security roles reference tables that Data Architect removed → update security matrix

### Step 3: Merge into Build Specification

Produce `build-specification.json` — the single source of truth for Phases 3-6:

```json
{
  "project_name": "SBA Cash App",
  "solution_name": "SBACashApp",
  "publisher_prefix": "mcpd",
  "reviewed_at": "ISO timestamp",
  "oob_entities_used": [
    {
      "logical_name": "contact",
      "custom_columns": ["mcpd_ApplicationCount", "mcpd_ProgramType"],
      "custom_forms": [],
      "custom_views": []
    }
  ],
  "custom_tables": [
    {
      "schema_name": "mcpd_Application",
      "display_name": "Application",
      "plural_name": "Applications",
      "primary_column": { "schema_name": "mcpd_Name", "display_name": "Application Name", "max_length": 200 },
      "ownership_type": "UserOwned",
      "description": "Tracks grant/loan applications",
      "columns": [
        {
          "schema_name": "mcpd_ApplicationNumber",
          "display_name": "Application Number",
          "type": "AutoNumber",
          "format": "APP-{SEQNUM:5}",
          "required": "Required",
          "source_refs": ["batch-001:REQ-003"]
        }
      ],
      "relationships": [
        {
          "type": "OneToMany",
          "related_table": "mcpd_Payment",
          "lookup_name": "mcpd_ApplicationId",
          "lookup_display": "Application",
          "cascade_delete": "RemoveLink"
        }
      ]
    }
  ],
  "global_option_sets": [
    {
      "schema_name": "mcpd_ProgramType",
      "display_name": "Program Type",
      "options": [
        { "label": "Grant", "value": 100000000 },
        { "label": "Loan", "value": 100000001 }
      ],
      "used_by": ["mcpd_Application", "contact"]
    }
  ],
  "forms": [
    {
      "table": "mcpd_Application",
      "type": "Main",
      "name": "Application Main Form",
      "tabs": [
        {
          "label": "General",
          "sections": [
            {
              "label": "Application Details",
              "columns": 2,
              "fields": [
                { "logical_name": "mcpd_name" },
                { "logical_name": "mcpd_applicationnumber" },
                { "logical_name": "mcpd_programtype" },
                { "logical_name": "mcpd_status" }
              ]
            }
          ]
        }
      ],
      "subgrids": [],
      "quick_views": [],
      "timeline": true
    }
  ],
  "views": [
    {
      "table": "mcpd_Application",
      "name": "Active Applications",
      "is_default": true,
      "columns": [
        { "name": "mcpd_name", "width": 200 },
        { "name": "mcpd_applicationnumber", "width": 150 },
        { "name": "mcpd_programtype", "width": 120 },
        { "name": "createdon", "width": 120 }
      ],
      "sort": { "field": "createdon", "direction": "desc" },
      "filter": "statecode eq 0"
    }
  ],
  "security_roles": [
    {
      "name": "App Administrator",
      "privileges": [
        {
          "table": "mcpd_application",
          "create": "Organization",
          "read": "Organization",
          "write": "Organization",
          "delete": "Organization",
          "append": "Organization",
          "append_to": "Organization"
        }
      ]
    }
  ],
  "sitemap": {
    "areas": [
      {
        "title": "Operations",
        "groups": [
          {
            "title": "Applications",
            "tables": ["mcpd_application", "mcpd_payment"]
          }
        ]
      }
    ]
  },
  "flows": [
    {
      "name": "Notify on Application Approval",
      "trigger": "Row Modified",
      "table": "mcpd_application",
      "filter_field": "mcpd_status",
      "description": "When application status changes to Approved, notify the applicant",
      "source_refs": ["batch-002:REQ-012"]
    }
  ],
  "source_references": {
    "batch-001:REQ-003": {
      "source_doc": "Requirements.docx",
      "source_url": "https://sharepoint.com/.../Requirements.docx",
      "snippet_range": "snippets 12-15 of 38"
    }
  }
}
```

### Step 4: Generate Field Matrix

Write `field-matrix.md` — a human-readable field matrix organized by table:

```markdown
# Field Matrix: {Project Name}

## {Table: Application}

| # | Field Name | Schema Name | Type | Length | Required | Default | Option Set | Lookup Target | Notes |
|---|-----------|-------------|------|--------|----------|---------|------------|--------------|-------|
| 1 | Application Name | mcpd_Name | String | 200 | Required | - | - | - | Primary column |
| 2 | Application Number | mcpd_ApplicationNumber | AutoNumber | - | System | APP-{SEQNUM:5} | - | - | Auto-generated |
| 3 | Program Type | mcpd_ProgramType | Choice | - | Required | - | mcpd_ProgramType (Global) | - | Grant, Loan |

## {Table: Payment}
...

## Relationships

| Parent | Child | Lookup Field | Cascade Delete | Type |
|--------|-------|-------------|----------------|------|
| Application | Payment | mcpd_ApplicationId | RemoveLink | 1:N |

## Global Option Sets

| Name | Schema | Options | Used By |
|------|--------|---------|---------|
| Program Type | mcpd_ProgramType | Grant (100000000), Loan (100000001) | Application, Contact |

## Security Roles

| Role | Description | Custom Tables Access |
|------|-------------|---------------------|
| App Administrator | Full access | Organization-level all |
```

### Step 5: Present to User

Show the consolidation summary:
- Tables: N custom + N OOB customized
- Columns: N total across all tables
- Relationships: N
- Forms: N
- Views: N
- Security roles: N
- Issues found: N (with severity breakdown)
- Changes made from specialist recommendations

**Decision gate:** User reviews `build-specification.json` and `field-matrix.md` before proceeding.

---

## Timing Estimates

| Step | Duration | Notes |
|------|----------|-------|
| 4 specialist agents (parallel) | ~10-15 min | All run simultaneously |
| Consolidation | ~5-10 min | Read + merge + conflict resolution |
| Field matrix generation | ~2-3 min | Markdown table generation |
| **Total Phase 2** | **~15-25 min** | Depends on requirement volume |

---

## Lessons Learned

- OOB entity filtering saves significant build time — creating tables that already exist wastes effort and can cause conflicts
- Global option sets identified early prevent duplicate local choices across tables
- Form design upfront (not ad-hoc during build) results in much better UX
- Security roles must be defined BEFORE the build phase so privileges can be created in one pass
- The field matrix is the single most valuable human-review artifact — clients can validate field names, types, and option values before any build work starts