| name | architecture-workflow |
| description | This skill should be used when the user is starting an architecture project or asking what to run next. Load whenever the task sounds like 'I'm starting a new project', 'guide me through', 'what command should I run', 'what comes next', 'how do I begin', 'help me get started', 'which $arckit-* in what order', 'set up a new project', 'new system build', or 'where do I start'. Recommends a tailored command sequence based on sector, project type, current stage, and timeline. |
Architecture Workflow
Guides users through project onboarding using adaptive-depth questions and recommends a tailored command sequence.
Do NOT run any `$arckit-*` commands during this process. Your only output is a recommended command plan. The user decides when and what to execute. This applies regardless of how simple the project seems.
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 by asking the user. 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
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 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):
| Condition | Modifier |
|---|
| Project type = AI/ML | Apply ai-ml-path.md |
| Project type = Data platform | Apply data-path.md |
| Both AI/ML and Data | Apply both modifiers |
Scope adjustments:
| Goal | Adjustment |
|---|
| Full governance lifecycle | Show full path from base + modifiers |
| Specific deliverable | Show only the relevant phase |
| Compliance check | Show only compliance phase from base path |
| Quick prototype documentation | Show minimum viable path from base path |
| Stage | Adjustment |
|---|
| Just starting | Show full path (or scoped path) |
| Have stakeholders/requirements | Skip Phases 1-2, start from Phase 3 |
| Have design artifacts | Skip to Phase 4 (Procurement) or Phase 5 (Design Reviews) |
| Need compliance review | Skip to compliance phase |
| Timeline | Adjustment |
|---|
| Weeks | Show minimum viable path only |
| Months | Show full path, note optional commands |
| Quarters | Show full path with all optional additions |
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.
