Skip to content
Back to search

aidevops

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/marcusquinn--aidevops/badge.svg)](/listings/marcusquinn--aidevops)

HTML

<a href="/listings/marcusquinn--aidevops"><img src="/api/listings/marcusquinn--aidevops/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](#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](.agents/reference/tabby-profiles.md).

For persistent remote tmux tabs across configured SSH hosts, use `aidevops tabby sessions new|restore|list|doctor`; see [Remote Tabby sessions](.agents/tools/terminal/remote-sessions.md).

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/<repo>`, organization or third-party repositories at `~/Git/<owner>/<repo>` ([repository organization](.agents/reference/repo-organization.md)).

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 read-only drift report 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines
  1. {
  2. "name": "aidevops",
  3. "owner": {
  4. "name": "Marcus Quinn",
  5. "email": "marcus@aidevops.sh"
  6. },
  7. "metadata": {
  8. "description": "AI DevOps Framework - comprehensive DevOps automation with 25+ service integrations",
  9. "version": "3.39.227"
  10. },
  11. "plugins": [
  12. {
  13. "name": "aidevops",
  14. "source": "./.agents",
  15. "description": "Complete AI DevOps framework - 14 domain agents, 80+ subagents, 100+ helper scripts for WordPress, SEO, hosting, code quality, browser automation, and more",
  16. "strict": false
  17. }
  18. ]
  19. }
README.md · README · 839 lines · 1 finding marked
  1. <!-- SPDX-License-Identifier: MIT -->
  2. <!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
  3. ![AI DevOps — 17 main agents, 2,250+ sub agents, 2,210+ helper scripts, and 110+ slash commands](docs/assets/og-image.png)
  4. # AI DevOps Framework
  5. **[aidevops.sh](https://aidevops.sh)** is an [OpenCode](https://opencode.ai/)
  6. plugin and AI DevOps framework for carrying work from intent to a verified
  7. outcome. It combines specialist agents, durable repository knowledge, safe Git
  8. workflows, model routing, operational automation, and service integrations for
  9. software, infrastructure, business, marketing, content, research, and creative
  10. production.
  11. Instead of treating every job as an isolated chat, aidevops gives people and AI
  12. agents a shared operating system: the right context is loaded on demand, work is
  13. isolated, consequential actions are gated, evidence is retained, and useful
  14. lessons improve later work.
  15. **One conversation, autonomous project delivery, with security, teamwork,
  16. token efficiency, and quality control built in.**
  17. [![GitHub Actions](https://github.com/marcusquinn/aidevops/actions/workflows/code-quality.yml/badge.svg?branch=main)](https://github.com/marcusquinn/aidevops/actions/workflows/code-quality.yml)
  18. [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=marcusquinn_aidevops&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=marcusquinn_aidevops)
  19. [![Maintainability](https://qlty.sh/gh/marcusquinn/projects/aidevops/maintainability.svg)](https://qlty.sh/gh/marcusquinn/projects/aidevops)
  20. [![Codacy Badge](https://app.codacy.com/project/badge/Grade/2b1adbd66c454dae92234341e801b984)](https://app.codacy.com/gh/marcusquinn/aidevops/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
  21. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  22. [![Version](https://img.shields.io/badge/Version-3.39.227-blue.svg)](https://github.com/marcusquinn/aidevops/releases)
  23. [![npm version](https://img.shields.io/npm/v/aidevops)](https://www.npmjs.com/package/aidevops)
  24. [![Homebrew](https://img.shields.io/badge/homebrew-marcusquinn%2Ftap-orange)](https://github.com/marcusquinn/homebrew-tap)
  25. [![Lines of code](docs/metrics/badges/loc.svg)](docs/metrics/repo-metrics.md)
  26. [![Dependencies](docs/metrics/badges/dependencies.svg)](docs/metrics/repo-metrics.md)
  27. [![Languages by lines of code](docs/metrics/badges/languages.svg)](docs/metrics/repo-metrics.md)
  28. ## The Aim
  29. **Maximum useful value for your time and money.** aidevops is built for the gap
  30. between “the model can probably do this” and “the work is done, verified, safe,
  31. and worth the cost.”
  32. - Load focused guidance only when it is relevant.
  33. - Match model capability and reasoning effort to the work.
  34. - Explore optional [Jev structured decisions](.agents/tools/ai-assistants/jev.md)
  35. with [reversible retrieval and shadow-triage pilots](.agents/tools/ai-assistants/jev-pilots.md),
  36. private evaluation reports and bounded continuation examples; no default routing,
  37. runtime hooks or compaction changes.
  38. - Keep secrets, protected data, and private state out of chat and Git.
  39. - Let people and agents work in parallel without sharing unsafe mutable state.
  40. - Preserve tasks, plans, decisions, evidence, and progress in durable sources of truth.
  41. - Detect stuck work, failing automation, review traps, and repeated friction.
  42. - Turn observed lessons into better guidance, checks, helpers, and follow-up work.
  43. - Reserve human attention for taste, authority, secrets, and consequential ambiguity.
  44. The “100x more capable” goal is an ambition to substantiate, not a guaranteed or
  45. measured result. The canonical purpose and decision criteria are in
  46. [`.agents/aidevops/purpose.md`](.agents/aidevops/purpose.md).
  47. ## Quick Setup
  48. New to aidevops? Work through these six steps once, in order, so nothing is
  49. missed. Commands are safe to rerun. For a guided version, type `/onboarding` in
  50. an AI session after step 2.
  51. ### 1. Install aidevops
  52. ```bash
  53. brew install marcusquinn/tap/aidevops && aidevops update # macOS (Homebrew)
  54. npm install -g aidevops && aidevops update # Linux / cross-platform
  55. ```
  56. Setup deploys agents to `~/.aidevops/agents/`, installs and configures
  57. OpenCode, and offers optional tools. Accept **Tabby** when offered. Other
  58. methods: [Installation](#installation). Check the result with
  59. `aidevops status`; `aidevops doctor --fix` resolves duplicate installs and PATH
  60. conflicts.
  61. ### 2. Open Tabby and start OpenCode
  62. ```bash
  63. brew install --cask tabby # macOS, only if you skipped Tabby during setup
  64. aidevops tabby sync # one Tabby profile per registered project
  65. aidevops opencode # launch OpenCode with the Build+ agent
  66. ```
  67. Rerun `aidevops tabby sync` after adding projects in step 4. Profile details:
  68. [Tabby profiles](.agents/reference/tabby-profiles.md).
  69. For persistent remote tmux tabs across configured SSH hosts, use
  70. `aidevops tabby sessions new|restore|list|doctor`; see
  71. [Remote Tabby sessions](.agents/tools/terminal/remote-sessions.md).
  72. ### 3. Connect model providers
  73. ```bash
  74. # OpenCode Go subscription: create an API key in your OpenCode account first
  75. opencode auth login # choose "OpenCode Go", paste the key
  76. # NanoGPT: create an API key in your NanoGPT account first
  77. opencode auth login # choose "NanoGPT", paste the key
  78. # OAuth pool for subscription accounts (browser sign-in, add one or more each)
  79. aidevops model-accounts-pool add anthropic # Claude Pro/Max
  80. aidevops model-accounts-pool add openai # ChatGPT Plus/Pro
  81. aidevops model-accounts-pool status # pool health
  82. aidevops model-accounts-pool check # live token test
  83. ```
  84. Inside OpenCode, `/connect` is equivalent to `opencode auth login`. Add several
  85. accounts per provider so the pool can rotate on rate limits, then restart
  86. OpenCode. Never paste keys or tokens into an AI chat; store other service
  87. credentials with `aidevops secret set NAME`.
  88. ### 4. Put projects in `~/Git` on the local drive
  89. Keep canonical clones on the local disk, not in a cloud-synced folder such as
  90. iCloud Drive, Dropbox, or OneDrive. Layout: personal repositories at
  91. `~/Git/<repo>`, organization or third-party repositories at
  92. `~/Git/<owner>/<repo>` ([repository organization](.agents/reference/repo-organization.md)).
  93. ```bash
  94. mkdir -p ~/Git
  95. mv ~/path/to/my-project ~/Git/my-project # move an existing checkout
  96. gh repo clone example-org/service ~/Git/example-org/service # or clone fresh
  97. cd ~/Git/my-project && aidevops init # add conventions and register
  98. aidevops detect # find and register other projects
  99. aidevops repos clean # drop entries for moved paths
  100. aidevops repos # review the registry
  101. aidevops tabby sync # refresh Tabby profiles
  102. ```
  103. Already-registered repositories in an older layout can use the guarded
  104. `aidevops repos migrate-layout plan` instead of a manual move.
  105. ### 5. Turn on auto-update, Pulse, workers, and routines
  106. ```bash
  107. aidevops auto-update enable # check for updates every 10 minutes
  108. aidevops repo-sync enable # daily read-only drift report for repos under ~/Git
  109. aidevops config set orchestration.supervisor_pulse true # unattended Pulse, survives reboots
  110. aidevops setup --scope pulse # install or refresh the Pulse scheduler
  111. aidevops pulse status # consent layers, workers, repos
  112. aidevops init-routines # private aidevops-routines repo (--local: no remote)
  113. ```
  114. Pulse runs every 2 minutes and dispatches headless workers only for repositories
  115. marked `"pulse": true` in `~/.config/aidevops/repos.json`; enable it only where
  116. autonomous work is approved. Workers pick up issues labelled `auto-dispatch`.
  117. Pause with `aidevops pulse stop`. In an AI session, use `/routine` to design
  118. recurring jobs, `/pulse` to supervise, and `/runners` for runner setup. Details:
  119. [routines](.agents/reference/routines.md),
  120. [worker diagnostics](.agents/reference/worker-diagnostics.md).
  121. ### 6. Verify and start working
  122. ```bash
  123. aidevops status
  124. aidevops security
  125. ```
  126. Then, in OpenCode inside a project:
  127. ```text
  128. /onboarding
  129. /skills recommend "TASK"
  130. /full-loop "Describe the outcome you want"
  131. ```
  132. <!-- AI-CONTEXT-START -->
  133. ## Quick Reference
  134. - **Install:** `npm install -g aidevops && aidevops update`
  135. - **Recommended runtime:** OpenCode; Claude Code and Codex CLI are supported interactive runtimes
  136. - **Entry points:** `aidevops`, `~/.aidevops/agents/AGENTS.md`, runtime commands and skills
  137. - **Default development agent:** Build+
  138. - **Routing:** provider-neutral `simple`, `standard`, and `thinking` workload tiers
  139. - **Core lifecycle:** understand → isolate → implement → verify → PR → authority-aware merge/release
  140. - **Agent sandbox backends:** [Apple container (opt-in executable); Firecracker Linux KVM (host probe only, not yet executable)](.agents/reference/agent-sandbox-lifecycle.md#backend-matrix)
  141. - **Primary sources:** [user guide](.agents/AGENTS.md), [domain index](.agents/reference/domain-index.md), [architecture](.agents/aidevops/architecture.md), [configuration](.agents/reference/configuration.md)
  142. ### Essential commands
  143. ```bash
  144. aidevops status # Installation, runtime and storage health
  145. aidevops init # Add aidevops conventions to a repository
  146. aidevops project-config restore owner/repo # Preview recovery of missing ignored local config
  147. aidevops update # Update the framework and registered projects
  148. aidevops features # Discover framework features
  149. aidevops repos # Manage registered projects
  150. aidevops skills # Discover available workflows and capabilities
  151. aidevops security # Security posture, hygiene and supply-chain checks
  152. aidevops metrics generate # Refresh local repository metrics
  153. ```
  154. For a registered repository whose GitHub Actions cannot run, record
  155. `aidevops repos actions off owner/repo "billing blocked"`. Full-loop and worker
  156. verification then uses the repository's configured local checks with trusted
  157. exact-head PR evidence, without polling unavailable Actions. Restore normal CI
  158. with `aidevops repos actions on owner/repo`. Non-billing failures, reviews and
  159. native branch protection still block; see the
  160. [local-verification contract](.agents/reference/ci-gate-policy.md#github-actions-unavailable).
  161. If a registered repository loses its ignored `.aidevops.json`, first preview
  162. `aidevops project-config restore owner/repo --backup /path/to/verified-backup.json`.
  163. Without a verified backup, omit `--backup` to preview only the explicitly enabled
  164. features and init scope recorded in the local registry; other settings (including
  165. plugins and `counter_branch`) are **unknown**, not defaults or explicit opt-outs.
  166. After reviewing the target and settings, rerun with `--apply` in an attached
  167. terminal and type the exact destination path. This operation writes only a new
  168. ignored local config in the registered checkout; it refuses tracked configs,
  169. linked-worktree registrations, symlinks, ambiguous entries, and overwrites.
  170. For tracked configs, use the existing linked-worktree migration instead. Do not
  171. run the full `aidevops init` workflow as a config-only repair.
  172. In an AI session:
  173. ```text
  174. /onboarding
  175. /skills recommend "TASK"
  176. /full-loop "Implement and ship the requested change"
  177. /pulse
  178. /report-render report.md
  179. ```
  180. ### Source inventory
  181. - 17 main agents with focused domain ownership
  182. - 2,250+ individually addressable subagents, skills, workflows, and references
  183. - 2,060+ production helpers and supporting modules, excluding tests
  184. - 100+ commands for common workflows
  185. <!-- aidevops:inventory:start -->
  186. Exact source inventory: **17 main agents**, **2,256 sub agents**, **2,218 helper scripts**, **111 slash commands**.
  187. <!-- aidevops:inventory:end -->
  188. These are tracked source modules and entry points, not simultaneously running
  189. agents. Audit the inventory with
  190. `bash .agents/scripts/readme-helper.sh counts --inventory`; counting and hero
  191. maintenance rules live in [DESIGN.md](DESIGN.md#readme-hero-counts).
  192. <!-- AI-CONTEXT-END -->
  193. ## Capabilities at a Glance
  194. | Area | What aidevops provides |
  195. |---|---|
  196. | **Software delivery** | Planning, implementation, debugging, review, CI, releases, deployment, and maintenance through linked worktrees and evidence gates |
  197. | **Autonomous operations** | Pulse supervision, workers, missions, routines, scheduling, diagnostics, recovery, and budget-aware concurrency |
  198. | **Knowledge and continuity** | Repository-owned tasks, plans, decisions, evidence, memory, knowledge ingestion, search, and session handoffs |
  199. | **Security and privacy** | Secret hygiene, prompt-injection defence, source-access approvals, supply-chain checks, operation verification, Vault, and audit trails |
  200. | **Infrastructure** | Hosting, DNS, networking, containers, cloud platforms, local development, monitoring, deployment, and object storage guidance |
  201. | **Product and business** | Product strategy, PRDs, analytics, onboarding, monetisation, accounting, invoices, reports, and operational routines |
  202. | **Growth and communication** | SEO/GEO, content, PR, email, outreach, paid ads, CRO, social workflows, and communications platforms |
  203. | **External data** | Native data providers and authorized extraction first, with cost-gated GetAnyAPI fallback access whose usage evidence guides graduation into direct aidevops subagents |
  204. | **Creative production** | Design systems, UI, browser/mobile verification, images, 3D/CAD, audio, video, animation, documents, and report exports |
  205. | **Extensibility** | Custom agents, imported skills, private agent sources, MCPs, API helpers, OpenAPI exploration, and project bundles |
  206. For YouTube transcripts, `python3 .agents/scripts/youtube-transcript.py VIDEO_ID`
  207. tries captions, then local speech-to-text, and emits timestamped JSON. Hosted
  208. TranscriptAPI access is opt-in (`--source api`). See the
  209. [transcription guide](.agents/tools/voice/transcription.md) for setup, Mac
  210. dictation alternatives, access boundaries, and optional [local anonymous
  211. speaker diarization](.agents/tools/voice/nemotron-diarization.md).
  212. The [domain index](.agents/reference/domain-index.md) is the human-readable map
  213. from user intent to specialist guidance. The generated
  214. [capability registry](.agents/reference/capability-registry.md) separately records
  215. runtime readiness requirements.
  216. > **Catalogue is not readiness.** A listed capability may still require local
  217. > deployment, compatible runtime support, installation, configuration,
  218. > authentication, authorization, network reachability, or explicit operator
  219. > approval. aidevops checks these states before provider actions and falls back
  220. > rather than pretending unavailable tooling worked.
  221. ## How Work Gets Done
  222. ```text
  223. User intent
  224. ↓
  225. Build+ or a domain primary
  226. ↓
  227. Focused guidance + capability-readiness check
  228. ↓
  229. Linked worktree, bounded operation, or approved service action
  230. ↓
  231. Runtime evidence + the narrowest applicable quality gates
  232. ↓
  233. PR / report / artifact / operational receipt
  234. ↓
  235. Authority-aware merge, publication, handoff, or follow-up
  236. ```
  237. ### Full-loop delivery
  238. `/full-loop` keeps one interactive owner responsible for a development task from
  239. implementation through verification and PR completion. The lifecycle uses fresh
  240. linked worktrees, exact-head checks, review evidence, protected merge helpers,
  241. and durable cleanup receipts.
  242. Repository authority controls the terminal path:
  243. - **Maintained aidevops work:** verified PR, merge, and—only with explicit trusted publication intent—snapshot release, postflight, and deployment.
  244. - **Other maintained repositories:** verified PR, merge, and guarded synchronization of the actual PR base branch.
  245. - **External contributions:** verified ready PR handed to upstream maintainers; no unauthorized merge, metadata mutation, or publication.
  246. Releases pin an immutable source snapshot, coordinate through a repository-wide
  247. publisher lane, bind provenance to the exact tag, and reconcile publication and
  248. deployment evidence. See [full-loop](.agents/workflows/full-loop.md),
  249. [Git workflow](.agents/workflows/git-workflow.md), and
  250. [release coordination](.agents/reference/release-lane-coordination.md).
  251. ### Pulse, workers, missions, and routines
  252. - **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.
  253. - **Workers** run issue-scoped tasks in isolated worktrees with scoped authority, model routing, runtime limits, and traceable Git outcomes.
  254. - **Missions** decompose larger goals into milestones and validated deliverables with budget tracking and automatic advancement.
  255. - **Routines** turn recurring reports, audits, monitoring, content, outreach, and operational checks into scheduled, evidence-bearing workflows.
  256. - **Runners and team interfaces** provide persistent identities, local scheduling, shared-team adapters, and bounded collaboration without turning observation into provider-write authority.
  257. Start with [orchestration](.agents/reference/orchestration.md),
  258. [worker discipline](.agents/reference/worker-discipline.md), and
  259. [routines](.agents/reference/routines.md).
  260. ### Knowledge, planning, and memory
  261. The repository owns durable work. `TODO.md`, plans, decisions, evidence, and
  262. progress remain useful even if a forge conversation or AI session disappears.
  263. GitHub, GitLab, Gitea, and Forgejo are linked execution surfaces, not the sole
  264. source of truth.
  265. - `TODO.md` and `todo/` hold tasks, PRDs, plans, dependencies, and verification state.
  266. - `_knowledge/` holds curated repository-local source material.
  267. - Cross-session memory stores concrete solutions, failures, decisions, and patterns with privacy filtering.
  268. - Session checkpoints preserve objective, state, evidence, blockers, and next actions across compaction or handoff.
  269. - Optional indexes and semantic search improve retrieval without replacing source evidence.
  270. - Ambient self-improvement repairs safe in-scope friction and routes larger findings into durable follow-up work.
  271. See [knowledge plane](.agents/aidevops/knowledge-plane.md),
  272. [memory](.agents/reference/memory.md), and
  273. [self-improvement](.agents/reference/self-improvement.md).
  274. ### Model and context efficiency
  275. aidevops keeps routing provider-neutral. Canonical `simple`, `standard`, and
  276. `thinking` tiers describe workload needs; runtime adapters map those tiers to
  277. available models and accounts. Stronger models are reserved for consequential
  278. judgement, architecture, and synthesis, while bounded work uses the cheapest
  279. capable route.
  280. Progressive disclosure loads only the relevant agents, references, and tools.
  281. TOON registries, compact terminal summaries, exact code search, context
  282. bundles, prompt caching, and compaction checkpoints reduce unnecessary context
  283. without hiding required evidence. Model comparisons and sealed historical replay
  284. can inform routing, but cannot silently rewrite production policy.
  285. OpenCode defaults resolved models with larger windows to a ~240K usable-input
  286. compaction budget, without expanding smaller native windows or overriding
  287. explicit per-model context/input limits. GPT-6.1 Sol/Terra, GPT-6 Sol/Luna and
  288. their Fast variants also advertise the budget in their model metadata. Run `aidevops
  289. gpt6-context status` to check those models in a fresh process, or `disable` to restore
  290. their native limits. Restart OpenCode after changes.
  291. See [model routing](.agents/tools/context/model-routing.md),
  292. [context efficiency](.agents/reference/context-efficiency.md), and
  293. [model-effort evaluation](.agents/reference/model-effort-evaluation.md).
  294. Worker dispatch retains priority-first routing by default. Operators can opt
  295. individual tiers into provider-level round-robin in the custom model routing
  296. table; model pins, retries and provider health gates remain unchanged.
  297. ## Primary Agents
  298. Build+ is the default for development, systems, and applications. Domain
  299. primaries add focused judgement while retaining the same applicable safety,
  300. authority, and verification boundaries.
  301. | Agent | Focus |
  302. |---|---|
  303. | **3D Modelling** | Editable 3D creation, parametric CAD, reconstruction, configurable products, and rendering |
  304. | **Audio** | Music composition, arrangement, sound design, editing, mixing, and reproducible audio projects |
  305. | **Automate** | Scheduling, dispatch, monitoring, routines, and background orchestration |
  306. | **Build+** | Planning and full-loop delivery for code, apps, systems, CI, releases, and DevOps |
  307. | **Business** | Company operations, strategy, accounting, finance, invoices, and management reporting |
  308. | **Content** | Writing, images, social, multi-channel stories, and content production coordination |
  309. | **Health** | Evidence-aware health, fitness, nutrition, and wellness guidance |
  310. | **Legal** | Legal research, contracts, privacy, compliance, and GDPR guidance |
  311. | **Marketing-Sales** | Campaigns, CRM, email, outreach, paid ads, direct response, and CRO |
  312. | **PR** | Earned media, newsworthiness, journalist research, media lists, and coverage tracking |
  313. | **Private Local AI** | Sensitive investigations using verified privacy-first and local-compute boundaries |
  314. | **Product** | Product strategy, validation, PRDs, roadmaps, onboarding, growth, and analytics |
  315. | **Reports** | Evidence contracts, decision-ready reports, exporters, citations, and routine handoffs |
  316. | **Research** | Technical, market, competitive, and source-grounded research |
  317. | **SEO** | Technical SEO, GEO/AI search, keyword research, content analysis, schema, and search data |
  318. | **Vault** | Protected-data classification, encrypted stores, fleet trust, secure sync, and lock policy |
  319. | **Video** | Editing, compositing, grading, animation, source projects, and verified delivery |
  320. Specialists under `.agents/tools/`, `.agents/services/`, `.agents/workflows/`,
  321. and `.agents/reference/` are loaded on demand. Use `/skills recommend "TASK"` or
  322. the OpenCode agent picker rather than memorising the catalogue.
  323. ## Domain Coverage
  324. | Domain | Examples |
  325. |---|---|
  326. | **Development** | Code, architecture, reviews, testing, accessibility, performance, APIs, databases, mobile, extensions |
  327. | **Infrastructure** | Hosting, [AWS](.agents/services/hosting/aws.md) (SSO, secret-backed CLI, SES), Google Cloud, Cloudflare, Coolify, Vercel, Cloudron, containers, remote compute, DNS, VPNs, local HTTPS |
  328. | **Storage and backups** | Backblaze B2, IDrive E2, Wasabi, S3-compatible inventories, Cloudron backup freshness |
  329. | **Security** | Secrets, dependency risk, prompt injection, source approvals, access reviews, incident response, Vault |
  330. | **Product** | Validation, roadmaps, UX, analytics, feature flags, experiments, onboarding, monetisation |
  331. | **Business and finance** | Strategy, accounting, QuickFile, receipts, reconciliation, forecasts, invoices, procurement |
  332. | **Marketing and sales** | Paid ads, direct response, CRO, CRM, lead generation, cold outreach, campaign operations |
  333. | **Search and content** | SEO, GEO, AI visibility, GSC, keywords, entities, schema, articles, newsletters, social publishing |
  334. | **PR and communications** | News research, journalist fit, media lists, press releases, coverage, chat and team interfaces |
  335. | **Design and creative** | DESIGN.md, brand systems, UI, email/decks, browser QA, images, 3D/CAD, video, audio, voice |
  336. | **Documents and reports** | OCR, extraction, Markdown-first reports, HTML, PDF, DOCX, slide profiles, citations, evidence ledgers |
  337. | **Personal operations** | Calendar, health, macOS diagnostics, productivity, recurring checks, private/local research |
  338. This table describes coverage, not live credentials or provider availability.
  339. Use `capability-readiness-helper.py query` through the documented workflow when a
  340. task depends on an external runtime or service.
  341. ## Security and Protected Data
  342. aidevops assumes agents may have powerful local and remote access. Security is
  343. part of normal work rather than a final checklist.
  344. - Credentials are stored through `aidevops secret` or private configuration, never pasted into chat or committed.
  345. - Prompt-injection scanning treats external instructions as untrusted content and extracts facts without surrendering control.
  346. - Git hooks and wrappers protect canonical branches, secrets, private paths, issue authority, signatures, and exact-head merge evidence.
  347. - High-risk destructive operations require explicit confirmation and may require independent cross-provider verification.
  348. - Imported skills are scanned before activation; high-severity findings block normal installation.
  349. - Source-read approvals are exact-path, digest-bound, session-bound, short-lived, and mediated by a root-owned broker.
  350. - Audit logs record security-relevant operations without credential values.
  351. ```bash
  352. aidevops secret set NAME
  353. aidevops security
  354. aidevops security status
  355. aidevops security scan
  356. aidevops secret audit-credentials # Names-only JSON Lines, including tenant stores
  357. aidevops security fix # Separate interactive terminal only
  358. aidevops source-access status
  359. ```
  360. Credential hygiene scans report parser errors, gopass drift, prune candidates,
  361. unsafe permissions, leftover backups and literal MCP environment secrets without
  362. printing values. Interactive fixes delegate to secret import/prune commands,
  363. confirm pruning and trash moves, and leave drift and malformed lines unchanged.
  364. Import and prune target only the active tenant. Scans do not probe provider APIs;
  365. an opt-in `--probe` may be added later. SSH checks parse `~/.ssh/config` and its
  366. `Include` files as text (never `ssh -G`, which runs `Match exec`): passphrase-less
  367. `id_*` and `IdentityFile` keys, loose key/config/`~/.ssh` permissions, and
  368. risky directives such as disabled host-key checking, global agent forwarding and
  369. command hooks, reported by keyword and line only. Fixes offer a per-file
  370. confirmed `chmod 600` for owned regular files, never through a symlinked target.
  371. ### Vault
  372. Vault adds protected-data classes, local encrypted stores, provider-routing
  373. labels, device trust, fleet lock/unlock policy, secure sync guidance, and
  374. approval-aware task metadata. It cannot protect information after that
  375. information is decrypted into a third-party model prompt, and it cannot recover
  376. a lost passphrase. Review [Vault boundaries](.agents/reference/vault.md) before
  377. using protected data.
  378. ## Reports and Creative Production
  379. ### Evidence-led reports
  380. Reports keep Markdown or JSON as the canonical source, then derive styled HTML,
  381. PDF, DOCX, or slide-profile outputs. Shared contracts cover citations, source
  382. cards, evidence states, executive summaries, action prompts, and recurring
  383. handoffs. Domain report guidance supports development, business, marketing, and
  384. SEO/GEO work.
  385. ```text
  386. /report-render report.md
  387. ```
  388. See [reports](.agents/reports/general.md) and the versioned
  389. [`_reports/examples/`](_reports/examples/) previews.
  390. ### Design, browser, mobile, and media
  391. - **Design:** Google `DESIGN.md` conventions, brand identity, visual concepts, distinctive UI, component guidance, previews, and accessibility verification. On macOS, the [Affinity Studio specialist](.agents/tools/design/affinity.md) offers opt-in, copy-first native artwork creation/editing and verified exports through its gated MCP connector ([setup guide](.agents/tools/design/affinity-setup.md)).
  392. - **Browser:** Playwright-first automation with bounded Luna-xhigh browser subagents in OpenCode (Sol-medium/parent fallback), reusable browser-operation learning, authenticated-profile boundaries, crawling, screenshots, and performance diagnostics.
  393. - **Mobile:** Expo, Swift/Xcode, App Store Connect, simulator workflows, device automation, simulator-backed web previews, and [opt-in Mobile MCP](.agents/tools/mobile/mobile-mcp.md) for local iOS/Android device control. Interactive setup can offer Android `adb` on macOS and explain full-Xcode simulator prerequisites; updates never silently install host SDKs.
  394. - **3D/CAD:** Blender and FreeCAD specialists, OpenSCAD script-based CAD guidance, dimensional truth, editable source models, configurable products, and rendered verification.
  395. - **Video:** DaVinci Resolve, conversational editing, Remotion, compositing, colour, audio, and rendered-output checks.
  396. - **Audio:** Ableton projects, MIDI, arrangement, stems, mixing, voice workflows, loudness, and export verification.
  397. - **Images:** provider routing, reference editing, dimensions, provenance, and publication checks.
  398. Creative work preserves originals, editable projects, dependencies, licences,
  399. decisions, technical checks, and perceptual review where the runtime supports it.
  400. Start with [creative production](.agents/workflows/creative-production.md).
  401. ## Integrations and Extensibility
  402. aidevops combines CLI tools, shell/Python/TypeScript helpers, direct APIs,
  403. OpenAPI exploration, browser automation, and on-demand MCP servers. MCPs remain
  404. disconnected until an approved specialist needs them, reducing idle processes,
  405. tool-schema context, and accidental authority.
  406. Integration families include:
  407. - GitHub, GitLab, Gitea, Forgejo, CI systems, quality platforms, and dependency scanners.
  408. - Hosting, DNS, cloud, deployment, object storage, networking, monitoring, and local development.
  409. - Product analytics, error monitoring, email, communications, social platforms, outreach, and payments.
  410. - Accounting, ecommerce, WordPress (including [Rank Math SEO MCP](.agents/tools/wordpress/rankmath-mcp.md)), documents, OCR, browser automation, and creative applications.
  411. - Context7, exact code search, OpenAPI search, local models, and model-provider account pools.
  412. ### Skills and private agent sources
  413. ```bash
  414. aidevops skill add owner/repo
  415. aidevops skill list
  416. aidevops skill check
  417. aidevops skill scan NAME
  418. aidevops sources add /path/to/private-agent-repo
  419. aidevops sources sync
  420. ```
  421. Imported skills retain source and update metadata, pass through security checks,
  422. and are adapted to aidevops conventions rather than copied blindly. Private
  423. agent repositories can deploy organization- or client-specific guidance beside
  424. the shared framework without publishing it.
  425. Custom agents progress through three tiers:
  426. | Tier | Location | Purpose |
  427. |---|---|---|
  428. | **Draft** | `~/.aidevops/agents/draft/` | Experimental and evaluation-stage capabilities |
  429. | **Custom** | `~/.aidevops/agents/custom/` | Durable private user or organization capabilities |
  430. | **Shared** | `.agents/` | Reviewed open-source framework capabilities |
  431. ## Installation
  432. ### npm
  433. ```bash
  434. npm install -g aidevops && aidevops update
  435. ```
  436. ### Bun
  437. ```bash
  438. bun install -g aidevops && aidevops update
  439. ```
  440. ### Homebrew
  441. ```bash
  442. brew install marcusquinn/tap/aidevops && aidevops update
  443. ```
  444. ### Direct installer
  445. ```bash
  446. bash <(curl -fsSL https://aidevops.sh/install)
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 562 on GitHub
  447. ```
  448. ### From source
  449. ```bash
  450. git clone https://github.com/marcusquinn/aidevops.git ~/Git/aidevops
  451. ~/Git/aidevops/setup.sh
  452. ```
  453. Setup deploys the framework under `~/.aidevops/agents/`, installs the CLI,
  454. configures detected supported runtimes, and offers optional tools. Existing
  455. personal settings and custom agents are preserved.
  456. Setup/update also manages a persistent OpenCode owner on macOS and on Linux/WSL2
  457. with a systemd user manager. `aidevops opencode managed --dir PATH` attaches a TUI
  458. to its shared history. Existing databases, routing choices, and disabled services
  459. are preserved; Desktop's first server/project selection remains manual. See the
  460. [managed-service guide](.agents/reference/opencode-service.md) for platform
  461. verification limits, opt-out, and rollback.
  462. For Desktop builds advertising connection-link support, opt in with
  463. `aidevops opencode-desktop --connect-managed --dir PATH`. Desktop confirms the
  464. server and folder without replacing saved defaults. Unsupported builds, including
  465. the released 1.18.32 app, retain the manual flow; this does not install a patched Desktop.
  466. ## Quick Start
  467. For the full first-run checklist (providers, project layout, automation), see
  468. [Quick Setup](#quick-setup).
  469. 1. Install aidevops using one of the methods above.
  470. 2. Start OpenCode in a project and run `/onboarding` for account-level setup.
  471. 3. Run `aidevops init` inside the repository.
  472. 4. Run `/setup-git` when the repository needs platform-specific secrets or workflows.
  473. 5. Describe the outcome you want, or use `/skills recommend "TASK"` to discover a route.
  474. Initialize selected features when a repository needs less than the default set:
  475. ```bash
  476. aidevops init planning
  477. aidevops init planning,git-workflow,code-quality
  478. aidevops init deployment-context
  479. aidevops init wordpress-context
  480. ```
  481. Depending on selected features and existing files, initialization can add:
  482. - `.aidevops.json` for repository feature and workflow metadata.
  483. - `.agents/AGENTS.md` for project-specific AI guidance.
  484. - `TODO.md` and `todo/` for tasks, plans, PRDs, and verification state.
  485. - `DESIGN.md` for repositories with a detected interface.
  486. - `context/keywords.md` search targets (keywords, AI-answer questions, entities)
  487. for standard-scope repositories; public repositories keep the data in a
  488. private team hub ([standard](.agents/seo/keywords-standard.md)).
  489. - Deployment and WordPress context manifests when explicitly selected.
  490. - Standard project courtesy files only when they do not already exist.
  491. Repository registration lives in `~/.config/aidevops/repos.json`; updates can
  492. then check initialized projects for framework and template drift.
  493. ## Common Workflows
  494. | Goal | Entry point |
  495. |---|---|
  496. | Discover capabilities | `/skills recommend "TASK"` or `aidevops skills` |
  497. | Define a complex objective | `/define`, `/goals`, `/mission` |
  498. | Plan implementation | `/show-plan`, PRD/task workflows, `TODO.md` |
  499. | Implement through PR | `/full-loop "TASK"` |
  500. | Review code or a PR | `/review`, `/cross-review` |
  501. | Run repository checks | `.agents/scripts/linters-local.sh --changed` |
  502. | Supervise autonomous work | `/pulse`, `/dashboard`, `/runners` |
  503. | Create a recurring operation | `/routine` |
  504. | Work with protected data | `/vault` |
  505. | Audit SEO/GEO | `/seo-audit`, `/seo-geo` |
  506. | Learn browser work | `/auto-browse` |
  507. | Produce an editable artifact | `/3d-modelling`, `/video`, `/audio`, `/design-artifact` |
  508. | Render a report | `/report-render` |
  509. | Capture or recall a lesson | `/remember`, `/recall`, `/patterns` |
  510. Runtime command names may be namespaced, such as `/aidevops-full-loop`, where a
  511. client reserves or groups slash commands differently. OpenCode exposes main
  512. agents in its agent picker.
  513. ## Configuration
  514. | File | Purpose |
  515. |---|---|
  516. | [`~/.config/aidevops/config.jsonc`](.agents/reference/configuration.md) | Framework updates, models, safety, quality, orchestration, and paths |
  517. | [`~/.config/aidevops/settings.json`](.agents/reference/configuration.md) | User preferences and onboarding state |
  518. | `~/.config/aidevops/repos.json` | Registered repositories, platforms, bundles, Pulse, and context metadata |
  519. | `.aidevops.json` | Repository-local feature and workflow configuration |
  520. | `configs/*.json.txt` | Safe committed templates for service configuration |
  521. | `configs/*.json` | Gitignored working service configuration |
  522. ```bash
  523. aidevops config list
  524. aidevops config validate
  525. aidevops config set updates.auto_update false
  526. ```
  527. Precedence is `AIDEVOPS_*` environment variables, then user configuration, then
  528. built-in defaults. Store secrets with `aidevops secret`; do not put credential
  529. values in committed templates, command arguments, logs, or AI conversations.
  530. ## Architecture
  531. ```text
  532. aidevops/
  533. ├── setup.sh # Source installer and deployment entry point
  534. ├── aidevops.sh # CLI implementation
  535. ├── AGENTS.md # Contributor guidance
  536. ├── .agents/
  537. │ ├── AGENTS.md # Deployed user guide
  538. │ ├── *.md # Main agents
  539. │ ├── workflows/ # Reusable operating workflows
  540. │ ├── tools/ # Cross-domain capabilities
  541. │ ├── services/ # Provider and service integrations
  542. │ ├── reference/ # Shared contracts and policies
  543. │ └── scripts/ # Deterministic helpers and validators
  544. ├── .opencode/ # OpenCode-native plugin tools
  545. ├── configs/ # Safe configuration templates
  546. ├── docs/ # Public documentation and generated metrics
  547. ├── templates/ # Project and user-home templates
  548. ├── tests/ # Framework verification
  549. └── _*/ # Repository-local data planes
  550. ```
  551. Strategy and execution are deliberately separated. Models own prioritisation,
  552. semantic judgement, diagnosis, and trade-offs. Deterministic tools own schemas,
  553. path safety, signatures, exact state transitions, reproducible generation, and
  554. other mechanically verifiable invariants.
  555. ### Repository data planes
  556. | Plane | Purpose |
  557. |---|---|
  558. | `_knowledge/` | Curated, source-identified knowledge for repository work |
  559. | `_cases/` | Structured case material and reusable case evidence |
  560. | `_campaigns/` | Campaign inputs, execution state, and reviewed reusable assets |
  561. | `_inbox/` | Controlled intake and transit before classification |
  562. | `_feedback/` | Product and framework feedback evidence |
  563. | `_projects/` | Non-software project work that does not fit task or campaign planes |
  564. | `_performance/` | Performance evidence and optimization state |
  565. | `_reports/` | Canonical report sources, drafts, examples, and derived outputs |
  566. See [architecture](.agents/aidevops/architecture.md),
  567. [repository layout](.agents/configs/repo-layout-policy.conf), and
  568. [storage lifecycle](.agents/reference/storage-lifecycle.md).
  569. ## Requirements and Platform Support
  570. aidevops itself is mostly Markdown, shell, Python, and TypeScript/Bun tooling.
  571. Most software, infrastructure, research, and operational workflows use cloud
  572. models and do not require a local GPU. Media generation, local models, creative
  573. applications, simulators, and voice pipelines have their own optional hardware
  574. and platform requirements.
  575. The framework is developed primarily on macOS and includes Linux support for
  576. documented workflows. Individual tools may require a specific operating system,
  577. architecture, desktop application, licence, API account, or human-present
  578. authorization. Check [platform support](.agents/reference/platform-support.md)
  579. and capability readiness before installation or execution.
  580. Common command-line dependencies are discovered by setup rather than assumed.
  581. `git`, `curl`, `jq`, `fd`, and `ripgrep` cover many core workflows; optional
  582. tools are installed or configured only through their documented, consent-aware
  583. paths.
  584. ## Development and Verification
  585. All interactive changes use a linked worktree; canonical `main` or `master`
  586. checkouts remain read-only service mirrors. The full lifecycle is documented in
  587. [Git workflow](.agents/workflows/git-workflow.md).
  588. ```bash
  589. ./setup.sh --non-interactive
  590. .agents/scripts/linters-local.sh --changed
  591. .agents/scripts/readme-helper.sh check
  592. .agents/scripts/managed-readme-helper.sh check --repo marcusquinn/aidevops --root .
  593. ```
  594. Verification follows risk and blast radius:
  595. 1. Exercise the real user-facing path where practical.
  596. 2. Inspect logs, framework diagnostics, or generated evidence.
  597. 3. Run the narrowest existing checks covering changed files and packages.
  598. 4. Broaden to repository-wide gates only when shared contracts or release scope require it.
  599. 5. Review the exact diff and bind remote evidence to the exact PR head.
  600. Tests are added when requested, required by repository policy, or the
  601. lowest-cost way to resolve material uncertainty. New test infrastructure is not
  602. created merely to make a completion report look stronger.
  603. ## Troubleshooting
  604. ### Installation or PATH problems
  605. ```bash
  606. aidevops status
  607. aidevops doctor
  608. aidevops update
  609. ```
  610. ### Model account or authentication problems
  611. ```bash
  612. aidevops model-accounts-pool status
  613. aidevops model-accounts-pool check
  614. aidevops model-accounts-pool rotate PROVIDER
  615. ```
  616. Restart the active runtime after changing account assignments. Authentication
  617. for one provider is isolated from other provider pools.
  618. ### A capability is listed but unavailable
  619. Check the capability registry and its owning guide. Confirm deployment, runtime
  620. compatibility, installation, configuration, authentication, authorization,
  621. reachability, and operator approval. Use the documented fallback when any
  622. mandatory state is missing.
  623. ### A worker, PR, or Pulse cycle is stuck
  624. Start with the read-only summary and the PR-specific diagnosis documented in
  625. [worker diagnostics](.agents/reference/worker-diagnostics.md). Pending CI is a
  626. wait state, not a failure; repair only terminal failing checks tied to the exact
  627. head.
  628. ### Security advice appears during update
  629. Treat the advisory as evidence to review, not text to follow blindly. Run the
  630. recommended security command in a separate attached terminal and never paste
  631. secrets into the AI session.
  632. ## Documentation
  633. - [Getting Started](.wiki/Getting-Started.md)
  634. - [CLI Reference](.wiki/CLI-Reference.md)
  635. - [Configuration Reference](.agents/reference/configuration.md)
  636. - [Domain Index](.agents/reference/domain-index.md)
  637. - [Capability Registry](.agents/reference/capability-registry.md)
  638. - [Agent Routing](.agents/reference/agent-routing.md)
  639. - [Git Workflow](.agents/workflows/git-workflow.md)
  640. - [Security](.agents/aidevops/security.md)
  641. - [Browser Automation](.agents/tools/browser/browser-automation.md)
  642. - [Stagehand v4 (opt-in local browser)](.agents/tools/browser/stagehand.md)
  643. - [Creative Production](.agents/workflows/creative-production.md)
  644. - [Reports](.agents/reports/general.md)
  645. - [Changelog](CHANGELOG.md)
  646. ## Contributing and License
  647. Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md), work from a
  648. safe linked worktree, preserve security and attribution boundaries, run the
  649. applicable checks, and submit a focused pull request with verification evidence.
  650. aidevops is licensed under the [MIT License](LICENSE). Reuse, including
  651. commercial use, is welcome when copyright and licence notices are retained.
  652. Derivative frameworks, automation products, and distinctive workflow reuse
  653. should also follow [ATTRIBUTION.md](ATTRIBUTION.md).
  654. Founded by [Marcus Quinn](https://github.com/marcusquinn) on 9 November 2025.
  655. <!-- aidevops:managed-readme:start -->
  656. <!-- managed by aidevops; refresh with managed-readme-helper.sh sync -->
  657. ## Star History
  658. ![marcusquinn/aidevops stars over time](docs/assets/star-history.svg)
  659. ## Built with aidevops
  660. This project was created and is maintained with
  661. [aidevops.sh](https://aidevops.sh).
  662. [View marcusquinn on GitHub](https://github.com/marcusquinn) ·
  663. [aidevops repository](https://github.com/marcusquinn/aidevops)
  664. <!-- aidevops:managed-readme:end -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.