Arc-Kit Prerequisites: Required Tools, Environment, and Artifact Setup

Arc-kit requires Bash 3.2+, jq, git, and bundled MCP servers in your environment, plus an initialized project structure with mandatory Architecture Principles and Stakeholder artifacts before executing governance commands.

Arc-kit is a template-driven, AI-assisted governance toolkit from the tractorjuice/arc-kit repository. Before any command can generate governance artifacts, the environment and a minimal set of artifacts must be present. The toolkit enforces these prerequisites automatically through helper scripts and command validation logic.

Core Environment Requirements

Arc-kit validates your shell environment before executing commands. The prerequisite checker ensures you have the necessary tools and connectivity to bundled MCP servers.

Required System Tools

According to scripts/bash/check-prerequisites.sh, your environment must provide:

• Bash 3.2+ – The scripting runtime for all arc-kit operations
• jq – Command-line JSON processor for parsing MCP responses and configuration
• git – Version control for managing project histories and template updates

These tools are validated at lines 37-44 of the prerequisite script, which aborts execution if any are missing.

MCP Server Connectivity

Arc-kit bundles four Model Context Protocol (MCP) servers that must be accessible:

• AWS Knowledge
• Microsoft Learn
• Google Developer
• govreposcrape

The check-prerequisites.sh script validates connectivity to these servers during environment setup. Without these connections, AI-assisted governance generation cannot function.

Project Structure Setup

Beyond environment tools, arc-kit requires a specific directory hierarchy.

Directory Initialization

You must initialize the repository structure using the /arckit.init command (or arckit init when installed via pip/uv). This creates:

• A projects/ directory at the repository root
• A 000-global folder within projects/ for shared artifacts

As documented in docs/guides/start.md (lines 12-19), this directory tree is mandatory for the toolkit to locate and store governance artifacts.

Repository Root Discovery

The scripts/bash/common.sh helper provides functions used by all bash scripts to discover the repository root. This ensures that commands executed from any subdirectory can locate the projects/ folder and validate the structure.

Mandatory Foundational Artifacts

Once the structure exists, you must create specific governance artifacts before running most commands.

Architecture Principles

Architecture Principles are mandatory for almost every arc-kit command. As stated in docs/guides/start.md (lines 18-20), you must create these principles before generating other artifacts.

Create them using:

/arckit.principles "Create principles for a digital health platform"

Without this file present in your project, the prerequisite checker will abort execution.

Stakeholder Analysis

Stakeholder analysis is required for strategy-level commands. According to docs/guides/strategy.md (lines 27-30), both principles and stakeholders are mandatory inputs for the strategy synthesis command.

Create stakeholders using:

/arckit.stakeholders "Analyze stakeholders for the health platform"

The check-prerequisites.sh script (lines 41-53) verifies the presence of stakeholder-drivers.md and other standard artifact files for the selected project.

Command-Specific Prerequisites

Different arc-kit commands require additional markdown artifacts beyond the foundational set.

Required Artifact Files

The prerequisite script validates the presence of command-specific files such as:

• stakeholder-drivers.md
• risk-register.md
• sobc.md (Statement of Business Context)
• requirements.md
• data-model.md

When you run a command, check-prerequisites.sh discovers the current project by prefix or number, then checks for the specific files required by that operation. If any mandatory file is missing, the command aborts with a clear error message indicating which prerequisite is absent.

Optional Template Overrides

While not strictly required, arc-kit supports custom templates in .arckit/templates-custom/. These overrides survive toolkit upgrades and allow organization-specific formatting.

The default templates reside in .arckit/templates/ and are read by every command. The README (lines 32-38) explains the lookup order: custom templates take precedence over defaults.

How ArcKit Enforces Prerequisites

Arc-kit automates prerequisite validation through a centralized checking mechanism.

Automated Validation Flow

1. Invocation: Most commands invoke check-prerequisites.sh automatically via the shared common.sh helper.
2. Discovery: The script discovers the repository root and resolves the current project by prefix or number.
3. Verification: It verifies the presence of environment tools, MCP connectivity, and the standard artifact list.
4. Abort/Continue: If any mandatory requirement is missing, the command aborts with a descriptive error; otherwise, execution continues.

Manual Checking

For CI pipelines or manual verification, run the prerequisite script directly:

./scripts/bash/check-prerequisites.sh --project "001" --json

The --json flag outputs machine-readable validation results, useful for automated build systems.

Practical Setup Examples

Quick Start Workflow

# 1. Orient yourself – see what’s missing

/arckit.start

# 2. Initialize the repository (creates projects/ and 000-global)

/arckit.init

# 3. Create the first mandatory artifact – Architecture Principles

/arckit.principles "Create principles for a digital health platform"

# 4. Add Stakeholder analysis (required before strategy synthesis)

/arckit.stakeholders "Analyze stakeholders for the health platform"

# 5. Run the prerequisite checker manually (useful in CI pipelines)

./scripts/bash/check-prerequisites.sh --project "001" --json

Installation from Source

# Clone the repo

git clone https://github.com/tractorjuice/arc-kit.git
cd arc-kit

# Install the CLI (uv or pip)

uv pip install -e .

# or: pip install -e .

# Initialize a new project

arckit init my-project --ai codex   # creates the folder structure

# Verify prerequisites for the new project

scripts/bash/check-prerequisites.sh --project "my-project" --json

Summary

• Environment: Arc-kit requires Bash 3.2+, jq, git, and connectivity to four bundled MCP servers (AWS Knowledge, Microsoft Learn, Google Developer, govreposcrape).
• Structure: You must run /arckit.init to create the projects/ directory and 000-global folder before any other operations.
• Foundational Artifacts: Architecture Principles are mandatory for most commands, and Stakeholder analysis is required for strategy-level synthesis.
• Validation: The scripts/bash/check-prerequisites.sh script enforces all requirements automatically, aborting execution with clear error messages if any prerequisites are missing.

Frequently Asked Questions

What happens if I try to run an arc-kit command without initializing the project first?

The command will abort immediately. The check-prerequisites.sh script validates the presence of the projects/ directory and the 000-global folder before executing any operation. You must run /arckit.init or arckit init <project> to create the required structure.

Are Architecture Principles really required for every command?

Almost every command requires Architecture Principles. According to the "Getting Started" guide in docs/guides/start.md, principles are a prerequisite for most commands. Only a few utility commands (like arckit.start or arckit.init) can run without them.

How do I check prerequisites in a CI/CD pipeline?

Use the standalone prerequisite checker with JSON output: ./scripts/bash/check-prerequisites.sh --project "your-project" --json. This returns machine-readable validation results that can be parsed by build scripts to ensure the environment and required artifacts are present before running automated governance generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}