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

$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 /skill:arckit-principles first.
• REQ (Requirements) — Extract: Platform capabilities from FR/NFR requirements, scalability, availability, security
  • If missing: warn user to run /skill: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 /skill: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)
• Then read .arckit/templates/_partials/RENDERING.md and resolve the <!-- DOC-CONTROL-HEADER --> marker in the template before writing. Do not hand-write the Document Control table: the partial RENDERING.md selects is the only source of the 14 standard fields and of the classification ladder.

Tip: Users can customize templates with /skill: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:

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:

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)

   (5+ learning services)

---

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:

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):

✅ 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)
- : {revenue model summary}
- : Supply LTV:CAC = {X}:1, Demand LTV:CAC = {Y}:1

### 7. Minimum Viable Platform (MVP)
- : {N} assumptions to validate
- : {X} features IN, {Y} features deferred
- : {brief description of chicken-and-egg solution}
- : {X} transactions in 90 days
- : £{X}K
- : {N} success criteria

### 8. Platform Design Canvas (Synthesis)
- : £{X} per transaction cost savings
- : {commission}% transaction fee + £{Y}/mo subscriptions
- : {type} - {brief description}
- : {key moat}
- : £{X}K projected

## Auto-Population Sources

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

{IF ARC-*-REQ-*.md used:}
✅  → 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:}
✅  → Build vs. buy strategy from {map_name}
 {N} components to BUILD (Custom/Genesis)
 {M} components to BUY (Product/Commodity)

{IF ARC-000-PRIN-.md
 {N} principles applied to platform design



{IF applicable:}
✅  alignment documented
✅  compliance approach
✅  implications analyzed
✅  positioning (G-Cloud/DOS)



✅ : {N} linkages created
✅ : {M} linkages created
✅ : {K} linkages created
✅ : {J} linkages created



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

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

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



📄  ({file

---

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 /skill:arckit-requirements and /skill:arckit-hld-review instead)
• Internal enterprise systems without multi-sided ecosystem (use /skill:arckit-requirements)
• Point-to-point integrations (use /skill:arckit-diagram for architecture)

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