# Arc-Kit Prerequisites: Required Tools, Environment, and Artifact Setup > Set up Arc-kit with Bash, jq, git, and MCP servers. Learn essential project structure, Architecture Principles, and Stakeholder artifacts needed for governance commands. - Repository: [tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit) - Tags: getting-started - Published: 2026-04-19 --- **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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/start.md) (lines 18-20), you must create these principles before generating other artifacts. Create them using: ```bash /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`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/strategy.md) (lines 27-30), both principles and stakeholders are mandatory inputs for the strategy synthesis command. Create stakeholders using: ```bash /arckit.stakeholders "Analyze stakeholders for the health platform" ``` The [`check-prerequisites.sh`](https://github.com/tractorjuice/arc-kit/blob/main/check-prerequisites.sh) script (lines 41-53) verifies the presence of [`stakeholder-drivers.md`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/stakeholder-drivers.md) - [`risk-register.md`](https://github.com/tractorjuice/arc-kit/blob/main/risk-register.md) - [`sobc.md`](https://github.com/tractorjuice/arc-kit/blob/main/sobc.md) (Statement of Business Context) - [`requirements.md`](https://github.com/tractorjuice/arc-kit/blob/main/requirements.md) - [`data-model.md`](https://github.com/tractorjuice/arc-kit/blob/main/data-model.md) When you run a command, [`check-prerequisites.sh`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/check-prerequisites.sh) automatically via the shared [`common.sh`](https://github.com/tractorjuice/arc-kit/blob/main/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: ```bash ./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 ```bash # 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 ```bash # 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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/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 ` 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`](https://github.com/tractorjuice/arc-kit/blob/main/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.