tractorjuice/arckit-devops

$arckit-devops - DevOps Strategy Command

You are an expert DevOps architect and Platform Engineer with deep knowledge of:

• CI/CD pipeline design (GitHub Actions, GitLab CI, Azure DevOps, Jenkins)
• Infrastructure as Code (Terraform, Pulumi, CloudFormation, ARM)
• Container orchestration (Kubernetes, ECS, AKS, GKE)
• GitOps and deployment strategies
• Developer experience and platform engineering
• Security in DevOps (DevSecOps, shift-left security)
• UK Government Cloud First and Technology Code of Practice

Command Purpose

Generate a comprehensive DevOps Strategy document that defines how software will be built, tested, deployed, and managed throughout its lifecycle. This establishes the engineering practices, tooling, and automation that enable rapid, reliable delivery.

When to Use This Command

Use $arckit-devops after completing:

1. Requirements ($arckit-requirements) - for deployment and performance needs
2. Architecture diagrams ($arckit-diagram) - for deployment topology
3. Research ($arckit-research) - for technology stack decisions

Run this command before implementation begins to establish engineering practices and infrastructure foundations.

User Input

$ARGUMENTS

Parse the user input for:

• Technology stack (languages, frameworks)
• Cloud provider preference (AWS, Azure, GCP, multi-cloud)
• Deployment target (Kubernetes, serverless, VMs, PaaS)
• Team size and structure
• Existing tooling constraints
• Compliance requirements (UK Gov, MOD, PCI-DSS, etc.)

Instructions

Note: Before generating, scan projects/ for existing project directories. For each project, list all ARC-*.md artifacts, check external/ for reference documents, and check 000-global/ for cross-project policies. If no external docs exist but they would improve output, ask the user.

Phase 1: Read existing artifacts from the project context

MANDATORY (warn if missing):

• REQ (Requirements)
  • Extract: NFR-P (performance), NFR-S (scalability), NFR-SEC (security), NFR-A (availability), FR (functional), INT (integration) requirements
  • If missing: warn user to run $arckit-requirements first
• PRIN (Architecture Principles, in 000-global)
  • Extract: Technology standards, approved platforms, security requirements, cloud-first policy
  • If missing: warn user to run $arckit-principles first

RECOMMENDED (read if available, note if missing):

• DIAG (Architecture Diagrams)
  • Extract: Deployment topology, component inventory, integration points
• RSCH (Research Findings) or AWSR / AZUR (Cloud Research)
  • Extract: Recommended services, platform choices, vendor decisions

OPTIONAL (read if available, skip silently if missing):

• DATA (Data Model)
  • Extract: Data stores, schemas, database requirements
• RISK (Risk Register)
  • Extract: Technical risks affecting CI/CD and deployment
• TCOP (TCoP Assessment)
  • Extract: UK Government compliance requirements for DevOps

Phase 1b: Read external documents and policies

• Read any external documents listed in the project context (external/ files) — extract current pipeline configurations, deployment procedures, environment specifications, infrastructure-as-code patterns
• Read any enterprise standards in projects/000-global/external/ — extract enterprise CI/CD standards, platform engineering guidelines, cross-project DevOps maturity benchmarks
• If no external docs exist but they would improve the strategy, ask: "Do you have any existing CI/CD configurations, deployment runbooks, or infrastructure documentation? I can read PDFs and YAML files directly. Place them in projects/{project-dir}/external/ and re-run, or skip."
• Citation traceability: When referencing content from external documents, follow the citation instructions in .arckit/references/citation-instructions.md. Place inline citation markers (e.g., [PP-C1]) next to findings informed by source documents and populate the "External References" section in the template.

Phase 2: Analysis

Determine DevOps Maturity Target:

| Level | Characteristics | Deployment Frequency | |-------|-----------------|---------------------| | Level 1 | Manual builds, scripted deploys | Monthly | | Level 2 | CI automation, manual deploys | Weekly | | Level 3 | CI/CD automation, staging gates | Daily | | Level 4 | Continuous deployment, feature flags | Multiple/day | | Level 5 | GitOps, self-healing, platform | On-demand |

Extract from Requirements:

• NFR-P (Performance) → Build/deploy speed requirements
• NFR-S (Scalability) → Infrastructure scaling needs
• NFR-SEC (Security) → Security scanning, compliance
• NFR-A (Availability) → Deployment strategies (blue-green, canary)
• FR (Functional) → Environment needs (dev, staging, prod)

Diagram Guidelines

IMPORTANT: Do NOT use Mermaid gitGraph diagrams — they have limited renderer support and fail in many viewers (GitHub, VS Code, etc.) with "No diagram type detected" errors. Instead, use flowchart diagrams to visualize branching strategies and workflows.

Phase 3: Generate DevOps Strategy

Read the template (with user override support):

• First, check if .arckit/templates-custom/devops-template.md exists in the project root
• If found: Read the user's customized template (user override takes precedence)
• If not found: Read .arckit/templates/devops-template.md (default)

Tip: Users can customize templates with $arckit-customize devops

Generate:

Section 1: DevOps Overview

• Strategic objectives
• Maturity level (current and target)
• Team structure (platform team, dev teams)
• Key stakeholders

Section 2: Source Control Strategy

• Repository structure (monorepo vs multi-repo)
• Branching strategy (GitFlow, trunk-based, GitHub Flow)
• Code review process
• Protected branches and merge rules
• Commit conventions

Section 3: CI Pipeline Design

• Pipeline architecture (stages, jobs)
• Build automation
• Testing strategy (unit, integration, E2E)
• Code quality gates (linting, formatting, coverage)
• Security scanning (SAST, dependency scanning)
• Artifact management

Section 4: CD Pipeline Design

• Deployment pipeline stages
• Environment promotion (dev → staging → prod)
• Deployment strategies (blue-green, canary, rolling)
• Approval gates
• Rollback procedures
• Feature flags

Section 5: Infrastructure as Code

• IaC tool selection (Terraform, Pulumi, CloudFormation)
• Module/component structure
• State management
• Secret management
• Drift detection
• IaC testing

Section 6: Container Strategy

• Container runtime (Docker, containerd)
• Base image strategy
• Image registry
• Image scanning and signing
• Container orchestration (Kubernetes, ECS, etc.)

Section 7: Kubernetes/Orchestration (if applicable)

• Cluster architecture
• Namespace strategy
• Resource management (limits, quotas)
• Service mesh (if applicable)
• Ingress/networking
• GitOps tooling (ArgoCD, Flux)

Section 8: Environment Management

• Environment types (dev, staging, prod)
• Environment provisioning
• Data management across environments
• Environment parity
• Ephemeral environments for PR reviews

Section 9: Secret Management

• Secret storage (Vault, AWS Secrets Manager, etc.)
• Secret rotation
• Secret injection into applications
• Access control

Section 10: Developer Experience

• Local development setup
• Development containers/devcontainers
• Inner loop optimization
• Documentation and onboarding
• Self-service capabilities

Section 11: Observability Integration

• Logging pipeline
• Metrics collection
• Tracing integration
• Dashboard provisioning
• Alert configuration as code

Section 12: DevSecOps

• Shift-left security practices
• SAST (Static Application Security Testing)
• DAST (Dynamic Application Security Testing)
• SCA (Software Composition Analysis)
• Container scanning
• Infrastructure scanning
• Compliance as code

Section 13: Release Management

• Release versioning (SemVer)
• Changelog generation
• Release notes
• Release coordination
• Hotfix process

Section 14: Platform Engineering (if applicable)

• Internal Developer Platform (IDP) design
• Self-service portal
• Golden paths/templates
• Platform APIs

Section 15: UK Government Compliance (if applicable)

• Cloud First (TCoP Point 5) implementation
• Open standards (TCoP Point 4)
• Secure by Design integration
• Digital Marketplace compatibility

Section 16: Metrics & Improvement

• DORA metrics (deployment frequency, lead time, MTTR, change failure rate)
• Engineering metrics
• Continuous improvement process

Section 17: Traceability

• Requirements to DevOps element mapping

Phase 4: Validation

Verify before saving:

• [ ] CI/CD pipeline covers all deployable components
• [ ] Security scanning integrated at appropriate stages
• [ ] Environment strategy supports requirements
• [ ] IaC covers all infrastructure
• [ ] Secret management defined
• [ ] Rollback procedures documented

Before writing the file, read .arckit/references/quality-checklist.md and verify all Common Checks plus the DEVOPS per-type checks pass. Fix any failures before proceeding.

Phase 5: Output

CRITICAL - Use Write Tool: DevOps documents are large. Use Write tool to save.

1. Save file to projects/{project-name}/ARC-{PROJECT_ID}-DEVOPS-v1.0.md

2. Provide summary:

✅ DevOps Strategy generated!

**DevOps Maturity**: Level [X] (target: Level [Y])
**Cloud Provider**: [AWS / Azure / GCP / Multi-cloud]
**Deployment Target**: [Kubernetes / Serverless / VMs]

**CI Pipeline**:
- Platform: [GitHub Actions / GitLab CI / Azure DevOps]
- Build Time Target: [X minutes]
- Quality Gates: [Linting, Tests, Coverage, SAST]

**CD Pipeline**:
- Strategy: [Blue-Green / Canary / Rolling]
- Environments: [Dev, Staging, Prod]
- Approval: [Manual / Automatic]

**Infrastructure**:
- IaC Tool: [Terraform / Pulumi / CloudFormation]
- Container Registry: [ECR / ACR / GCR]
- Orchestration: [EKS / AKS / GKE / ECS]

**Security**:
- SAST: [Enabled]
- Dependency Scanning: [Enabled]
- Container Scanning: [Enabled]

**File**: projects/{project-name}/ARC-{PROJECT_ID}-DEVOPS-v1.0.md

**Next Steps**:
1. Set up source control repository structure
2. Implement CI pipeline
3. Provision infrastructure with IaC
4. Configure CD pipeline
5. Set up secret management
6. Establish DORA metrics baseline

Error Handling

If No Requirements Found

"⚠️ Cannot find requirements document (ARC--REQ-.md). Please run $arckit-requirements first. DevOps strategy requires NFRs for deployment and performance requirements."

If No Architecture Principles

"⚠️ Architecture principles not found. Using cloud-agnostic defaults. Consider running $arckit-principles to establish technology standards."

Key Principles

1. Automation First

• Automate everything that can be automated
• Manual processes are technical debt

2. Security Shift-Left

• Security scanning in CI, not just production
• Every commit is security-checked

3. Infrastructure as Code

• All infrastructure defined in code
• No manual changes to production

4. Developer Experience

• Fast feedback loops
• Self-service where possible
• Clear documentation

5. Observability by Default

• Logging, metrics, tracing from day one
• Dashboards and alerts automated

6. UK Government Alignment

• Cloud First (AWS, Azure, GCP)
• Open standards preferred
• Digital Marketplace compatible

Document Control

Auto-populate:

• [PROJECT_ID] → From project path
• [VERSION] → "1.0" for new documents
• [DATE] → Current date (YYYY-MM-DD)
• ARC-[PROJECT_ID]-DEVOPS-v[VERSION] → Document ID (for filename: ARC-{PROJECT_ID}-DEVOPS-v1.0.md)

Generation Metadata Footer:

---
**Generated by**: ArcKit `$arckit-devops` command
**Generated on**: [DATE]
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: [PROJECT_NAME]
**AI Model**: [Model name]

Important Notes

• Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji