Skip to main content

/arckit.start

The /arckit.start command provides a guided onboarding and navigation experience for ArcKit. It analyzes your current project state and recommends the best next steps.
This is a slash command (not a CLI command). Run it from within your AI assistant after initializing your project with arckit init.

Description

Provides a console-only diagnostic and navigation aid that:
  • Displays ArcKit version and available commands
  • Detects current project state (projects, artifacts, completeness)
  • Checks connected MCP tools (AWS, Azure, GCP research)
  • Shows command decision tree organized by workflow
  • Provides context-aware recommendations based on project state
  • Offers conversational entry points for common workflows
This command does not create a file. It outputs a navigation aid to help you choose your next command.

Usage

/arckit.start [WORKFLOW_FOCUS]

Basic Examples

# General onboarding (shows full decision tree)
/arckit.start

# Focus on specific workflow area
/arckit.start new project
/arckit.start procurement
/arckit.start governance review

Arguments

WORKFLOW_FOCUS
string
Optional focus area to jump directly to a specific workflow section.Examples:
  • new project - Show project initiation workflow
  • procurement - Show vendor procurement workflow
  • governance - Show quality and governance workflow
  • compliance - Show UK Government compliance workflow

What It Shows

Welcome Banner

Displays ArcKit version and high-level summary:
ArcKit β€” Enterprise Architecture Governance Toolkit
Version 0.11.5 | 54 commands | Plugin mode

Your AI-powered assistant for architecture governance, vendor procurement,
and compliance β€” all driven by templates and traceability.

Project State Detection

Scans your projects/ directory and displays:
  • Project inventory with completeness estimates
  • Global foundations (architecture principles, policies, external docs)
  • Artifact summary for each project
Example output:
Projects
--------
🟒 [001] windows-11-migration-intune (12 artifacts, ~75% complete)
🟠 [002] application-packaging (5 artifacts, ~30% complete)

Global foundations:
  βœ“ Architecture Principles (ARC-000-PRIN-v1.0.md)
  βœ— No policies directory
  βœ— No external reference documents
Completeness heuristic:
PercentageProject State
0-24%Only stakeholders/principles/requirements
25-49%Has research, data-model, or ADRs
50-74%Has design reviews, SOW, or evaluations
75-100%Has traceability, governance analysis, conformance

Connected Tools

Shows which MCP servers are available (if any):
Connected Tools
---------------
βœ“ AWS Knowledge β€” AWS service research and architecture patterns
βœ“ Microsoft Learn β€” Azure and Microsoft documentation
βœ— Google Developer β€” not connected (GCP research available via web search fallback)
This section only appears if at least one cloud research MCP is detected.

Command Decision Tree

Shows all 54 commands organized by workflow:
What are you working on?

Starting a new project
β”œβ”€β”€ No project structure?     β†’ /arckit.init
β”œβ”€β”€ Need principles first?    β†’ /arckit.principles (global, required by most commands)
β”œβ”€β”€ Planning phases & gates?  β†’ /arckit.plan
└── Ready to scope?           β†’ /arckit.stakeholders β†’ /arckit.requirements

Architecture decisions
β”œβ”€β”€ Technology research?      β†’ /arckit.research (build vs buy, market scan)
β”œβ”€β”€ Cloud service research?   β†’ /arckit.aws-research, /arckit.azure-research, /arckit.gcp-research
β”œβ”€β”€ Data architecture?        β†’ /arckit.data-model β†’ /arckit.datascout
β”œβ”€β”€ Platform strategy?        β†’ /arckit.platform-design β†’ /arckit.wardley
└── Record a decision?        β†’ /arckit.adr

Procurement & evaluation
β”œβ”€β”€ Statement of work / RFP?  β†’ /arckit.sow
β”œβ”€β”€ G-Cloud services?         β†’ /arckit.gcloud-search β†’ /arckit.gcloud-clarify
β”œβ”€β”€ Digital Outcomes?          β†’ /arckit.dos
└── Evaluate vendors?         β†’ /arckit.evaluate

Quality & governance
β”œβ”€β”€ Artifact health scan?     β†’ /arckit.health
β”œβ”€β”€ Governance analysis?      β†’ /arckit.analyze
β”œβ”€β”€ Architecture conformance? β†’ /arckit.conformance
β”œβ”€β”€ Principles compliance?    β†’ /arckit.principles-compliance
└── Traceability matrix?      β†’ /arckit.traceability

UK Government compliance
β”œβ”€β”€ GDS Service Standard?     β†’ /arckit.service-assessment
β”œβ”€β”€ Technology Code of Practice? β†’ /arckit.tcop
β”œβ”€β”€ Secure by Design?         β†’ /arckit.secure
β”œβ”€β”€ AI Playbook?              β†’ /arckit.ai-playbook
└── MOD Secure by Design?     β†’ /arckit.mod-secure

Reporting & publishing
β”œβ”€β”€ Project narrative?        β†’ /arckit.story
β”œβ”€β”€ MARP presentation?        β†’ /arckit.presentation
└── GitHub Pages site?        β†’ /arckit.pages

Context-Aware Recommendations

Based on your project state, provides 3-5 specific next steps: Example for empty project:
Suggested next steps
--------------------
1. Run /arckit.principles to establish architecture principles (required by most commands)
2. Run /arckit.stakeholders to analyze stakeholder drivers and goals
3. Run /arckit.requirements to create your requirements specification
Example for 50% complete project:
Suggested next steps
--------------------
1. Run /arckit.sow to generate vendor RFP (requirements are complete)
2. Run /arckit.evaluate to create vendor evaluation framework
3. Run /arckit.hld-review to prepare for design gate

Conversational Entry Points

Offers three guided workflows:
How can I help today?

1. "I'm starting a new project"
   β†’ I'll guide you through init β†’ principles β†’ stakeholders β†’ requirements

2. "I need to make an architecture decision"
   β†’ I'll help with research, ADRs, and design reviews

3. "I want to review existing work"
   β†’ I'll run health checks, governance analysis, and compliance scans
After this prompt, the assistant waits for your response and begins the selected workflow.

Prerequisites

The command expects a project structure created by arckit init:
arckit init my-project --ai codex
cd my-project

Example Output

ArcKit β€” Enterprise Architecture Governance Toolkit
Version 0.11.5 | 54 commands | Plugin mode

Your AI-powered assistant for architecture governance, vendor procurement,
and compliance β€” all driven by templates and traceability.

Projects
--------
No project structure found. Run /arckit.init to create your first project.

What are you working on?

Starting a new project
β”œβ”€β”€ No project structure?     β†’ /arckit.init
β”œβ”€β”€ Need principles first?    β†’ /arckit.principles (global, required by most commands)
β”œβ”€β”€ Planning phases & gates?  β†’ /arckit.plan
└── Ready to scope?           β†’ /arckit.stakeholders β†’ /arckit.requirements

[... full decision tree ...]

Suggested next steps
--------------------
1. Run /arckit.init to create your project structure
2. Run /arckit.principles to establish architecture principles
3. Run /arckit.plan to create your project timeline

How can I help today?

1. "I'm starting a new project"
   β†’ I'll guide you through init β†’ principles β†’ stakeholders β†’ requirements

2. "I need to make an architecture decision"
   β†’ I'll help with research, ADRs, and design reviews

3. "I want to review existing work"
   β†’ I'll run health checks, governance analysis, and compliance scans

Usage Patterns

Daily Standup

Run at the start of your work session:
/arckit.start
Quickly see:
  • What projects need attention
  • What artifacts are missing
  • What governance checks are due

New Team Member Onboarding

New team member runs:
/arckit.start
They immediately see:
  • Project inventory
  • Current state of each project
  • Available commands organized by workflow
  • Recommended next steps

Workflow-Specific Navigation

Jump to a specific workflow area:
/arckit.start procurement
Expands the procurement section with detailed guidance:
Procurement & evaluation
β”œβ”€β”€ Statement of work / RFP?
β”‚   β†’ /arckit.sow
β”‚   Prerequisites: requirements, architecture principles
β”‚   Creates: ARC-{ID}-SOW-v1.0.md
β”‚   
β”œβ”€β”€ G-Cloud services?
β”‚   β†’ /arckit.gcloud-search (find services)
β”‚   β†’ /arckit.gcloud-clarify (validate and clarify)
β”‚   Prerequisites: requirements
β”‚   Creates: ARC-{ID}-GCLD-v1.0.md, clarification questions
β”‚   
β”œβ”€β”€ Digital Outcomes?
β”‚   β†’ /arckit.dos
β”‚   Prerequisites: requirements
β”‚   Creates: DOS procurement pack
β”‚   
└── Evaluate vendors?
    β†’ /arckit.evaluate
    Prerequisites: SOW, vendor proposals
    Creates: ARC-{ID}-EVAL-v1.0.md, scoring matrix

Troubleshooting

Symptom:
No project structure found. Run /arckit.init to create your first project.
Cause: The projects/ directory does not exist or is empty.Solution: Run /arckit.plan or manually create a project directory:
mkdir -p projects/001-my-project
Symptom: Version shows as β€œunknown” or is missing.Cause: The VERSION file is missing from the project root.Solution: Run arckit init again to refresh project files:
arckit init --here --ai codex
Symptom: β€œConnected Tools” section is missing.Cause: No MCP servers are configured or connected.Solution: This is normal. The section only appears if at least one cloud research MCP is available. To enable:
  • Install AWS Knowledge MCP
  • Install Microsoft Learn MCP
  • Install Google Developer Knowledge MCP

arckit init

Initialize ArcKit project structure

/arckit.plan

Create project plan with timeline

/arckit.principles

Define architecture principles

/arckit.health

Scan projects for quality issues

Build docs developers (and LLMs) love