arckit-platform-design

---
name: arckit-platform-design
description: "Create platform strategy using Platform Design Toolkit (8 canvases for multi-sided ecosystems)"
---

You are helping an enterprise architect design a **platform strategy** for a multi-sided ecosystem using the **Platform Design Toolkit (PDT)** from Boundaryless.io.

## User Input

```text
$ARGUMENTS
```

## Your Task

Generate a comprehensive platform strategy design document using PDT v2.2.1 methodology, covering all 8 strategy design canvases: Ecosystem Canvas, Entity Portraits, Motivations Matrix, Transactions Board, Learning Engine, Platform Experience Canvas, MVP Canvas, and Platform Design Canvas.

---

## Instructions

### Step 0: Read Available Documents

> **Note**: Before generating, scan `projects/` for existing project directories. For each project, list all `ARC-*.md` artifacts, check `external/` for reference documents, and check `000-global/` for cross-project policies. If no external docs exist but they would improve output, ask the user.

**MANDATORY** (warn if missing):

- **PRIN** (Architecture Principles, in 000-global) — Extract: Platform governance principles, ecosystem orchestration standards, technology choices
  - If missing: STOP — platform designs require architecture principles. Run `$arckit-principles` first.
- **REQ** (Requirements) — Extract: Platform capabilities from FR/NFR requirements, scalability, availability, security
  - If missing: warn user to run `$arckit-requirements` first

**RECOMMENDED** (read if available, note if missing):

- **STKE** (Stakeholder Analysis) — Extract: Ecosystem entities from stakeholder drivers, user personas, goals
  - If missing: recommend running `$arckit-stakeholders` for better entity portraits
- **WARD** (Wardley Maps, in wardley-maps/) — Extract: Evolution analysis for build vs buy decisions, component positioning

**OPTIONAL** (read if available, skip silently if missing):

- **RISK** (Risk Register) — Extract: Platform risks, ecosystem risks, governance risks
- **DATA** (Data Model) — Extract: Data exchange patterns, entity schemas, data governance
- **SOBC** (Business Case) — Extract: Investment context, ROI targets, benefits

---

### Step 1: Identify or Create Project

Identify the target project from the hook context. If the user specifies a project that doesn't exist yet, create a new project:

1. Use Glob to list `projects/*/` directories and find the highest `NNN-*` number (or start at `001` if none exist)
2. Calculate the next number (zero-padded to 3 digits, e.g., `002`)
3. Slugify the project name (lowercase, replace non-alphanumeric with hyphens, trim)
4. Use the Write tool to create `projects/{NNN}-{slug}/README.md` with the project name, ID, and date — the Write tool will create all parent directories automatically
5. Also create `projects/{NNN}-{slug}/external/README.md` with a note to place external reference documents here
6. Set `PROJECT_ID` = the 3-digit number, `PROJECT_PATH` = the new directory path

If the project already exists, check for existing `ARC-{PROJECT_ID}-PLAT-v*.md` files. If found, ask user if they want to overwrite or update.

**Gathering rules** (apply to all user questions in this command):

- Ask the most important question first; fill in secondary details from context or reasonable defaults.
- **Maximum 2 rounds of questions total.** After that, infer the best answer from available context.
- If still ambiguous after 2 rounds, make a reasonable choice and note: *"I went with [X] — easy to adjust if you prefer [Y]."*

---

### Step 2: Read the Template

Read the platform design template:

**Read the template** (with user override support):

- **First**, check if `.arckit/templates/platform-design-template.md` exists in the project root
- **If found**: Read the user's customized template (user override takes precedence)
- **If not found**: Read `.arckit/templates/platform-design-template.md` (default)

> **Tip**: Users can customize templates with `$arckit-customize platform-design`

This template contains the structure for all 8 PDT canvases.

---

### Step 3: Auto-Populate from Existing Artifacts

**CRITICAL**: To create a high-quality, integrated platform design, extract data from existing ArcKit artifacts:

#### 3.1 Extract Stakeholder Data → Entity Portraits

If `projects/{project_id}/ARC-*-STKE-*.md` exists:

**Read the file** and extract:

- **Stakeholders** → Map to **Entities** in ecosystem
  - Example: "CFO" stakeholder → "Enterprise Buyer" entity (demand side)
  - Example: "Service Provider" stakeholder → "Independent Consultant" entity (supply side)

- **Drivers** → Map to **Performance Pressures**
  - Example: Driver "Reduce procurement costs" → Pressure "Cost reduction imperatives"

- **Goals** → Map to **Entity Goals**
  - Example: Goal "Reduce vendor search time by 50%" → Entity goal in portrait

- **RACI Matrix** → Map to **Ecosystem Roles**
  - Example: "Responsible" roles → Supply-side entities
  - Example: "Accountable" roles → Demand-side entities or regulators

**Extraction Logic**:

```text
For each stakeholder in ARC-*-STKE-*.md:
  - Determine entity type (Supply/Demand/Supporting)
  - Create Entity Portrait (Section 2.2, 2.3, 2.4)
  - Populate context from stakeholder description
  - Populate pressures from drivers
  - Populate goals from stakeholder goals
  - Populate gains from outcomes
```

#### 3.2 Extract Requirements → Platform Capabilities

If `projects/{project_id}/ARC-*-REQ-*.md` exists:

**Read the file** and extract:

- **BR (Business Requirements)** → Map to **Value Creation** and **Revenue Model**
  - Example: "BR-001: Reduce vendor onboarding time by 80%" → Transaction T-002 cost reduction

- **FR (Functional Requirements)** → Map to **Platform Features** and **Transaction Engine**
  - Example: "FR-010: Provider search and filtering" → Core journey step, T-001 transaction

- **NFR (Non-Functional Requirements)** → Map to **Platform Architecture** and **MVP Scope**
  - Example: "NFR-S-002: Handle 10,000 transactions/month" → Transaction velocity target
  - Example: "NFR-A-001: 99.9% availability SLA" → Platform Experience Canvas SLA

- **DR (Data Requirements)** → Map to **Learning Engine** (analytics, insights)
  - Example: "DR-005: Performance analytics data" → Learning Service 1

**Extraction Logic**:

```text
For each requirement in ARC-*-REQ-*.md:
  - Map BR-xxx to business model and value creation
  - Map FR-xxx to platform features and transactions
  - Map NFR-xxx to architecture and scale targets
  - Map DR-xxx to learning engine data flows
```

#### 3.3 Extract Wardley Map → Build vs. Buy Strategy

If `projects/{project_id}/wardley-maps/ARC-*-WARD-*.md` exists:

**Read Wardley map(s)** and extract:

- **Components** and their **Evolution Stages**:
  - Genesis (0.00-0.25) → **Build** (novel, differentiating)
  - Custom (0.25-0.50) → **Build or Partner** (emerging, core capability)
  - Product (0.50-0.75) → **Buy** (commercial products available)
  - Commodity (0.75-1.00) → **Use Utility** (cloud, SaaS, APIs)

**Use evolution analysis** in Platform Design Canvas (Section 8.3):

- Identify which platform components to build (Custom/Genesis)
- Identify which to buy/use (Product/Commodity)
- Example: "Service matching algorithm" at Custom (0.35) → Build as core differentiator
- Example: "Payment processing" at Product (0.70) → Use Stripe API

#### 3.4 Extract Architecture Principles → Platform Governance

Read `projects/000-global/ARC-000-PRIN-*.md`:

**Extract principles** that apply to platform strategy:

- Example: Principle "API-First" → Platform must expose APIs for ecosystem integrations
- Example: Principle "Data Privacy by Design" → Learning engine must anonymize entity data
- Example: Principle "Cloud-Native" → Platform runs on AWS/Azure, serverless where possible

**Apply principles** in Platform Design Canvas (Section 8.4 Strategic Alignment)

---

### Step 3b: Read external documents and policies

- Read any **external documents** listed in the project context (`external/` files) — extract current platform architecture, ecosystem participants, API catalogues, platform metrics
- Read any **enterprise standards** in `projects/000-global/external/` — extract enterprise platform strategy, shared service catalogues, cross-project platform integration standards
- If no external platform docs found but they would improve the design, ask: "Do you have any existing platform documentation, ecosystem maps, or API catalogues? I can read PDFs and images directly. Place them in `projects/{project-dir}/external/` and re-run, or skip."
- **Citation traceability**: When referencing content from external documents, follow the citation instructions in `.arckit/references/citation-instructions.md`. Place inline citation markers (e.g., `[PP-C1]`) next to findings informed by source documents and populate the "External References" section in the template.

---

### Step 4: Detect Version

Before generating the document ID, check if a previous version exists:

1. Look for existing `ARC-{PROJECT_ID}-PLAT-v*.md` files in the project directory
2. **If no existing file**: Use VERSION="1.0"
3. **If existing file found**:
   - Read the existing document to understand its scope
   - Compare against current inputs and requirements
   - **Minor increment** (e.g., 1.0 → 1.1): Scope unchanged — refreshed content, updated entity details, corrected details
   - **Major increment** (e.g., 1.0 → 2.0): Scope materially changed — new ecosystem entities, fundamentally different platform strategy, significant new canvases
4. Use the determined version for document ID, filename, Document Control, and Revision History
5. For v1.1+/v2.0+: Add a Revision History entry describing what changed from the previous version

### Step 5: Construct Document Control Metadata

- **Document ID**: `ARC-{PROJECT_ID}-PLAT-v{VERSION}` (e.g., `ARC-001-PLAT-v1.0`)

**Populate document control fields**:

- `document_id`: Constructed from format above
- `project_id`: From Step 1
- `project_name`: From Step 1
- `version`: Determined version from Step 4
- `author`: "ArcKit Platform Design Command"
- `date_created`: Current date (YYYY-MM-DD)
- `date_updated`: Current date (YYYY-MM-DD)
- `generation_date`: Current date and time
- `ai_model`: Your model name (e.g., "Claude 3.5 Sonnet")

---

### Step 6: Generate Platform Design Using PDT Methodology

**CRITICAL INSTRUCTIONS FOR QUALITY**:

1. **This is a LARGE document** (8 canvases, 1,800+ lines). You MUST use the **Write tool** to create the file. DO NOT output the full document to the user (you will exceed token limits).

2. **Follow PDT v2.2.1 methodology** (Boundaryless.io):
   - 8 canvases in sequence
   - Focus on multi-sided ecosystem thinking
   - Transaction cost reduction is core value proposition
   - Learning engine creates long-term defensibility

3. **Complete ALL 8 canvases** with depth:

   **Canvas 1: Ecosystem Canvas**
   - Map 5-15 entity types (Supply side, Demand side, Supporting)
   - Create Mermaid diagram showing relationships
   - Catalog entities with roles, resources provided/consumed
   - Define ecosystem boundaries and interfaces

   **Canvas 2: Entity-Role Portraits** (3-5 portraits minimum)
   - Portrait 1: Primary supply-side entity (e.g., service providers, sellers, creators)
   - Portrait 2: Primary demand-side entity (e.g., buyers, consumers, learners)
   - Portrait 3: Supporting entity (e.g., regulator, payment provider, insurer)
   - For EACH portrait:
     - Context: Who they are, current situation, constraints
     - Performance Pressures: External and internal forces
     - Goals: Short-term (0-6mo), medium-term (6-18mo), long-term (18+mo)
     - Gains Sought: 5 value propositions with metrics
     - Linkage to Platform Features: Map goals → features → value delivery

   **Canvas 3: Motivations Matrix**
   - Cross-entity motivation analysis (NxN matrix where N = number of entities)
   - Identify synergies (aligned motivations)
   - Identify conflicts (misaligned motivations)
   - For each conflict: Platform solution to resolve it

   **Canvas 4: Transactions Board** (10-20 transactions minimum)
   - Catalog all transactions in ecosystem
   - For EACH transaction:
     - Transaction name
     - From entity → To entity
     - Existing? (Yes/No - does it happen today?)
     - Current channel and transaction costs
     - Platform channel and reduced costs
     - Cost reduction percentage
   - Analyze transaction costs: Search, Information, Negotiation, Coordination, Enforcement
   - Calculate total value created (cost savings × transaction volume)

   **Canvas 5: Learning Engine Canvas** (5+ learning services)
   - Design services that help entities improve continuously
   - For EACH learning service:
     - What: Service description
     - Inputs: Data sources
     - Outputs: Delivered value
     - How Entity Improves: Specific improvements
     - Platform Benefit: Why this creates defensibility
     - Success Metric: Measurable impact
   - Define learning services business model (freemium, premium tiers)

   **Canvas 6: Platform Experience Canvas** (2+ core journeys)
   - Journey 1: Supply-side onboarding and first sale
   - Journey 2: Demand-side discovery and first purchase
   - For EACH journey:
     - Journey map: 8-10 stages from awareness to retention
     - For each stage: Entity action, platform service, transaction ID, learning service, touchpoint, pain point addressed
     - Journey metrics: Time, cost, completion rate, satisfaction
   - Business Model Canvas: Revenue streams, cost structure, unit economics, LTV:CAC ratios

   **Canvas 7: Minimum Viable Platform Canvas**
   - Critical assumptions (5+): What must be true for platform to succeed?
   - For each assumption: Riskiness (High/Medium/Low), evidence needed, test method
   - MVP feature set: What's IN, what's OUT (defer to post-validation)
   - Liquidity bootstrapping strategy: How to solve chicken-and-egg problem
     - Phase 1: Curate initial supply
     - Phase 2: Seed demand
     - Phase 3: Test transaction velocity
     - Phase 4: Expand liquidity
   - Validation metrics: 10+ success criteria for Go/No-Go decision after 90 days
   - MVP timeline and budget

   **Canvas 8: Platform Design Canvas (Synthesis)**
   - The 6 Building Blocks:
     1. Ecosystem: Who participates, ecosystem size targets
     2. Value Creation: Value for supply, demand, overall ecosystem
     3. Value Capture: Revenue model, pricing rationale
     4. Network Effects: Same-side, cross-side, data, learning effects; defensibility
     5. Transaction Engine: Core transactions, cost reductions, velocity targets
     6. Learning Engine: Learning services summary, revenue, impact
   - Strategic Alignment: Link to stakeholders, requirements, principles, Wardley maps
   - UK Government Context: GaaP, TCoP, Service Standard, Digital Marketplace

5. **Auto-populate from artifacts** (from Step 3):
   - Entity portraits from ARC-*-STKE-*.md
   - Platform capabilities from ARC-*-REQ-*.md
   - Build vs. buy from wardley-maps/ARC-*-WARD-*.md
   - Governance from ARC-000-PRIN-*.md

6. **UK Government Context** (if applicable):
   - Government as a Platform (GaaP) principles
   - Technology Code of Practice (TCoP) alignment
   - GDS Service Standard implications
   - Digital Marketplace positioning (G-Cloud, DOS)

7. **Generate complete traceability** (Section 9):
   - Stakeholder → Entity → Value Proposition
   - Requirement → Platform Feature → Implementation
   - Wardley Component → Build/Buy Decision
   - Risk → Platform Mitigation

8. **Provide actionable next steps** (Section 10):
   - Immediate actions (30 days): Validate assumptions, prototype MVP
   - MVP build phase (Months 2-4): Product development, provider acquisition
   - MVP validation phase (Months 5-7): Buyer onboarding, transaction velocity
   - Go/No-Go decision (Month 7): Review validation metrics
   - Scale phase (Months 8-24): Full feature set, growth, funding

---

### Step 7: Write the Document

Before writing the file, read `.arckit/references/quality-checklist.md` and verify all **Common Checks** plus the **PLAT** per-type checks pass. Fix any failures before proceeding.

**USE THE WRITE TOOL** to create the platform design document:

```text
File path: projects/{project_id}-{project_name}/ARC-{PROJECT_ID}-PLAT-v${VERSION}.md
Content: [Complete platform design following template, all 8 canvases filled out]
```

**IMPORTANT**:

- This document will be 1,500-2,500 lines
- DO NOT output the full document in chat (token limit)
- Use Write tool to create file
- Only show summary to user

---

### Step 8: Generate Summary for User

After writing the file, provide a **concise summary** (NOT the full document):

```markdown
✅ Platform Strategy Design Created

**Project**: {project_name} ({project_id})
**Document**: projects/{project_id}-{project_name}/ARC-{PROJECT_ID}-PLAT-v1.0.md
**Document ID**: {document_id}

## Platform Overview

**Platform Name**: {platform_name}
**Platform Vision**: {one-sentence vision}

**Ecosystem Size (3-year target)**:
- {X} supply-side entities
- {Y} demand-side entities
- £{Z}M Gross Merchandise Value (GMV) annually

## The 8 PDT Canvases (Summary)

### 1. Ecosystem Canvas
- **Entities Mapped**: {N} entity types
- **Supply Side**: {entity types}
- **Demand Side**: {entity types}
- **Supporting**: {entity types}

### 2. Entity Portraits
- **Portraits Created**: {N} (supply-side, demand-side, supporting)
- **Key Entity 1**: {name} - {primary value sought}
- **Key Entity 2**: {name} - {primary value sought}

### 3. Motivations Matrix
- **Key Synergies**: {N synergies identified}
- **Key Conflicts**: {N conflicts to resolve}
- **Example Synergy**: {brief description}
- **Example Conflict**: {brief description + platform solution}

### 4. Transactions Board
- **Transactions Cataloged**: {N} transactions
- **Transaction Cost Reduction**: {X}% average reduction
- **Annual Value Created**: £{Y}M in transaction cost savings
- **Key Transaction**: {T-ID}: {name} - {cost reduction}%

### 5. Learning Engine
- **Learning Services**: {N} services designed
- **Supply-Side Services**: {list}
- **Demand-Side Services**: {list}
- **Learning Revenue**: £{X}K/year projected

### 6. Platform Experience
- **Core Journeys Mapped**: {N} journeys
- **Journey 1**: {name} - {completion time} ({X}% faster than current)
- **Journey 2**: {name} - {completion time} ({X}% faster than current)
- **Business Model**: {revenue model summary}
- **Unit Economics**: Supply LTV:CAC = {X}:1, Demand LTV:CAC = {Y}:1

### 7. Minimum Viable Platform (MVP)
- **Critical Assumptions**: {N} assumptions to validate
- **MVP Scope**: {X} features IN, {Y} features deferred
- **Liquidity Strategy**: {brief description of chicken-and-egg solution}
- **Validation Target**: {X} transactions in 90 days
- **MVP Budget**: £{X}K
- **Go/No-Go Metrics**: {N} success criteria

### 8. Platform Design Canvas (Synthesis)
- **Value Creation**: £{X} per transaction cost savings
- **Value Capture**: {commission}% transaction fee + £{Y}/mo subscriptions
- **Network Effects**: {type} - {brief description}
- **Defensibility**: {key moat}
- **Year 1 Revenue**: £{X}K projected

## Auto-Population Sources

{IF ARC-*-STKE-*.md used:}
✅ **Stakeholders** → Entity portraits auto-populated from ARC-*-STKE-*.md
   - {N} stakeholders mapped to {M} ecosystem entities

{IF ARC-*-REQ-*.md used:}
✅ **Requirements** → Platform capabilities auto-populated from ARC-*-REQ-*.md
   - {N} BR requirements → Value creation
   - {M} FR requirements → Platform features
   - {K} NFR requirements → Architecture and scale

{IF wardley-maps used:}
✅ **Wardley Maps** → Build vs. buy strategy from {map_name}
   - {N} components to BUILD (Custom/Genesis)
   - {M} components to BUY (Product/Commodity)

{IF ARC-000-PRIN-*.md used:}
✅ **Architecture Principles** → Platform governance from ARC-000-PRIN-*.md
   - {N} principles applied to platform design

## UK Government Context

{IF applicable:}
✅ **Government as a Platform (GaaP)** alignment documented
✅ **Technology Code of Practice (TCoP)** compliance approach
✅ **GDS Service Standard** implications analyzed
✅ **Digital Marketplace** positioning (G-Cloud/DOS)

## Traceability

✅ **Stakeholder-to-Platform**: {N} linkages created
✅ **Requirements-to-Platform**: {M} linkages created
✅ **Wardley-to-Strategy**: {K} linkages created
✅ **Risk-to-Mitigation**: {J} linkages created

## Next Steps (Immediate Actions)

1. **Validate Assumptions** (Next 30 days):
   - Interview {X} potential supply-side entities
   - Interview {Y} potential demand-side entities
   - Test pricing sensitivity

2. **Prototype MVP** (Next 30 days):
   - Design wireframes for core journeys
   - Build tech stack proof-of-concept
   - Test payment escrow

3. **Fundraising**:
   - Pitch deck based on Platform Design Canvas
   - Financial model (GMV, revenue, unit economics)
   - Raise £{X}K seed funding for MVP

## Files Created

📄 `projects/{project_id}-{project_name}/ARC-{PROJECT_ID}-PLAT-v1.0.md` ({file_size} lines)

## Related Commands

**Prerequisites** (should run before platform design):
- `$arckit-principles` - Architecture principles
- `$arckit-stakeholders` - Stakeholder analysis (highly recommended)
- `$arckit-requirements` - Platform requirements (recommended)
- `$arckit-wardley` - Value chain analysis (recommended)

**Next Steps** (run after platform design):
- `$arckit-sow` - RFP for platform development vendors
- `$arckit-hld-review` - Review high-level platform architecture
- `$arckit-backlog` - Generate sprint backlog from platform features

## Methodology Reference

**Platform Design Toolkit (PDT) v2.2.1**
- Source: Boundaryless.io
- License: Creative Commons CC-BY-SA
- Documentation: https://boundaryless.io/pdt-toolkit/
- Guide: docs/guides/platform-design.md

---

💡 **Tip**: The platform design document is comprehensive (1,500-2,500 lines). Review each canvas section to understand:
- Who participates in your ecosystem
- What value you create and how you capture it
- How transactions and learning create defensibility
- What MVP to build and how to validate it

The Platform Design Canvas (Section 8) provides a single-page synthesis perfect for executive presentations and fundraising.
```

---

## Important Notes

1. **Template-Driven**: Use platform-design-template.md as structure, fill with project-specific content

2. **Auto-Population**: Extract data from existing artifacts to create integrated, traceability-rich design

3. **PDT Methodology**: Follow Boundaryless.io Platform Design Toolkit v2.2.1 rigorously
   - 8 canvases in sequence
   - Transaction cost economics
   - Learning engine as moat
   - Network effects analysis
   - MVP validation strategy

4. **UK Government Context**: If project is UK gov/public sector, emphasize GaaP, TCoP, Digital Marketplace

5. **Multi-Sided Markets**: Platform design is for 2+ sided markets (supply-demand). If project is not a platform/marketplace, suggest alternative commands.

6. **Token Management**: Use Write tool for large document. Show summary only to user.

7. **Traceability**: Every platform decision should link back to stakeholders, requirements, principles, or Wardley maps

8. **MVP Focus**: Canvas 7 (MVP) is critical - help architect define smallest testable platform to validate riskiest assumptions

9. **Liquidity Bootstrapping**: Canvas 7 must address chicken-and-egg problem with specific strategy

10. **Network Effects**: Canvas 8 must articulate defensibility through network effects, data moats, learning loops

---

- **Markdown escaping**: When writing less-than or greater-than comparisons, always include a space after `<` or `>` (e.g., `< 3 seconds`, `> 99.9% uptime`) to prevent markdown renderers from interpreting them as HTML tags or emoji

## Example Use Cases

**Good Use Cases for Platform Design**:

- Multi-sided marketplaces (e.g., supplier-buyer platforms, G-Cloud)
- Data sharing platforms (e.g., cross-government data mesh, NHS data sharing)
- Service platforms (e.g., GOV.UK services ecosystem, local government platforms)
- Ecosystem orchestration (e.g., vendor ecosystem, partner network, app store)

**Not Suitable for Platform Design**:

- Single-product SaaS applications (use $arckit-requirements and $arckit-hld-review instead)
- Internal enterprise systems without multi-sided ecosystem (use $arckit-requirements)
- Point-to-point integrations (use $arckit-diagram for architecture)

If user's project doesn't fit platform pattern, recommend appropriate alternative command.