Environment Setup

Position in workflow: v0.6 Architecture Design / Technical Specification → v0.6 Environment Setup → v0.7 Build Execution

Environment setup documents the tools, packages, and configurations developers need to work on the project. This eliminates environment drift and speeds up onboarding.

Environment Types

Rule: ENV-001 (Development Environment) is required for every project. ENV-002 and ENV-003 are optional based on project needs.

Design Principles

1. Prefer CLIs Over MCPs

Rule: Use CLIs for operations, MCPs only when CLIs are insufficient.

Decision: Default to CLI. Only document MCPs for operations where CLIs don't exist.

2. Per-Project Over Global

Rule: Language-specific packages installed per-project, not globally.

Global (OK):

• Version managers (mise, asdf, nvm)
• System tools (jq, ripgrep)
• Platform CLIs (gh, aws-cli)

Per-Project (Required):

• Linters/formatters (eslint, prettier)
• Type checkers (typescript)
• Testing frameworks (jest, pytest)

3. Structured Over Prose

Rule: ENV- specs use structured data (tables, code blocks), not narrative.

Why:

• AI agents can parse and execute
• Humans can scan quickly
• Diff-friendly in version control

4. Verification Required

Rule: Every ENV- spec includes verification commands.

Why:

• Confirms setup succeeded
• Debugging aid
• Onboarding confidence

Setup Process

1. Pull TECH- decisions — What technologies are we using?
2. Pull ARC- decisions — What architecture patterns apply?
3. Inventory tooling needs — What do developers need installed?
4. Categorize by scope — Global vs per-project
5. Define configuration files — What configs are needed?
6. Create verification steps — How to confirm setup works?
7. Document in ENV- entries — Record in SoT.TECHNICAL_DECISIONS.md

ENV-001 Output Template (Development Environment)

ENV-001: Development Environment
Category: Development Setup
Status: Approved | Date: YYYY-MM-DD
Owner: {Team/Person}

Purpose:
Document local development requirements for team consistency.

CLIs (Global):
- {tool}: {purpose} — {install command}

Packages (Per-Project):
- {package}: {purpose}

Configuration Files:
| File | Purpose |
|------|---------|
| {file} | {purpose} |

Scripts:
{
  "validate": "{quality check command}",
  "fix": "{auto-fix command}",
  "test": "{test command}"
}

Verification:
# 1. Check tools
{tool} --version

# 2. Check packages
{package manager list command}

# 3. Run validation
npm run validate

Related IDs: TECH-XXX, ARC-XXX

ENV-002 Output Template (CI/CD Pipeline)

ENV-002: CI/CD Pipeline
Category: Automation
Status: Approved | Date: YYYY-MM-DD

Purpose:
Document automated testing and deployment configuration.

Workflow Files:
- {path}: {purpose}

Required Secrets:
| Secret | Purpose | Where to Set |
|--------|---------|--------------|
| {name} | {purpose} | {location} |

Pipeline Stages:
1. {Stage}: {What happens}
2. {Stage}: {What happens}

Related IDs: ENV-001, DEP-XXX

ENV-003 Output Template (Production Infrastructure)

ENV-003: Production Infrastructure
Category: Infrastructure
Status: Approved | Date: YYYY-MM-DD

Purpose:
Document production hosting and services configuration.

Hosting Platform:
{Platform and configuration details}

Environment Variables:
| Variable | Purpose | Required |
|----------|---------|----------|
| {name} | {purpose} | {yes/no} |

Services:
| Service | Purpose | Connection |
|---------|---------|------------|
| {service} | {purpose} | {how connected} |

Related IDs: DEP-XXX, MON-XXX

Common Tool Categories

Version/Environment Managers

• mise, asdf, nvm, pyenv, rbenv
• Purpose: Manage language versions per-project

Code Quality

• JavaScript/TypeScript: eslint, prettier, biome
• Python: ruff, black, pylint
• Go: golangci-lint

Type Checking

• JavaScript/TypeScript: typescript
• Python: mypy, pyright

Data Processing

• jq (JSON), yq (YAML)

API Testing

• httpie, curl, bruno-cli

Git Workflows

• gh (GitHub CLI), glab (GitLab CLI)

Anti-Patterns to Avoid

Quality Gates

Before proceeding to Build Execution:

• ENV-001 documents all development tools
• All tools have install commands
• All packages are in package manifest
• Configuration files are listed with purpose
• Standard scripts defined (validate, fix, test)
• Verification commands work
• CLI preferred over MCP documented

Downstream Connections

ENV- entries feed into:

Detailed References

• ENV- entry template: See assets/env.md
• Environment examples: See references/examples.md