# 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 needs Claude Code **v2.1.287 or later**. From a terminal:

```bash
claude install latest
claude --version
```

If `claude` isn't on your PATH yet, follow the [official Claude Code install guide](https://docs.claude.com/en/docs/claude-code/quickstart) 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:

```bash
# 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](https://arckit.org/getting-started.html).

### Step 1: Run the workflow

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

For Codex CLI, the same workflow is:

```bash
$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:

```text
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 the Claude Code session default, normally Claude Sonnet 5, and move to Claude Fable 5.1 (the default Fable model since Claude Code v2.1.257) only where your tenant exposes it and the work justifies the higher tier.

### 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.

```bash
# 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

```text
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.

```bash
# 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

```text
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:

```text
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](../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