tractorjuice--arckit-gemini/docs/guides/start.md

Getting Started with ArcKit

Guide Origin: Official | ArcKit Version: [VERSION]

The start and init commands are your entry points to ArcKit. Start gives you orientation and routes you to the right workflow; init creates the project structure.

Command syntax depends on your AI platform:

Platform	Start	Init	Principles
Claude Code / OpenCode	/arckit:start	/arckit:init	/arckit:principles
Gemini CLI	/arckit:start	/arckit:init	/arckit:principles
Codex CLI	$arckit-start	$arckit-init	$arckit-principles
GitHub Copilot	/arckit-start	/arckit-init	/arckit-principles

Examples below use Claude Code / OpenCode syntax. Translate commands using the table above for other platforms.

---

Quick Start

Step 0: Check your platform setup

If ArcKit is already installed and enabled for your platform, skip to Step 1.

For Claude Code, ArcKit v4.14.0 needs Claude Code v2.1.121 or later. From a terminal:

claude install latest
claude --version

If claude isn't on your PATH yet, follow the official Claude Code install guide first, then run claude install latest. ArcKit will warn you at session start if your client is below the supported floor.

For Codex CLI, install or upgrade the ArcKit plugin marketplace and enable plugin hooks:

# First install
codex plugin marketplace add tractorjuice/arckit-codex

# Existing install
codex plugin marketplace upgrade arckit

# Required for plugin-bundled lifecycle hooks
codex features enable hooks
codex features enable plugin_hooks

Restart Codex, run /plugins, choose ArcKit Plugins, then install and enable ArcKit.

For Gemini CLI, OpenCode CLI, and GitHub Copilot, use the platform-specific install steps on the Getting Started page.

Step 1: Run the workflow

# Claude Code / OpenCode: get oriented, initialize, then create principles
/arckit:start
/arckit:init
/arckit:principles

For Codex CLI, the same workflow is:

$arckit-start
$arckit-init
$arckit-principles

Claude Code users — ArcKit "workflows" are unrelated to Claude Code's dynamic-workflows feature. Throughout this guide, "workflow" means an ArcKit command sequence. Claude Code's built-in dynamic workflows (which fan work out across many agents) are a separate feature; as of Claude Code v2.1.160 their free-text trigger keyword is ultracode — the word workflow no longer starts one — so the term is safe to type here. ArcKit ships no ultracode content, and running a slash command (/arckit:start) or the architecture-workflow skill never starts a dynamic workflow. Other platforms (Codex, Gemini, OpenCode, Copilot) have no equivalent feature.

---

Vibe Start — The 3-Prompt Super Prompt

If you want to skip the decision tree and let ArcKit do the heavy lifting, this is the fastest possible path from empty repo to a fully-populated project. Three prompts, no manual orchestration:

1. /arckit:init  This is a project for {one-line description of what you're building}.

2. /arckit:principles

3. Now create all the artifacts. Take your time. Do not stop until complete.

What Happens

• Prompt 1 — init scaffolds the projects/ structure and the one-line description seeds the project context.
• Prompt 2 — principles generates ARC-000-PRIN-v1.0.md, the prerequisite that most other commands depend on.
• Prompt 3 — the assistant works through the standard delivery workflow autonomously: stakeholders → requirements → risk → sobc → adr → data-model → hld-review → roadmap, etc., chaining via the handoffs: metadata in each command's frontmatter.

When To Use It

• Greenfield projects where you want a complete first-pass set of artifacts to react to.
• Demos and proofs of concept where speed matters more than per-command supervision.
• Vibe-coding sessions where you want the assistant to keep going until everything is on disk.

When Not To Use It

• Heavily regulated work (UK Gov Secure by Design, MOD, EU AI Act) where each artifact needs reviewer sign-off before the next is generated.
• Existing projects with artifacts already on disk — run /arckit:navigator first to see what is missing rather than regenerating.
• Token-constrained sessions — the full chain can run dozens of commands. Use Opus 4.7 or 4.8 with the max or xhigh effort levels.

Tips For Vibe Start

• Add constraints to prompt 1: /arckit:init This is a project for X. Target users are Y. Budget is Z.
• Use prompt 3 verbatim — the phrase "do not stop until complete" reliably suppresses early stopping. Followed by /arckit:health to spot anything skipped.
• If the run stalls, resume with: Continue from where you stopped. Do not stop until complete.

---

/arckit:start — Get Oriented

Inputs: None required. Optionally provide a focus area.

# Full onboarding experience
/arckit:start

# Jump to a specific workflow area
/arckit:start new project
/arckit:start procurement
/arckit:start governance review

Output: Console only (no file created). This is a navigation aid, not a governance artifact.

What It Does

1. Welcome banner — shows ArcKit version, command count, and mode
2. Project detection — scans projects/ for existing artifacts and estimates completeness
3. Tool survey — checks for connected MCP servers (AWS Knowledge, Microsoft Learn, Google Developer)
4. Command decision tree — visual routing guide organised by workflow area
5. Context-aware recommendations — suggests 3-5 next steps based on your project maturity
6. Conversational entry points — three quick-start paths for common scenarios

Example Output

ArcKit — The Enterprise Architecture Governance Harness
Plugin mode

Your AI-powered harness for strategy, architecture, delivery, and assurance
— all driven by templates and traceability.

Projects
--------
🟢 [001] nhs-appointment (12 artifacts, ~75% complete)
🟠 [002] data-platform   (4 artifacts, ~30% complete)

Global foundations:
  ✓ Architecture Principles (ARC-000-PRIN-v1.0.md)
  ✓ Policies directory
  ✗ No external reference documents

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)

What are you working on?

Starting a new project
├── No project structure?     → /arckit:init
├── Need principles first?    → /arckit:principles
├── Planning phases & gates?  → /arckit:plan
└── Ready to scope?           → /arckit:stakeholders → /arckit:requirements

...

Suggested next steps
--------------------
1. Project [002] data-platform needs attention (30% complete)
2. Run /arckit:research for data-platform to evaluate technology options
3. Run /arckit:health to scan all projects for stale artifacts

How can I help today?

1. "I'm starting a new project"
2. "I need to make an architecture decision"
3. "I want to review existing work"

---

/arckit:init — Create Project Structure

Inputs: None required.

# Initialize project structure
/arckit:init

Output: Creates projects/ directory structure. No governance artifact is generated.

What It Does

1. Checks for existing structure — looks for a projects/ directory in the current working directory
2. Creates the global directory — sets up projects/000-global/ with policies/ and external/ subdirectories
3. Shows next steps — recommends the first commands to run

Example Output

ArcKit project structure initialized:

projects/
├── 000-global/
│   ├── policies/   (organization-wide policies)
│   └── external/   (external reference documents)

Next steps:
1. Run /arckit:principles to create architecture principles
2. Run /arckit:stakeholders to analyze stakeholders for a project
3. Run /arckit:requirements to create requirements

Individual projects will be created automatically in numbered directories (001-*, 002-*).

Project Structure

After initialization and running a few commands, your project grows into:

projects/
├── 000-global/
│   ├── ARC-000-PRIN-v1.0.md      (architecture principles)
│   ├── policies/                   (organization-wide policies)
│   └── external/                   (external reference documents)
├── 001-project-name/
│   ├── ARC-001-REQ-v1.0.md        (requirements)
│   ├── ARC-001-STKE-v1.0.md       (stakeholder analysis)
│   ├── ARC-001-RISK-v1.0.md       (risk register)
│   └── vendors/                    (vendor evaluations)
└── 002-another-project/
    └── ...

Each command automatically creates numbered project directories (001-*, 002-*) as needed.

---

Workflow Paths

/arckit:start connects to all five standard ArcKit workflows:

Workflow	Entry Point	Key Commands
Standard Delivery	"I'm starting a new project"	init → principles → stakeholders → requirements
UK Government	Compliance focus	service-assessment, tcop, secure, ai-playbook
AI/ML Projects	Architecture decisions	research → adr → mlops → ai-playbook
Cloud Migration	Platform strategy	aws-research / azure-research → platform-design → wardley
Data Platform	Data architecture	data-model → datascout → data-mesh-contract

See WORKFLOW-DIAGRAMS.md for visual workflow diagrams.

---

Tips

• Run /arckit:start at the beginning of any session — it gives you a quick snapshot of where things stand and what to do next.
• Run /arckit:init once per repository — it creates the project structure. Safe to re-run if the structure already exists.
• Use a focus argument like /arckit:start procurement to skip directly to that section of the decision tree.
• Principles next — after init, run /arckit:principles as most commands depend on architecture principles.
• Pairs well with /arckit:health — start gives you navigation, health gives you artifact-level diagnostics.

---

Related Commands

• /arckit:principles — Create architecture principles (run after init)
• /arckit:plan — Create project plan with timeline and phases
• /arckit:health — Detailed artifact health scan
• /arckit:customize — Customize document templates