Skip to content

CLAUDE.md

Latest commit

 

History

History
476 lines (360 loc) · 24.4 KB

CLAUDE.md

File metadata and controls

476 lines (360 loc) · 24.4 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

ArcKit is an Enterprise Architecture Governance & Vendor Procurement Toolkit providing 67 slash commands for AI coding assistants (Claude Code, Codex CLI, Gemini CLI, OpenCode CLI) to generate architecture artifacts. It transforms architecture governance from scattered documents into a systematic, template-driven process.

Six distribution formats exist side-by-side in this repo:

  1. CLI package (src/arckit_cli/) -- Python CLI installed via pip/uv, runs arckit init to scaffold projects for Codex CLI or OpenCode CLI (copies templates/commands into them)
  2. Claude Code plugin (arckit-claude/) -- Standalone plugin for Claude Code, installed via marketplace (/plugin marketplace add tractorjuice/arc-kit)
  3. Gemini CLI extension (arckit-gemini/) -- Native extension for Gemini CLI with sub-agents, hooks, policies, and GDS theme, published as a separate repo (tractorjuice/arckit-gemini) and installed via gemini extensions install
  4. OpenCode CLI extension (arckit-opencode/) -- Extension for OpenCode CLI, scaffolded via arckit init --ai opencode
  5. Codex CLI extension (arckit-codex/) -- Standalone extension for Codex CLI with skills, agents, and MCP servers, published as a separate repo (tractorjuice/arckit-codex)
  6. Copilot extension (arckit-copilot/) -- Prompt files + custom agents for GitHub Copilot in VS Code, scaffolded via arckit init --ai copilot

The CLI and plugin have independent version numbers (CLI: VERSION + pyproject.toml, Plugin: arckit-claude/VERSION + arckit-claude/.claude-plugin/plugin.json). The Gemini extension version tracks the plugin version (arckit-gemini/VERSION + arckit-gemini/gemini-extension.json). The OpenCode extension version also tracks the plugin version (arckit-opencode/VERSION). The Codex extension version also tracks the plugin version (arckit-codex/VERSION). The Copilot extension version also tracks the plugin version (arckit-copilot/VERSION). Claude Code support was removed from the CLI in favour of the plugin, which references files in-place via ${CLAUDE_PLUGIN_ROOT}. The Gemini, OpenCode, Codex, and Copilot extensions are generated by scripts/converter.py which rewrites paths, copies supporting files, generates config.toml (Codex MCP + agent roles), and rewrites skill command references.

Build & Development Commands

# Install in development mode
pip install -e .
# Or using uv (recommended)
uv pip install -e .

# Test CLI
arckit --help
arckit check

# Test project initialization
arckit init test-project --ai codex --no-git
arckit init test-project --ai opencode --no-git
arckit init test-project --ai codex --minimal  # Skip docs/guides
cd test-project && ls -la .agents/skills/

# Build distribution
python -m build

# Convert Claude commands to Codex, OpenCode, Gemini, and Copilot extension formats
python scripts/converter.py

# Debug data path resolution
python -c "from arckit_cli import get_data_paths; print(get_data_paths())"

# Lint markdown files
npx markdownlint-cli2 "**/*.md"

# Auto-fix markdown lint violations
npx markdownlint-cli2 --fix "**/*.md"

Architecture

Core Components

CLI Entry Point (src/arckit_cli/__init__.py):

  • Single-file CLI using typer for command parsing
  • arckit init creates project structure and copies templates/commands from package data
  • arckit check validates tool installation
  • get_data_paths() handles data resolution across install methods (uv tools, pip, source)

Package Data (distributed via pyproject.toml shared-data):

  • .codex/prompts/arckit.*.md - Codex prompts (generated by scripts/converter.py, paths -> .arckit)
  • .opencode/commands/arckit.*.md - OpenCode commands (generated by scripts/converter.py, paths -> .arckit)
  • .arckit/templates/*.md - Document templates
  • scripts/bash/*.sh - Helper scripts
  • docs/guides/*.md - Command usage guides
  • docs/README.md - Documentation index
  • docs/DEPENDENCY-MATRIX.md - Command dependencies
  • docs/WORKFLOW-DIAGRAMS.md - Visual workflows

Claude Code commands/agents are now exclusively in the plugin (arckit-claude/commands/, arckit-claude/agents/).

Data Path Resolution Order (in get_data_paths()):

  1. Source/dev mode: {repo_root}/ (if .arckit and .codex dirs exist)
  2. uv tool install: ~/.local/share/uv/tools/arckit-cli/share/arckit/
  3. pip install: {site-packages}/share/arckit/
  4. platformdirs: {user_data_dir}/arckit/
  5. Fallback to source: {repo_root}/

Slash Command System

Commands exist in multiple formats across the distribution:

Plugin (Claude Code): arckit-claude/commands/{name}.md - YAML frontmatter + prompt, loaded via plugin auto-discovery. Frontmatter supports effort: for model effort override and handoffs: for machine-readable next-step workflow metadata (see schema below) Gemini Extension: arckit-gemini/commands/arckit/{name}.toml - TOML format (generated by scripts/converter.py, paths rewritten to ~/.gemini/extensions/arckit) Codex CLI: .codex/prompts/arckit.{name}.md - Markdown format (generated by scripts/converter.py, paths rewritten to .arckit) OpenCode CLI: .opencode/commands/arckit.{name}.md - Markdown format (generated by scripts/converter.py, paths rewritten to .arckit)

Multi-AI Command Formats:

AI Format Location
Claude Code /arckit.requirements (plugin) arckit-claude/commands/requirements.md
Codex CLI $arckit-requirements (skill) .agents/skills/arckit-requirements/SKILL.md
Gemini CLI /arckit:requirements (extension) arckit-gemini/commands/arckit/requirements.toml
OpenCode CLI /arckit.requirements .opencode/commands/arckit.requirements.md
Copilot /arckit-requirements (prompt) arckit-copilot/prompts/arckit-requirements.prompt.md

Handoffs Schema

Commands can declare handoffs: in YAML frontmatter to specify suggested next steps. The converter renders these as a ## Suggested Next Steps section in Codex/OpenCode/Gemini output. Plugin commands leave handoffs as raw YAML (Claude Code reads frontmatter directly).

---
description: Create comprehensive business and technical requirements
effort: max
handoffs:
  - command: data-model
    description: Create data model from data requirements
    condition: "DR-xxx data requirements were generated"
  - command: research
    description: Research technology options
---

Fields per handoff entry:

  • command (required): Command name without arckit: prefix (matches filename stem)
  • description (optional): Why this is a logical next step
  • condition (optional): Human-readable condition when this handoff applies

Effort field (optional): Overrides the session effort level when the command is invoked. Valid values: low, medium, high, max (requires Opus 4.6). Only set on commands that benefit from deeper reasoning — simple utility commands inherit the session default. The converter strips this field for non-Claude targets.

Agent System

Some commands delegate to autonomous agents (arckit-claude/agents/arckit-{name}.md) that run as subprocesses via the Task tool. Agents are used for commands that perform extensive web research (dozens of WebSearch/WebFetch calls) to keep that context isolated from the main conversation.

Current Agents (plugin only):

Agent Command Purpose
arckit-research /arckit.research Market research, vendor evaluation, build vs buy, TCO
arckit-datascout /arckit.datascout Data source discovery, API catalogue search, scoring
arckit-aws-research /arckit.aws-research AWS service research via AWS Knowledge MCP
arckit-azure-research /arckit.azure-research Azure service research via Microsoft Learn MCP
arckit-gcp-research /arckit.gcp-research GCP service research via Google Developer Knowledge MCP
arckit-framework /arckit.framework Transform artifacts into structured framework with principles, patterns, and guidance
arckit-gov-reuse /arckit.gov-reuse Government code reuse assessment via govreposcrape
arckit-gov-code-search /arckit.gov-code-search Government code semantic search via govreposcrape
arckit-gov-landscape /arckit.gov-landscape Government code landscape analysis via govreposcrape

Agent file structure (arckit-claude/agents/arckit-{name}.md):

---
name: arckit-{name}
description: |
  Use this agent when [triggering conditions]. Examples:
  <example>...</example>
model: inherit
---

You are [role description]...

## Process
1. Read prerequisites
2. Conduct web research
3. Write document to file
4. Return summary only

Plugin agent frontmatter: Valid fields are name (required), description (required), model (optional), effort (optional), maxTurns (optional), disallowedTools (optional). Fields like color, permissionMode, tools are invalid in plugin context and cause errors. Requires Claude Code v2.1.78+ for effort, maxTurns, and disallowedTools.

When to make a command an agent: If the command performs heavy WebSearch/WebFetch/MCP calls (>10 calls), reads many artifacts, or produces large intermediate context. The slash command becomes a thin wrapper that launches the agent via Task tool, with a fallback to direct execution.

Multi-AI note: Agents are Claude Code only. Codex, OpenCode, and Gemini extension equivalents keep the full inline prompts since they don't support the Task/agent architecture. The converter (scripts/converter.py) automatically extracts agent prompts and inlines them into Codex/OpenCode Markdown and Gemini extension TOML formats.

Project Structure Created by arckit init

project/
├── .arckit/
│   ├── templates/        # Document templates
│   └── scripts/bash/     # create-project.sh, generate-document-id.sh, etc.
├── .agents/skills/       # Codex CLI skills (auto-discovered, invoked as $arckit-*)
├── .codex/
│   ├── agents/           # Agent configs (.toml + .md)
│   └── config.toml       # MCP servers + agent roles
├── .opencode/commands/   # OpenCode CLI commands
├── docs/                 # Documentation (unless --minimal)
│   ├── README.md         # Documentation index
│   ├── guides/           # Command usage guides
│   ├── DEPENDENCY-MATRIX.md  # Command dependencies
│   └── WORKFLOW-DIAGRAMS.md  # Visual workflows
└── projects/
    ├── 000-global/       # Cross-project artifacts
    │   └── ARC-000-PRIN-v1.0.md  # Global architecture principles
    └── 001-project-name/ # Numbered project directories
        ├── ARC-001-REQ-v1.0.md      # Requirements
        ├── ARC-001-STKE-v1.0.md     # Stakeholder analysis
        ├── ARC-001-RISK-v1.0.md     # Risk register
        ├── ARC-001-SOBC-v1.0.md     # Business case
        ├── ARC-001-ADR-001-v1.0.md  # ADRs (multi-instance)
        ├── ARC-001-DIAG-001-v1.0.md # Diagrams (multi-instance)
        └── vendors/

Init flags:

  • --ai codex / --ai opencode / --ai copilot - Select AI assistant. --ai claude redirects to plugin installation. --ai gemini redirects to extension installation.
  • --minimal - Skip docs, guides, and reference files
  • --no-git - Skip git repository initialization
  • --here - Initialize in current directory

Helper Scripts

scripts/bash/common.sh: Shared utility functions (find repo root, get paths, slugify, logging) sourced by all other scripts scripts/bash/create-project.sh: Creates numbered project directories (001-, 002-), returns JSON with path scripts/bash/generate-document-id.sh: Generates doc IDs (e.g., ARC-001-REQ-v1.0) and filenames

  • --filename flag returns the filename with .md extension
  • --next-num flag returns the next sequential number for multi-instance types (ADR, DIAG, WARD, DMC) scripts/bash/check-prerequisites.sh: Validates environment (principles exist, tools available) scripts/bash/list-projects.sh: Lists all ArcKit projects with artifact counts (table or JSON output) scripts/bash/migrate-filenames.sh: Migrates existing project files to new naming convention (supports --dry-run) scripts/converter.py: Config-driven converter using AGENT_CONFIG dictionary — adding a new AI target only requires a new dict entry. Converts plugin commands (arckit-claude/commands/*.md) to all configured output formats (currently: Codex Markdown .codex/, Codex Skills arckit-codex/skills/arckit-*/ with SKILL.md + agents/openai.yaml, OpenCode Markdown .opencode/ + arckit-opencode/, Gemini extension TOML arckit-gemini/, Copilot prompt .prompt.md arckit-copilot/). The "skill" format creates directory-per-command with YAML frontmatter (name, description) and allow_implicit_invocation: false. Rewrites ${CLAUDE_PLUGIN_ROOT} paths, copies supporting files to extension dirs, and extracts full agent prompts for non-Claude targets. For the Codex extension, also generates config.toml (MCP servers + agent roles), per-agent .toml files with developer_instructions, and rewrites skill command references (/arckit:X -> /prompts:arckit.X). Key functions: rewrite_paths(prompt, config), format_output(description, prompt, fmt), convert(commands_dir, agents_dir), copy_extension_files(plugin_dir), generate_codex_config_toml(), generate_agent_toml_files(), rewrite_codex_skills(), generate_gemini_agents(), generate_gemini_hooks(), generate_gemini_policies(), generate_copilot_agents(), generate_copilot_instructions() — all driven by AGENT_CONFIG scripts/bump-version.sh: Updates all 13 version files in one go (VERSION, pyproject.toml, README.md, docs, plugin, extensions) scripts/generate-release-notes.sh: Parses git log between tags into Keep a Changelog sections (Added/Fixed/Changed/Breaking Changes). Filters out chore: bump version commits. Auto-detects previous tag if none supplied scripts/push-extensions.sh: Pushes extension directories to their separate GitHub repos (tractorjuice/arckit-gemini, tractorjuice/arckit-codex, etc.). Clones each repo, syncs files, commits, and pushes. Uses GH_TOKEN for auth. Usage: ./scripts/push-extensions.sh (all) or ./scripts/push-extensions.sh gemini codex (selective). Skips repos that don't exist on GitHub yet

Adding a New Slash Command

  1. Create arckit-claude/commands/{name}.md with YAML frontmatter (this is the source of truth for Claude Code)
  2. Create .arckit/templates/{name}-template.md with document control section (also copy to arckit-claude/templates/)
  3. Create docs/guides/{name}.md with usage guide (also copy to arckit-claude/guides/)
  4. If command needs heavy web research (>10 WebSearch/WebFetch calls), also create arckit-claude/agents/arckit-{name}.md and make the slash command a thin wrapper that delegates to the agent
  5. Run python scripts/converter.py to generate Codex Markdown (.codex/), OpenCode Markdown (.opencode/ + arckit-opencode/), Gemini extension TOML (arckit-gemini/), and Copilot prompts (arckit-copilot/)
  6. Test plugin: Open a test repo with the plugin enabled and run the command
  7. Test CLI: arckit init test --ai codex --no-git && cd test && codex (or --ai opencode)
  8. Update documentation: README.md, docs/index.html, docs/DEPENDENCY-MATRIX.md, CHANGELOG.md

Command must:

  • Check prerequisites before generating
  • Use create-project.sh --json to get/create project path
  • Read the corresponding template file
  • Use Write tool to save output (avoids token limit issues)
  • Show only a summary to user
  • Delegate to agent if research-heavy (see Agent System above)
  • Add handoffs: to frontmatter if the command has logical next steps (see Handoffs Schema above)

Template Customization

Users can customize document templates to match their organization's requirements.

Template locations:

  • Defaults: .arckit/templates/ (shipped with ArcKit, refreshed by arckit init)
  • User overrides: .arckit/templates-custom/ (your customizations, preserved across updates)

How it works:

  1. Commands check .arckit/templates-custom/ first (user override)
  2. Fall back to .arckit/templates/ if no override exists
  3. User customizations are preserved when ArcKit CLI updates

Workflow:

# List available templates
/arckit.customize list

# Copy a template for customization
/arckit.customize requirements

# Edit the template
# (file is now at .arckit/templates-custom/requirements-template.md)

# Run command - uses your customized template
/arckit.requirements My Project

Common customizations:

  • Remove UK Government sections for non-UK Gov projects
  • Add organization-specific Document Control fields
  • Change requirement ID prefixes (BR/FR/NFR → custom)
  • Add branding, headers, footers

Plugin Version (arckit-claude/):

  • Plugin commands reference templates via ${CLAUDE_PLUGIN_ROOT}/templates/
  • User overrides in .arckit/templates/ or .arckit/templates-custom/ take precedence
  • When adding/modifying templates, update both arckit-claude/templates/ and .arckit/templates/

Document Control Standard

Every template must start with a Document Control table followed by Revision History:

Document Control fields (in order):

Field Example
Document ID ARC-001-REQ-v1.0 (use generate-document-id.sh)
Document Type Requirements Specification
Project PROJECT_NAME (Project PROJECT_ID)
Classification PUBLIC / OFFICIAL / OFFICIAL-SENSITIVE / SECRET
Status DRAFT / IN_REVIEW / APPROVED / PUBLISHED / SUPERSEDED / ARCHIVED
Version 1.0
Created Date YYYY-MM-DD
Last Modified YYYY-MM-DD
Review Cycle Monthly / Quarterly / Annual / On-Demand
Next Review Date YYYY-MM-DD
Owner Role or individual
Reviewed By Name (date) or PENDING
Approved By Name (date) or PENDING
Distribution Distribution list

Domain-specific fields (e.g., "ADR Number", "Assessment Phase") go after standard fields.

Revision History columns: Version | Date | Author | Changes | Approved By | Approval Date

Standard Footer (at end of every template):

---

**Generated by**: ArcKit `/arckit.{command}` command
**Generated on**: [DATE]
**ArcKit Version**: [VERSION]
**Project**: [PROJECT_NAME]
**Model**: [AI_MODEL]

Version Management

CLI version (keep synchronized):

  1. VERSION file (source of truth)
  2. pyproject.toml version field

Plugin version (independent from CLI, keep synchronized):

  1. arckit-claude/VERSION (source of truth)
  2. arckit-claude/.claude-plugin/plugin.json version field

Extension versions (track plugin version):

  • arckit-gemini/VERSION + arckit-gemini/gemini-extension.json
  • arckit-opencode/VERSION
  • arckit-codex/VERSION
  • arckit-copilot/VERSION

Release automation:

  • scripts/bump-version.sh <version> updates all 13 version files at once
  • scripts/generate-release-notes.sh [prev-tag] parses git log into Keep a Changelog markdown (auto-detects previous tag if omitted)
  • .github/workflows/release.yml creates a GitHub Release automatically on v* tag push (tag-push triggered, does NOT commit back to main)

Development workflow:

All changes must go through a feature branch and be merged to main via PR. Never push directly to main.

# 1. Create a feature branch
git checkout -b feat/my-feature

# 2. Make changes, commit
git add <files> && git commit -m "feat: description"

# 3. Push branch and create PR
git push -u origin feat/my-feature
gh pr create --title "feat: description" --body "Summary of changes"

# 4. Merge PR (squash or merge commit)
gh pr merge --squash

Local release flow (after PR is merged to main):

# 1. Ensure you're on main with latest changes
git checkout main && git pull
# 2. Edit CHANGELOGs manually
# 3. Preview release notes (optional)
./scripts/generate-release-notes.sh
# 4. Bump all version files
./scripts/bump-version.sh X.Y.Z
# 5. Regenerate Codex/OpenCode/Gemini formats
python scripts/converter.py
# 6. Commit, tag, push — GitHub Release created automatically
git add -A && git commit -m "chore: bump version to X.Y.Z"
git tag -a vX.Y.Z -m "vX.Y.Z"
git push && git push --tags
# 7. Push to extension repos (Gemini, Codex, etc.)
./scripts/push-extensions.sh

Adding new package data files: Update pyproject.toml [tool.hatch.build.targets.wheel.shared-data]

Test Repositories

ArcKit maintains 22 test repos on GitHub (pattern: arckit-test-project-v*):

Version Name Type Description
v0 mod-chatbot Private MOD chatbot project
v1 m365 Public Microsoft 365 migration
v2 hmrc-chatbot Public HMRC chatbot
v3 windows11 Public Windows 11 deployment
v4 ipa Private Infrastructure Projects Authority
v5 dstl Private Defence Science & Technology Lab
v6 patent-system Public Patent system modernization
v7 nhs-appointment Public NHS appointment booking
v8 ons-data-platform Public ONS data platform
v9 cabinet-office-genai Public Cabinet Office GenAI
v10 training-marketplace Public UK Government Training Marketplace
v11 national-highways-data Public National Highways data architecture
v12 honky-tonks Private Restaurant data analytics
v13 plymouth-research Private Plymouth restaurant web scraping
v14 scottish-courts Public Scottish Courts and Tribunals Service GenAI strategy
v15 ipad-framework Private Investment Promotion Agency Data Framework
v16 doctors-appointment Public Doctors Online Appointment System
v17 fuel-prices Public UK Government Fuel Price Transparency Service
v18 smart-meter Public UK Smart Meter Data Consumer Mobile App
v19 gov-api-aggregator Public UK Government API Aggregator
v20 uae-moi-ipad Private UAE MOI IPAD Framework
v21 criminal-courts Public Independent Review of the Criminal Courts - Technology & AI

Plugin-based setup (since 2026-02-07):

All test repos now use the arckit plugin via the marketplace instead of synced files. Each repo has a .claude/settings.json that auto-enables the plugin:

{
  "extraKnownMarketplaces": {
    "arc-kit": {
      "source": {
        "source": "github",
        "repo": "tractorjuice/arc-kit"
      }
    }
  },
  "enabledPlugins": {
    "arckit@arc-kit": true
  }
}

What the plugin provides (no longer synced to test repos):

  • Commands, agents, templates, scripts, MCP servers (AWS Knowledge + Microsoft Learn)

What stays in test repos (repo-specific content):

  • projects/ (generated architecture artifacts)
  • docs/ (including index.html, README.md, guides/, manifest.json)
  • README.md, CLAUDE.md (repo-specific)
  • .devcontainer/, CHANGELOG.md, VERSION

Note: Plugin requires a Claude Code restart after first opening a repo to resolve the marketplace. Plugin updates are picked up automatically from the marketplace repo — no file syncing needed. After updating pages-template.html in the plugin, re-run /arckit:pages in each repo that has a docs/index.html to regenerate it.

Key Patterns

Agent Delegation: Commands that perform heavy web research (research, datascout) delegate to agents in arckit-claude/agents/ via the Task tool. The slash command is a thin wrapper; the agent runs autonomously in its own context window.

Token Limit Handling: Commands MUST use Write tool for large documents (requirements, SOBC, research) to avoid 32K output token limit.

Template-Driven Generation: Never generate freeform documents - always use templates from .arckit/templates/.

Traceability Chain: Stakeholders → Goals → Requirements (BR/FR/NFR/INT/DR) → Data Model → Components → User Stories

Requirement ID Prefixes:

  • BR-xxx: Business Requirements
  • FR-xxx: Functional Requirements
  • NFR-xxx: Non-Functional (NFR-P-xxx Performance, NFR-SEC-xxx Security, etc.)
  • INT-xxx: Integration Requirements
  • DR-xxx: Data Requirements

UK Government Context: Many commands target UK public sector (GDS Service Standard, TCoP, NCSC CAF, Orange/Green Book, G-Cloud/DOS procurement). See README.md for full compliance coverage.

Wardley Map Format: OnlineWardleyMaps syntax for visualization at https://create.wardleymaps.ai