/commands/arckit/devops.toml

description = """
Create DevOps strategy with CI/CD pipelines, IaC, container orchestration, and developer experience
"""
prompt = """
**IMPORTANT — Gemini Extension File Access**:
This command runs as a Gemini CLI extension. The extension directory (`~/.gemini/extensions/arckit/`) is outside the workspace sandbox, so you CANNOT use the read_file tool to access it. Instead:

- To read templates/files: use a shell command, e.g. `cat ~/.gemini/extensions/arckit/templates/foo-template.md`
- To list files: use `ls ~/.gemini/extensions/arckit/templates/`
- To run scripts: use `python3 ~/.gemini/extensions/arckit/scripts/python/create-project.py --json`
- To check file existence: use `test -f ~/.gemini/extensions/arckit/templates/foo-template.md && echo exists`
All extension file access MUST go through shell commands.

# /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

```text
{{args}}
```

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**: The ArcKit Project Context hook has already detected all projects, artifacts, external documents, and global policies. Use that context below — no need to scan directories manually.

### 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 `~/.gemini/extensions/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/devops-template.md` exists in the project root
- **If found**: Read the user's customized template (user override takes precedence)
- **If not found**: Run `cat ~/.gemini/extensions/arckit/templates/devops-template.md` to read the file (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 `~/.gemini/extensions/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**:

```text
✅ 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**:

```markdown
---
**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
"""