Arckit Presentation

You are helping an enterprise architect generate a MARP-format presentation from existing ArcKit project artifacts. The presentation summarises the project's architecture, requirements, risks, and roadmap in a slide deck suitable for governance boards, stakeholder briefings, and gate reviews.

This command creates an ARC-{PROJECT_ID}-PRES-v1.0.md document that serves as:

• A slide deck in MARP format (renders to PDF/PPTX/HTML via MARP CLI or VS Code extension)
• A governance-ready summary drawing from existing ArcKit artifacts
• A tailored presentation for different audiences (executive, technical, stakeholder)

User Input

$ARGUMENTS

Instructions

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.

Step 1: Identify the target project

• Use the ArcKit Project Context (above) to find the project matching the user's input (by name or number)
• If no match, 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

Step 2: Read existing artifacts from the project context

MANDATORY (warn if missing):

• PRIN (Architecture Principles, in projects/000-global/)
  • Extract: Governance standards, technology constraints, compliance framework
  • If missing: warn user to run $arckit-principles first

RECOMMENDED (read if available, note if missing):

• STKE (Stakeholder Analysis) — personas, goals, priorities → Stakeholder slide
• REQ (Requirements) — BR/FR/NFR/INT/DR counts and critical items → Requirements slide
• RISK (Risk Register) — top risks, mitigations, distribution → Risk slide
• PLAN (Project Plan) — phases, milestones, Gantt → Timeline slide
• ROAD (Roadmap) — delivery roadmap → Roadmap slide
• STRAT (Architecture Strategy) — vision, decisions → Context slide
• SOBC (Business Case) — benefits, costs, ROI → Executive summary
• DIAG (Architecture Diagrams) — C4, deployment, data flow → Architecture slide
• WARD (Wardley Map) — strategic positioning → Strategy slide
• RSCH / AWSR / AZUR / GCRS — technology research → Technology decisions
• SOW / DOS — procurement → Procurement status
• HLDR / DLDR (Design Reviews) → Quality assurance
• TCOP / SECD / MSBD — compliance assessments → Compliance slide
• DPIA (DPIA) → Data protection
• AIPB / ATRS — AI governance → AI compliance
• DEVOPS (DevOps Strategy) → Delivery approach

Minimum artifact check: A meaningful presentation requires at least 3 artifacts. If the project has fewer than 3, warn:

⚠️  Warning: This project only has [N] artifacts.

A useful presentation typically requires at least:
- Architecture principles (global)
- Stakeholder analysis or requirements
- Risk register or project plan

Run more /arckit commands first, then re-run $arckit-presentation.

Step 3: Interactive Configuration

Before generating the presentation, ask the user for preferences. Skip any question the user has already answered in their arguments.

Gathering rules — the one-message interview in .arckit/references/interview-pattern.md:

• Prefill from the arguments and the project context; say what you inferred.
• Ask every remaining question in one call. There is no second round.
• An unanswered question takes its (Recommended) option, listed as an assumption in your closing summary. With no question tool available, take every default and never block.

Question 1 — header: Focus, multiSelect: false

"What audience is this presentation for?"

• Executive (Recommended): High-level summary — business case, timeline, risks, decisions needed. Fewer slides, minimal technical detail.
• Technical: Architecture detail — diagrams, technology decisions, integration points, data model. More slides, Mermaid diagrams.
• Stakeholder: Benefits-focused — user impact, timeline, risks, change management. Balanced detail, emphasis on outcomes.
• Procurement: Vendor-focused — requirements summary, evaluation criteria, timeline, contract structure. For RFP briefings.

Question 2 — header: Slides, multiSelect: false

"How many slides should the presentation contain?"

• 10-12 slides (Recommended): Standard governance board deck — covers all key areas concisely
• 6-8 slides: Brief update — executive summary, key decisions, next steps only
• 15-20 slides: Comprehensive briefing — detailed sections with supporting data and diagrams

Apply the user's selections: the focus determines which artifacts are emphasised and the level of technical detail. The slide count constrains how much content is included per section.

Step 4: Read the template (with user override support)

• First, check if .arckit/templates-custom/presentation-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/presentation-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 $arckit-customize presentation

Step 4b: Load Mermaid Syntax References

Read .arckit/skills/mermaid-syntax/references/quadrantChart.md, .arckit/skills/mermaid-syntax/references/c4.md, .arckit/skills/mermaid-syntax/references/pie.md, and .arckit/skills/mermaid-syntax/references/gantt.md for official Mermaid syntax — quadrant chart axes, C4 diagram elements, pie chart syntax, date formats, and styling options.

Step 5: Generate the MARP presentation

Build the slide deck by extracting key content from each artifact:

Title Slide: Project name, date, classification, presenter/team

Context & Objectives (from STRAT, SOBC, REQ):

• Business challenge and strategic opportunity
• Key objectives and success criteria

Stakeholder Landscape (from STKE):

• Key stakeholders with roles, interest, and influence
• Mermaid quadrant chart if data available (see Mermaid label rules below)

Architecture Overview (from DIAG, STRAT):

• Current state summary and pain points
• Target state and key changes
• Embed Mermaid C4 context diagram or reference existing diagrams

Technology Decisions (from RSCH, AWSR, AZUR, GCRS, ADR):

• Key build vs buy decisions
• Technology choices with rationale

Key Requirements (from REQ):

• Summary counts by category (BR/FR/NFR/INT/DR)
• Top 3-5 critical requirements

Risk Summary (from RISK):

• Top 3-5 risks with likelihood/impact/mitigation
• Mermaid pie chart of risk distribution

Roadmap & Timeline (from PLAN, ROAD):

• Mermaid Gantt chart of project phases
• Key milestones with status

Compliance & Governance (from TCOP, SECD, MSBD, DPIA, AIPB):

• Standards compliance status table
• Only include if UK Government or compliance-heavy project

Recommendations & Next Steps:

• Immediate actions with owners and deadlines
• Decisions required from the audience

Questions & Discussion: Contact details and next review date

Slide count guidelines:

• 6-8 slides: Title + Context + Architecture + Requirements + Risks + Timeline + Next Steps
• 10-12 slides: All of the above + Stakeholders + Technology Decisions + Compliance + Questions
• 15-20 slides: All sections expanded with additional detail slides, data model, integration points

Step 6: MARP formatting rules

• Use --- between slides (MARP slide separator)
• Include MARP YAML frontmatter: marp: true, theme: default, paginate: true
• Use header and footer for persistent slide branding
• Keep each slide to 3-5 bullet points or one table/diagram — avoid overloading
• Use Mermaid diagrams where data supports them (Gantt, pie, C4, quadrant)
• Use <!-- fit --> for headings that need auto-sizing
• Tables should have no more than 5 rows per slide

Mermaid label rules (applies to ALL Mermaid diagrams, especially quadrantChart):

• No accented characters: Use ASCII only in labels — replace é→e, í→i, ó→o, ñ→n, ü→u, etc.
• No hyphens in data point labels: Use spaces instead — e.g., DST Cybersecurity not DST-Cybersecurity
• No special characters: Avoid colons, parentheses, brackets, or quotes in labels
• These restrictions exist because Mermaid's parser breaks on non-ASCII and certain punctuation

Step 7: Write the output

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

• Write to projects/{project-dir}/ARC-{PROJECT_ID}-PRES-v${VERSION}.md
• Use the exact template structure with MARP frontmatter

CRITICAL - Auto-Populate Document Control Fields:

Step 7a: Detect Version

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

1. Look for existing ARC-{PROJECT_ID}-PRES-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): Same focus and artifact set — refreshed content
   • Major increment (e.g., 1.0 → 2.0): Different focus, significantly different artifact set, or new audience
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 7b: Construct Document ID

• Document ID: ARC-{PROJECT_ID}-PRES-v{VERSION} (e.g., ARC-001-PRES-v1.0)

Step 7c: Populate Required Fields

Auto-populated fields (populate these automatically):

• [PROJECT_ID] → Extract from project path (e.g., "001" from "projects/001-project-name")
• [VERSION] → Determined version from Step 7a
• [DATE] / [YYYY-MM-DD] → Current date in YYYY-MM-DD format
• [DOCUMENT_TYPE_NAME] → "Architecture Presentation"
• ARC-[PROJECT_ID]-PRES-v[VERSION] → Construct using format from Step 7b
• [COMMAND] → "arckit.presentation"

User-provided fields (extract from project metadata or user input):

• [PROJECT_NAME] → Full project name from project metadata or user input
• [OWNER_NAME_AND_ROLE] → Document owner (prompt user if not in metadata)
• [CLASSIFICATION] (MARP footer and title slide) → copy the Classification value from the resolved Document Control header, so the slides and the header cannot disagree. That header's ladder comes from _partials/RENDERING.md.

Pending fields (leave as [PENDING] until manually updated):

• [REVIEWER_NAME] → [PENDING]
• [APPROVER_NAME] → [PENDING]
• [DISTRIBUTION_LIST] → Default to "Project Team, Architecture Team" or [PENDING]

Step 7d: Populate Revision History

| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-presentation` command | [PENDING] | [PENDING] |

Step 7e: Populate Generation Metadata Footer

**Generated by**: ArcKit `$arckit-presentation` command
**Generated on**: {DATE} {TIME} GMT
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Use actual model name, e.g., "Claude Sonnet 5 (session default)"]
**Generation Context**: [Brief note about source documents used]

Step 8: Summarize what you created

Show ONLY a concise summary after writing the file.

Example Usage

User: $arckit-presentation Generate executive presentation for NHS appointment booking

You should:

• Find project 007-nhs-appointment
• Read all available artifacts (STKE, REQ, RISK, PLAN, DIAG, etc.)
• Ask about focus (executive) and slide count (10-12)
• Generate MARP slide deck with executive focus
• Write to projects/007-nhs-appointment/ARC-007-PRES-v1.0.md
• Show summary only

Important Notes

• MARP rendering: The output .md file can be rendered using MARP CLI (marp --pdf ARC-001-PRES-v1.0.md) or the MARP for VS Code extension

• Mermaid diagrams: MARP supports Mermaid natively — use them for Gantt charts, pie charts, C4 diagrams, and quadrant charts

• This command reads existing artifacts and reformats them — it does not generate new analysis

• If no artifacts exist, recommend running $arckit-plan or $arckit-requirements first

• Keep slides concise: 3-5 bullets per slide, one table or diagram per slide

• For UK Government projects, include GDS Service Standard and TCoP compliance status

• 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

Resources

• MARP Official Documentation
• MARP CLI
• MARP Themes
• Mermaid Diagram Syntax

Output Instructions

CRITICAL - Token Efficiency:

1. Generate Presentation

Create the MARP slide deck following the template structure and user's focus/slide preferences.

2. Write Directly to File

Use the Write tool to create projects/[PROJECT]/ARC-{PROJECT_ID}-PRES-v${VERSION}.md with the complete presentation.

DO NOT output the full document in your response. This would exceed token limits.

3. Show Summary Only

After writing the file, show ONLY a concise summary:

## Presentation Complete ✅

**Project**: [Project Name]
**File Created**: `projects/[PROJECT]/ARC-{PROJECT_ID}-PRES-v1.0.md`

### Presentation Summary

**Focus**: [Executive / Technical / Stakeholder / Procurement]
**Slides**: [N] slides
**Theme**: [default / gaia / uncover]

**Content Sources**:
- [List artifacts read and what was extracted from each]

**Slide Deck**:
1. Title — [Project name, date, classification]
2. Context & Objectives — [Key points]
3. Stakeholder Landscape — [Key stakeholders]
4. Architecture Overview — [Current → Target]
5. Key Requirements — [N] total ([N] BR, [N] FR, [N] NFR)
6. Risk Summary — [N] risks ([N] high, [N] medium, [N] low)
7. Roadmap — [Duration], [N] milestones
8. Next Steps — [N] actions, [N] decisions

**Rendering**:
- VS Code: Install [MARP for VS Code](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode) → Open file → Preview
- CLI: `marp --pdf ARC-{PROJECT_ID}-PRES-v1.0.md` (requires [MARP CLI](https://github.com/marp-team/marp-cli))
- HTML: `marp ARC-{PROJECT_ID}-PRES-v1.0.md` → opens in browser

### Next Steps

- Review slides for accuracy and completeness
- Customize MARP theme if needed (`theme: gaia` or `theme: uncover`)
- Export to PDF/PPTX: `marp --pdf` or `marp --pptx`
- Run `$arckit-story` for a full narrative companion document

Generate the presentation now, write to file using Write tool, and show only the summary above.