marcusquinn/aidevops

AI DevOps Framework

aidevops.sh is an OpenCode plugin and AI DevOps framework for carrying work from intent to a verified outcome. It combines specialist agents, durable repository knowledge, safe Git workflows, model routing, operational automation, and service integrations for software, infrastructure, business, marketing, content, research, and creative production.

Instead of treating every job as an isolated chat, aidevops gives people and AI agents a shared operating system: the right context is loaded on demand, work is isolated, consequential actions are gated, evidence is retained, and useful lessons improve later work.

One conversation, autonomous project delivery, with security, teamwork, token efficiency, and quality control built in.

The Aim

Maximum useful value for your time and money. aidevops is built for the gap between “the model can probably do this” and “the work is done, verified, safe, and worth the cost.”

• Load focused guidance only when it is relevant.
• Match model capability and reasoning effort to the work.
• Explore optional Jev structured decisions

with reversible retrieval and shadow-triage pilots, private evaluation reports and bounded continuation examples; no default routing, runtime hooks or compaction changes.

• Keep secrets, protected data, and private state out of chat and Git.
• Let people and agents work in parallel without sharing unsafe mutable state.
• Preserve tasks, plans, decisions, evidence, and progress in durable sources of truth.
• Detect stuck work, failing automation, review traps, and repeated friction.
• Turn observed lessons into better guidance, checks, helpers, and follow-up work.
• Reserve human attention for taste, authority, secrets, and consequential ambiguity.

The “100x more capable” goal is an ambition to substantiate, not a guaranteed or measured result. The canonical purpose and decision criteria are in .agents/aidevops/purpose.md.

Quick Setup

New to aidevops? Work through these six steps once, in order, so nothing is missed. Commands are safe to rerun. For a guided version, type /onboarding in an AI session after step 2.

1. Install aidevops

brew install marcusquinn/tap/aidevops && aidevops update   # macOS (Homebrew)
npm install -g aidevops && aidevops update                 # Linux / cross-platform

Setup deploys agents to ~/.aidevops/agents/, installs and configures OpenCode, and offers optional tools. Accept Tabby when offered. Other methods: Installation. Check the result with aidevops status; aidevops doctor --fix resolves duplicate installs and PATH conflicts.

2. Open Tabby and start OpenCode

brew install --cask tabby   # macOS, only if you skipped Tabby during setup
aidevops tabby sync         # one Tabby profile per registered project
aidevops opencode           # launch OpenCode with the Build+ agent

Rerun aidevops tabby sync after adding projects in step 4. Profile details: Tabby profiles.

For persistent remote tmux tabs across configured SSH hosts, use aidevops tabby sessions new|restore|list|doctor; see Remote Tabby sessions.

3. Connect model providers

# OpenCode Go subscription: create an API key in your OpenCode account first
opencode auth login                          # choose "OpenCode Go", paste the key
NanoGPT: create an API key in your NanoGPT account first
opencode auth login                          # choose "NanoGPT", paste the key
OAuth pool for subscription accounts (browser sign-in, add one or more each)
aidevops model-accounts-pool add anthropic   # Claude Pro/Max
aidevops model-accounts-pool add openai      # ChatGPT Plus/Pro
aidevops model-accounts-pool status          # pool health
aidevops model-accounts-pool check           # live token test

Inside OpenCode, /connect is equivalent to opencode auth login. Add several accounts per provider so the pool can rotate on rate limits, then restart OpenCode. Never paste keys or tokens into an AI chat; store other service credentials with aidevops secret set NAME.

4. Put projects in ~/Git on the local drive

Keep canonical clones on the local disk, not in a cloud-synced folder such as iCloud Drive, Dropbox, or OneDrive. Layout: personal repositories at ~/Git/, organization or third-party repositories at ~/Git// (repository organization).

mkdir -p ~/Git
mv ~/path/to/my-project ~/Git/my-project                  # move an existing checkout
gh repo clone example-org/service ~/Git/example-org/service   # or clone fresh
cd ~/Git/my-project && aidevops init                      # add conventions and register
aidevops detect                                           # find and register other projects
aidevops repos clean                                      # drop entries for moved paths
aidevops repos                                            # review the registry
aidevops tabby sync                                       # refresh Tabby profiles

Already-registered repositories in an older layout can use the guarded aidevops repos migrate-layout plan instead of a manual move.

5. Turn on auto-update, Pulse, workers, and routines

aidevops auto-update enable                                # check for updates every 10 minutes
aidevops repo-sync enable                                  # daily git pull for repos under ~/Git
aidevops config set orchestration.supervisor_pulse true    # unattended Pulse, survives reboots
aidevops setup --scope pulse                               # install or refresh the Pulse scheduler
aidevops pulse status                                      # consent layers, workers, repos
aidevops init-routines                                     # private aidevops-routines repo (--local: no remote)

Pulse runs every 2 minutes and dispatches headless workers only for repositories marked "pulse": true in ~/.config/aidevops/repos.json; enable it only where autonomous work is approved. Workers pick up issues labelled auto-dispatch. Pause with aidevops pulse stop. In an AI session, use /routine to design recurring jobs, /pulse to supervise, and /runners for runner setup. Details: routines, worker diagnostics.

6. Verify and start working

aidevops status
aidevops security

Then, in OpenCode inside a project:

/onboarding
/skills recommend "TASK"
/full-loop "Describe the outcome you want"

Quick Reference

• Install: npm install -g aidevops && aidevops update
• Recommended runtime: OpenCode; Claude Code and Codex CLI are supported interactive runtimes
• Entry points: aidevops, ~/.aidevops/agents/AGENTS.md, runtime commands and skills
• Default development agent: Build+
• Routing: provider-neutral simple, standard, and thinking workload tiers
• Core lifecycle: understand → isolate → implement → verify → PR → authority-aware merge/release
• Agent sandbox backends: Apple container (opt-in executable); Firecracker Linux KVM (host probe only, not yet executable)
• Primary sources: user guide, domain index, architecture, configuration

Essential commands

aidevops status                 # Installation, runtime and storage health
aidevops init                   # Add aidevops conventions to a repository
aidevops project-config restore owner/repo   # Preview recovery of missing ignored local config
aidevops update                 # Update the framework and registered projects
aidevops features               # Discover framework features
aidevops repos                  # Manage registered projects
aidevops skills                 # Discover available workflows and capabilities
aidevops security               # Security posture, hygiene and supply-chain checks
aidevops metrics generate       # Refresh local repository metrics

For a registered repository whose GitHub Actions cannot run, record aidevops repos actions off owner/repo "billing blocked". Full-loop and worker verification then uses the repository's configured local checks with trusted exact-head PR evidence, without polling unavailable Actions. Restore normal CI with aidevops repos actions on owner/repo. Non-billing failures, reviews and native branch protection still block; see the local-verification contract.

If a registered repository loses its ignored .aidevops.json, first preview aidevops project-config restore owner/repo --backup /path/to/verified-backup.json. Without a verified backup, omit --backup to preview only the explicitly enabled features and init scope recorded in the local registry; other settings (including plugins and counter_branch) are unknown, not defaults or explicit opt-outs. After reviewing the target and settings, rerun with --apply in an attached terminal and type the exact destination path. This operation writes only a new ignored local config in the registered checkout; it refuses tracked configs, linked-worktree registrations, symlinks, ambiguous entries, and overwrites. For tracked configs, use the existing linked-worktree migration instead. Do not run the full aidevops init workflow as a config-only repair.

In an AI session:

/onboarding
/skills recommend "TASK"
/full-loop "Implement and ship the requested change"
/pulse
/report-render report.md

Source inventory

• 17 main agents with focused domain ownership
• 2,250+ individually addressable subagents, skills, workflows, and references
• 2,060+ production helpers and supporting modules, excluding tests
• 100+ commands for common workflows

Exact source inventory: 17 main agents, 2,256 sub agents, 2,218 helper scripts, 111 slash commands.

These are tracked source modules and entry points, not simultaneously running agents. Audit the inventory with bash .agents/scripts/readme-helper.sh counts --inventory; counting and hero maintenance rules live in DESIGN.md.

Capabilities at a Glance

| Area | What aidevops provides | |---|---| | Software delivery | Planning, implementation, debugging, review, CI, releases, deployment, and maintenance through linked worktrees and evidence gates | | Autonomous operations | Pulse supervision, workers, missions, routines, scheduling, diagnostics, recovery, and budget-aware concurrency | | Knowledge and continuity | Repository-owned tasks, plans, decisions, evidence, memory, knowledge ingestion, search, and session handoffs | | Security and privacy | Secret hygiene, prompt-injection defence, source-access approvals, supply-chain checks, operation verification, Vault, and audit trails | | Infrastructure | Hosting, DNS, networking, containers, cloud platforms, local development, monitoring, deployment, and object storage guidance | | Product and business | Product strategy, PRDs, analytics, onboarding, monetisation, accounting, invoices, reports, and operational routines | | Growth and communication | SEO/GEO, content, PR, email, outreach, paid ads, CRO, social workflows, and communications platforms | | External data | Native data providers and authorized extraction first, with cost-gated GetAnyAPI fallback access whose usage evidence guides graduation into direct aidevops subagents | | Creative production | Design systems, UI, browser/mobile verification, images, 3D/CAD, audio, video, animation, documents, and report exports | | Extensibility | Custom agents, imported skills, private agent sources, MCPs, API helpers, OpenAPI exploration, and project bundles |

For YouTube transcripts, python3 .agents/scripts/youtube-transcript.py VIDEO_ID tries captions, then local speech-to-text, and emits timestamped JSON. Hosted TranscriptAPI access is opt-in (--source api). See the transcription guide for setup, Mac dictation alternatives, access boundaries, and optional local anonymous speaker diarization.

The domain index is the human-readable map from user intent to specialist guidance. The generated capability registry separately records runtime readiness requirements.

Catalogue is not readiness. A listed capability may still require local

deployment, compatible runtime support, installation, configuration,

authentication, authorization, network reachability, or explicit operator

approval. aidevops checks these states before provider actions and falls back

rather than pretending unavailable tooling worked.

How Work Gets Done

User intent
   ↓
Build+ or a domain primary
   ↓
Focused guidance + capability-readiness check
   ↓
Linked worktree, bounded operation, or approved service action
   ↓
Runtime evidence + the narrowest applicable quality gates
   ↓
PR / report / artifact / operational receipt
   ↓
Authority-aware merge, publication, handoff, or follow-up

Full-loop delivery

/full-loop keeps one interactive owner responsible for a development task from implementation through verification and PR completion. The lifecycle uses fresh linked worktrees, exact-head checks, review evidence, protected merge helpers, and durable cleanup receipts.

Repository authority controls the terminal path:

• Maintained aidevops work: verified PR, merge, and—only with explicit trusted publication intent—snapshot release, postflight, and deployment.
• Other maintained repositories: verified PR, merge, and guarded synchronization of the actual PR base branch.
• External contributions: verified ready PR handed to upstream maintainers; no unauthorized merge, metadata mutation, or publication.

Releases pin an immutable source snapshot, coordinate through a repository-wide publisher lane, bind provenance to the exact tag, and reconcile publication and deployment evidence. See full-loop, Git workflow, and release coordination.

Pulse, workers, missions, and routines

• Pulse supervises registered repositories: it evaluates ready work, merges eligible PRs, dispatches workers, diagnoses failures, and recovers stalled or orphaned activity within API and resource budgets.
• Workers run issue-scoped tasks in isolated worktrees with scoped authority, model routing, runtime limits, and traceable Git outcomes.
• Missions decompose larger goals into milestones and validated deliverables with budget tracking and automatic advancement.
• Routines turn recurring reports, audits, monitoring, content, outreach, and operational checks into scheduled, evidence-bearing workflows.
• Runners and team interfaces provide persistent identities, local scheduling, shared-team adapters, and bounded collaboration without turning observation into provider-write authority.

Start with orchestration, worker discipline, and routines.

Knowledge, planning, and memory

The repository owns durable work. TODO.md, plans, decisions, evidence, and progress remain useful even if a forge conversation or AI session disappears. GitHub, GitLab, Gitea, and Forgejo are linked execution surfaces, not the sole source of truth.

• TODO.md and todo/ hold tasks, PRDs, plans, dependencies, and verification state.
• _knowledge/ holds curated repository-local source material.
• Cross-session memory stores concrete solutions, failures, decisions, and patterns with privacy filtering.
• Session checkpoints preserve objective, state, evidence, blockers, and next actions across compaction or handoff.
• Optional indexes and semantic search improve retrieval without replacing source evidence.
• Ambient self-improvement repairs safe in-scope friction and routes larger findings into durable follow-up work.

See knowledge plane, memory, and self-improvement.

Model and context efficiency

aidevops keeps routing provider-neutral. Canonical simple, standard, and thinking tiers describe workload needs; runtime adapters map those tiers to available models and accounts. Stronger models are reserved for consequential judgement, architecture, and synthesis, while bounded work uses the cheapest capable route.

Progressive disclosure loads only the relevant agents, references, and tools. TOON registries, compact terminal summaries, exact code search, context bundles, prompt caching, and compaction checkpoints reduce unnecessary context without hiding required evidence. Model comparisons and sealed historical replay can inform routing, but cannot silently rewrite production policy.

OpenCode defaults resolved models with larger windows to a ~240K usable-input compaction budget, without expanding smaller native windows or overriding explicit per-model context/input limits. GPT-6.1 Sol/Terra, GPT-6 Sol/Luna and their Fast variants also advertise the budget in their model metadata. Run `aidevops gpt6-context status to check those models in a fresh process, or disable` to restore their native limits. Restart OpenCode after changes.

See model routing, context efficiency, and model-effort evaluation. Worker dispatch retains priority-first routing by default. Operators can opt individual tiers into provider-level round-robin in the custom model routing table; model pins, retries and provider health gates remain unchanged.

Primary Agents

Build+ is the default for development, systems, and applications. Domain primaries add focused judgement while retaining the same applicable safety, authority, and verification boundaries.

| Agent | Focus | |---|---| | 3D Modelling | Editable 3D creation, parametric CAD, reconstruction, configurable products, and rendering | | Audio | Music composition, arrangement, sound design, editing, mixing, and reproducible audio projects | | Automate | Scheduling, dispatch, monitoring, routines, and background orchestration | | Build+ | Planning and full-loop delivery for code, apps, systems, CI, releases, and DevOps | | Business | Company operations, strategy, accounting, finance, invoices, and management reporting | | Content | Writing, images, social, multi-channel stories, and content production coordination | | Health | Evidence-aware health, fitness, nutrition, and wellness guidance | | Legal | Legal research, contracts, privacy, compliance, and GDPR guidance | | Marketing-Sales | Campaigns, CRM, email, outreach, paid ads, direct response, and CRO | | PR | Earned media, newsworthiness, journalist research, media lists, and coverage tracking | | Private Local AI | Sensitive investigations using verified privacy-first and local-compute boundaries | | Product | Product strategy, validation, PRDs, roadmaps, onboarding, growth, and analytics | | Reports | Evidence contracts, decision-ready reports, exporters, citations, and routine handoffs | | Research | Technical, market, competitive, and source-grounded research | | SEO | Technical SEO, GEO/AI search, keyword research, content analysis, schema, and search data | | Vault | Protected-data classification, encrypted stores, fleet trust, secure sync, and lock policy | | Video | Editing, compositing, grading, animation, source projects, and verified delivery |

Specialists under .agents/tools/, .agents/services/, .agents/workflows/, and .agents/reference/ are loaded on demand. Use /skills recommend "TASK" or the OpenCode agent picker rather than memorising the catalogue.

Domain Coverage

| Domain | Examples | |---|---| | Development | Code, architecture, reviews, testing, accessibility, performance, APIs, databases, mobile, extensions | | Infrastructure | Hosting, AWS (SSO, secret-backed CLI, SES), Google Cloud, Cloudflare, Coolify, Vercel, Cloudron, containers, remote compute, DNS, VPNs, local HTTPS | | Storage and backups | Backblaze B2, IDrive E2, Wasabi, S3-compatible inventories, Cloudron backup freshness | | Security | Secrets, dependency risk, prompt injection, source approvals, access reviews, incident response, Vault | | Product | Validation, roadmaps, UX, analytics, feature flags, experiments, onboarding, monetisation | | Business and finance | Strategy, accounting, QuickFile, receipts, reconciliation, forecasts, invoices, procurement | | Marketing and sales | Paid ads, direct response, CRO, CRM, lead generation, cold outreach, campaign operations | | Search and content | SEO, GEO, AI visibility, GSC, keywords, entities, schema, articles, newsletters, social publishing | | PR and communications | News research, journalist fit, media lists, press releases, coverage, chat and team interfaces | | Design and creative | DESIGN.md, brand systems, UI, email/decks, browser QA, images, 3D/CAD, video, audio, voice | | Documents and reports | OCR, extraction, Markdown-first reports, HTML, PDF, DOCX, slide profiles, citations, evidence ledgers | | Personal operations | Calendar, health, macOS diagnostics, productivity, recurring checks, private/local research |

This table