/arckit.principles

The /arckit.principles command creates or updates enterprise architecture principles that govern all technology decisions in your organization.

This is a slash command (not a CLI command). Run it from within your AI assistant after initializing your project with arckit init.

IMPORTANT: Architecture principles are technology-agnostic. They define WHAT qualities the architecture must have, not HOW to implement them with specific products.

Description

Creates comprehensive architecture principles following TOGAF and UK Government best practices:

Strategic Principles (Scalability, Resilience, Interoperability, Security by Design)
Data Principles (Single Source of Truth, Data Quality, Privacy by Design)
Integration Principles (Loose Coupling, Standard Interfaces, Asynchronous Communication)
Quality Attributes (Performance, Availability, Maintainability, Observability)
Development Practices (Automation, Testing, Code Review, Continuous Improvement)
Exception Process (how to request deviations)

These principles become the “constitution” for all architecture decisions, referenced in requirements documents, design reviews, and vendor evaluations.

Usage

/arckit.principles [DOMAIN_OR_FOCUS]

Basic Examples

# Create principles from scratch
/arckit.principles

# Focus on specific domain
/arckit.principles cloud-first
/arckit.principles data governance
/arckit.principles API design

# Industry-specific principles
/arckit.principles financial services
/arckit.principles healthcare
/arckit.principles retail
/arckit.principles UK Government

Arguments

DOMAIN_OR_FOCUS

string

Domain or focus area for principles. Can be a technical domain, industry, or specific guidance request.Examples:

cloud-first - Cloud migration principles
data governance - Data management principles
API design - API and integration principles
financial services - Add SOX, PCI-DSS compliance
healthcare - Add HIPAA, PHI data handling
UK Government - Add GDS, TCoP, accessibility

Prerequisites

Project Initialized

Must have run arckit init to create project structure:

arckit init my-project --ai codex
cd my-project

External Governance Documents (Optional)

Place existing architecture principles, TOGAF standards, or departmental policies in:

projects/000-global/policies/

The command will read PDFs and Word docs to extract existing principles.If no external documents are found, the command asks:

Do you have any existing architecture principles, governance frameworks,
or departmental technology standards? I can read PDFs and Word docs directly.
Place them in `projects/000-global/policies/` and re-run, or skip to create
principles from scratch.

What It Creates

Document Structure

Each principle includes:

Clear statement with MUST/SHOULD/MAY (technology-agnostic)Example:

## Principle: Horizontal Scalability

All applications MUST support horizontal scaling to meet demand.

Explains WHY this principle mattersExample:

**Rationale**: Horizontal scaling allows adding capacity by deploying
more instances rather than upgrading individual servers. This provides:
- Linear cost scaling (pay only for capacity needed)
- No single point of failure
- Graceful degradation under load
- Cloud-native deployment flexibility

How it affects design decisionsExample:

**Implications**:
- Applications must be stateless or use external state stores
- Session data must be externalized (Redis, database)
- Database connections must use connection pooling
- File storage must use shared/distributed systems
- Load balancers required for traffic distribution

Checklist items to verify complianceExample:

**Validation Gates**:
- [ ] HLD shows multiple application instances
- [ ] No local file system dependencies
- [ ] Session state externalized
- [ ] Load testing demonstrates linear scaling
- [ ] Auto-scaling policies defined

Good vs bad examples (without specific products)Example:

**Example Scenarios**:

✅ **Good**: Web application with stateless instances behind load balancer,
session data in distributed cache, auto-scaling based on CPU/memory

❌ **Bad**: Application stores session data on local disk, hard-coded to
single server IP, manual server upgrades for capacity

Anti-patterns to avoidExample:

**Common Violations**:
- Storing session data in local memory or disk
- Hard-coding server hostnames or IP addresses
- Using in-process caches without synchronization
- Relying on sticky sessions for application state

File Location

projects/000-global/
└── ARC-000-PRIN-v1.0.md

The 000-global/ directory is for cross-project artifacts like architecture principles. The 000 project ID indicates this applies globally.

Technology-Agnostic Principles

Critical Distinction: Principles describe WHAT qualities the architecture must have, not HOW to implement them.

Examples of Good vs Bad Principles

❌ BAD (Technology-Specific)
✅ GOOD (Technology-Agnostic)

These prescribe specific technologies:

“All applications MUST use Kubernetes for container orchestration”
“Authentication MUST use Auth0”
“Databases MUST be PostgreSQL or MySQL”
“APIs MUST use REST with JSON payloads”
“Message queues MUST use Apache Kafka”
“Infrastructure MUST use Terraform”

Why bad? They lock you into specific vendors and prevent innovation.

What TO Include

include

list

Architectural qualities (scalable, resilient, maintainable)
Patterns (event-driven, microservices, layered)
Practices (automation, testing, code review)
Decision criteria (build vs buy, cloud vs on-premise)
Constraints (compliance, security, cost)

What NOT to Include

exclude

list

Specific vendors (AWS, Azure, GCP)
Specific products (Kubernetes, PostgreSQL, Kafka)
Specific cloud providers
Specific programming languages
Specific frameworks or libraries

Industry-Specific Customization

The command automatically adds industry-specific principles:

Financial Services
Healthcare
UK Government
Retail

Automatically adds:

Transaction integrity principles
Audit trail requirements
Regulatory compliance (SOX, PCI-DSS)
Data retention policies
Fraud detection and prevention

Example:

/arckit.principles financial services

Automatically adds:

HIPAA compliance principles
PHI data handling requirements
Consent management
Patient privacy safeguards
Clinical data integrity

Example:

/arckit.principles healthcare

Automatically adds:

GDS Service Standard alignment
Technology Code of Practice (TCoP)
Accessibility (WCAG 2.1 AA)
Open Standards principles
Security classification handling

Example:

/arckit.principles UK Government

Automatically adds:

Payment processing security
Inventory system integration
Customer data protection
Omnichannel consistency
High availability for peak traffic

Example:

/arckit.principles retail

Versioning

The command automatically detects and increments versions:

First Version (v1.0)

/arckit.principles

Creates: ARC-000-PRIN-v1.0.md

Minor Update (v1.1)

Triggers when:

Scope unchanged
Refreshed content
Updated details
Corrections

Example:

# After editing principles
/arckit.principles update with cloud-first guidance

Creates: ARC-000-PRIN-v1.1.md Revision History Entry:

| 1.1 | 2024-02-15 | ArcKit AI | Added cloud-first principles | J. Smith | Approved |

Major Update (v2.0)

Triggers when:

Scope materially changed
New principle categories added
Removed categories
Fundamentally different guidance

Example:

# Adding AI/ML governance
/arckit.principles add AI governance and responsible AI

Creates: ARC-000-PRIN-v2.0.md Revision History Entry:

| 2.0 | 2024-03-01 | ArcKit AI | Added AI governance section with 8 new principles | J. Smith | Approved |

Example Output

# Enterprise Architecture Principles

**Document ID**: ARC-000-PRIN-v1.0  
**Project**: Global Enterprise Architecture (Project 000)  
**Version**: 1.0  
**Status**: DRAFT  
**Date**: 2024-01-15  
**Owner**: Jane Smith, Chief Architect  
**Classification**: OFFICIAL  

---

## Document Control

| Field | Value |
|-------|-------|
| Document Type | Architecture Principles |
| Scope | Enterprise-wide |
| Review Date | 2024-02-15 |
| Approver | Architecture Board |
| Distribution | All Technical Staff |

## Revision History

| Version | Date | Author | Changes | Reviewer | Status |
|---------|------|--------|---------|----------|--------|
| 1.0 | 2024-01-15 | ArcKit AI | Initial creation from `/arckit.principles` command | [PENDING] | [PENDING] |

Summary

After generation, the command provides:

Architecture Principles Created ✅

Location: projects/000-global/ARC-000-PRIN-v1.0.md

Summary:
- 15 principles defined across 5 categories
- Strategic: Scalability, Resilience, Interoperability, Security by Design
- Data: Single Source of Truth, Data Quality, Privacy by Design
- Integration: Loose Coupling, Standard Interfaces, Event-Driven
- Quality: Performance, Availability, Maintainability, Observability
- Development: Automation, Testing, Code Review

Industry-specific additions:
- UK Government: GDS Service Standard, TCoP, Accessibility
- Financial Services: SOX compliance, PCI-DSS, audit trails

Next Steps:
1. Review principles with Architecture Board
2. Get stakeholder sign-off
3. Run `/arckit.stakeholders` to analyze stakeholder drivers and goals
4. Run `/arckit.requirements` to create requirements aligned with these principles

Document Control

All generated principles include auto-populated metadata:

**Generated by**: ArcKit `/arckit.principles` command
**Generated on**: 2024-01-15 14:30 GMT
**ArcKit Version**: 0.11.5
**Project**: Global Enterprise Architecture (Project 000)
**AI Model**: claude-sonnet-4-20250514
**Generation Context**: Created from scratch with UK Government customization

Troubleshooting

Error: Project structure not found

Cause: The command expects projects/000-global/ directory.Solution: Run arckit init first:

arckit init my-project --ai codex
cd my-project
/arckit.principles

Principles too generic

Cause: No industry or domain specified.Solution: Re-run with specific focus:

/arckit.principles UK Government financial services

Want to add custom principles

Solution: Edit the generated file directly or use /arckit.customize:

/arckit.customize architecture-principles

Then edit .arckit/templates-custom/architecture-principles-template.md and re-run /arckit.principles.

arckit init

Initialize project structure first