USER REQUEST → TASK UNDERSTANDING → CONTEXT DISCOVERY → INSPECTION → ROOT CAUSE ANALYSIS
             → PLAN → RISK ASSESSMENT → APPROVAL GATE → IMPLEMENTATION → VALIDATION
             → DOCUMENTATION → JIRA / PR UPDATE → FINAL REPORT

git clone https://github.com/stwins60/devops-agent-harness.git
cd devops-agent-harness
python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

devops-agent --mock "Why is my Kubernetes API deployment failing?"
devops-agent --mock --yes jira DEVOPS-382
devops-agent --mock --approve-all incident "production API is returning 503"
devops-agent --mock plan "upgrade our Kubernetes worker nodes"
devops-agent --mock fix DEVOPS-382 --dry-run
make test

FACT: Deployment production/api: 0/3 replicas ready, image registry.example.com/sample-app/api:1.4.2, revision 7.
FACT: Pod api-7c98d9b55c-abc12: phase Running, ready=False, restarts=12, waiting reason CrashLoopBackOff, last exit code 137 (Error).
FACT: Event Unhealthy (41x): Readiness probe failed: dial tcp 10.0.1.21:8000: connect: connection refused
FACT: Application log shows it listens on port 8080.
FACT: Container api: containerPorts=[8080], probes=readinessProbe->8000/healthz, livenessProbe->8000/healthz.

HYPOTHESIS (confirmed, confidence 95%):
Probe port mismatch: readinessProbe checks port 8000 but the container listens on 8080; kubelet kills/never readies the pod.

HYPOTHESIS (rejected, confidence 40%):
Container was killed with exit 137 (SIGKILL); possible OOM kill (limit 512Mi, usage 48Mi) or liveness-probe kill.

CONCLUSION: Confirmed - Probe port mismatch ... (confidence 95%)
RECOMMENDATION: Set readinessProbe port to 8080 in the deployment manifest.

# 1. Install into an isolated environment
pipx install "git+https://github.com/stwins60/devops-agent-harness.git"

# 2. Initialise the repository the agent should operate on
cd /path/to/your/service-repo
devops-agent init        # creates .agent/config.yaml, .agent/{memory,decisions,runbooks,...} and an AGENTS.md skeleton

# 3. Provide credentials through the environment only (never in config files)
export JIRA_URL=https://your-company.atlassian.net JIRA_EMAIL=you@company.com JIRA_API_TOKEN=...
export GITHUB_TOKEN=...              # or GITLAB_TOKEN + GITLAB_URL
export KUBECONFIG=~/.kube/config     # contexts are bound to environments in .agent/config.yaml
export AWS_PROFILE=readonly          # standard AWS credential chain

# 4. First run in read-only mode to confirm environment resolution
devops-agent --mode read-only "why is deployment api failing in production?"

mode: approval                 # read-only | plan | approval | autonomous
environment: dev               # declared; trusted bindings below can only make it stricter
provider: auto                 # auto | mock | none | openai | anthropic | claude-code | opencode | copilot | ollama
jira_url: https://your-company.atlassian.net
github_repo: your-org/service-repo
git_provider: github           # or gitlab (+ gitlab_project)
default_namespace: production
prometheus_url: http://prometheus.monitoring:9090

environments:                  # trusted identity -> environment; anything unbound == production
  production: { kube_contexts: [prod-eks], aws_accounts: ["123456789012"], namespaces: [production] }
  staging:    { kube_contexts: [staging-eks], namespaces: [staging] }
  dev:        { kube_contexts: [kind-dev, docker-desktop], namespaces: [dev, default] }

mcp_preapproved: [git_create_branch, git_add, git_commit, jira_add_comment]   # low-risk writes allowed over MCP
mcp_servers: []                # consume other MCP servers as governed tools

devops-agent --project-root /path/to/repo --mode approval mcp-serve

claude mcp add devops-agent --scope project -- devops-agent --project-root . --mode approval mcp-serve

{ "mcpServers": { "devops-agent": { "command": "devops-agent",
    "args": ["--project-root", ".", "--mode", "approval", "mcp-serve"] } } }

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "devops-agent": {
      "type": "local",
      "command": ["devops-agent", "--project-root", "/path/to/repo", "--mode", "approval", "mcp-serve"],
      "enabled": true
    }
  },
  "agent": {
    "devops": {
      "description": "DevOps engineer using the governed devops-agent tools",
      "mode": "primary",
      "prompt": "{file:/path/to/repo/AGENTS.md}",
      "tools": { "devops-agent*": true, "atlassian*": false, "github*": false, "gitlab*": false }
    }
  }
}

{ "servers": { "devops-agent": { "type": "stdio", "command": "devops-agent",
    "args": ["--project-root", "${workspaceFolder}", "--mode", "approval", "mcp-serve"] } } }

[mcp_servers.devops-agent]
command = "devops-agent"
args = ["--project-root", ".", "--mode", "approval", "mcp-serve"]

printf '%s\n%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | devops-agent --mock mcp-serve

devops-agent --provider anthropic   jira DEVOPS-382                 # ANTHROPIC_API_KEY
devops-agent --provider openai      incident "…"                    # OPENAI_API_KEY (+ OPENAI_BASE_URL for Azure / vLLM)
devops-agent --provider ollama      "why is my pod crashing?"       # local OpenAI-compatible server
devops-agent --provider claude-code plan "…"                        # claude CLI
devops-agent --provider opencode    "…"                             # opencode CLI
devops-agent --provider copilot     "…"                             # copilot CLI

                    ┌──────────────────────────┐
                    │   USER · IDE · MCP CLIENT │
                    └─────────────┬────────────┘
                                  ▼
                    ┌──────────────────────────┐
                    │      AGENT HARNESS       │  agent/harness.py
                    └─────────────┬────────────┘
            ┌─────────────────────┼─────────────────────┐
            ▼                     ▼                     ▼
      Orchestrator          Policy Engine         Approval Engine
      (lifecycle)         (YAML, outside LLM)   (interactive · allowlist · auto)
            │
            ▼
      Specialist Agents
      kubernetes · docker · linux · jira · git · cicd · aws · terraform
      ansible · networking · observability · security · incident · documentation
            │
            ▼
      Tool Executor  →  policy → approval → tool → audit log + task state + rollback plan
            │
            ▼
      Tool Registry (115 tools)
      Native · CLI · REST · MCP · SDK backends, each with a real and a mock implementation