architecture-workflow

Architecture Workflow

Guides users through project onboarding using adaptive-depth questions and recommends a tailored command sequence.

Anti-Patterns

"I already know what I need"

Even experienced architects benefit from the triage. It catches blind spots — missing compliance requirements, forgotten dependencies, stakeholder gaps. The triage is fast (3-4 questions). Skip it and you risk generating artifacts in the wrong order or missing mandatory prerequisites.

"Just run everything"

A 30-command sequence helps nobody. The skill's job is to recommend the right commands for this project, in the right order. Every project is different — a compliance review needs 6 commands, not 30.

Process

Follow these steps in order. Ask questions one at a time using AskUserQuestion. Prefer multiple-choice options.

Step 1: Detect Project State

Automatically check the project context (no questions needed):

• Check if projects/ directory exists and count projects
• Check for principles document (ARC-000-PRIN-*)
• Count existing artifacts per project
• Use ArcKit Project Context from the SessionStart hook if available

Based on findings, determine:

• New project: No projects/ directory or empty — recommend starting from scratch
• Early stage: Projects exist but few artifacts (0-24% complete) — recommend next foundation steps
• Mid stage: Has requirements, some design artifacts (25-74%) — recommend design and procurement steps
• Late stage: Has most artifacts (75-100%) — recommend quality, compliance, and reporting steps

Display a brief status summary before asking questions:

Project State: [1 project found, 4 artifacts, ~20% complete]

Or:

Project State: No project structure found. Starting fresh.

Step 2: Triage Questions

Ask these questions one at a time. Each uses AskUserQuestion with multiple-choice options.

Question 1 — Sector:

• UK Government (civilian departments)
• Defence (MOD, defence contractors)
• Public sector (non-UK)
• Private sector

Question 2 — Project Type:

• New system build
• System migration or modernization
• Procurement / vendor selection
• Data platform or analytics
• AI/ML system
• Strategy or governance review only

Question 3 — Current Stage:

• Just starting (no artifacts yet)
• Have stakeholders and/or requirements
• Have design artifacts (data model, research, diagrams)
• Need compliance review of existing work

Question 4 — Primary Goal:

• Full governance lifecycle (end-to-end)
• Specific deliverable (e.g., just requirements, just SOBC)
• Compliance check (assess existing work)
• Quick prototype documentation (minimum viable)

Step 3: Deep Questions (Complex Projects Only)

Only ask these if the project triggers complexity:

• Sector is UK Government or Defence
• Project type is AI/ML
• Primary goal is full governance lifecycle

Ask one at a time:

Q5 — Compliance Frameworks (multiple select):

• GDS Service Standard
• Technology Code of Practice (TCoP)
• NCSC Cyber Assessment Framework
• AI Playbook
• JSP 440 / MOD Secure by Design
• JSP 936 / MOD AI Assurance
• None / not sure

Q6 — Procurement (if applicable):

• G-Cloud (Digital Marketplace)
• Digital Outcomes and Specialists (DOS)
• Open tender / framework agreement
• No procurement needed

Q7 — Strategic Analysis:

• Yes, need Wardley Maps and strategic positioning
• Yes, need platform design (multi-sided platform)
• No, straightforward technology choices

Q8 — Timeline Pressure:

• Weeks (urgent, minimum viable only)
• Months (standard delivery)
• Quarters (major programme, full governance)

Step 4: Present Tailored Plan

Based on the answers, select the appropriate path and present the plan.

Decision Logic

Base path selection:

Modifiers (applied on top of base path):

Scope adjustments:

Plan Output Format

Present the plan as a numbered list grouped by phase:

Recommended Command Sequence
=============================

Based on: [UK Government] + [AI/ML] project, starting fresh, full lifecycle

Phase 1: Foundation
  1. /arckit:principles — Governance foundation (GDS + TCoP aligned)
  2. /arckit:stakeholders — Map DDaT roles, SROs, policy owners
  3. /arckit:risk — HMG Orange Book risk methodology

Phase 2: Business Justification
  4. /arckit:sobc — HM Treasury Green Book 5-case model
  5. /arckit:requirements — Central artifact for all downstream work

Phase 3: Design & Analysis
  6. /arckit:datascout — Discover UK Gov open data sources
  7. /arckit:data-model — Data architecture with GDPR considerations
  ...

[Total: N commands across M phases]
[Estimated duration: X-Y months]

Run commands in order. Each command will guide you through its process.

After presenting the plan, ask if they want to adjust anything or if they're ready to begin.

Key Principles

• One question at a time — do not overwhelm with multiple questions per message
• Multiple choice preferred — easier to answer than open-ended
• Adaptive depth — simple projects get 4 questions, complex get 8
• Scaled output — minimum viable = 5 commands, full lifecycle = 25-30
• No commands executed — only present the plan, user drives execution
• Reference existing artifacts — skip phases where artifacts already exist

ArcKit Integration

This skill is invoked by the /arckit:start command, which delegates project onboarding to this skill. Users can also trigger it by asking about getting started, command sequences, or workflow recommendations.

For the detailed command dependency matrix, see DEPENDENCY-MATRIX.md in the user's project root (installed by arckit init). For visual workflow diagrams, see WORKFLOW-DIAGRAMS.md in the user's project root.