aidevops 3.32.362 → 3.32.364
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +509 -2802
- package/VERSION +1 -1
- package/aidevops.sh +1 -1
- package/bun.lock +35 -71
- package/docs/metrics/badges/languages.svg +10 -10
- package/docs/metrics/badges/loc-languages.svg +10 -10
- package/docs/metrics/badges/loc-total.svg +3 -3
- package/docs/metrics/badges/loc.svg +3 -3
- package/docs/metrics/repo-metrics.json +52 -52
- package/docs/metrics/repo-metrics.md +13 -13
- package/package.json +4 -4
- package/setup.sh +1 -1
package/README.md
CHANGED
|
@@ -1,2944 +1,651 @@
|
|
|
1
1
|
<!-- SPDX-License-Identifier: MIT -->
|
|
2
2
|
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
|
|
3
3
|
|
|
4
|
-
|
|
5
5
|
|
|
6
6
|
# AI DevOps Framework
|
|
7
7
|
|
|
8
|
-
**[aidevops.sh](https://aidevops.sh)** is an [OpenCode](https://opencode.ai/)
|
|
8
|
+
**[aidevops.sh](https://aidevops.sh)** is an [OpenCode](https://opencode.ai/)
|
|
9
|
+
plugin and AI DevOps framework for carrying work from intent to a verified
|
|
10
|
+
outcome. It combines specialist agents, durable repository knowledge, safe Git
|
|
11
|
+
workflows, model routing, operational automation, and service integrations for
|
|
12
|
+
software, infrastructure, business, marketing, content, research, and creative
|
|
13
|
+
production.
|
|
9
14
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
only record of the work. The aim of helping people become 100x more capable at
|
|
15
|
-
value generation is an ambition to substantiate, not a guaranteed or measured
|
|
16
|
-
result.
|
|
15
|
+
Instead of treating every job as an isolated chat, aidevops gives people and AI
|
|
16
|
+
agents a shared operating system: the right context is loaded on demand, work is
|
|
17
|
+
isolated, consequential actions are gated, evidence is retained, and useful
|
|
18
|
+
lessons improve later work.
|
|
17
19
|
|
|
18
|
-
|
|
20
|
+
**One conversation, autonomous project delivery, with security, teamwork,
|
|
21
|
+
token efficiency, and quality control built in.**
|
|
19
22
|
|
|
20
|
-
> **Recommended setup:** [OpenCode](https://opencode.ai/) + OpenAI GPT-5.6 Luna / Terra and GPT-6 Astra. aidevops routes Luna to bounded work, Terra to general implementation, and Astra at low reasoning to consequential reasoning and synthesis. Claude models (Anthropic) remain fully supported fallbacks, and other model providers are evaluated as their quality, latency, and cost profiles change.
|
|
21
|
-
|
|
22
|
-
*"Scope a mission to redesign the landing pages — break it into milestones, dispatch workers in parallel, validate each milestone, and track budget across the whole project."*
|
|
23
|
-
|
|
24
|
-
**One conversation, autonomous project delivery, with security, teamwork, token efficiency, and quality control built in.**
|
|
25
|
-
|
|
26
|
-
Founded by [Marcus Quinn](https://github.com/marcusquinn) on 9th November 2025 to help anyone level-up their AI & Open-Source game.
|
|
27
|
-
|
|
28
|
-
## **The Aim**
|
|
29
|
-
|
|
30
|
-
**Maximum value for your time and money.** **[aidevops](https://aidevops.sh)** is built for the gap between “the model can probably do this” and “the work is actually done, verified, safe, and worth the cost.”
|
|
31
|
-
|
|
32
|
-
- Load the right context when it is needed, instead of stuffing every agent, skill, and tool into the prompt.
|
|
33
|
-
- Spend tokens and model budget deliberately. Cheap and fast models should handle routine work; stronger models should handle judgement, architecture, review, and risk.
|
|
34
|
-
- Keep secrets out of chat. Credentials, tenants, scans, confirmations, and audit logs are part of the workflow, not an afterthought.
|
|
35
|
-
- Let people and agents work across machines without trampling each other. Worktrees, branches, PRs, task IDs, mailbox state, and memory keep the work separated and traceable.
|
|
36
|
-
- Notice when the system is struggling. Stuck workers, orphaned PRs, stale assignments, CI failures, review-bot traps, and repeated mistakes should become visible signals.
|
|
37
|
-
- Improve the framework from real use. Imported skills, session learnings, quality findings, and better patterns should become better agents, hooks, scripts, and docs.
|
|
38
|
-
- Optimise for profitable outcomes: useful work shipped, lower supervision cost, safer operations, and decisions that make sense beyond the next prompt.
|
|
39
|
-
- Make ownership structural: explicit sources of truth, generated views, consistency checks, and verified fallback behaviour prevent knowledge and progress from drifting between tools.
|
|
40
|
-
|
|
41
|
-
The result: an AI operations platform that manages projects across every business domain — absorbing everything automatable so you can focus on what matters.
|
|
42
|
-
|
|
43
|
-
The canonical purpose and architectural decision criteria are in
|
|
44
|
-
[`.agents/aidevops/purpose.md`](.agents/aidevops/purpose.md).
|
|
45
|
-
|
|
46
|
-
**Built on proven patterns**: aidevops implements [industry-standard agent design patterns](#agent-design-patterns) - including multi-layer action spaces, context isolation, and iterative execution loops.
|
|
47
|
-
|
|
48
|
-
## **Why This Framework?**
|
|
49
|
-
|
|
50
|
-
**Beyond single-task AI.** A normal AI harness can be brilliant for one job and still weak at the work around the job. aidevops is for the surrounding discipline: context, routing, safety, git hygiene, collaboration, verification, memory, and follow-through.
|
|
51
|
-
|
|
52
|
-
**What makes it different:**
|
|
53
|
-
|
|
54
|
-
- **Pulse supervision** - scheduled checks can dispatch workers, merge ready PRs, close loops, and surface stuck work.
|
|
55
|
-
- **Domain agents** - code, automation, product, business, marketing, legal, content, research, SEO, health, reports, and framework work each get their own guidance.
|
|
56
|
-
- **Cross-model checks** - risky operations can be reviewed by a second provider to reduce shared failure modes.
|
|
57
|
-
- **Service coverage** - hosting, Git platforms, DNS, security, monitoring, deployment, payments, communications, and more are handled through repeatable helpers.
|
|
58
|
-
- **Mission work** - larger goals can be split into milestones with validation, budget tracking, and automatic advancement.
|
|
59
|
-
|
|
60
|
-
---
|
|
61
|
-
|
|
62
|
-
<!-- Build & Quality Status -->
|
|
63
23
|
[](https://github.com/marcusquinn/aidevops/actions/workflows/code-quality.yml)
|
|
64
24
|
[](https://sonarcloud.io/summary/new_code?id=marcusquinn_aidevops)
|
|
65
|
-
[](https://www.codefactor.io/repository/github/marcusquinn/aidevops)
|
|
66
25
|
[](https://qlty.sh/gh/marcusquinn/projects/aidevops)
|
|
67
26
|
[](https://app.codacy.com/gh/marcusquinn/aidevops/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
|
|
68
|
-
[](https://coderabbit.ai)
|
|
69
|
-
|
|
70
|
-
<!-- License & Legal -->
|
|
71
27
|
[](https://opensource.org/licenses/MIT)
|
|
72
|
-
[](https://github.com/marcusquinn/aidevops/releases)
|
|
28
|
+
[](https://github.com/marcusquinn/aidevops/releases)
|
|
76
29
|
[](https://www.npmjs.com/package/aidevops)
|
|
77
30
|
[](https://github.com/marcusquinn/homebrew-tap)
|
|
78
|
-
[](https://github.com/marcusquinn/aidevops)
|
|
79
31
|
|
|
80
|
-
<!-- Framework Specific -->
|
|
81
|
-
[](#comprehensive-service-coverage)
|
|
82
|
-
[](https://agents.md/)
|
|
83
|
-
[](https://github.com/marcusquinn/aidevops/blob/main/AGENTS.md)
|
|
84
|
-
[](#mcp-integrations)
|
|
85
|
-
[](#comprehensive-service-coverage)
|
|
86
|
-
|
|
87
|
-
<!-- Repository Metrics -->
|
|
88
32
|
[](docs/metrics/repo-metrics.md)
|
|
89
33
|
[](docs/metrics/repo-metrics.md)
|
|
90
|
-
|
|
91
34
|
[](docs/metrics/repo-metrics.md)
|
|
92
35
|
|
|
93
|
-
##
|
|
36
|
+
## The Aim
|
|
94
37
|
|
|
95
|
-
|
|
96
|
-
the
|
|
97
|
-
|
|
98
|
-
code or distinctive operating patterns, see [ATTRIBUTION.md](ATTRIBUTION.md) for
|
|
99
|
-
the required notices and preferred credit text.
|
|
38
|
+
**Maximum useful value for your time and money.** aidevops is built for the gap
|
|
39
|
+
between “the model can probably do this” and “the work is done, verified, safe,
|
|
40
|
+
and worth the cost.”
|
|
100
41
|
|
|
101
|
-
|
|
42
|
+
- Load focused guidance only when it is relevant.
|
|
43
|
+
- Match model capability and reasoning effort to the work.
|
|
44
|
+
- Keep secrets, protected data, and private state out of chat and Git.
|
|
45
|
+
- Let people and agents work in parallel without sharing unsafe mutable state.
|
|
46
|
+
- Preserve tasks, plans, decisions, evidence, and progress in durable sources of truth.
|
|
47
|
+
- Detect stuck work, failing automation, review traps, and repeated friction.
|
|
48
|
+
- Turn observed lessons into better guidance, checks, helpers, and follow-up work.
|
|
49
|
+
- Reserve human attention for taste, authority, secrets, and consequential ambiguity.
|
|
102
50
|
|
|
103
|
-
|
|
51
|
+
The “100x more capable” goal is an ambition to substantiate, not a guaranteed or
|
|
52
|
+
measured result. The canonical purpose and decision criteria are in
|
|
53
|
+
[`.agents/aidevops/purpose.md`](.agents/aidevops/purpose.md).
|
|
104
54
|
|
|
105
|
-
|
|
106
|
-
- **Install**: `npm install -g aidevops && aidevops update`
|
|
107
|
-
- **Recommended runtime/models**: OpenCode + OpenAI GPT-5.6 Luna / Terra / GPT-6 Astra
|
|
108
|
-
- **Entry**: `aidevops` CLI, `~/.aidevops/agents/AGENTS.md`
|
|
109
|
-
- **Stack**: Bash scripts, TypeScript (Bun), MCP servers
|
|
110
|
-
- **Recent focus**: evidence-based model routing, indexed worker worktrees, audited deployment copies, release provenance, and OpenCode control-plane safety
|
|
111
|
-
|
|
112
|
-
### Key Commands
|
|
113
|
-
|
|
114
|
-
- `aidevops init` - Initialize in any project
|
|
115
|
-
- `aidevops update` - Update framework
|
|
116
|
-
- `aidevops auto-update` - Automatic update polling (enable/disable/status)
|
|
117
|
-
- `aidevops runtime-bundle list` - List retained validated runtime bundles; use `rollback --bundle-id <id> --reason <text>` for an explicit audited rollback
|
|
118
|
-
- `aidevops gpt56-context [enable|disable|status]` - Keep GPT-5.6 at a 300K advertised context window in OpenCode (enabled by default), so 80% auto-compaction runs near 240K before long-context pricing; `status` verifies plugin discovery, initialization, hook registration, and effective limits
|
|
119
|
-
- `aidevops astra-context [enable|disable|status]` - Opt into ~240K usable-input Astra compaction; `disable` restores the default 400K target while preserving native-metadata opt-out. Settings survive updates; `status` probes fresh-process configuration. Restart OpenCode after changes; subscription savings are not guaranteed
|
|
120
|
-
- `aidevops buzz [status|apply|rollback]` - Inspect or manage Buzz Desktop OpenCode ACP compatibility
|
|
121
|
-
- `~/.aidevops/agents/scripts/team-interface-helper.sh [providers|detect|status|doctor|plan]` - Inspect registered collaboration providers, persist read-only observations, or emit deterministic dry-run plans; no provider-write command is exposed
|
|
122
|
-
- `aidevops opencode conversation --overlay FILE --dir PATH` - Launch fixed-argv OpenCode ACP with a schema-validated ephemeral team-interface overlay and a final read-only capability guard; see `.agents/reference/team-interface-opencode-overlays.md`
|
|
123
|
-
- `aidevops secret` - Manage secrets (gopass encrypted, AI-safe)
|
|
124
|
-
- `aidevops source-access` - Manage exact-path, session-bound source-read approvals signed via sudo
|
|
125
|
-
- `aidevops security` - Full security assessment (posture, secrets, supply chain)
|
|
126
|
-
- `aidevops lint audit` - Audit native lint/format/typecheck commands and repo-verify hooks
|
|
127
|
-
- `aidevops lint configure --dry-run` - Preview safe evidence-based lint provisioning
|
|
128
|
-
- `aidevops metrics generate` - Generate local LOC, language, and dependency data for README badges or app about pages
|
|
129
|
-
- `/onboarding` - Interactive setup wizard (in AI assistant)
|
|
130
|
-
- `/design-artifact` - Route artifact-first UI, deck, email, poster, and mobile mockup work
|
|
131
|
-
- `/open-design` - Manage the optional Open Design companion studio
|
|
132
|
-
- `/auto-browse` - Learn, optimize, and graduate repeatable browser operations and web data-mining workflows
|
|
133
|
-
- `/report-render` - Render report-ready Markdown or JSON to HTML with sticky TOC, print CSS, evidence badges, and source cards for PDF export
|
|
134
|
-
- `/report-token-use` - Generate a local per-session token, model, compaction, and MCP-use report
|
|
135
|
-
- `/report-token-use efficiency --since 7d` - Compare model/effort, reasoning, prompt sizes, cache tokens, and consistently repriced API-equivalent costs without changing the ledger
|
|
136
|
-
- `/optimize-tiers` - Optionally investigate unresolved model comparisons with production telemetry and sealed historical replay
|
|
137
|
-
- `/pulse` - Run the autonomous supervisor loop for dispatch, merge, diagnostics, and stuck-work recovery
|
|
138
|
-
- `/serve-sim` / `serve-sim-helper.sh` - Exercise mobile web flows in simulator-backed local previews
|
|
139
|
-
|
|
140
|
-
### Agent Structure
|
|
141
|
-
|
|
142
|
-
- 14 main agents (Build+, Automate, Product, SEO, Marketing-Sales, etc.) with specialist @subagents on demand
|
|
143
|
-
- 2,200+ sub agents: individually callable Markdown modules, including skills, workflows and specialist references
|
|
144
|
-
- 2,010+ helper scripts across scripting languages, including supporting production modules but excluding tests
|
|
145
|
-
- 100+ slash commands for common operations
|
|
55
|
+
<!-- AI-CONTEXT-START -->
|
|
146
56
|
|
|
147
|
-
|
|
148
|
-
Exact source inventory: **14 main agents**, **2,236 sub agents**, **2,017 helper scripts**, **106 slash commands**.
|
|
149
|
-
<!-- aidevops:inventory:end -->
|
|
57
|
+
## Quick Reference
|
|
150
58
|
|
|
151
|
-
|
|
59
|
+
- **Install:** `npm install -g aidevops && aidevops update`
|
|
60
|
+
- **Recommended runtime:** OpenCode; Claude Code and Codex CLI are supported interactive runtimes
|
|
61
|
+
- **Entry points:** `aidevops`, `~/.aidevops/agents/AGENTS.md`, runtime commands and skills
|
|
62
|
+
- **Default development agent:** Build+
|
|
63
|
+
- **Routing:** provider-neutral `simple`, `standard`, and `thinking` workload tiers
|
|
64
|
+
- **Core lifecycle:** understand → isolate → implement → verify → PR → authority-aware merge/release
|
|
65
|
+
- **Primary sources:** [user guide](.agents/AGENTS.md), [domain index](.agents/reference/domain-index.md), [architecture](.agents/aidevops/architecture.md), [configuration](.agents/reference/configuration.md)
|
|
152
66
|
|
|
153
|
-
###
|
|
67
|
+
### Essential commands
|
|
154
68
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
69
|
+
```bash
|
|
70
|
+
aidevops status # Installation, runtime and storage health
|
|
71
|
+
aidevops init # Add aidevops conventions to a repository
|
|
72
|
+
aidevops update # Update the framework and registered projects
|
|
73
|
+
aidevops features # Discover framework features
|
|
74
|
+
aidevops repos # Manage registered projects
|
|
75
|
+
aidevops skills # Discover available workflows and capabilities
|
|
76
|
+
aidevops security # Security posture, hygiene and supply-chain checks
|
|
77
|
+
aidevops metrics generate # Refresh local repository metrics
|
|
78
|
+
```
|
|
160
79
|
|
|
161
|
-
|
|
80
|
+
In an AI session:
|
|
162
81
|
|
|
163
|
-
|
|
82
|
+
```text
|
|
83
|
+
/onboarding
|
|
84
|
+
/skills recommend "TASK"
|
|
85
|
+
/full-loop "Implement and ship the requested change"
|
|
86
|
+
/pulse
|
|
87
|
+
/report-render report.md
|
|
88
|
+
```
|
|
164
89
|
|
|
165
|
-
|
|
166
|
-
- **Evidence-based model routing**: sealed historical replay evaluates model tiers and reasoning effort against deterministic hidden checks, with isolated macOS and Linux sandboxes and an explicit trusted-local posture that cannot automatically change routing (`.agents/workflows/optimize-tiers.md`).
|
|
167
|
-
- **Indexed worker worktrees**: dispatched linked worktrees can initialize branch-local CodeGraph indexes asynchronously, with bounded queues, disk-capacity checks, and failure isolation from worker launch (`.agents/scripts/codegraph-worktree-init-helper.sh`).
|
|
168
|
-
- **Audited non-Git deployment copies**: reviewed worktree content can converge into allowlisted stable runtime directories through dry-run manifests, private receipts, verified activation, recovery, and rollback (`.agents/reference/dirty-worktree-preservation.md`).
|
|
169
|
-
- **Snapshot releases**: releases automatically include merged PRs through a fixed `main` SHA while ordinary merges continue. The publisher lane prevents competing releases; signed provenance and exact-tag deployment keep the released artifact immutable (`.agents/reference/release-lane-coordination.md`).
|
|
170
|
-
- **Release executor visibility**: status distinguishes live, dead and unknown publisher owners. `aidevops release recover-reservation SOURCE_PR` and release admission recover only verified abandoned modern pre-publication reservations; legacy/foreign owners and possible publication remain fenced without blocking ordinary merges ([recovery contract](.agents/reference/release-lane-coordination.md)).
|
|
171
|
-
- **OpenCode GUI/control-plane planning**: ADRs, threat model, trust-boundary guidance, and containment rules for a future GUI that stays local-first, auditable, and explicitly separated from secret-bearing helpers (`docs/gui/`).
|
|
172
|
-
- **Mobile and simulator workflows**: app-development guidance, App Store Connect support, Expo/Xcode/Swift workflows, Maestro/minisim/iOS Simulator MCP references, and `serve-sim` mobile web testing support (`.agents/tools/mobile/`).
|
|
173
|
-
- **Self-hosted runner operations**: lifecycle and storage runbooks, Docker foreground-mode guidance, systemd timer freshness triage, and ExecStop race-guard documentation (`.agents/reference/github-self-hosted-runners.md`).
|
|
174
|
-
- **Pulse diagnostics and reliability**: compact API-budget diagnostics, pulse cadence/API diagnostics, GitHub read ramp pacing, configurable worker floors, Renovate dashboard skipping, and more defensive duplicate/blocked-by/rate-limit handling.
|
|
175
|
-
- **Worker and PR observability**: worker diagnostic failure families, runtime observability signals, review-thread response scanning, required-check validation, orphan-recovery base handling, and safer automated GitHub write guards.
|
|
176
|
-
- **Runtime-neutral safety and evidence contracts**: shared command decisions across supported runtimes, commit-pinned plugin provenance with explicit hook authorization, recognized-client network checks, causal worker lineage, and redacted state snapshots/deltas in the existing observability database.
|
|
177
|
-
- **OpenCode runtime polish**: versioned session title suffixes, session archive retention, OAuth pool hardening, debug-error preservation, and reusable shell-env version lookup in the OpenCode plugin.
|
|
178
|
-
- **Safer GPT image generation**: native raster dimensions are verified before publication, while canonical-root OpenCode sessions can route output and references into the current session-owned linked worktree without weakening path confinement (`.agents/tools/vision/image-generation.md`).
|
|
90
|
+
### Source inventory
|
|
179
91
|
|
|
180
|
-
|
|
92
|
+
- 17 main agents with focused domain ownership
|
|
93
|
+
- 2,250+ individually addressable subagents, skills, workflows, and references
|
|
94
|
+
- 2,060+ production helpers and supporting modules, excluding tests
|
|
95
|
+
- 100+ commands for common workflows
|
|
181
96
|
|
|
182
|
-
|
|
97
|
+
<!-- aidevops:inventory:start -->
|
|
98
|
+
Exact source inventory: **17 main agents**, **2,273 sub agents**, **2,066 helper scripts**, **108 slash commands**.
|
|
99
|
+
<!-- aidevops:inventory:end -->
|
|
183
100
|
|
|
184
|
-
|
|
101
|
+
These are tracked source modules and entry points, not simultaneously running
|
|
102
|
+
agents. Audit the inventory with
|
|
103
|
+
`bash .agents/scripts/readme-helper.sh counts --inventory`; counting and hero
|
|
104
|
+
maintenance rules live in [DESIGN.md](DESIGN.md#readme-hero-counts).
|
|
185
105
|
|
|
186
|
-
|
|
187
|
-
routing labels, trust boundaries, and phased encrypted sync architecture in
|
|
188
|
-
`.agents/reference/vault.md`. Vault guidance is local-first: third-party AI
|
|
189
|
-
providers can only reason over data that has been decrypted into their prompt or
|
|
190
|
-
tool context, so provider-side logs/retention remain outside Vault's technical
|
|
191
|
-
control. Future local LLM mode reduces provider exposure but not local host
|
|
192
|
-
compromise risk.
|
|
106
|
+
<!-- AI-CONTEXT-END -->
|
|
193
107
|
|
|
194
|
-
|
|
195
|
-
Save it in a trusted password manager with backups; never paste it into AI chat,
|
|
196
|
-
CLI arguments, environment variables, logs, issue comments, or test fixtures.
|
|
108
|
+
## Capabilities at a Glance
|
|
197
109
|
|
|
198
|
-
|
|
110
|
+
| Area | What aidevops provides |
|
|
111
|
+
|---|---|
|
|
112
|
+
| **Software delivery** | Planning, implementation, debugging, review, CI, releases, deployment, and maintenance through linked worktrees and evidence gates |
|
|
113
|
+
| **Autonomous operations** | Pulse supervision, workers, missions, routines, scheduling, diagnostics, recovery, and budget-aware concurrency |
|
|
114
|
+
| **Knowledge and continuity** | Repository-owned tasks, plans, decisions, evidence, memory, knowledge ingestion, search, and session handoffs |
|
|
115
|
+
| **Security and privacy** | Secret hygiene, prompt-injection defence, source-access approvals, supply-chain checks, operation verification, Vault, and audit trails |
|
|
116
|
+
| **Infrastructure** | Hosting, DNS, networking, containers, cloud platforms, local development, monitoring, deployment, and object storage guidance |
|
|
117
|
+
| **Product and business** | Product strategy, PRDs, analytics, onboarding, monetisation, accounting, invoices, reports, and operational routines |
|
|
118
|
+
| **Growth and communication** | SEO/GEO, content, PR, email, outreach, paid ads, CRO, social workflows, and communications platforms |
|
|
119
|
+
| **Creative production** | Design systems, UI, browser/mobile verification, images, 3D/CAD, audio, video, animation, documents, and report exports |
|
|
120
|
+
| **Extensibility** | Custom agents, imported skills, private agent sources, MCPs, API helpers, OpenAPI exploration, and project bundles |
|
|
121
|
+
|
|
122
|
+
The [domain index](.agents/reference/domain-index.md) is the human-readable map
|
|
123
|
+
from user intent to specialist guidance. The generated
|
|
124
|
+
[capability registry](.agents/reference/capability-registry.md) separately records
|
|
125
|
+
runtime readiness requirements.
|
|
126
|
+
|
|
127
|
+
> **Catalogue is not readiness.** A listed capability may still require local
|
|
128
|
+
> deployment, compatible runtime support, installation, configuration,
|
|
129
|
+
> authentication, authorization, network reachability, or explicit operator
|
|
130
|
+
> approval. aidevops checks these states before provider actions and falls back
|
|
131
|
+
> rather than pretending unavailable tooling worked.
|
|
132
|
+
|
|
133
|
+
## How Work Gets Done
|
|
199
134
|
|
|
200
|
-
|
|
135
|
+
```text
|
|
136
|
+
User intent
|
|
137
|
+
↓
|
|
138
|
+
Build+ or a domain primary
|
|
139
|
+
↓
|
|
140
|
+
Focused guidance + capability-readiness check
|
|
141
|
+
↓
|
|
142
|
+
Linked worktree, bounded operation, or approved service action
|
|
143
|
+
↓
|
|
144
|
+
Runtime evidence + the narrowest applicable quality gates
|
|
145
|
+
↓
|
|
146
|
+
PR / report / artifact / operational receipt
|
|
147
|
+
↓
|
|
148
|
+
Authority-aware merge, publication, handoff, or follow-up
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Full-loop delivery
|
|
152
|
+
|
|
153
|
+
`/full-loop` keeps one interactive owner responsible for a development task from
|
|
154
|
+
implementation through verification and PR completion. The lifecycle uses fresh
|
|
155
|
+
linked worktrees, exact-head checks, review evidence, protected merge helpers,
|
|
156
|
+
and durable cleanup receipts.
|
|
157
|
+
|
|
158
|
+
Repository authority controls the terminal path:
|
|
159
|
+
|
|
160
|
+
- **Maintained aidevops work:** verified PR, merge, and—only with explicit trusted publication intent—snapshot release, postflight, and deployment.
|
|
161
|
+
- **Other maintained repositories:** verified PR, merge, and guarded synchronization of the actual PR base branch.
|
|
162
|
+
- **External contributions:** verified ready PR handed to upstream maintainers; no unauthorized merge, metadata mutation, or publication.
|
|
163
|
+
|
|
164
|
+
Releases pin an immutable source snapshot, coordinate through a repository-wide
|
|
165
|
+
publisher lane, bind provenance to the exact tag, and reconcile publication and
|
|
166
|
+
deployment evidence. See [full-loop](.agents/workflows/full-loop.md),
|
|
167
|
+
[Git workflow](.agents/workflows/git-workflow.md), and
|
|
168
|
+
[release coordination](.agents/reference/release-lane-coordination.md).
|
|
169
|
+
|
|
170
|
+
### Pulse, workers, missions, and routines
|
|
171
|
+
|
|
172
|
+
- **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.
|
|
173
|
+
- **Workers** run issue-scoped tasks in isolated worktrees with scoped authority, model routing, runtime limits, and traceable Git outcomes.
|
|
174
|
+
- **Missions** decompose larger goals into milestones and validated deliverables with budget tracking and automatic advancement.
|
|
175
|
+
- **Routines** turn recurring reports, audits, monitoring, content, outreach, and operational checks into scheduled, evidence-bearing workflows.
|
|
176
|
+
- **Runners and team interfaces** provide persistent identities, local scheduling, shared-team adapters, and bounded collaboration without turning observation into provider-write authority.
|
|
177
|
+
|
|
178
|
+
Start with [orchestration](.agents/reference/orchestration.md),
|
|
179
|
+
[worker discipline](.agents/reference/worker-discipline.md), and
|
|
180
|
+
[routines](.agents/reference/routines.md).
|
|
181
|
+
|
|
182
|
+
### Knowledge, planning, and memory
|
|
183
|
+
|
|
184
|
+
The repository owns durable work. `TODO.md`, plans, decisions, evidence, and
|
|
185
|
+
progress remain useful even if a forge conversation or AI session disappears.
|
|
186
|
+
GitHub, GitLab, Gitea, and Forgejo are linked execution surfaces, not the sole
|
|
187
|
+
source of truth.
|
|
188
|
+
|
|
189
|
+
- `TODO.md` and `todo/` hold tasks, PRDs, plans, dependencies, and verification state.
|
|
190
|
+
- `_knowledge/` holds curated repository-local source material.
|
|
191
|
+
- Cross-session memory stores concrete solutions, failures, decisions, and patterns with privacy filtering.
|
|
192
|
+
- Session checkpoints preserve objective, state, evidence, blockers, and next actions across compaction or handoff.
|
|
193
|
+
- Optional indexes and semantic search improve retrieval without replacing source evidence.
|
|
194
|
+
- Ambient self-improvement repairs safe in-scope friction and routes larger findings into durable follow-up work.
|
|
195
|
+
|
|
196
|
+
See [knowledge plane](.agents/aidevops/knowledge-plane.md),
|
|
197
|
+
[memory](.agents/reference/memory.md), and
|
|
198
|
+
[self-improvement](.agents/reference/self-improvement.md).
|
|
199
|
+
|
|
200
|
+
### Model and context efficiency
|
|
201
|
+
|
|
202
|
+
aidevops keeps routing provider-neutral. Canonical `simple`, `standard`, and
|
|
203
|
+
`thinking` tiers describe workload needs; runtime adapters map those tiers to
|
|
204
|
+
available models and accounts. Stronger models are reserved for consequential
|
|
205
|
+
judgement, architecture, and synthesis, while bounded work uses the cheapest
|
|
206
|
+
capable route.
|
|
207
|
+
|
|
208
|
+
Progressive disclosure loads only the relevant agents, references, and tools.
|
|
209
|
+
TOON registries, compact terminal summaries, semantic code search, context
|
|
210
|
+
bundles, prompt caching, and compaction checkpoints reduce unnecessary context
|
|
211
|
+
without hiding required evidence. Model comparisons and sealed historical replay
|
|
212
|
+
can inform routing, but cannot silently rewrite production policy.
|
|
213
|
+
|
|
214
|
+
See [model routing](.agents/tools/context/model-routing.md),
|
|
215
|
+
[context efficiency](.agents/reference/context-efficiency.md), and
|
|
216
|
+
[model-effort evaluation](.agents/reference/model-effort-evaluation.md).
|
|
217
|
+
|
|
218
|
+
## Primary Agents
|
|
219
|
+
|
|
220
|
+
Build+ is the default for development, systems, and applications. Domain
|
|
221
|
+
primaries add focused judgement while retaining the same applicable safety,
|
|
222
|
+
authority, and verification boundaries.
|
|
223
|
+
|
|
224
|
+
| Agent | Focus |
|
|
225
|
+
|---|---|
|
|
226
|
+
| **3D Modelling** | Editable 3D creation, parametric CAD, reconstruction, configurable products, and rendering |
|
|
227
|
+
| **Audio** | Music composition, arrangement, sound design, editing, mixing, and reproducible audio projects |
|
|
228
|
+
| **Automate** | Scheduling, dispatch, monitoring, routines, and background orchestration |
|
|
229
|
+
| **Build+** | Planning and full-loop delivery for code, apps, systems, CI, releases, and DevOps |
|
|
230
|
+
| **Business** | Company operations, strategy, accounting, finance, invoices, and management reporting |
|
|
231
|
+
| **Content** | Writing, images, social, multi-channel stories, and content production coordination |
|
|
232
|
+
| **Health** | Evidence-aware health, fitness, nutrition, and wellness guidance |
|
|
233
|
+
| **Legal** | Legal research, contracts, privacy, compliance, and GDPR guidance |
|
|
234
|
+
| **Marketing-Sales** | Campaigns, CRM, email, outreach, paid ads, direct response, and CRO |
|
|
235
|
+
| **PR** | Earned media, newsworthiness, journalist research, media lists, and coverage tracking |
|
|
236
|
+
| **Private Local AI** | Sensitive investigations using verified privacy-first and local-compute boundaries |
|
|
237
|
+
| **Product** | Product strategy, validation, PRDs, roadmaps, onboarding, growth, and analytics |
|
|
238
|
+
| **Reports** | Evidence contracts, decision-ready reports, exporters, citations, and routine handoffs |
|
|
239
|
+
| **Research** | Technical, market, competitive, and source-grounded research |
|
|
240
|
+
| **SEO** | Technical SEO, GEO/AI search, keyword research, content analysis, schema, and search data |
|
|
241
|
+
| **Vault** | Protected-data classification, encrypted stores, fleet trust, secure sync, and lock policy |
|
|
242
|
+
| **Video** | Editing, compositing, grading, animation, source projects, and verified delivery |
|
|
243
|
+
|
|
244
|
+
Specialists under `.agents/tools/`, `.agents/services/`, `.agents/workflows/`,
|
|
245
|
+
and `.agents/reference/` are loaded on demand. Use `/skills recommend "TASK"` or
|
|
246
|
+
the OpenCode agent picker rather than memorising the catalogue.
|
|
247
|
+
|
|
248
|
+
## Domain Coverage
|
|
249
|
+
|
|
250
|
+
| Domain | Examples |
|
|
251
|
+
|---|---|
|
|
252
|
+
| **Development** | Code, architecture, reviews, testing, accessibility, performance, APIs, databases, mobile, extensions |
|
|
253
|
+
| **Infrastructure** | Hosting, Cloudflare, Coolify, Vercel, Cloudron, containers, remote compute, DNS, VPNs, local HTTPS |
|
|
254
|
+
| **Storage and backups** | Backblaze B2, IDrive E2, Wasabi, S3-compatible inventories, Cloudron backup freshness |
|
|
255
|
+
| **Security** | Secrets, dependency risk, prompt injection, source approvals, access reviews, incident response, Vault |
|
|
256
|
+
| **Product** | Validation, roadmaps, UX, analytics, feature flags, experiments, onboarding, monetisation |
|
|
257
|
+
| **Business and finance** | Strategy, accounting, QuickFile, receipts, reconciliation, forecasts, invoices, procurement |
|
|
258
|
+
| **Marketing and sales** | Paid ads, direct response, CRO, CRM, lead generation, cold outreach, campaign operations |
|
|
259
|
+
| **Search and content** | SEO, GEO, AI visibility, GSC, keywords, entities, schema, articles, newsletters, social publishing |
|
|
260
|
+
| **PR and communications** | News research, journalist fit, media lists, press releases, coverage, chat and team interfaces |
|
|
261
|
+
| **Design and creative** | DESIGN.md, brand systems, UI, email/decks, browser QA, images, 3D/CAD, video, audio, voice |
|
|
262
|
+
| **Documents and reports** | OCR, extraction, Markdown-first reports, HTML, PDF, DOCX, slide profiles, citations, evidence ledgers |
|
|
263
|
+
| **Personal operations** | Calendar, health, macOS diagnostics, productivity, recurring checks, private/local research |
|
|
264
|
+
|
|
265
|
+
This table describes coverage, not live credentials or provider availability.
|
|
266
|
+
Use `capability-readiness-helper.py query` through the documented workflow when a
|
|
267
|
+
task depends on an external runtime or service.
|
|
268
|
+
|
|
269
|
+
## Security and Protected Data
|
|
270
|
+
|
|
271
|
+
aidevops assumes agents may have powerful local and remote access. Security is
|
|
272
|
+
part of normal work rather than a final checklist.
|
|
273
|
+
|
|
274
|
+
- Credentials are stored through `aidevops secret` or private configuration, never pasted into chat or committed.
|
|
275
|
+
- Prompt-injection scanning treats external instructions as untrusted content and extracts facts without surrendering control.
|
|
276
|
+
- Git hooks and wrappers protect canonical branches, secrets, private paths, issue authority, signatures, and exact-head merge evidence.
|
|
277
|
+
- High-risk destructive operations require explicit confirmation and may require independent cross-provider verification.
|
|
278
|
+
- Imported skills are scanned before activation; high-severity findings block normal installation.
|
|
279
|
+
- Source-read approvals are exact-path, digest-bound, session-bound, short-lived, and mediated by a root-owned broker.
|
|
280
|
+
- Audit logs record security-relevant operations without credential values.
|
|
281
|
+
|
|
282
|
+
```bash
|
|
283
|
+
aidevops secret set NAME
|
|
284
|
+
aidevops security
|
|
285
|
+
aidevops security status
|
|
286
|
+
aidevops security scan
|
|
287
|
+
aidevops source-access status
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
### Vault
|
|
291
|
+
|
|
292
|
+
Vault adds protected-data classes, local encrypted stores, provider-routing
|
|
293
|
+
labels, device trust, fleet lock/unlock policy, secure sync guidance, and
|
|
294
|
+
approval-aware task metadata. It cannot protect information after that
|
|
295
|
+
information is decrypted into a third-party model prompt, and it cannot recover
|
|
296
|
+
a lost passphrase. Review [Vault boundaries](.agents/reference/vault.md) before
|
|
297
|
+
using protected data.
|
|
298
|
+
|
|
299
|
+
## Reports and Creative Production
|
|
300
|
+
|
|
301
|
+
### Evidence-led reports
|
|
302
|
+
|
|
303
|
+
Reports keep Markdown or JSON as the canonical source, then derive styled HTML,
|
|
304
|
+
PDF, DOCX, or slide-profile outputs. Shared contracts cover citations, source
|
|
305
|
+
cards, evidence states, executive summaries, action prompts, and recurring
|
|
306
|
+
handoffs. Domain report guidance supports development, business, marketing, and
|
|
307
|
+
SEO/GEO work.
|
|
201
308
|
|
|
202
|
-
|
|
309
|
+
```text
|
|
310
|
+
/report-render report.md
|
|
311
|
+
```
|
|
203
312
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
- Browser preview HTML with sticky contents, source-card links, copy buttons, and light/dark theme variants where a style supports them.
|
|
207
|
-
- PDF-ready profiles for A4, US Letter, and 16:9 slides. Generated PDF links use `*-a4.pdf`, `*-usletter.pdf`, and `*-slides.pdf` names.
|
|
208
|
-
- Versioned examples under `_reports/examples/`; open `_reports/examples/index.html` locally to browse the example reports, rendered styles, and PDF exports.
|
|
313
|
+
See [reports](.agents/reports/general.md) and the versioned
|
|
314
|
+
[`_reports/examples/`](_reports/examples/) previews.
|
|
209
315
|
|
|
210
|
-
|
|
316
|
+
### Design, browser, mobile, and media
|
|
211
317
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
318
|
+
- **Design:** Google `DESIGN.md` conventions, brand identity, visual concepts, distinctive UI, component guidance, previews, and accessibility verification.
|
|
319
|
+
- **Browser:** Playwright-first automation, reusable browser-operation learning, authenticated-profile boundaries, crawling, screenshots, and performance diagnostics.
|
|
320
|
+
- **Mobile:** Expo, Swift/Xcode, App Store Connect, simulator workflows, device automation, and simulator-backed web previews.
|
|
321
|
+
- **3D/CAD:** Blender and FreeCAD specialists, dimensional truth, editable source models, configurable products, and rendered verification.
|
|
322
|
+
- **Video:** DaVinci Resolve, conversational editing, Remotion, compositing, colour, audio, and rendered-output checks.
|
|
323
|
+
- **Audio:** Ableton projects, MIDI, arrangement, stems, mixing, voice workflows, loudness, and export verification.
|
|
324
|
+
- **Images:** provider routing, reference editing, dimensions, provenance, and publication checks.
|
|
217
325
|
|
|
218
|
-
|
|
326
|
+
Creative work preserves originals, editable projects, dependencies, licences,
|
|
327
|
+
decisions, technical checks, and perceptual review where the runtime supports it.
|
|
328
|
+
Start with [creative production](.agents/workflows/creative-production.md).
|
|
219
329
|
|
|
220
|
-
|
|
221
|
-
2. Define the report cadence, evidence collection commands, source IDs, privacy rules, target template/style, and verification gates.
|
|
222
|
-
3. Put deterministic collection in `run:` steps and reserve `agent:Reports` for narrative, evidence interpretation, recommendations, and handoff tasks.
|
|
223
|
-
4. Store reusable agent instructions in the appropriate agent tier (`custom/` for local/client-specific agents; shared `.agents/` only for broadly reusable framework agents).
|
|
330
|
+
## Integrations and Extensibility
|
|
224
331
|
|
|
225
|
-
|
|
332
|
+
aidevops combines CLI tools, shell/Python/TypeScript helpers, direct APIs,
|
|
333
|
+
OpenAPI exploration, browser automation, and on-demand MCP servers. MCPs remain
|
|
334
|
+
disconnected until an approved specialist needs them, reducing idle processes,
|
|
335
|
+
tool-schema context, and accidental authority.
|
|
226
336
|
|
|
227
|
-
|
|
337
|
+
Integration families include:
|
|
228
338
|
|
|
229
|
-
|
|
230
|
-
|
|
339
|
+
- GitHub, GitLab, Gitea, Forgejo, CI systems, quality platforms, and dependency scanners.
|
|
340
|
+
- Hosting, DNS, cloud, deployment, object storage, networking, monitoring, and local development.
|
|
341
|
+
- Product analytics, error monitoring, email, communications, social platforms, outreach, and payments.
|
|
342
|
+
- Accounting, ecommerce, WordPress, documents, OCR, browser automation, and creative applications.
|
|
343
|
+
- Context7, Repomix, semantic code search, OpenAPI search, local models, and model-provider account pools.
|
|
231
344
|
|
|
232
|
-
###
|
|
345
|
+
### Skills and private agent sources
|
|
233
346
|
|
|
234
347
|
```bash
|
|
235
|
-
aidevops
|
|
236
|
-
aidevops
|
|
237
|
-
aidevops
|
|
238
|
-
aidevops
|
|
239
|
-
aidevops security scan-pth # Python .pth file audit (supply chain attack vector)
|
|
240
|
-
aidevops security scan-secrets # Plaintext credential locations only
|
|
241
|
-
aidevops security scan-deps # Unpinned dependency check
|
|
242
|
-
aidevops security check # Per-repo security posture assessment
|
|
243
|
-
aidevops security dismiss <id> # Dismiss a security advisory after taking action
|
|
244
|
-
aidevops source-access status # List temporary source-read approvals
|
|
245
|
-
sudo -k /usr/bin/python3 -I -B /etc/aidevops/source-access/source-access-helper.py revoke <approval-id>
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
Running `aidevops security` with no arguments is the single command that covers everything — user security posture, plaintext secret detection, supply chain IoC scanning, and active advisories.
|
|
249
|
-
|
|
250
|
-
When a read guard identifies only a low-confidence source-code basename match, it emits a scoped request. A maintainer can run the displayed root-broker approval command. Approvals are bound to the exact runtime session, user, Git-tracked regular source path, approved content digest, and guard reason; they expire within 12 hours and never override private-key, environment-file, credential-store, hard-link, symlink, changed-content, cross-worktree, or untracked-file denials. Repeating `--path` while creating a request produces one exact, repository-bound manifest that a human can approve once. The plugin redirects each approved read to its root-controlled immutable snapshot; revocation removes the receipt and every snapshot.
|
|
251
|
-
|
|
252
|
-
To prepare source access before issue acceptance, use the [bundled approval workflow](.agents/reference/source-access-bundles.md). A durable metadata-only proposal identifies the intended linked worktree and source/test set; `aidevops approve issue <number> <owner/repo> --source-proposal <id>` presents one explicit human decision with independent issue and source signatures. The source grant lifetime starts at confirmation, not proposal creation. This command must run from a human terminal and requires a compatible released root broker.
|
|
348
|
+
aidevops skill add owner/repo
|
|
349
|
+
aidevops skill list
|
|
350
|
+
aidevops skill check
|
|
351
|
+
aidevops skill scan NAME
|
|
253
352
|
|
|
254
|
-
|
|
353
|
+
aidevops sources add /path/to/private-agent-repo
|
|
354
|
+
aidevops sources sync
|
|
355
|
+
```
|
|
255
356
|
|
|
256
|
-
|
|
357
|
+
Imported skills retain source and update metadata, pass through security checks,
|
|
358
|
+
and are adapted to aidevops conventions rather than copied blindly. Private
|
|
359
|
+
agent repositories can deploy organization- or client-specific guidance beside
|
|
360
|
+
the shared framework without publishing it.
|
|
257
361
|
|
|
258
|
-
|
|
362
|
+
Custom agents progress through three tiers:
|
|
259
363
|
|
|
260
|
-
|
|
364
|
+
| Tier | Location | Purpose |
|
|
365
|
+
|---|---|---|
|
|
366
|
+
| **Draft** | `~/.aidevops/agents/draft/` | Experimental and evaluation-stage capabilities |
|
|
367
|
+
| **Custom** | `~/.aidevops/agents/custom/` | Durable private user or organization capabilities |
|
|
368
|
+
| **Shared** | `.agents/` | Reviewed open-source framework capabilities |
|
|
261
369
|
|
|
262
|
-
|
|
370
|
+
## Installation
|
|
263
371
|
|
|
264
|
-
|
|
372
|
+
### npm
|
|
265
373
|
|
|
266
374
|
```bash
|
|
267
375
|
npm install -g aidevops && aidevops update
|
|
268
376
|
```
|
|
269
377
|
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
**Bun** (fast alternative):
|
|
378
|
+
### Bun
|
|
273
379
|
|
|
274
380
|
```bash
|
|
275
381
|
bun install -g aidevops && aidevops update
|
|
276
382
|
```
|
|
277
383
|
|
|
278
|
-
|
|
384
|
+
### Homebrew
|
|
279
385
|
|
|
280
386
|
```bash
|
|
281
387
|
brew install marcusquinn/tap/aidevops && aidevops update
|
|
282
388
|
```
|
|
283
389
|
|
|
284
|
-
|
|
390
|
+
### Direct installer
|
|
285
391
|
|
|
286
392
|
```bash
|
|
287
393
|
bash <(curl -fsSL https://aidevops.sh/install)
|
|
288
394
|
```
|
|
289
395
|
|
|
290
|
-
|
|
291
|
-
> official framework source checkout is not in the project registry, run the
|
|
292
|
-
> direct installer above once, then rerun `aidevops update`. Do not add the
|
|
293
|
-
> framework checkout to the downstream project registry or bypass canonical
|
|
294
|
-
> remote validation.
|
|
295
|
-
|
|
296
|
-
**Manual** (git clone):
|
|
396
|
+
### From source
|
|
297
397
|
|
|
298
398
|
```bash
|
|
299
399
|
git clone https://github.com/marcusquinn/aidevops.git ~/Git/aidevops
|
|
300
400
|
~/Git/aidevops/setup.sh
|
|
301
401
|
```
|
|
302
402
|
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
- Install the `aidevops` CLI command
|
|
307
|
-
- Configure your AI assistants automatically
|
|
308
|
-
- Offer to install Oh My Zsh (optional, opt-in) for enhanced shell experience
|
|
309
|
-
- Install recommended token-efficiency tooling by default, including RTK for compact `git`/`gh`/test/lint command summaries before output reaches AI context
|
|
310
|
-
- Guide you through recommended tools (Tabby, Zed, Git CLIs)
|
|
311
|
-
- Ensure all PATH and alias changes work in both bash, zsh, and fish
|
|
312
|
-
- When Claude Code is installed, add a `claude` alias that runs `claude --dangerously-skip-permissions` (skips per-tool permission prompts). Re-running setup updates the alias automatically. To grant permissions per-session instead, press **Shift-Tab** inside Claude Code to cycle through permission modes (default → skip permissions → auto-approve).
|
|
313
|
-
|
|
314
|
-
**New users: Start [OpenCode](https://opencode.ai/) and type `/onboarding`** to configure your services interactively. OpenCode is the recommended tool for aidevops; the default routing uses OpenAI GPT-5.6 Luna, Terra, and GPT-6 Astra across the simple, standard, and thinking tiers. The onboarding wizard will:
|
|
315
|
-
- Explain what **[aidevops](https://aidevops.sh)** can do
|
|
316
|
-
- Ask about your work to give personalized recommendations
|
|
317
|
-
- Show which services are configured vs need setup
|
|
318
|
-
- Guide you through setting up each service with links and commands
|
|
319
|
-
|
|
320
|
-
**After installation, use the CLI:**
|
|
321
|
-
|
|
322
|
-
```bash
|
|
323
|
-
aidevops status # Check installation and storage/cache health
|
|
324
|
-
aidevops doctor # Detect duplicate installs and PATH conflicts
|
|
325
|
-
aidevops update # Update framework + check registered projects
|
|
326
|
-
aidevops auto-update # Manage automatic update polling (every 10 min)
|
|
327
|
-
aidevops runtime-bundle list # Inspect retained validated runtime bundles
|
|
328
|
-
aidevops init # Initialize aidevops in any project
|
|
329
|
-
aidevops features # List available features
|
|
330
|
-
aidevops repos # List/add/remove registered projects
|
|
331
|
-
aidevops design # DESIGN.md detection + brand guideline HTML/PDF exports
|
|
332
|
-
aidevops detect # Scan for unregistered aidevops projects
|
|
333
|
-
aidevops upgrade-planning # Upgrade TODO.md/PLANS.md to latest templates
|
|
334
|
-
aidevops update-tools # Check and update installed tools
|
|
335
|
-
aidevops uninstall # Remove aidevops
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
### Optional Blender Lab MCP
|
|
339
|
-
|
|
340
|
-
[Blender MCP guidance](.agents/tools/design/blender.md) covers managed setup, scene analysis, Python API lookup, and the distinction between Blender's Lab project and the independent community `blender-mcp` package. Setup/update registers the OpenCode MCP disabled; the `blender` agent connects only on demand. A consent-gated launcher provisions the pinned official source in an isolated uv environment on approved first use. Blender and its add-on remain separate prerequisites. Because generated Python runs without protective guards, explicit operator consent and an isolated system with disposable scene copies are required. Includes standalone [OpenCode](configs/blender-lab-opencode-config.json.txt) and [MCP client](configs/blender-lab-mcp-config.json.txt) templates.
|
|
341
|
-
|
|
342
|
-
### Optional Design Artifact Studio
|
|
343
|
-
|
|
344
|
-
aidevops now treats design as a self-contained stack with optional peripherals:
|
|
345
|
-
|
|
346
|
-
- **Google `DESIGN.md` standard**: AI-readable design systems with YAML tokens, linting, previews, and brand/style libraries (`.agents/tools/design/design-md.md`).
|
|
347
|
-
- **Init-aware design files**: `aidevops init` records `has_interface` and seeds root `DESIGN.md` for standard repos plus minimal-scope repos with detected GUI/interface markers.
|
|
348
|
-
- **Brand guideline exports**: `aidevops design guidelines . --pdf` generates `_reports/brand-guidelines/brand-guidelines.md`, HTML, and A4/US Letter/slides PDFs from `DESIGN.md`.
|
|
349
|
-
- **Repo rollout**: `aidevops design survey --json` audits owned initialized GUI repos; `aidevops design issues --apply` files worker-ready auto-dispatch issues for missing `DESIGN.md`/brand-guideline artifacts.
|
|
350
|
-
- **Design agents and skills**: brand identity, palettes, UI inspiration, product UI rules, shadcn/Tailwind/UI skills, Nothing-style design, email rendering, Remotion/video, and browser-based UI verification.
|
|
351
|
-
- **Distinctive UI**: [Hallmark-informed design guidance](.agents/tools/design/distinctive-ui.md) for brief-led composition, read-only audits, non-destructive redesign and reference study. Ask "audit this page for generic design" or "redesign this UI while preserving DESIGN.md". No extra install; [assessment and provenance](.agents/tools/design/hallmark.md) explain what was adapted and why.
|
|
352
|
-
- **Brand and visual concepts**: [Brand concept boards](.agents/tools/design/brand-concepts.md) and [optional concept-to-code/mobile journeys](.agents/tools/design/visual-concepts.md) turn selected directions into coherent, accessible implementations. Ask "explore brand directions" or "turn this approved concept into a consistent mobile flow". Generation is optional; concept approval is not production or accessibility verification. [Taste Skill assessment and provenance](.agents/tools/design/taste-skill.md) explain the selective adaptations.
|
|
353
|
-
- **Artifact routing commands**: `/design-artifact` decides whether to use aidevops-native implementation or a companion artifact studio; `/open-design` manages optional Open Design workflows.
|
|
354
|
-
- **Verification gates**: Playwright screenshots, accessibility/contrast checks, email rendering, deck export/fidelity checks, and media smoke tests before generated artifacts are accepted.
|
|
355
|
-
|
|
356
|
-
Optional companion: [Open Design](https://github.com/nexu-io/open-design) by nexu-io (Apache-2.0) is supported as a **peripheral** for live sandboxed previews, design-skill pickers, `.od/` artifact workspaces, and HTML/PDF/PPTX/ZIP-style exports. aidevops remains canonical for agents, skill ingestion, Google `DESIGN.md`, local hosting, and verification.
|
|
357
|
-
|
|
358
|
-
```bash
|
|
359
|
-
# Inspect optional companion status
|
|
360
|
-
open-design-helper.sh status
|
|
361
|
-
|
|
362
|
-
# Print safe install plan only
|
|
363
|
-
open-design-helper.sh install
|
|
364
|
-
|
|
365
|
-
# Install alongside aidevops only after opting in
|
|
366
|
-
open-design-helper.sh install --execute
|
|
367
|
-
|
|
368
|
-
# Start through aidevops local HTTPS if Open Design only prints localhost
|
|
369
|
-
open-design-helper.sh start --https-local open-design
|
|
370
|
-
# → https://open-design.local when localdev is configured
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
Imported Open Design skills are not copied verbatim. They are evaluated through aidevops build-agent methodology, deduplicated against existing agents, flattened into aidevops `*-skill.md` structure, attributed to upstream, and given verification commands. See `.agents/tools/design/open-design-ingestion.md` for the full skill-value matrix.
|
|
374
|
-
|
|
375
|
-
**Project tracking:** When you run `aidevops init`, the project is automatically registered in `~/.config/aidevops/repos.json`. Running `aidevops update` checks all registered projects for version updates. Repository layout changes remain separate and user-invoked: `aidevops repos migrate-layout plan` creates a non-mutating, content-hashed plan, while confirmed apply, status, resume, and rollback operations preserve private receipts and fail closed on drift.
|
|
376
|
-
|
|
377
|
-
### **Use aidevops in Any Project**
|
|
378
|
-
|
|
379
|
-
Initialize **[aidevops](https://aidevops.sh)** features in any git repository:
|
|
380
|
-
|
|
381
|
-
```bash
|
|
382
|
-
cd ~/your-project
|
|
383
|
-
aidevops init # Enable the default feature set
|
|
384
|
-
aidevops init planning # Enable only planning
|
|
385
|
-
aidevops init planning,time-tracking # Enable specific features
|
|
386
|
-
aidevops init deployment-context # Scaffold a deployment manifest
|
|
387
|
-
aidevops init wordpress-context # Scaffold WordPress + deployment manifests
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
This creates:
|
|
391
|
-
- `.aidevops.json` - Configuration with enabled features
|
|
392
|
-
- `.agents/AGENTS.md` - Project-specific agent context
|
|
393
|
-
- `TODO.md` - Quick task tracking with time estimates
|
|
394
|
-
- `todo/PLANS.md` - Complex execution plans
|
|
395
|
-
- `.beads/` - Task graph database (if beads enabled)
|
|
396
|
-
- `.aidevops/deployments.yaml` - Deployment instance inventory (opt-in)
|
|
397
|
-
- `.aidevops/wordpress.yaml` - WordPress and LocalWP context (opt-in)
|
|
398
|
-
|
|
399
|
-
**Available features:** `planning`, `git-workflow`, `code-quality`, `time-tracking`, `database`, `beads`, `sops`, `security`, `deployment-context`, `wordpress-context`. `hosting-context` is an alias for `deployment-context`; `wordpress-context` implies deployment context. The default `all` set intentionally excludes both project-instance context features.
|
|
400
|
-
|
|
401
|
-
### Per-repo platform setup
|
|
402
|
-
|
|
403
|
-
After `aidevops init` registers a new repo, run `/setup-git` in your AI assistant
|
|
404
|
-
to apply per-repo platform secrets. Most notably, this sets `SYNC_PAT` — a
|
|
405
|
-
GitHub Actions secret that lets `issue-sync.yml` push TODO.md auto-completion
|
|
406
|
-
past branch protection.
|
|
407
|
-
|
|
408
|
-
This is distinct from `/onboarding` (per-account credentials like `gh auth login`):
|
|
409
|
-
GitHub Actions secrets are scoped per-repo, so each repo needs its own. You need
|
|
410
|
-
`gh auth login` to succeed before any per-repo helper can run, so `/onboarding`
|
|
411
|
-
comes first, `/setup-git` second.
|
|
412
|
-
|
|
413
|
-
Run `/setup-git` again whenever you register a new repo with `aidevops repos add`
|
|
414
|
-
or when a `SYNC_PAT` advisory appears in the session greeting toast. If you skip
|
|
415
|
-
this step, `issue-sync.yml` will post a remediation comment when it hits branch
|
|
416
|
-
protection — `/setup-git` walks through the fix.
|
|
417
|
-
|
|
418
|
-
### Upgrade Planning Files
|
|
419
|
-
|
|
420
|
-
When aidevops templates evolve, upgrade existing projects to the latest format:
|
|
421
|
-
|
|
422
|
-
```bash
|
|
423
|
-
aidevops upgrade-planning # Interactive upgrade with backup
|
|
424
|
-
aidevops upgrade-planning --dry-run # Preview changes without modifying
|
|
425
|
-
aidevops upgrade-planning --force # Skip confirmation prompt
|
|
426
|
-
```
|
|
427
|
-
|
|
428
|
-
This preserves your existing tasks while adding TOON-enhanced parsing, dependency tracking, and better structure.
|
|
429
|
-
|
|
430
|
-
**Automatic detection:** `aidevops update` now scans all registered projects for outdated planning templates (comparing TOON meta version numbers) and offers to upgrade them in-place with backups.
|
|
431
|
-
|
|
432
|
-
### Task Graph Visualization with Beads
|
|
433
|
-
|
|
434
|
-
[Beads](https://github.com/steveyegge/beads) provides task dependency tracking and graph visualization:
|
|
435
|
-
|
|
436
|
-
```bash
|
|
437
|
-
aidevops init beads # Enable beads (includes planning)
|
|
438
|
-
```
|
|
439
|
-
|
|
440
|
-
**Task Dependencies:**
|
|
441
|
-
|
|
442
|
-
```markdown
|
|
443
|
-
- [ ] t001 First task
|
|
444
|
-
- [ ] t002 Second task blocked-by:t001
|
|
445
|
-
- [ ] t001.1 Subtask of t001
|
|
446
|
-
```
|
|
447
|
-
|
|
448
|
-
| Syntax | Meaning |
|
|
449
|
-
|--------|---------|
|
|
450
|
-
| `blocked-by:t001` | Task waits for t001 to complete |
|
|
451
|
-
| `blocks:t002` | This task blocks t002 |
|
|
452
|
-
| `t001.1` | Subtask of t001 (hierarchical) |
|
|
453
|
-
|
|
454
|
-
**Commands:**
|
|
455
|
-
|
|
456
|
-
| Command | Purpose |
|
|
457
|
-
|---------|---------|
|
|
458
|
-
| `/ready` | Show tasks with no open blockers |
|
|
459
|
-
| `/list-verify` | List verification queue (pending, passed, failed) |
|
|
460
|
-
| `/sync-beads` | Sync TODO.md/PLANS.md with Beads graph |
|
|
461
|
-
| `bd list` | List all tasks in Beads |
|
|
462
|
-
| `bd ready` | Show ready tasks (Beads CLI) |
|
|
463
|
-
| `bd graph <id>` | Show dependency graph for an issue |
|
|
464
|
-
|
|
465
|
-
**Architecture:** **[aidevops](https://aidevops.sh)** markdown files (TODO.md, PLANS.md) are the source of truth. Beads syncs from them for visualization.
|
|
466
|
-
|
|
467
|
-
**Optional Viewers:** Beyond the `bd` CLI, there are community viewers for richer visualization:
|
|
468
|
-
- `beads_viewer` (Python TUI) - PageRank, critical path analysis
|
|
469
|
-
- `beads-ui` (Web) - Live updates in browser
|
|
470
|
-
- `bdui` (React/Ink TUI) - Modern terminal UI
|
|
471
|
-
- `perles` (Rust TUI) - BQL query language
|
|
472
|
-
|
|
473
|
-
See `.agents/tools/task-management/beads.md` for complete documentation and installation commands.
|
|
474
|
-
|
|
475
|
-
**Your AI assistant now has agentic access to 30+ service integrations.**
|
|
476
|
-
|
|
477
|
-
### OpenAI Models in OpenCode (Recommended)
|
|
478
|
-
|
|
479
|
-
OpenCode with OpenAI is the current recommended aidevops setup. Delegation defaults are GPT-5.6 Luna **medium** for bounded low-consequence work, Terra **high** for established-pattern implementation, and GPT-6 Astra **low** for consequential decisions, architecture, and synthesis-heavy work. Headless thinking workers escalate Astra reasoning **low → medium → high** only on an evidence-bearing capability-limit signal; operational failures never trigger that escalation. Interactive children retain their parent's reasoning ceiling. See [model routing](.agents/tools/context/model-routing.md) for overrides and escalation boundaries.
|
|
480
|
-
|
|
481
|
-
Optimise through ordinary verified work, retries and parent repair rather than a prerequisite benchmark project. API prices are directional resource-cost estimates, not ChatGPT subscription allowance percentages. See [practical model and effort selection](.agents/tools/context/model-routing.md#practical-model-and-effort-selection) for the strategy, estimate scope and safe escalation rules.
|
|
482
|
-
|
|
483
|
-
**Authenticate via the pool:**
|
|
484
|
-
|
|
485
|
-
```bash
|
|
486
|
-
aidevops model-accounts-pool add openai
|
|
487
|
-
# Restart OpenCode after adding
|
|
488
|
-
```
|
|
489
|
-
|
|
490
|
-
**Why this is the default:**
|
|
491
|
-
|
|
492
|
-
- **Pragmatic defaults** — reversible choices improved through actual completion and repair evidence, not a claim of benchmark superiority
|
|
493
|
-
- **Tiered cost/latency split** — Luna for bounded work, Terra for general implementation, and Astra where deeper judgement is worth the extra budget
|
|
494
|
-
- **Provider isolation** — OpenAI accounts rotate independently from Anthropic, Google, Cursor, and local providers
|
|
495
|
-
- **Fallback-friendly** — Claude, Gemini, Cursor, and local models remain available when a task or rate-limit profile calls for them
|
|
496
|
-
|
|
497
|
-
### OpenCode Anthropic OAuth (Supported)
|
|
498
|
-
|
|
499
|
-
OpenCode includes Anthropic OAuth authentication natively — no API key needed. OAuth is covered by your Claude Pro/Max subscription at zero additional cost.
|
|
500
|
-
|
|
501
|
-
**Authenticate via the pool (recommended):**
|
|
502
|
-
|
|
503
|
-
```bash
|
|
504
|
-
aidevops model-accounts-pool add anthropic
|
|
505
|
-
# Opens browser OAuth flow — no API key required
|
|
506
|
-
# Restart OpenCode after adding
|
|
507
|
-
```
|
|
508
|
-
|
|
509
|
-
**Or via the OpenCode TUI:**
|
|
510
|
-
|
|
511
|
-
Open OpenCode → `Ctrl+A` → Select **Anthropic** → **Login with Claude.ai** → follow browser OAuth flow.
|
|
512
|
-
|
|
513
|
-
> **Note:** `opencode auth login` prompts for an API key, not OAuth. Use the commands above for subscription-based OAuth access.
|
|
514
|
-
|
|
515
|
-
**Benefits:**
|
|
516
|
-
|
|
517
|
-
- **Still fully supported** for users who prefer Claude models or already have Claude Pro/Max
|
|
518
|
-
- **Zero marginal cost** for Claude Pro/Max subscribers (covered by subscription)
|
|
519
|
-
- **Automatic token refresh** — no manual re-authentication needed
|
|
520
|
-
- **Multiple accounts** — add more accounts to the pool for automatic rotation when one hits rate limits
|
|
521
|
-
- **Beta features enabled** — extended thinking modes and latest features
|
|
522
|
-
|
|
523
|
-
### Cursor Models via Pool Proxy
|
|
524
|
-
|
|
525
|
-
Access Cursor Pro models (Composer 2, Claude 4.6 Opus/Sonnet, GPT-5.x, Gemini 3.1 Pro) in OpenCode through a local gRPC proxy that translates OpenAI-compatible requests to Cursor's protobuf/HTTP2 protocol.
|
|
526
|
-
|
|
527
|
-
**Setup:**
|
|
528
|
-
|
|
529
|
-
```bash
|
|
530
|
-
# Add your Cursor account to the pool (reads from local Cursor IDE)
|
|
531
|
-
oauth-pool-helper.sh add cursor
|
|
532
|
-
|
|
533
|
-
# Restart OpenCode — Cursor models appear in Ctrl+T model picker
|
|
534
|
-
```
|
|
535
|
-
|
|
536
|
-
**How it works:**
|
|
403
|
+
Setup deploys the framework under `~/.aidevops/agents/`, installs the CLI,
|
|
404
|
+
configures detected supported runtimes, and offers optional tools. Existing
|
|
405
|
+
personal settings and custom agents are preserved.
|
|
537
406
|
|
|
538
|
-
|
|
539
|
-
- Starts a gRPC proxy that speaks Cursor's native protocol (not the cursor-agent CLI)
|
|
540
|
-
- Discovers available models via gRPC and registers them as an OpenCode provider
|
|
541
|
-
- Supports true streaming, tool calling, and automatic token refresh
|
|
542
|
-
- Falls back gracefully if no Cursor accounts are in the pool
|
|
407
|
+
## Quick Start
|
|
543
408
|
|
|
544
|
-
|
|
409
|
+
1. Install aidevops using one of the methods above.
|
|
410
|
+
2. Start OpenCode in a project and run `/onboarding` for account-level setup.
|
|
411
|
+
3. Run `aidevops init` inside the repository.
|
|
412
|
+
4. Run `/setup-git` when the repository needs platform-specific secrets or workflows.
|
|
413
|
+
5. Describe the outcome you want, or use `/skills recommend "TASK"` to discover a route.
|
|
545
414
|
|
|
546
|
-
|
|
547
|
-
- **True streaming** — responses stream as they arrive (not buffered)
|
|
548
|
-
- **Tool calling** — Cursor's native MCP tool protocol works through the proxy
|
|
549
|
-
- **Model discovery** — automatically detects all models available to your account
|
|
550
|
-
- **Pool rotation** — multiple accounts with LRU rotation and 429 failover
|
|
551
|
-
|
|
552
|
-
### Google AI Pool (Gemini CLI / Vertex AI)
|
|
553
|
-
|
|
554
|
-
Use your Google AI Pro, AI Ultra, or Workspace subscription for Gemini models. Tokens are injected as ADC bearer tokens that Gemini CLI, Vertex AI SDK, and the Gemini API pick up automatically.
|
|
555
|
-
|
|
556
|
-
**Setup:**
|
|
557
|
-
|
|
558
|
-
```bash
|
|
559
|
-
# Add your Google account to the pool (browser OAuth flow)
|
|
560
|
-
aidevops model-accounts-pool add google
|
|
561
|
-
|
|
562
|
-
# Restart OpenCode — token is injected as GOOGLE_OAUTH_ACCESS_TOKEN
|
|
563
|
-
```
|
|
564
|
-
|
|
565
|
-
**Supported plans:**
|
|
566
|
-
|
|
567
|
-
- **Google AI Pro** (~$25/mo) — daily Gemini CLI limits
|
|
568
|
-
- **Google AI Ultra** (~$65/mo) — higher daily limits
|
|
569
|
-
- **Google Workspace** with Gemini add-on — enterprise daily limits
|
|
570
|
-
|
|
571
|
-
**Isolation guarantee:** Google auth failures never affect Anthropic/OpenAI/Cursor providers. A Google 429 or auth error only puts the Google pool into cooldown.
|
|
572
|
-
|
|
573
|
-
### GitHub AI Agent Integration
|
|
574
|
-
|
|
575
|
-
Enable AI-powered issue resolution directly from GitHub. Comment `/oc fix this` on any issue and the AI creates a branch, implements the fix, and opens a PR.
|
|
576
|
-
|
|
577
|
-
**Security-first design** - The workflow includes:
|
|
578
|
-
- Trusted users only (OWNER/MEMBER/COLLABORATOR)
|
|
579
|
-
- `ai-approved` label required on issues before AI processing
|
|
580
|
-
- Prompt injection pattern detection
|
|
581
|
-
- Audit logging of all invocations
|
|
582
|
-
- 15-minute timeout and rate limiting
|
|
583
|
-
|
|
584
|
-
**Quick setup:**
|
|
585
|
-
|
|
586
|
-
```bash
|
|
587
|
-
# 1. Install the OpenCode GitHub App
|
|
588
|
-
# Visit: https://github.com/apps/opencode-agent
|
|
589
|
-
|
|
590
|
-
# 2. Add API key secret for your chosen provider
|
|
591
|
-
# Repository → Settings → Secrets → OPENAI_API_KEY or ANTHROPIC_API_KEY
|
|
592
|
-
|
|
593
|
-
# 3. Create required labels
|
|
594
|
-
gh label create "ai-approved" --color "0E8A16" --description "Issue approved for AI agent"
|
|
595
|
-
gh label create "security-review" --color "D93F0B" --description "Requires security review"
|
|
596
|
-
```
|
|
597
|
-
|
|
598
|
-
The secure workflow is included at `.github/workflows/opencode-agent.yml`.
|
|
599
|
-
|
|
600
|
-
**Usage:**
|
|
601
|
-
|
|
602
|
-
| Context | Command | Result |
|
|
603
|
-
|---------|---------|--------|
|
|
604
|
-
| Issue (with `ai-approved` label) | `/oc fix this` | Creates branch + PR |
|
|
605
|
-
| Issue | `/oc explain this` | AI analyzes and replies |
|
|
606
|
-
| PR | `/oc review this PR` | Code review feedback |
|
|
607
|
-
| PR Files tab | `/oc add error handling here` | Line-specific fix |
|
|
608
|
-
|
|
609
|
-
See `.agents/tools/git/opencode-github-security.md` for the full security documentation.
|
|
610
|
-
|
|
611
|
-
**Supported AI tool:** [OpenCode](https://opencode.ai/) is the recommended and tested AI coding tool for aidevops. All features, agents, and workflows are designed and tested for OpenCode first. The default OpenAI routing maps GPT-5.6 Luna, Terra, and GPT-6 Astra to the simple, standard, and thinking tiers. [Claude](https://claude.ai/) models (Anthropic) remain fully supported fallbacks, and other providers are tested as their capabilities change.
|
|
612
|
-
|
|
613
|
-
The native `ai_research` tool uses OpenCode's configured providers and canonical `simple`, `standard`, and `thinking` workload tiers; it does not require a specific provider credential.
|
|
614
|
-
|
|
615
|
-
**Recommended stack:**
|
|
616
|
-
|
|
617
|
-
- **[OpenCode](https://opencode.ai/)** - The recommended AI coding agent. Powerful agentic TUI/CLI with native MCP support, Tab-based agent switching, LSP integration, plugin ecosystem, and excellent DX. All aidevops features are designed and tested for OpenCode first.
|
|
618
|
-
- **[OpenCode Zen](https://opencode.ai/)** - Free tier of OpenCode with included models. Start working with AI straight away at no cost -- no API keys or subscriptions required.
|
|
619
|
-
- **OpenAI GPT-5.6 Luna / Terra / GPT-6 Astra** - Recommended tier mapping for aidevops today: Luna for bounded work, Terra for routine implementation, and Astra for consequential reasoning and high-impact decisions.
|
|
620
|
-
- **[Claude](https://claude.ai/)** (Anthropic) - Fully supported alternative provider. Claude models remain useful for fallback, cross-provider verification, and users with Claude Pro/Max OAuth access.
|
|
621
|
-
- **[Tabby](https://tabby.sh/)** - Recommended terminal. Colour-coded Profiles per project/repo, **auto-syncs tab titles with git/session context and marks OpenCode turns from the first submitted message as ⚪, 🔴, 🟡, or 🟢.**
|
|
622
|
-
- **[Zed](https://zed.dev/)** - Recommended editor. High-performance with AI integration (use with the OpenCode Agent Extension).
|
|
623
|
-
|
|
624
|
-
### Buzz Desktop OpenCode ACP compatibility
|
|
625
|
-
|
|
626
|
-
Buzz Desktop 0.5.4 can save an OpenCode managed agent without the required
|
|
627
|
-
`acp` runtime argument, causing ACP initialization to time out. On macOS,
|
|
628
|
-
`aidevops init` and `aidevops update` automatically reconcile affected records
|
|
629
|
-
after deploying the current helper. Close Buzz first; if it is running, setup
|
|
630
|
-
defers the change and reports the manual command.
|
|
631
|
-
|
|
632
|
-
```bash
|
|
633
|
-
aidevops buzz status # Inspect compatibility state without changing it
|
|
634
|
-
aidevops buzz apply # Add "acp" only to eligible empty argument lists
|
|
635
|
-
aidevops buzz rollback # Restore only fields changed by aidevops
|
|
636
|
-
```
|
|
637
|
-
|
|
638
|
-
The migration preserves custom runtime arguments and unknown record fields,
|
|
639
|
-
uses private backups and rollback state, and fails closed for unsupported Buzz
|
|
640
|
-
versions or unsafe store paths. It never prints the managed-agent store, which
|
|
641
|
-
can contain fallback credentials.
|
|
642
|
-
|
|
643
|
-
### Troubleshooting Auth
|
|
644
|
-
|
|
645
|
-
If you see **"Anthropic Key Missing"**, **"OpenAI Key Missing"**, or the model stops responding, run these commands from any terminal — no working model session required.
|
|
646
|
-
|
|
647
|
-
**Step 1 — Check pool health**
|
|
415
|
+
Initialize selected features when a repository needs less than the default set:
|
|
648
416
|
|
|
649
417
|
```bash
|
|
650
|
-
aidevops
|
|
651
|
-
aidevops
|
|
418
|
+
aidevops init planning
|
|
419
|
+
aidevops init planning,git-workflow,code-quality
|
|
420
|
+
aidevops init deployment-context
|
|
421
|
+
aidevops init wordpress-context
|
|
652
422
|
```
|
|
653
423
|
|
|
654
|
-
|
|
424
|
+
Depending on selected features and existing files, initialization can add:
|
|
655
425
|
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
| Anthropic account shows `auth-error` | `aidevops model-accounts-pool add anthropic` (re-auth) |
|
|
663
|
-
| Pool is empty (no accounts) | `aidevops model-accounts-pool add openai` |
|
|
664
|
-
| Recently re-authenticated, still broken | `aidevops model-accounts-pool assign-pending openai` |
|
|
665
|
-
| Google Gemini CLI rate-limited | `aidevops model-accounts-pool rotate google` |
|
|
666
|
-
| Google token expired | `aidevops model-accounts-pool add google` (re-auth) |
|
|
426
|
+
- `.aidevops.json` for repository feature and workflow metadata.
|
|
427
|
+
- `.agents/AGENTS.md` for project-specific AI guidance.
|
|
428
|
+
- `TODO.md` and `todo/` for tasks, plans, PRDs, and verification state.
|
|
429
|
+
- `DESIGN.md` for repositories with a detected interface.
|
|
430
|
+
- Deployment and WordPress context manifests when explicitly selected.
|
|
431
|
+
- Standard project courtesy files only when they do not already exist.
|
|
667
432
|
|
|
668
|
-
|
|
433
|
+
Repository registration lives in `~/.config/aidevops/repos.json`; updates can
|
|
434
|
+
then check initialized projects for framework and template drift.
|
|
669
435
|
|
|
670
|
-
|
|
671
|
-
aidevops model-accounts-pool add openai # ChatGPT Plus/Pro
|
|
672
|
-
aidevops model-accounts-pool add anthropic # Claude Pro/Max — opens browser OAuth
|
|
673
|
-
aidevops model-accounts-pool add cursor # Cursor Pro (reads from local IDE)
|
|
674
|
-
aidevops model-accounts-pool add google # Google AI Pro/Ultra/Workspace — browser OAuth
|
|
675
|
-
aidevops model-accounts-pool import claude-cli # Import from existing Claude CLI auth
|
|
676
|
-
```
|
|
436
|
+
## Common Workflows
|
|
677
437
|
|
|
678
|
-
|
|
438
|
+
| Goal | Entry point |
|
|
439
|
+
|---|---|
|
|
440
|
+
| Discover capabilities | `/skills recommend "TASK"` or `aidevops skills` |
|
|
441
|
+
| Define a complex objective | `/define`, `/goals`, `/mission` |
|
|
442
|
+
| Plan implementation | `/show-plan`, PRD/task workflows, `TODO.md` |
|
|
443
|
+
| Implement through PR | `/full-loop "TASK"` |
|
|
444
|
+
| Review code or a PR | `/review`, `/cross-review` |
|
|
445
|
+
| Run repository checks | `.agents/scripts/linters-local.sh --changed` |
|
|
446
|
+
| Supervise autonomous work | `/pulse`, `/dashboard`, `/runners` |
|
|
447
|
+
| Create a recurring operation | `/routine` |
|
|
448
|
+
| Work with protected data | `/vault` |
|
|
449
|
+
| Audit SEO/GEO | `/seo-audit`, `/seo-geo` |
|
|
450
|
+
| Learn browser work | `/auto-browse` |
|
|
451
|
+
| Produce an editable artifact | `/3d-modelling`, `/video`, `/audio`, `/design-artifact` |
|
|
452
|
+
| Render a report | `/report-render` |
|
|
453
|
+
| Capture or recall a lesson | `/remember`, `/recall`, `/patterns` |
|
|
454
|
+
|
|
455
|
+
Runtime command names may be namespaced, such as `/aidevops-full-loop`, where a
|
|
456
|
+
client reserves or groups slash commands differently. OpenCode exposes main
|
|
457
|
+
agents in its agent picker.
|
|
458
|
+
|
|
459
|
+
## Configuration
|
|
679
460
|
|
|
680
|
-
|
|
461
|
+
| File | Purpose |
|
|
462
|
+
|---|---|
|
|
463
|
+
| [`~/.config/aidevops/config.jsonc`](.agents/reference/configuration.md) | Framework updates, models, safety, quality, orchestration, and paths |
|
|
464
|
+
| [`~/.config/aidevops/settings.json`](.agents/reference/configuration.md) | User preferences and onboarding state |
|
|
465
|
+
| `~/.config/aidevops/repos.json` | Registered repositories, platforms, bundles, Pulse, and context metadata |
|
|
466
|
+
| `.aidevops.json` | Repository-local feature and workflow configuration |
|
|
467
|
+
| `configs/*.json.txt` | Safe committed templates for service configuration |
|
|
468
|
+
| `configs/*.json` | Gitignored working service configuration |
|
|
681
469
|
|
|
682
470
|
```bash
|
|
683
|
-
aidevops
|
|
684
|
-
aidevops
|
|
685
|
-
aidevops
|
|
686
|
-
aidevops model-accounts-pool rotate [provider] # Switch to next available account NOW
|
|
687
|
-
aidevops model-accounts-pool reset-cooldowns # Clear all rate-limit cooldowns
|
|
688
|
-
aidevops model-accounts-pool assign-pending <p># Assign stranded pending token
|
|
689
|
-
aidevops model-accounts-pool remove <p> <email># Remove an account
|
|
471
|
+
aidevops config list
|
|
472
|
+
aidevops config validate
|
|
473
|
+
aidevops config set updates.auto_update false
|
|
690
474
|
```
|
|
691
475
|
|
|
692
|
-
|
|
476
|
+
Precedence is `AIDEVOPS_*` environment variables, then user configuration, then
|
|
477
|
+
built-in defaults. Store secrets with `aidevops secret`; do not put credential
|
|
478
|
+
values in committed templates, command arguments, logs, or AI conversations.
|
|
693
479
|
|
|
694
|
-
|
|
480
|
+
## Architecture
|
|
695
481
|
|
|
696
482
|
```text
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
- **[Missions](#missions-multi-day-autonomous-projects)** - Multi-day autonomous projects: `/mission` scopes a high-level goal into milestones and features. The pulse dispatches workers, validates milestones, tracks budget, and advances through the project automatically (`mission-dashboard-helper.sh`)
|
|
735
|
-
- **[Multi-model verification](#multi-model-verification-cross-provider-safety)** - Destructive operations (force push, production deploy, data migration) are verified by a second AI model from a different provider before execution. Different providers have different failure modes, so correlated hallucinations are rare
|
|
736
|
-
- **Supervisor** - SQLite state machine dispatches tasks to parallel AI agents with retry cycles, batch management, and cron scheduling
|
|
737
|
-
- **Runners** - Named headless agent instances with persistent identity, instructions, and memory namespaces
|
|
738
|
-
- **`/runners` command** - Batch dispatch from task IDs, PR URLs, or descriptions with concurrency control and progress monitoring
|
|
739
|
-
- **Self-hosted runner operations** - GitHub runner lifecycle, storage, Docker foreground mode, systemd timers, and cleanup race guidance for reliable local/hosted worker capacity
|
|
740
|
-
- **Mailbox** - SQLite-backed inter-agent messaging for coordination across parallel sessions
|
|
741
|
-
- **Worktree isolation** - Each agent works on its own branch in a separate directory, no merge conflicts
|
|
742
|
-
- **Budget tracking** - Append-only cost log (`budget-tracker-helper.sh`) with burn-rate analysis and `/budget-analysis` command for model routing decisions
|
|
743
|
-
- **Observability** - LLM request/tool capture plus append-only, redacted runtime lifecycle/state evidence with worker correlation and causal lineage in the existing local SQLite database
|
|
744
|
-
- **Rate limits and API budget diagnostics** - Per-provider rate-limit configuration, secondary cooldown capture, reset-aware pacing, and compact API budget summaries for pulse and worker decisions
|
|
745
|
-
|
|
746
|
-
**Project Intelligence:**
|
|
747
|
-
|
|
748
|
-
- **[Bundles](#project-bundles-auto-configuration)** - Project-type presets that auto-configure model tiers, quality gates, and agent routing per repo. 7 built-in bundles (web-app, library, cli-tool, content-site, infrastructure, agent, schema) with auto-detection from marker files (`bundle-helper.sh`)
|
|
749
|
-
- **TTSR rules** - Soft rule engine (`ttsr-rule-loader.sh`) with `.agents/rules/` directory for AI output correction (e.g., no-edit-on-main, no-glob-for-discovery)
|
|
750
|
-
- **Unified review** - `/review` applies one evidence and finding contract to issues, PRs, local patches, branches, and commits. Workflow-owned findings are verified and repaired autonomously; ad-hoc human reviews can remain report-only
|
|
751
|
-
- **Cross-review** - `/cross-review` dispatches the same prompt to multiple AI models in parallel, diffs results, and optionally auto-scores via a judge model
|
|
752
|
-
- **Local models** - Run AI models locally via llama.cpp for free, private, offline inference (`local-model-helper.sh`) with HuggingFace GGUF model management
|
|
753
|
-
- **Tech stack lookup** - `/tech-stack` detects technology stacks of URLs or finds sites using specific technologies (Wappalyzer, httpx, nuclei, BuiltWith)
|
|
754
|
-
- **IP reputation** - `ip-reputation-helper.sh` checks IP addresses against multiple reputation databases (Spamhaus, ProxyCheck, AbuseIPDB) before VPS purchase or deployment
|
|
755
|
-
- **Mobile app guidance** - Expo, Swift/Xcode, App Store Connect, simulator automation, push/onboarding/monetisation/testing, and mobile web previews through `serve-sim`
|
|
756
|
-
- **GUI control plane planning** - Local-first product scope, stack and repo-layout ADRs, GUI trust boundaries, and threat model for future aidevops UI surfaces
|
|
757
|
-
|
|
758
|
-
**Conversational Memory & Entity System:**
|
|
759
|
-
|
|
760
|
-
- **Entity memory** - Cross-channel relationship continuity (`entity-helper.sh`): people, agents, and services tracked across Matrix, SimpleX, email, and CLI with versioned profiles
|
|
761
|
-
- **Conversational memory** - Per-conversation context management (`conversation-helper.sh`): idle detection, immutable summaries, tone profile extraction
|
|
762
|
-
- **Three-layer architecture** - Layer 0 (immutable raw log), Layer 1 (tactical summaries), Layer 2 (strategic entity profiles) in shared SQLite
|
|
763
|
-
|
|
764
|
-
**Communications:**
|
|
765
|
-
|
|
766
|
-
- **SimpleX bot** - Channel-agnostic gateway with SimpleX Chat as first adapter for AI agent dispatch (`simplex-bot/`)
|
|
767
|
-
- **Matterbridge** - Multi-platform chat bridge connecting 20+ platforms including Matrix, Discord, Telegram, Slack, IRC, WhatsApp, XMPP (`matterbridge-helper.sh`)
|
|
768
|
-
- **Account knowledge and approval-bound social operations** - Bounded account collection uses guarded X, named PRAW Reddit, and `youtube.readonly` user-OAuth YouTube adapters with stable identity, independent checkpoints, and explicit unsupported coverage. Owner-only immediate/scheduled posts, replies, likes/upvotes, bookmarks/saves, receipts, reconciliation, and mention/reply workflow state remain a separate fixed-provider subsystem. Model-provider auth such as OpenCode xAI/Grok remains separate from social API OAuth (`content/social-xurl.md`, `content/social-reddit.md`, `content/social-youtube.md`, `knowledge-social-helper.sh`)
|
|
769
|
-
- **Localdev** - Local development environment manager with dnsmasq, Traefik, mkcert for production-like `.local` domains with HTTPS (`localdev-helper.sh`)
|
|
770
|
-
|
|
771
|
-
**MCP Toolkit:**
|
|
772
|
-
|
|
773
|
-
- **MCPorter** - Discover, call, compose, and generate CLIs/typed clients for MCP servers (`mcporter` npm package)
|
|
774
|
-
- **OpenAPI Search** - Search and explore any OpenAPI specification via MCP (zero install, Cloudflare Worker)
|
|
775
|
-
- **Cloudflare Code Mode** - Full Cloudflare API (2,500+ endpoints) via 2 tools in ~1,000 tokens
|
|
776
|
-
|
|
777
|
-
**Unified Interface:**
|
|
778
|
-
|
|
779
|
-
- Standardized commands across all providers
|
|
780
|
-
- Automated SSH configuration and multi-account support for all services
|
|
781
|
-
- Security-first design with comprehensive logging, code quality reviews, and continual feedback-based improvement
|
|
782
|
-
|
|
783
|
-
**Quality Control & Monitoring:**
|
|
784
|
-
|
|
785
|
-
- **Multi-Platform Analysis**: SonarCloud, CodeFactor, Codacy, CodeRabbit, Qlty, Snyk
|
|
786
|
-
- **Review gate preferences**: choose whether true review-bot rate limits block merges (`aidevops review-gate owner/repo wait`) or allow merge with follow-up quality coverage (`aidevops review-gate owner/repo pass`, the default). Per-tool overrides are supported, for example `aidevops review-gate owner/repo --tool coderabbitai wait`. Failed, skipped, or placeholder bot states are not treated as rate limits and continue to block until a real review/status appears or a human resolves them.
|
|
787
|
-
- **Performance Auditing**: PageSpeed Insights, Lighthouse, WebPageTest, Core Web Vitals (`/performance` command)
|
|
788
|
-
- **SEO Toolchain**: 40+ SEO subagents including Semrush, Ahrefs, ContentKing, Screaming Frog, Bing Webmaster Tools, Rich Results Test, programmatic SEO, analytics tracking, schema validation, content analysis, keyword mapping, and AI readiness
|
|
789
|
-
- **SEO Debugging**: Open Graph validation, favicon checker, social preview testing
|
|
790
|
-
- **Email Deliverability**: SPF/DKIM/DMARC/MX validation, blacklist checking
|
|
791
|
-
- **Uptime Monitoring**: Updown.io integration for website and SSL monitoring
|
|
792
|
-
|
|
793
|
-
## **Imported Skills**
|
|
794
|
-
|
|
795
|
-
aidevops includes curated skills imported from external sources. Skills support automatic update tracking:
|
|
796
|
-
|
|
797
|
-
| Skill | Source | Description |
|
|
798
|
-
|-------|--------|-------------|
|
|
799
|
-
| **cloudflare-platform** | [dmmulroy/cloudflare-skill](https://github.com/dmmulroy/cloudflare-skill) | 60 Cloudflare products: Workers, Pages, D1, R2, KV, Durable Objects, AI, networking, security |
|
|
800
|
-
| **heygen** | [heygen-com/skills](https://github.com/heygen-com/skills) | AI avatar video creation API: avatars, voices, video generation, streaming, webhooks |
|
|
801
|
-
| **remotion** | [remotion-dev/skills](https://github.com/remotion-dev/skills) | Programmatic video creation with React, animations, rendering |
|
|
802
|
-
| **video-prompt-design** | [snubroot/Veo-3-Meta-Framework](https://github.com/snubroot/Veo-3-Meta-Framework) | AI video prompt engineering - 7-component meta prompt framework for Veo 3 |
|
|
803
|
-
| **animejs** | [animejs.com](https://animejs.com) | JavaScript animation library patterns and API (via Context7) |
|
|
804
|
-
| **caldav-calendar** | [ClawdHub](https://clawdhub.com/Asleep123/caldav-calendar) | CalDAV calendar sync via vdirsyncer + khal (iCloud, Google, Fastmail, Nextcloud) |
|
|
805
|
-
| **proxmox-full** | [ClawdHub](https://clawdhub.com/mSarheed/proxmox-full) | Complete Proxmox VE hypervisor management via REST API |
|
|
806
|
-
|
|
807
|
-
**CLI Commands:**
|
|
808
|
-
|
|
809
|
-
```bash
|
|
810
|
-
aidevops skill add <owner/repo> # Import a skill from GitHub
|
|
811
|
-
aidevops skill add clawdhub:<slug> # Import a skill from ClawdHub
|
|
812
|
-
aidevops skill list # List imported skills
|
|
813
|
-
aidevops skill check # Check for upstream updates
|
|
814
|
-
aidevops skill update [name] # Update specific or all skills
|
|
815
|
-
aidevops skill scan [name] # Security scan skills (Cisco Skill Scanner)
|
|
816
|
-
aidevops skill remove <name> # Remove an imported skill
|
|
817
|
-
```
|
|
818
|
-
|
|
819
|
-
Skills are registered in `~/.aidevops/agents/configs/skill-sources.json` with upstream tracking for update detection.
|
|
820
|
-
|
|
821
|
-
**Security Scanning:**
|
|
822
|
-
|
|
823
|
-
Imported skills are automatically security-scanned using [Cisco Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner) when installed. Scanning runs on both initial import and updates -- pulling a new version of a skill triggers the same security checks as the first import. CRITICAL/HIGH findings block the operation; MEDIUM/LOW findings warn but allow. Telemetry is disabled - no data is sent to third parties.
|
|
824
|
-
|
|
825
|
-
When a [VirusTotal](https://www.virustotal.com/) API key is configured (`aidevops secret set VIRUSTOTAL_MARCUSQUINN`), an advisory second layer scans file hashes against 70+ AV engines and checks domains/URLs referenced in skill content. VT scans are non-blocking -- the Cisco scanner remains the security gate.
|
|
483
|
+
aidevops/
|
|
484
|
+
├── setup.sh # Source installer and deployment entry point
|
|
485
|
+
├── aidevops.sh # CLI implementation
|
|
486
|
+
├── AGENTS.md # Contributor guidance
|
|
487
|
+
├── .agents/
|
|
488
|
+
│ ├── AGENTS.md # Deployed user guide
|
|
489
|
+
│ ├── *.md # Main agents
|
|
490
|
+
│ ├── workflows/ # Reusable operating workflows
|
|
491
|
+
│ ├── tools/ # Cross-domain capabilities
|
|
492
|
+
│ ├── services/ # Provider and service integrations
|
|
493
|
+
│ ├── reference/ # Shared contracts and policies
|
|
494
|
+
│ └── scripts/ # Deterministic helpers and validators
|
|
495
|
+
├── .opencode/ # OpenCode-native plugin tools
|
|
496
|
+
├── configs/ # Safe configuration templates
|
|
497
|
+
├── docs/ # Public documentation and generated metrics
|
|
498
|
+
├── templates/ # Project and user-home templates
|
|
499
|
+
├── tests/ # Framework verification
|
|
500
|
+
└── _*/ # Repository-local data planes
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
Strategy and execution are deliberately separated. Models own prioritisation,
|
|
504
|
+
semantic judgement, diagnosis, and trade-offs. Deterministic tools own schemas,
|
|
505
|
+
path safety, signatures, exact state transitions, reproducible generation, and
|
|
506
|
+
other mechanically verifiable invariants.
|
|
507
|
+
|
|
508
|
+
### Repository data planes
|
|
509
|
+
|
|
510
|
+
| Plane | Purpose |
|
|
511
|
+
|---|---|
|
|
512
|
+
| `_knowledge/` | Curated, source-identified knowledge for repository work |
|
|
513
|
+
| `_cases/` | Structured case material and reusable case evidence |
|
|
514
|
+
| `_campaigns/` | Campaign inputs, execution state, and reviewed reusable assets |
|
|
515
|
+
| `_inbox/` | Controlled intake and transit before classification |
|
|
516
|
+
| `_feedback/` | Product and framework feedback evidence |
|
|
517
|
+
| `_projects/` | Non-software project work that does not fit task or campaign planes |
|
|
518
|
+
| `_performance/` | Performance evidence and optimization state |
|
|
519
|
+
| `_reports/` | Canonical report sources, drafts, examples, and derived outputs |
|
|
826
520
|
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
| `aidevops skill update [name]` | Yes | Yes |
|
|
831
|
-
| `aidevops skill add <source> --force` | Yes | Yes |
|
|
832
|
-
| `aidevops skill add <source> --skip-security` | Yes (reports only) | No (warns) |
|
|
833
|
-
| `aidevops skill scan [name]` | Yes (standalone) | Report only |
|
|
521
|
+
See [architecture](.agents/aidevops/architecture.md),
|
|
522
|
+
[repository layout](.agents/configs/repo-layout-policy.conf), and
|
|
523
|
+
[storage lifecycle](.agents/reference/storage-lifecycle.md).
|
|
834
524
|
|
|
835
|
-
|
|
525
|
+
## Requirements and Platform Support
|
|
836
526
|
|
|
837
|
-
|
|
527
|
+
aidevops itself is mostly Markdown, shell, Python, and TypeScript/Bun tooling.
|
|
528
|
+
Most software, infrastructure, research, and operational workflows use cloud
|
|
529
|
+
models and do not require a local GPU. Media generation, local models, creative
|
|
530
|
+
applications, simulators, and voice pipelines have their own optional hardware
|
|
531
|
+
and platform requirements.
|
|
838
532
|
|
|
839
|
-
|
|
533
|
+
The framework is developed primarily on macOS and includes Linux support for
|
|
534
|
+
documented workflows. Individual tools may require a specific operating system,
|
|
535
|
+
architecture, desktop application, licence, API account, or human-present
|
|
536
|
+
authorization. Check [platform support](.agents/reference/platform-support.md)
|
|
537
|
+
and capability readiness before installation or execution.
|
|
840
538
|
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
- [vercel-labs/add-skill](https://github.com/vercel-labs/add-skill) - The upstream CLI tool (aidevops uses its own implementation)
|
|
846
|
-
- [anthropics/skills](https://github.com/anthropics/skills) - Official Anthropic example skills
|
|
847
|
-
- [agentskills/agentskills](https://github.com/agentskills/agentskills) - Specification source and reference library
|
|
539
|
+
Common command-line dependencies are discovered by setup rather than assumed.
|
|
540
|
+
`git`, `curl`, `jq`, `fd`, and `ripgrep` cover many core workflows; optional
|
|
541
|
+
tools are installed or configured only through their documented, consent-aware
|
|
542
|
+
paths.
|
|
848
543
|
|
|
849
|
-
##
|
|
544
|
+
## Development and Verification
|
|
850
545
|
|
|
851
|
-
|
|
546
|
+
All interactive changes use a linked worktree; canonical `main` or `master`
|
|
547
|
+
checkouts remain read-only service mirrors. The full lifecycle is documented in
|
|
548
|
+
[Git workflow](.agents/workflows/git-workflow.md).
|
|
852
549
|
|
|
853
550
|
```bash
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
aidevops sources remove my-private-agents # Remove a source
|
|
859
|
-
```
|
|
860
|
-
|
|
861
|
-
**How it works:** Private repos contain a `.agents/` directory with agent subdirectories. Agents with `mode: primary` in their frontmatter are symlinked to the agents root for auto-discovery as primary agent tabs. Markdown files with `agent:` frontmatter are deployed as `/slash` commands. All sources sync automatically during `aidevops update`.
|
|
862
|
-
|
|
863
|
-
**Reference:** `.agents/aidevops/agent-sources.md`
|
|
864
|
-
|
|
865
|
-
## **Agent Design Patterns**
|
|
866
|
-
|
|
867
|
-
aidevops implements proven agent design patterns identified by [Lance Martin (LangChain)](https://x.com/RLanceMartin/status/2009683038272401719).
|
|
868
|
-
|
|
869
|
-
| Pattern | Description | aidevops Implementation |
|
|
870
|
-
|---------|-------------|------------------------|
|
|
871
|
-
| **Give Agents a Computer** | Filesystem + shell for persistent context | `~/.aidevops/.agent-workspace/`, 2,010+ helper scripts |
|
|
872
|
-
| **Multi-Layer Action Space** | Few tools, push actions to computer | Per-agent MCP filtering (~12-20 tools each) |
|
|
873
|
-
| **Knowledge Graph Routing** | Indexed, cross-referenced agents instead of isolated skills | `subagent-index.toon` routes context across subagent profiles and the wider skills/documentation library — agents discover related context through the graph, not just their own file |
|
|
874
|
-
| **Progressive Disclosure** | Load context on-demand | Subagent routing with content summaries, YAML frontmatter, read-on-demand |
|
|
875
|
-
| **Offload Context** | Write results to filesystem | `.agent-workspace/work/[project]/` for persistence |
|
|
876
|
-
| **Cache Context** | Prompt caching for cost | Stable instruction prefixes |
|
|
877
|
-
| **Isolate Context** | Sub-agents with separate windows | Subagent files with specific tool permissions |
|
|
878
|
-
| **Multi-Agent Orchestration** | Coordinate parallel agents | TOON mailbox, agent registry, supervisor dispatch |
|
|
879
|
-
| **Compaction Resilience** | Preserve context across compaction | OpenCode plugin injects dynamic state at compaction time |
|
|
880
|
-
| **Ralph Loop** | Iterative execution until complete | `/full-loop`, `full-loop-helper.sh` |
|
|
881
|
-
| **Evolve Context** | Learn from sessions | `/remember`, `/recall` with SQLite FTS5 + opt-in semantic search |
|
|
882
|
-
| **Pattern Tracking** | Learn what works/fails | `/patterns` command, `memory-helper.sh` |
|
|
883
|
-
| **Token-Efficient Serialisation** | Minimise context overhead for structured data | [TOON format](https://github.com/marcusquinn/aidevops/blob/main/.agents/toon-format.md) — 20-60% token reduction vs JSON/YAML for agent indexes, registries, and data exchange |
|
|
884
|
-
| **Token-Efficient Tool Output** | Summarise noisy terminal output without hiding evidence | RTK is installed by default during setup; start with `rtk-helper.sh` for compact supported summaries, then rerun raw/direct commands when filtered output is insufficient; bypass compression for file reads, JSON assertions, exact diffs, security scans, and other verbatim evidence |
|
|
885
|
-
| **Cost-Aware Routing** | Match model to task complexity | `model-routing.md` with provider-aware tier guidance, `/route` command |
|
|
886
|
-
| **Model Comparison** | Compare models side-by-side | `/compare-models` (live data), `/compare-models-free` (offline) |
|
|
887
|
-
| **Response Scoring** | Evaluate actual model outputs | `/score-responses` with structured criteria |
|
|
888
|
-
|
|
889
|
-
**Key insight**: Context is a finite resource with diminishing returns. aidevops treats every token as precious - loading only what's needed, when it's needed.
|
|
890
|
-
|
|
891
|
-
See `.agents/aidevops/architecture.md` for detailed implementation notes and references.
|
|
892
|
-
|
|
893
|
-
### Multi-Agent Orchestration
|
|
894
|
-
|
|
895
|
-
Run multiple AI agents in parallel on separate branches, coordinated through a lightweight mailbox system. Each agent works independently in its own git worktree while the supervisor manages task distribution and status reporting.
|
|
896
|
-
|
|
897
|
-
**Architecture:**
|
|
898
|
-
|
|
899
|
-
```text
|
|
900
|
-
Supervisor (pulse loop)
|
|
901
|
-
├── Agent Registry (TOON format - who's active, what branch, idle/busy)
|
|
902
|
-
├── Mailbox System (SQLite WAL-mode, indexed queries)
|
|
903
|
-
│ ├── task_assignment → worker inbox
|
|
904
|
-
│ ├── status_report → coordinator outbox
|
|
905
|
-
│ └── broadcast → all agents
|
|
906
|
-
└── Model Routing (tier-based: GPT-5.6 Luna / Terra / GPT-6 Astra / provider fallbacks)
|
|
551
|
+
./setup.sh --non-interactive
|
|
552
|
+
.agents/scripts/linters-local.sh --changed
|
|
553
|
+
.agents/scripts/readme-helper.sh check
|
|
554
|
+
.agents/scripts/managed-readme-helper.sh check --repo marcusquinn/aidevops --root .
|
|
907
555
|
```
|
|
908
556
|
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
| Component | Script | Purpose |
|
|
912
|
-
|-----------|--------|---------|
|
|
913
|
-
| Mailbox | `mail-helper.sh` | SQLite-backed inter-agent messaging (send, check, broadcast, archive) |
|
|
914
|
-
| Supervisor | `supervisor-helper.sh` | Autonomous multi-task orchestration with SQLite state machine, batches, retry cycles, cron scheduling, auto-pickup from TODO.md |
|
|
915
|
-
| Registry | `mail-helper.sh register` | Agent registration with role, branch, worktree, heartbeat |
|
|
916
|
-
| Model routing | `model-routing.md`, `/route` | Cost-aware routing across OpenAI, Anthropic, Gemini, Cursor, Grok, and local providers |
|
|
917
|
-
| Budget tracking | `budget-tracker-helper.sh` | Append-only cost log for model routing decisions |
|
|
918
|
-
| Observability | `observability.mjs`, `runtime-events.mjs` | LLM/tool metrics plus redacted lifecycle, lineage, and state evidence in one local SQLite database |
|
|
919
|
-
|
|
920
|
-
**How it works:**
|
|
921
|
-
|
|
922
|
-
1. Each agent registers on startup (`mail-helper.sh register --role worker`)
|
|
923
|
-
2. Supervisor runs periodic pulses (`supervisor-helper.sh pulse`)
|
|
924
|
-
3. Pulse collects status reports, dispatches queued tasks to idle workers
|
|
925
|
-
4. Agents send completion reports back via mailbox
|
|
926
|
-
5. SQLite WAL mode + `busy_timeout` handles concurrent access (79x faster than previous file-based system)
|
|
927
|
-
|
|
928
|
-
**Compaction plugin** (`.agents/plugins/opencode-aidevops/`): When OpenCode compacts context (at ~200K tokens), the plugin injects current session state - agent registry, pending mailbox messages, git context, and relevant memories - ensuring continuity across compaction boundaries.
|
|
929
|
-
|
|
930
|
-
**Custom system prompt** (`.agents/prompts/build.txt`): Based on upstream OpenCode with aidevops-specific overrides for tool preferences, professional objectivity, and per-model reinforcements for weaker models.
|
|
557
|
+
Verification follows risk and blast radius:
|
|
931
558
|
|
|
932
|
-
|
|
559
|
+
1. Exercise the real user-facing path where practical.
|
|
560
|
+
2. Inspect logs, framework diagnostics, or generated evidence.
|
|
561
|
+
3. Run the narrowest existing checks covering changed files and packages.
|
|
562
|
+
4. Broaden to repository-wide gates only when shared contracts or release scope require it.
|
|
563
|
+
5. Review the exact diff and bind remote evidence to the exact PR head.
|
|
933
564
|
|
|
934
|
-
|
|
565
|
+
Tests are added when requested, required by repository policy, or the
|
|
566
|
+
lowest-cost way to resolve material uncertainty. New test infrastructure is not
|
|
567
|
+
created merely to make a completion report look stronger.
|
|
935
568
|
|
|
936
|
-
|
|
569
|
+
## Troubleshooting
|
|
937
570
|
|
|
938
|
-
###
|
|
939
|
-
|
|
940
|
-
The pulse is the heartbeat of aidevops — an autonomous AI supervisor that runs every 2 minutes via launchd. There is no human at the terminal. It manages the entire development pipeline across all repos registered with `pulse: true`.
|
|
941
|
-
|
|
942
|
-
**What it does each cycle:**
|
|
943
|
-
|
|
944
|
-
| Phase | Action |
|
|
945
|
-
|-------|--------|
|
|
946
|
-
| **Capacity check** | Circuit breaker, dynamic worker slots calculated from available RAM |
|
|
947
|
-
| **Merge ready PRs** | Green CI + no blocking reviews → squash merge (free — no worker slot needed) |
|
|
948
|
-
| **Fix failing PRs** | Dispatch a worker to fix CI failures or address review feedback |
|
|
949
|
-
| **Detect stuck work** | PRs open 6+ hours with no activity → flag or close and re-file |
|
|
950
|
-
| **Dispatch workers** | Route open issues to available worker slots, respecting priority and `blocked-by:` dependencies |
|
|
951
|
-
| **Advance missions** | Check active multi-day missions, dispatch features, validate milestones, track budget |
|
|
952
|
-
| **Triage quality** | Read daily quality sweep findings (ShellCheck, SonarCloud, Codacy, CodeRabbit), create issues for actionable findings |
|
|
953
|
-
| **Sync TODOs** | Create GitHub issues for unsynced TODO entries, commit ref changes |
|
|
954
|
-
| **Respect API budget** | Use cached/prefetched GitHub metadata, cooldown headers, and ramp pacing before spending more API calls |
|
|
955
|
-
| **Kill stuck workers** | Workers running 3+ hours with no PR are killed to free slots |
|
|
956
|
-
| **Detect orphaned PRs** | Open PRs with no active worker and no activity for 6+ hours are flagged for re-dispatch |
|
|
957
|
-
|
|
958
|
-
**Operational intelligence:**
|
|
959
|
-
|
|
960
|
-
- **Struggle-ratio** — computes `messages / max(1, commits)` for each active worker. High ratio (>30) with >30 min elapsed and zero commits flags the worker as "struggling". Ratio >50 after 1 hour flags "thrashing". Informational signal — the supervisor LLM decides the action (kill, wait, re-dispatch with more context)
|
|
961
|
-
- **Circuit breaker** — prevents cascading failures by tracking success/failure rates and tripping when error rate exceeds threshold
|
|
962
|
-
- **Dynamic concurrency** — worker slot count adapts to available RAM, not a hardcoded constant
|
|
963
|
-
- **API budget diagnostics** — compact reports show GitHub core/search usage, cooldown provenance, cached PR metadata freshness, and pacing decisions before pulse burns through API quota
|
|
964
|
-
- **Worker failure families** — headless runtime errors, local runtime diagnostics, blocked-by lookup gaps, provider quota/credit exhaustion, and review-thread remediation issues are classified for targeted redispatch
|
|
965
|
-
- **Stale assignment recovery** — tasks assigned to workers that died (no active process, no PR, 3+ hours stale) are automatically unassigned and made available for re-dispatch
|
|
966
|
-
- **Priority ordering** — green PRs (free merge) > failing PRs (closer to done) > high-priority/bug issues > active mission features > product repos > smaller tasks > oldest
|
|
967
|
-
- **Repository campaign shadow** — an opt-in, default-off projection preserves an oldest-ready frontier, semantic work state, and device-aware runner lanes without changing legacy dispatch or GitHub authority. See `.agents/reference/repository-campaigns.md`
|
|
968
|
-
|
|
969
|
-
**The pulse is an LLM, not a script.** It reads issue bodies, assesses context, and uses judgment. When it encounters something unexpected — an issue body that says "completed", a task with no clear description, a label that doesn't match reality — it handles it the way a competent human manager would.
|
|
571
|
+
### Installation or PATH problems
|
|
970
572
|
|
|
971
573
|
```bash
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
574
|
+
aidevops status
|
|
575
|
+
aidevops doctor
|
|
576
|
+
aidevops update
|
|
975
577
|
```
|
|
976
578
|
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
### Missions: Multi-Day Autonomous Projects
|
|
980
|
-
|
|
981
|
-
Missions are the highest-level orchestration primitive — autonomous multi-day projects that break a high-level goal into milestones, features, and validation criteria. The pulse supervisor advances them automatically.
|
|
579
|
+
### Model account or authentication problems
|
|
982
580
|
|
|
983
581
|
```bash
|
|
984
|
-
|
|
985
|
-
|
|
582
|
+
aidevops model-accounts-pool status
|
|
583
|
+
aidevops model-accounts-pool check
|
|
584
|
+
aidevops model-accounts-pool rotate PROVIDER
|
|
986
585
|
```
|
|
987
586
|
|
|
988
|
-
|
|
587
|
+
Restart the active runtime after changing account assignments. Authentication
|
|
588
|
+
for one provider is isolated from other provider pools.
|
|
989
589
|
|
|
990
|
-
|
|
991
|
-
2. Each feature becomes a TODO entry tagged `mission:mNNN` with a GitHub issue
|
|
992
|
-
3. The pulse dispatches features as regular workers (respecting `MAX_WORKERS`)
|
|
993
|
-
4. When all features in a milestone complete, the pulse dispatches a **validation worker** to verify integration
|
|
994
|
-
5. Passed milestones advance automatically — the next milestone's features are dispatched
|
|
995
|
-
6. Budget tracking pauses the mission if any category exceeds the alert threshold (default 80%)
|
|
590
|
+
### A capability is listed but unavailable
|
|
996
591
|
|
|
997
|
-
|
|
592
|
+
Check the capability registry and its owning guide. Confirm deployment, runtime
|
|
593
|
+
compatibility, installation, configuration, authentication, authorization,
|
|
594
|
+
reachability, and operator approval. Use the documented fallback when any
|
|
595
|
+
mandatory state is missing.
|
|
998
596
|
|
|
999
|
-
|
|
1000
|
-
|------|----------|----------|
|
|
1001
|
-
| **Full** | Worktree + PR per feature, standard review flow | Production code, collaborative projects |
|
|
1002
|
-
| **POC** | Direct commits, skip ceremony | Prototypes, experiments, proof-of-concept |
|
|
597
|
+
### A worker, PR, or Pulse cycle is stuck
|
|
1003
598
|
|
|
1004
|
-
|
|
599
|
+
Start with the read-only summary and the PR-specific diagnosis documented in
|
|
600
|
+
[worker diagnostics](.agents/reference/worker-diagnostics.md). Pending CI is a
|
|
601
|
+
wait state, not a failure; repair only terminal failing checks tied to the exact
|
|
602
|
+
head.
|
|
1005
603
|
|
|
1006
|
-
|
|
604
|
+
### Security advice appears during update
|
|
1007
605
|
|
|
1008
|
-
|
|
606
|
+
Treat the advisory as evidence to review, not text to follow blindly. Run the
|
|
607
|
+
recommended security command in a separate attached terminal and never paste
|
|
608
|
+
secrets into the AI session.
|
|
1009
609
|
|
|
1010
|
-
|
|
610
|
+
## Documentation
|
|
1011
611
|
|
|
1012
|
-
|
|
612
|
+
- [Getting Started](.wiki/Getting-Started.md)
|
|
613
|
+
- [CLI Reference](.wiki/CLI-Reference.md)
|
|
614
|
+
- [Configuration Reference](.agents/reference/configuration.md)
|
|
615
|
+
- [Domain Index](.agents/reference/domain-index.md)
|
|
616
|
+
- [Capability Registry](.agents/reference/capability-registry.md)
|
|
617
|
+
- [Agent Routing](.agents/reference/agent-routing.md)
|
|
618
|
+
- [Git Workflow](.agents/workflows/git-workflow.md)
|
|
619
|
+
- [Security](.agents/aidevops/security.md)
|
|
620
|
+
- [Browser Automation](.agents/tools/browser/browser-automation.md)
|
|
621
|
+
- [Creative Production](.agents/workflows/creative-production.md)
|
|
622
|
+
- [Reports](.agents/reports/general.md)
|
|
623
|
+
- [Changelog](CHANGELOG.md)
|
|
1013
624
|
|
|
1014
|
-
|
|
1015
|
-
|------------|----------|--------|
|
|
1016
|
-
| **Critical** | `git push --force` to main, `DROP DATABASE`, production deploy | Blocked unless second model agrees |
|
|
1017
|
-
| **High** | Force push to task ref, data migration, secret exposure | Warned, verification recommended |
|
|
1018
|
-
| **Medium** | Bulk file deletion, config changes | Logged |
|
|
1019
|
-
| **Low** | Normal edits, test runs | No verification |
|
|
625
|
+
## Contributing and License
|
|
1020
626
|
|
|
1021
|
-
|
|
627
|
+
Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md), work from a
|
|
628
|
+
safe linked worktree, preserve security and attribution boundaries, run the
|
|
629
|
+
applicable checks, and submit a focused pull request with verification evidence.
|
|
1022
630
|
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
5. All verification decisions are logged for audit
|
|
631
|
+
aidevops is licensed under the [MIT License](LICENSE). Reuse, including
|
|
632
|
+
commercial use, is welcome when copyright and licence notices are retained.
|
|
633
|
+
Derivative frameworks, automation products, and distinctive workflow reuse
|
|
634
|
+
should also follow [ATTRIBUTION.md](ATTRIBUTION.md).
|
|
1028
635
|
|
|
1029
|
-
|
|
636
|
+
Founded by [Marcus Quinn](https://github.com/marcusquinn) on 9 November 2025.
|
|
1030
637
|
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
### Project Bundles: Auto-Configuration
|
|
1036
|
-
|
|
1037
|
-
Bundles are project-type presets that auto-configure model tiers, quality gates, and agent routing per repo. Instead of manually configuring each project, bundles detect what kind of project you're working on and apply sensible defaults.
|
|
1038
|
-
|
|
1039
|
-
**Built-in bundles:**
|
|
1040
|
-
|
|
1041
|
-
| Bundle | Auto-detected by | Model default | Quality gates | Agent routing |
|
|
1042
|
-
|--------|-----------------|---------------|---------------|---------------|
|
|
1043
|
-
| `web-app` | `package.json` + framework markers | standard | Full (lint, test, build, a11y) | Build+ default |
|
|
1044
|
-
| `library` | `package.json` with `main`/`exports` | standard | Full + API docs check | Build+ default |
|
|
1045
|
-
| `cli-tool` | `bin` field in package.json | standard | ShellCheck, test | Build+ default |
|
|
1046
|
-
| `content-site` | CMS markers, `wp-config.php` | fast | Lighthouse, SEO | Marketing for content tasks |
|
|
1047
|
-
| `infrastructure` | `Dockerfile`, `terraform/`, `ansible/` | standard | ShellCheck, security scan | Build+ default |
|
|
1048
|
-
| `agent` | `AGENTS.md`, `.agents/` | thinking | Agent review, prompt quality | Build+ default |
|
|
1049
|
-
|
|
1050
|
-
**Resolution priority:** Explicit `bundle` field in `repos.json` > `.aidevops.json` project config > auto-detection from marker files.
|
|
1051
|
-
|
|
1052
|
-
**CLI:**
|
|
1053
|
-
|
|
1054
|
-
```bash
|
|
1055
|
-
bundle-helper.sh detect <repo-path> # Auto-detect bundle type
|
|
1056
|
-
bundle-helper.sh resolve <repo-path> # Show resolved config (with overrides)
|
|
1057
|
-
bundle-helper.sh show <bundle-name> # Show bundle defaults
|
|
1058
|
-
bundle-helper.sh list # List all available bundles
|
|
1059
|
-
```
|
|
1060
|
-
|
|
1061
|
-
**See:** `.agents/bundles/` for bundle definitions, `.agents/scripts/bundle-helper.sh` for the CLI.
|
|
1062
|
-
|
|
1063
|
-
### Parallel Agents & Headless Dispatch
|
|
1064
|
-
|
|
1065
|
-
Run multiple AI sessions concurrently with isolated contexts. Named **runners** provide persistent agent identities with their own instructions and memory.
|
|
1066
|
-
|
|
1067
|
-
| Feature | Description |
|
|
1068
|
-
|---------|-------------|
|
|
1069
|
-
| **Headless dispatch** | `headless-runtime-helper.sh run` provides canonical model routing, retries, and session isolation |
|
|
1070
|
-
| **Durable one-shot scheduling** | `aidevops schedule once` queues private, restart-safe delayed work without fake recurring jobs or sleeper processes |
|
|
1071
|
-
| **Runners** | Named agent instances with per-runner AGENTS.md, config, and run logs (`runner-helper.sh`) |
|
|
1072
|
-
| **Self-hosted runner runbooks** | GitHub runner storage, lifecycle, Docker foreground mode, timer freshness, and cleanup-race guidance (`.agents/reference/github-self-hosted-runners.md`) |
|
|
1073
|
-
| **Session management** | Resume sessions with `-s <id>` or `-c`, fork with SDK |
|
|
1074
|
-
| **Memory namespaces** | Per-runner memory isolation with shared access when needed |
|
|
1075
|
-
| **SDK orchestration** | `@opencode-ai/sdk` for TypeScript parallel dispatch via `Promise.all` |
|
|
1076
|
-
| **Matrix integration** | Chat-triggered dispatch via self-hosted Matrix (optional) |
|
|
638
|
+
<!-- aidevops:managed-readme:start -->
|
|
639
|
+
<!-- managed by aidevops; refresh with managed-readme-helper.sh sync -->
|
|
640
|
+
## Star History
|
|
1077
641
|
|
|
1078
|
-
|
|
1079
|
-
# Create a named runner
|
|
1080
|
-
runner-helper.sh create code-reviewer --description "Reviews code for security and quality"
|
|
642
|
+
|
|
1081
643
|
|
|
1082
|
-
|
|
1083
|
-
runner-helper.sh run code-reviewer "Review src/auth/ for vulnerabilities"
|
|
644
|
+
## Built with aidevops
|
|
1084
645
|
|
|
1085
|
-
|
|
1086
|
-
aidevops
|
|
1087
|
-
--dir ~/Git/example --prompt-file ~/.config/aidevops/prompts/auth-review.md
|
|
1088
|
-
aidevops schedule status
|
|
1089
|
-
|
|
1090
|
-
# Dispatch against warm server (faster, no MCP cold boot)
|
|
1091
|
-
opencode serve --port 4096 &
|
|
1092
|
-
runner-helper.sh run code-reviewer "Review src/auth/" --attach http://localhost:4096
|
|
1093
|
-
|
|
1094
|
-
# Parallel dispatch via CLI
|
|
1095
|
-
opencode run --attach http://localhost:4096 --title "Review" "Review src/auth/" &
|
|
1096
|
-
opencode run --attach http://localhost:4096 --title "Tests" "Generate tests for src/utils/" &
|
|
1097
|
-
wait
|
|
1098
|
-
|
|
1099
|
-
# List runners and status
|
|
1100
|
-
runner-helper.sh list
|
|
1101
|
-
runner-helper.sh status code-reviewer
|
|
1102
|
-
```
|
|
1103
|
-
|
|
1104
|
-
**Architecture:**
|
|
1105
|
-
|
|
1106
|
-
```text
|
|
1107
|
-
OpenCode Server (opencode serve)
|
|
1108
|
-
├── Session 1 (runner/code-reviewer)
|
|
1109
|
-
├── Session 2 (runner/seo-analyst)
|
|
1110
|
-
└── Session 3 (scheduled-task)
|
|
1111
|
-
↑
|
|
1112
|
-
HTTP API / SSE Events
|
|
1113
|
-
↑
|
|
1114
|
-
┌────────┴────────┐
|
|
1115
|
-
│ Dispatch Layer │ ← runner-helper.sh, cron, Matrix bot, SDK
|
|
1116
|
-
└─────────────────┘
|
|
1117
|
-
```
|
|
1118
|
-
|
|
1119
|
-
**Example runner templates:** [code-reviewer](.agents/tools/ai-assistants/runners/code-reviewer.md), [seo-analyst](.agents/tools/ai-assistants/runners/seo-analyst.md) - copy and customize for your own runners.
|
|
1120
|
-
|
|
1121
|
-
**Matrix bot dispatch** (optional): Bridge Matrix chat rooms to runners for chat-triggered AI. Accepted text events normalize through the provider-neutral contract and are durably claimed before dispatch. SQLite context is isolated by room and actor; idle sessions compact to summaries without deleting immutable interaction history.
|
|
1122
|
-
|
|
1123
|
-
```bash
|
|
1124
|
-
# Setup Matrix bot (interactive wizard)
|
|
1125
|
-
matrix-dispatch-helper.sh setup
|
|
1126
|
-
|
|
1127
|
-
# Map rooms to runners (mutable context is isolated by room and actor)
|
|
1128
|
-
matrix-dispatch-helper.sh map '!dev-room:server' code-reviewer
|
|
1129
|
-
matrix-dispatch-helper.sh map '!seo-room:server' seo-analyst
|
|
1130
|
-
|
|
1131
|
-
# Start bot (daemon mode)
|
|
1132
|
-
matrix-dispatch-helper.sh start --daemon
|
|
1133
|
-
|
|
1134
|
-
# In Matrix room: "!ai Review src/auth.ts for security issues"
|
|
1135
|
-
|
|
1136
|
-
# Manage sessions
|
|
1137
|
-
matrix-dispatch-helper.sh sessions list
|
|
1138
|
-
matrix-dispatch-helper.sh sessions stats
|
|
1139
|
-
```
|
|
1140
|
-
|
|
1141
|
-
**See:** [headless-dispatch.md](.agents/tools/ai-assistants/headless-dispatch.md) for full documentation including parallel vs sequential decision guide, SDK examples, CI/CD integration, and custom agent configuration. [matrix-bot.md](.agents/services/communications/matrix-bot.md) for Matrix bot setup including Cloudron Synapse guide and session persistence.
|
|
1142
|
-
|
|
1143
|
-
### Self-Improving Agent System
|
|
1144
|
-
|
|
1145
|
-
Agents that learn from experience and contribute improvements:
|
|
1146
|
-
|
|
1147
|
-
| Phase | Description |
|
|
1148
|
-
|-------|-------------|
|
|
1149
|
-
| **Review** | Analyze memory for success/failure patterns (`memory-helper.sh`) |
|
|
1150
|
-
| **Refine** | Generate and apply improvements to agents |
|
|
1151
|
-
| **Test** | Validate in isolated OpenCode sessions |
|
|
1152
|
-
| **PR** | Contribute to community with privacy filtering |
|
|
1153
|
-
|
|
1154
|
-
**Safety guardrails:**
|
|
1155
|
-
- Worktree isolation for all changes
|
|
1156
|
-
- Human approval required for PRs
|
|
1157
|
-
- Mandatory privacy filter (secretlint + pattern redaction)
|
|
1158
|
-
- Dry-run default, explicit opt-in for PR creation
|
|
1159
|
-
- Audit log to memory
|
|
1160
|
-
|
|
1161
|
-
### Agent Testing Framework
|
|
1162
|
-
|
|
1163
|
-
Test agent behavior through isolated AI sessions with automated validation:
|
|
1164
|
-
|
|
1165
|
-
```bash
|
|
1166
|
-
# Create a test suite
|
|
1167
|
-
agent-test-helper.sh create my-tests
|
|
1168
|
-
|
|
1169
|
-
# Run tests (auto-detects claude or opencode CLI)
|
|
1170
|
-
agent-test-helper.sh run my-tests
|
|
1171
|
-
|
|
1172
|
-
# Quick single-prompt test
|
|
1173
|
-
agent-test-helper.sh run-one "What tools do you have?" --expect "bash"
|
|
1174
|
-
|
|
1175
|
-
# Before/after comparison for agent changes
|
|
1176
|
-
agent-test-helper.sh baseline my-tests # Save current behavior
|
|
1177
|
-
# ... modify agents ...
|
|
1178
|
-
agent-test-helper.sh compare my-tests # Detect regressions
|
|
1179
|
-
```
|
|
1180
|
-
|
|
1181
|
-
Test suites are JSON files with prompts and validation rules (`expect_contains`, `expect_not_contains`, `expect_regex`, `min_length`, `max_length`). Results are saved for historical tracking.
|
|
1182
|
-
|
|
1183
|
-
**See:** `agent-testing.md` subagent for full documentation and example test suites.
|
|
1184
|
-
|
|
1185
|
-
### Voice Bridge - Talk to Your AI Agent
|
|
1186
|
-
|
|
1187
|
-
Speak naturally to your AI coding agent and hear it respond. The voice bridge connects your microphone to OpenCode via a fast local pipeline -- ask questions, give instructions, execute tasks, all by voice.
|
|
1188
|
-
|
|
1189
|
-
```text
|
|
1190
|
-
Mic → Silero VAD → Whisper MLX (1.4s) → OpenCode (4-6s) → Edge TTS (0.4s) → Speaker
|
|
1191
|
-
```
|
|
1192
|
-
|
|
1193
|
-
**Round-trip: ~6-8 seconds** on Apple Silicon. The agent can edit files, run commands, create PRs, and confirm what it did -- all via voice.
|
|
1194
|
-
|
|
1195
|
-
**Quick start:**
|
|
1196
|
-
|
|
1197
|
-
```bash
|
|
1198
|
-
# Start a voice conversation (installs deps automatically)
|
|
1199
|
-
voice-helper.sh talk
|
|
1200
|
-
|
|
1201
|
-
# Choose engines and voice
|
|
1202
|
-
voice-helper.sh talk whisper-mlx edge-tts en-GB-SoniaNeural
|
|
1203
|
-
voice-helper.sh talk whisper-mlx macos-say # Offline mode
|
|
1204
|
-
|
|
1205
|
-
# Utilities
|
|
1206
|
-
voice-helper.sh devices # List audio input/output devices
|
|
1207
|
-
voice-helper.sh voices # List available TTS voices
|
|
1208
|
-
voice-helper.sh benchmark # Test STT/TTS/LLM speeds
|
|
1209
|
-
voice-helper.sh status # Check component availability
|
|
1210
|
-
```
|
|
1211
|
-
|
|
1212
|
-
**Features:**
|
|
1213
|
-
|
|
1214
|
-
| Feature | Details |
|
|
1215
|
-
|---------|---------|
|
|
1216
|
-
| **Swappable STT** | whisper-mlx (fastest on Apple Silicon), faster-whisper (CPU) |
|
|
1217
|
-
| **Swappable TTS** | edge-tts (best quality), macos-say (offline), facebookMMS (local) |
|
|
1218
|
-
| **Voice exit** | Say "that's all", "goodbye", "all for now" to end naturally |
|
|
1219
|
-
| **STT correction** | LLM sanity-checks transcription errors before acting (e.g. "test.txte" → "test.txt") |
|
|
1220
|
-
| **Task execution** | Full tool access -- edit files, git operations, run commands |
|
|
1221
|
-
| **Session handback** | Conversation transcript output on exit for calling agent context |
|
|
1222
|
-
| **TUI compatible** | Graceful degradation when launched from AI tool's Bash (no tty) |
|
|
1223
|
-
|
|
1224
|
-
**How it works:** The bridge uses `opencode run --attach` to connect to a running OpenCode server for low-latency responses (~4-6s vs ~30s cold start). It automatically starts `opencode serve` if not already running.
|
|
1225
|
-
|
|
1226
|
-
**Requirements:** Apple Silicon Mac (for whisper-mlx), Python 3.10+, internet (for edge-tts). The voice helper installs Python dependencies automatically into the S2S venv.
|
|
1227
|
-
|
|
1228
|
-
### Speech-to-Speech Pipeline (Advanced)
|
|
1229
|
-
|
|
1230
|
-
For advanced use cases (custom LLMs, server/client deployment, multi-language, phone integration), the full [huggingface/speech-to-speech](https://github.com/huggingface/speech-to-speech) pipeline is also available:
|
|
1231
|
-
|
|
1232
|
-
```bash
|
|
1233
|
-
speech-to-speech-helper.sh setup # Install pipeline
|
|
1234
|
-
speech-to-speech-helper.sh start --local-mac # Run on Apple Silicon
|
|
1235
|
-
speech-to-speech-helper.sh start --cuda # Run on NVIDIA GPU
|
|
1236
|
-
speech-to-speech-helper.sh start --server # Server mode (remote clients)
|
|
1237
|
-
```
|
|
1238
|
-
|
|
1239
|
-
**Supported languages:** English, French, Spanish, Chinese, Japanese, Korean (auto-detect or fixed).
|
|
1240
|
-
|
|
1241
|
-
**Additional voice methods:**
|
|
1242
|
-
|
|
1243
|
-
| Method | Description |
|
|
1244
|
-
|--------|-------------|
|
|
1245
|
-
| **VoiceInk + Shortcut** | macOS: transcription → OpenCode API → response |
|
|
1246
|
-
| **iPhone Shortcut** | iOS: dictate → HTTP → speak response |
|
|
1247
|
-
| **Pipecat STS** | Full voice pipeline: Soniox STT → AI → Cartesia TTS |
|
|
1248
|
-
|
|
1249
|
-
**See:** [speech-to-speech.md](.agents/tools/voice/speech-to-speech.md) for full component options, CLI parameters, and integration patterns (Twilio phone, video narration, voice-driven DevOps).
|
|
1250
|
-
|
|
1251
|
-
### Scheduled Agent Tasks
|
|
1252
|
-
|
|
1253
|
-
Cron-based agent dispatch for automated workflows:
|
|
1254
|
-
|
|
1255
|
-
```bash
|
|
1256
|
-
# Example: Daily SEO report at 9am
|
|
1257
|
-
0 9 * * * ~/.aidevops/agents/scripts/runner-helper.sh run "seo-analyst" "Generate daily SEO report"
|
|
1258
|
-
```
|
|
1259
|
-
|
|
1260
|
-
**See:** [TODO.md](TODO.md) tasks t109-t118 for implementation status.
|
|
1261
|
-
|
|
1262
|
-
## **Requirements**
|
|
1263
|
-
|
|
1264
|
-
### **Recommended Hardware**
|
|
1265
|
-
|
|
1266
|
-
aidevops itself is lightweight (shell scripts + markdown), but AI model workloads benefit from capable hardware:
|
|
1267
|
-
|
|
1268
|
-
| Tier | Machine | CPU | RAM | GPU | Best For |
|
|
1269
|
-
|------|---------|-----|-----|-----|----------|
|
|
1270
|
-
| **Minimum** | Any modern laptop | 4+ cores | 8GB | None | Framework only, cloud AI APIs |
|
|
1271
|
-
| **Recommended** | Mac Studio / desktop | Apple M1+ or 8+ cores | 16GB+ | MPS (Apple) or NVIDIA 8GB+ | Local voice, browser automation, dev servers |
|
|
1272
|
-
| **Power User** | Workstation | 8+ cores | 32GB+ | NVIDIA 24GB+ VRAM | Full voice pipeline, local LLMs, parallel agents |
|
|
1273
|
-
| **Server** | Cloud GPU | Any | 16GB+ | A100 / H100 | Production voice, multi-user, batch processing |
|
|
1274
|
-
|
|
1275
|
-
**Cloud GPU providers** for on-demand GPU access: [NVIDIA Cloud](https://www.nvidia.com/en-us/gpu-cloud/), [Vast.ai](https://vast.ai/), [RunPod](https://www.runpod.io/), [Lambda](https://lambdalabs.com/). See `.agents/tools/infrastructure/cloud-gpu.md` for the full deployment guide (SSH setup, Docker, model caching, cost optimization).
|
|
1276
|
-
|
|
1277
|
-
**Note:** Most aidevops features (infrastructure management, SEO, code quality, Git workflows) require no GPU. GPU is only needed for local AI model inference (voice pipeline, vision models, local LLMs).
|
|
1278
|
-
|
|
1279
|
-
### **Software Dependencies**
|
|
1280
|
-
|
|
1281
|
-
```bash
|
|
1282
|
-
# Install dependencies (auto-detected by setup.sh)
|
|
1283
|
-
brew install sshpass jq curl mkcert dnsmasq fd ripgrep # macOS
|
|
1284
|
-
sudo apt-get install sshpass jq curl dnsmasq fd-find ripgrep # Ubuntu/Debian
|
|
1285
|
-
|
|
1286
|
-
# Generate SSH key
|
|
1287
|
-
ssh-keygen -t ed25519 -C "your-email@domain.com"
|
|
1288
|
-
```
|
|
1289
|
-
|
|
1290
|
-
### **File Discovery Tools**
|
|
1291
|
-
|
|
1292
|
-
AI agents use fast file discovery tools for efficient codebase navigation:
|
|
1293
|
-
|
|
1294
|
-
| Tool | Purpose | Speed |
|
|
1295
|
-
|------|---------|-------|
|
|
1296
|
-
| `fd` | Fast file finder (replaces `find`) | ~10x faster |
|
|
1297
|
-
| `ripgrep` | Fast content search (replaces `grep`) | ~10x faster |
|
|
1298
|
-
|
|
1299
|
-
Both tools respect `.gitignore` by default and are written in Rust for maximum performance.
|
|
1300
|
-
|
|
1301
|
-
**Preference order for file discovery:**
|
|
1302
|
-
|
|
1303
|
-
1. `git ls-files '*.md'` - Instant, git-tracked files only
|
|
1304
|
-
2. `fd -e md` - Fast, respects .gitignore
|
|
1305
|
-
3. `rg --files -g '*.md'` - Fast, respects .gitignore
|
|
1306
|
-
4. Built-in glob tools - Fallback when bash unavailable
|
|
1307
|
-
|
|
1308
|
-
The setup script offers to install these tools automatically.
|
|
1309
|
-
|
|
1310
|
-
## **Comprehensive Service Coverage**
|
|
1311
|
-
|
|
1312
|
-
### **Infrastructure & Hosting**
|
|
1313
|
-
|
|
1314
|
-
- **[Hostinger](https://www.hostinger.com/)**: Shared hosting, domains, email
|
|
1315
|
-
- **[Hetzner Cloud](https://www.hetzner.com/cloud)**: VPS servers, networking, load balancers
|
|
1316
|
-
- **[Closte](https://closte.com/)**: Managed hosting, application deployment
|
|
1317
|
-
- **[Coolify](https://coolify.io/)** *Enhanced with CLI*: Self-hosted PaaS with CLI integration
|
|
1318
|
-
- **[Cloudron](https://www.cloudron.io/)** *Enhanced with packaging guide*: Server and app management platform with custom app packaging support
|
|
1319
|
-
- **[Vercel](https://vercel.com/)** *Enhanced with CLI*: Modern web deployment platform with CLI integration
|
|
1320
|
-
- **[AWS](https://aws.amazon.com/)**: Cloud infrastructure support via standard protocols
|
|
1321
|
-
- **[DigitalOcean](https://www.digitalocean.com/)**: Cloud infrastructure support via standard protocols
|
|
1322
|
-
|
|
1323
|
-
### **Domain & DNS**
|
|
1324
|
-
|
|
1325
|
-
- **[Cloudflare](https://www.cloudflare.com/)**: DNS, CDN, security services
|
|
1326
|
-
- **[Spaceship](https://www.spaceship.com/)**: Domain registration and management
|
|
1327
|
-
- **[101domains](https://www.101domain.com/)**: Domain purchasing and DNS
|
|
1328
|
-
- **[AWS Route 53](https://aws.amazon.com/route53/)**: AWS DNS management
|
|
1329
|
-
- **[Namecheap](https://www.namecheap.com/)**: Domain and DNS services
|
|
1330
|
-
|
|
1331
|
-
### **Development & Git Platforms with CLI Integration**
|
|
1332
|
-
|
|
1333
|
-
- **[GitHub](https://github.com/)** *Enhanced with CLI*: Repository management, actions, API, GitHub CLI (gh) integration
|
|
1334
|
-
- **[GitLab](https://gitlab.com/)** *Enhanced with CLI*: Self-hosted and cloud Git platform with GitLab CLI (glab) integration
|
|
1335
|
-
- **[Gitea](https://gitea.io/)** *Enhanced with CLI*: Lightweight Git service with Gitea CLI (tea) integration
|
|
1336
|
-
- **[Agno](https://agno.com/)**: Local AI agent operating system for DevOps automation
|
|
1337
|
-
- **[Pandoc](https://pandoc.org/)**: Document conversion to markdown for AI processing
|
|
1338
|
-
|
|
1339
|
-
### **AI Orchestration Frameworks**
|
|
1340
|
-
|
|
1341
|
-
- **[Langflow](https://langflow.org/)**: Visual drag-and-drop builder for AI workflows (MIT, localhost:7860)
|
|
1342
|
-
- **[CrewAI](https://crewai.com/)**: Multi-agent teams with role-based orchestration (MIT, localhost:8501)
|
|
1343
|
-
- **[AutoGen](https://microsoft.github.io/autogen/)**: Microsoft's agentic AI framework with MCP support (MIT, localhost:8081)
|
|
1344
|
-
|
|
1345
|
-
### **Design, UI & Artifact Creation**
|
|
1346
|
-
|
|
1347
|
-
- **Google `DESIGN.md` standard**: Canonical AI-readable design systems with YAML tokens, Markdown rationale, linting, Tailwind/DTCG export, and preview generation. aidevops keeps `DESIGN.md` as the source of truth for UI agents.
|
|
1348
|
-
- **Design library**: 54 brand examples and 12 original style archetypes for agent-ready visual direction, plus palette, brand identity, and UI inspiration workflows.
|
|
1349
|
-
- **Artifact commands**: `/design-artifact` routes prototype, deck, email, poster, social carousel, and mobile mockup requests; `/open-design` manages optional Open Design companion workflows.
|
|
1350
|
-
- **[Open Design](https://github.com/nexu-io/open-design)** *Optional peripheral*: Local-first design artifact studio by nexu-io (Apache-2.0) for sandboxed previews, design-skill pickers, `.od/` workspaces, and exports. It installs alongside aidevops only when requested; selected skills are ingested via aidevops build-agent optimisation, not imported verbatim.
|
|
1351
|
-
- **Local HTTPS previews**: `localdev-helper.sh` can wrap Open Design or other dev servers with mkcert-backed `.local` routes when tools only expose localhost.
|
|
1352
|
-
- **Verification**: `workflows/ui-verification.md`, `email-design-test-helper.sh`, design preview screenshots, and deck/media smoke tests provide evidence before generated artifacts ship.
|
|
1353
|
-
|
|
1354
|
-
### **Mobile App & Simulator Testing**
|
|
1355
|
-
|
|
1356
|
-
- **Mobile app stack guidance**: Expo, Swift/Xcode, backend, analytics, monetisation, onboarding, notification, publishing, and test strategy references for mobile delivery (`.agents/tools/mobile/`).
|
|
1357
|
-
- **Simulator-backed web testing**: `serve-sim` guidance and helpers cover local/mobile preview flows, prompt failure handling, and simulator smoke tests before mobile UI changes ship.
|
|
1358
|
-
- **Device and automation options**: agent-device, App Store Connect, Maestro, minisim, iOS Simulator MCP, Xcodebuild MCP, and accessibility tooling references help agents choose the right mobile verification path.
|
|
1359
|
-
- **Mobile-first artifact routing**: `/design-artifact` can route mobile mockups and app screens through the design stack, then hand implementation to mobile/testing specialists.
|
|
1360
|
-
|
|
1361
|
-
### **Video Creation**
|
|
1362
|
-
|
|
1363
|
-
- **[Video-use](https://github.com/browser-use/video-use)**: Conversational footage editing through the [video-editor runtime adapter](.agents/tools/video/video-use-runtime.md), with a reviewed executable pin, explicit installation, whole-repository update checks and a no-upload synthetic render smoke test. Run `python3 ~/.aidevops/agents/scripts/video-use-helper.py status` to check readiness.
|
|
1364
|
-
- **[Remotion](https://remotion.dev/)**: Programmatic video creation with React - animations, compositions, media handling, captions
|
|
1365
|
-
- **[Video Prompt Design](https://github.com/snubroot/Veo-3-Meta-Framework)**: AI video prompt engineering using the 7-component meta prompt framework for Veo 3 and similar models
|
|
1366
|
-
- **[Kie.ai](https://kie.ai/)**: Unified asynchronous Market API and `kie-helper.sh` workflow for image, video, audio, uploads, callbacks, and credit checks with model-specific JSON pass-through
|
|
1367
|
-
- **[MuAPI](https://muapi.ai/)**: Multimodal AI API for image/video/audio/VFX generation, workflows, agents, music (Suno), and lip-sync - unified creative orchestration platform
|
|
1368
|
-
- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)**: YouTube video/audio/playlist/channel downloads, transcript extraction, and local file audio conversion via ffmpeg
|
|
1369
|
-
|
|
1370
|
-
### **WordPress Development**
|
|
1371
|
-
|
|
1372
|
-
- **[LocalWP](https://localwp.com)**: WordPress development environment with MCP database access
|
|
1373
|
-
- **[MainWP](https://mainwp.com/)**: WordPress site management dashboard
|
|
1374
|
-
|
|
1375
|
-
**Git CLI Enhancement Features:**
|
|
1376
|
-
|
|
1377
|
-
- **.agents/scripts/github-cli-helper.sh**: Advanced GitHub repository, issue, PR, and branch management
|
|
1378
|
-
- **.agents/scripts/gitlab-cli-helper.sh**: Complete GitLab project, issue, MR, and branch management
|
|
1379
|
-
- **.agents/scripts/gitea-cli-helper.sh**: Full Gitea repository, issue, PR, and branch management
|
|
1380
|
-
|
|
1381
|
-
### **Security & Code Quality**
|
|
1382
|
-
|
|
1383
|
-
- **[gopass](https://github.com/gopasspw/gopass)**: GPG-encrypted secret management with AI-native wrapper (`aidevops secret`) - subprocess injection + output redaction keeps secrets out of AI context
|
|
1384
|
-
- **[Vaultwarden](https://github.com/dani-garcia/vaultwarden)**: Password and secrets management
|
|
1385
|
-
- **[SonarCloud](https://sonarcloud.io/)**: Security and quality analysis (A-grade ratings)
|
|
1386
|
-
- **[CodeFactor](https://www.codefactor.io/)**: Code quality metrics (A+ score)
|
|
1387
|
-
- **[Codacy](https://www.codacy.com/)**: Multi-tool analysis with a live quality badge and daily A-grade monitoring
|
|
1388
|
-
- **[CodeRabbit](https://coderabbit.ai/)**: AI-powered code reviews
|
|
1389
|
-
- **[Snyk](https://snyk.io/)**: Security vulnerability scanning
|
|
1390
|
-
- **[Socket](https://socket.dev/)**: Dependency security and supply chain protection
|
|
1391
|
-
- **[Sentry](https://sentry.io/)**: Error monitoring and performance tracking
|
|
1392
|
-
- **[Cisco Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner)**: Security scanner for AI agent skills (prompt injection, exfiltration, malicious code)
|
|
1393
|
-
- **[VirusTotal](https://www.virustotal.com/)**: Advisory threat intelligence via VT API v3 -- file hash scanning (70+ AV engines), domain/URL reputation checks for imported skills
|
|
1394
|
-
- **[Secretlint](https://github.com/secretlint/secretlint)**: Detect exposed secrets in code
|
|
1395
|
-
- **[OSV Scanner](https://google.github.io/osv-scanner/)**: Google's vulnerability database scanner
|
|
1396
|
-
- **[Qlty](https://qlty.sh/)**: Universal code quality platform (70+ linters, auto-fixes)
|
|
1397
|
-
- **Retired review compatibility**: Historical Gemini Code Assist GitHub reviews remain readable, but the sunset integration is no longer advertised or configurable
|
|
1398
|
-
|
|
1399
|
-
### **AI Prompt Optimization**
|
|
1400
|
-
|
|
1401
|
-
- **[Repomix](https://repomix.com/)**: Pack codebases into AI-friendly context (80% token reduction with compress mode)
|
|
1402
|
-
- **[DSPy](https://dspy.ai/)**: Framework for programming with language models
|
|
1403
|
-
- **[DSPyGround](https://dspyground.com/)**: Interactive playground for prompt optimization
|
|
1404
|
-
- **[TOON Format](https://github.com/marcusquinn/aidevops/blob/main/.agents/toon-format.md)**: Token-Oriented Object Notation - 20-60% token reduction for LLM prompts
|
|
1405
|
-
|
|
1406
|
-
### **Document Processing & OCR**
|
|
1407
|
-
|
|
1408
|
-
- **Document Creation Agent** (`document-creation-helper.sh`): Unified document format conversion, template-based creation, and OCR for scanned PDFs/images. Routes to the best available tool (pandoc, odfpy, LibreOffice, Tesseract, EasyOCR, GLM-OCR) based on format pair and availability. Supports 13+ formats (ODT, DOCX, PDF, MD, HTML, EPUB, PPTX, ODP, XLSX, ODS, RTF, CSV, TSV).
|
|
1409
|
-
- **[LibPDF](https://libpdf.dev/)**: PDF form filling, digital signatures (PAdES B-B/T/LT/LTA), encryption, merge/split, text extraction
|
|
1410
|
-
- **[MinerU](https://github.com/opendatalab/MinerU)**: Layout-aware PDF-to-markdown/JSON conversion with OCR (109 languages), formula-to-LaTeX, and table extraction (53k+ stars, AGPL-3.0)
|
|
1411
|
-
- **[Unstract](https://github.com/Zipstack/unstract)**: LLM-powered structured data extraction from unstructured documents (PDF, images, DOCX)
|
|
1412
|
-
- **[GLM-OCR](https://ollama.com/library/glm-ocr)**: Local OCR via Ollama - purpose-built for document text extraction (tables, forms, complex layouts) with zero cloud dependency
|
|
1413
|
-
|
|
1414
|
-
**PDF/OCR Tool Selection:**
|
|
1415
|
-
|
|
1416
|
-
| Need | Tool | Why |
|
|
1417
|
-
|------|------|-----|
|
|
1418
|
-
| **Format conversion** | Document Creation Agent | Auto-selects best tool, 13+ formats |
|
|
1419
|
-
| **Complex PDF to markdown** | MinerU | Layout-aware, formulas, tables, 109-language OCR |
|
|
1420
|
-
| **Quick text extraction** | GLM-OCR | Local, fast, no API keys, privacy-first |
|
|
1421
|
-
| **Structured JSON output** | Unstract | Schema-based extraction, complex documents |
|
|
1422
|
-
| **Screen/window OCR** | Peekaboo + GLM-OCR | `peekaboo image --analyze --model ollama/glm-ocr` |
|
|
1423
|
-
| **PDF text extraction** | LibPDF | Native PDF parsing, no AI needed |
|
|
1424
|
-
| **Simple format conversion** | Pandoc | Lightweight, broad format support |
|
|
1425
|
-
| **Scanned PDF OCR** | Document Creation Agent | Auto-detects, routes to Tesseract/EasyOCR/GLM-OCR |
|
|
1426
|
-
|
|
1427
|
-
**Quick start:**
|
|
1428
|
-
|
|
1429
|
-
```bash
|
|
1430
|
-
# Document creation agent
|
|
1431
|
-
document-creation-helper.sh status # Check available tools
|
|
1432
|
-
document-creation-helper.sh install --standard # Install core tools
|
|
1433
|
-
document-creation-helper.sh convert report.pdf --to odt # Convert formats
|
|
1434
|
-
document-creation-helper.sh convert scan.pdf --to md --ocr # OCR scanned PDF
|
|
1435
|
-
document-creation-helper.sh template draft --type letter # Generate template
|
|
1436
|
-
|
|
1437
|
-
# GLM-OCR direct
|
|
1438
|
-
ollama pull glm-ocr
|
|
1439
|
-
ollama run glm-ocr "Extract all text" --images /path/to/document.png
|
|
1440
|
-
```
|
|
1441
|
-
|
|
1442
|
-
See `.agents/tools/ocr/glm-ocr.md` for batch processing, PDF workflows, and Peekaboo integration.
|
|
1443
|
-
|
|
1444
|
-
### **Communications**
|
|
1445
|
-
|
|
1446
|
-
- **[Twilio](https://www.twilio.com/)**: SMS, voice calls, WhatsApp, phone verification (Verify API), call recording & transcription
|
|
1447
|
-
- **[Telfon](https://mytelfon.com/)**: Twilio-powered cloud phone system with iOS/Android/Chrome apps for end-user calling interface
|
|
1448
|
-
- **[Matrix](https://matrix.org/)**: Self-hosted chat with bot integration for AI runner dispatch (`matrix-dispatch-helper.sh`)
|
|
1449
|
-
- **[SimpleX Chat](https://simplex.chat/)**: Privacy-first messaging with AI bot gateway for agent dispatch (`simplex-bot/`)
|
|
1450
|
-
- **[Matterbridge](https://github.com/42wim/matterbridge)**: Multi-platform chat bridge connecting 20+ platforms (Matrix, Discord, Telegram, Slack, IRC, WhatsApp, XMPP) with SimpleX adapter (`matterbridge-helper.sh`)
|
|
1451
|
-
|
|
1452
|
-
### **Animation & Video**
|
|
1453
|
-
|
|
1454
|
-
- **[Anime.js](https://animejs.com/)**: Lightweight JavaScript animation library for CSS, SVG, DOM attributes, and JS objects
|
|
1455
|
-
- **[Remotion](https://remotion.dev/)**: Programmatic video creation with React - create videos using code with 29 specialized rule files
|
|
1456
|
-
- **[Video Prompt Design](https://github.com/snubroot/Veo-3-Meta-Framework)**: Structured prompt engineering for AI video generation (Veo 3, 7-component framework, character consistency, audio design)
|
|
1457
|
-
|
|
1458
|
-
### **Voice AI**
|
|
1459
|
-
|
|
1460
|
-
- **Voice Bridge**: Talk to your AI coding agent via speech -- Silero VAD → Whisper MLX → OpenCode → Edge TTS (~6-8s round-trip)
|
|
1461
|
-
- **[Speech-to-Speech](https://github.com/huggingface/speech-to-speech)**: Open-source modular voice pipeline (VAD → STT → LLM → TTS) with local GPU and cloud GPU deployment
|
|
1462
|
-
- **[Pipecat](https://github.com/pipecat-ai/pipecat)**: Real-time voice agent framework with Soniox STT, Cartesia TTS, and multi-LLM support
|
|
1463
|
-
|
|
1464
|
-
### **Performance & Monitoring**
|
|
1465
|
-
|
|
1466
|
-
- **[PageSpeed Insights](https://pagespeed.web.dev/)**: Website performance auditing
|
|
1467
|
-
- **[Lighthouse](https://developer.chrome.com/docs/lighthouse/)**: Comprehensive web app analysis
|
|
1468
|
-
- **[WebPageTest](https://www.webpagetest.org/)**: Real-world performance testing from 40+ global locations with filmstrip, waterfall, and Core Web Vitals
|
|
1469
|
-
- **[Updown.io](https://updown.io/)**: Website uptime and SSL monitoring
|
|
1470
|
-
|
|
1471
|
-
### **AI & Documentation**
|
|
1472
|
-
|
|
1473
|
-
- **[Context7](https://context7.io/)**: Real-time documentation access for libraries and frameworks
|
|
1474
|
-
- **Context7 CLI mode**: `npx ctx7 setup --opencode --cli` for docs lookup without MCP transport (useful fallback in shell-first workflows)
|
|
1475
|
-
- **[Local Models](https://github.com/ggml-org/llama.cpp)**: Run AI models locally via llama.cpp for free, private, offline inference with HuggingFace GGUF model management (`local-model-helper.sh`)
|
|
1476
|
-
|
|
1477
|
-
### **Local Development**
|
|
1478
|
-
|
|
1479
|
-
- **[Localdev](https://mkcert.dev/)**: Local development environment manager with dnsmasq, Traefik, and mkcert for production-like `.local` domains with HTTPS on port 443 (`localdev-helper.sh`)
|
|
1480
|
-
|
|
1481
|
-
## **MCP Integrations**
|
|
1482
|
-
|
|
1483
|
-
**Model Context Protocol servers for real-time AI assistant integration.** The framework configures these MCPs for **[OpenCode](https://opencode.ai/)** (TUI, Desktop, and Extension for Zed/VSCode).
|
|
1484
|
-
|
|
1485
|
-
### **All Supported MCPs (20 available)**
|
|
1486
|
-
|
|
1487
|
-
MCP integrations use reviewed local package runners or remote HTTPS endpoints. Security-sensitive local integrations use exact package pins where required; setup may globally cache selected tools for faster startup. Run `setup.sh` or `aidevops update-tools` to refresh managed tooling.
|
|
1488
|
-
|
|
1489
|
-
| MCP | Purpose | Tier | API Key Required |
|
|
1490
|
-
|-----|---------|------|------------------|
|
|
1491
|
-
| [Claude Code MCP](https://github.com/steipete/claude-code-mcp) | Claude as sub-agent | Global | No |
|
|
1492
|
-
| [Amazon Order History](https://github.com/marcusquinn/amazon-order-history-csv-download-mcp) | Order data extraction | Per-agent | No |
|
|
1493
|
-
| [Chrome DevTools](https://chromedevtools.github.io/devtools-protocol/) | Browser debugging & automation | Per-agent | No |
|
|
1494
|
-
| [Context7](https://context7.com/) | Library documentation lookup | Per-agent | No |
|
|
1495
|
-
| [Docker MCP](https://docs.docker.com/ai/mcp-catalog/) | Container management | Per-agent | No |
|
|
1496
|
-
| [Google Analytics](https://developers.google.com/analytics) | Analytics data | Per-agent | Yes (Google API) |
|
|
1497
|
-
| [Google Search Console](https://developers.google.com/webmaster-tools) | Search performance data | Per-agent | Yes (Google API) |
|
|
1498
|
-
| [Grep by Vercel](https://grep.app/) | GitHub code search | Per-agent | No |
|
|
1499
|
-
| [LocalWP](https://localwp.com/) | WordPress database access | Per-agent | No (local) |
|
|
1500
|
-
| [macOS Automator](https://github.com/steipete/macos-automator-mcp) | macOS automation | Per-agent | No |
|
|
1501
|
-
| [Playwright MCP](https://github.com/microsoft/playwright-mcp) | Isolated or extension-connected browser automation | Per-agent | No |
|
|
1502
|
-
| [PostHog](https://posthog.com/docs/model-context-protocol) | Product analytics, feature flags, experiments, and error data | On-demand per-agent | OAuth |
|
|
1503
|
-
| [QuickFile](https://github.com/marcusquinn/quickfile-mcp) | Guarded multi-account accounting API | On-demand per-agent | Yes |
|
|
1504
|
-
| [Repomix](https://github.com/yamadashy/repomix) | Codebase packing for AI context | Per-agent | No |
|
|
1505
|
-
| [Sentry](https://sentry.io/) | Error tracking | Per-agent | Yes |
|
|
1506
|
-
| [shadcn](https://ui.shadcn.com/) | UI component library | Per-agent | No |
|
|
1507
|
-
| [Socket](https://socket.dev/) | Dependency security | Per-agent | No |
|
|
1508
|
-
| [Unstract](https://github.com/Zipstack/unstract) | Document data extraction | Per-agent | Yes |
|
|
1509
|
-
| [OpenAPI Search](https://openapi-mcp.openapisearch.com/mcp) | Search and explore any OpenAPI spec | Per-agent | No |
|
|
1510
|
-
| [Cloudflare Code Mode](https://mcp.cloudflare.com/mcp) | Full Cloudflare API (2,500+ endpoints via 2 tools) | Per-agent | Yes (Cloudflare) |
|
|
1511
|
-
|
|
1512
|
-
**Tier explanation:**
|
|
1513
|
-
- **Global** - Tools always available (loaded into every session)
|
|
1514
|
-
- **Per-agent** - Tools disabled globally, enabled per-agent via config (zero context overhead when unused)
|
|
1515
|
-
|
|
1516
|
-
**Performance optimization:** MCPs stay disabled globally and connect on demand when their subagent is invoked. Selected packages may be globally installed or cached, while integrations such as Playwright use an exact pinned package runner to preserve their reviewed CLI contract.
|
|
1517
|
-
|
|
1518
|
-
### **SEO Integrations (curl subagents - no MCP overhead)**
|
|
1519
|
-
|
|
1520
|
-
These use direct API calls via curl, avoiding MCP server startup entirely:
|
|
1521
|
-
|
|
1522
|
-
| Integration | Purpose | API Key Required |
|
|
1523
|
-
|-------------|---------|------------------|
|
|
1524
|
-
| [Ahrefs](https://ahrefs.com/api) | SEO analysis & backlinks | Yes |
|
|
1525
|
-
| [DataForSEO](https://dataforseo.com/) | SERP, keywords, backlinks, on-page | Yes |
|
|
1526
|
-
| [Serper](https://serper.dev/) | Google Search API (web, images, news) | Yes |
|
|
1527
|
-
| [Semrush](https://www.semrush.com/api-documentation/) | Domain analytics, keywords, backlinks, competitor research | Yes |
|
|
1528
|
-
| [ContentKing](https://www.contentkingapp.com/) | Real-time SEO monitoring, change tracking, issues | Yes |
|
|
1529
|
-
| [WebPageTest](https://www.webpagetest.org/) | Real-world performance testing from 40+ global locations | Yes |
|
|
1530
|
-
| [Hostinger](https://developers.hostinger.com/) | Hosting management | Yes |
|
|
1531
|
-
| [NeuronWriter](https://neuronwriter.com/) | Content optimization & NLP analysis | Yes |
|
|
1532
|
-
| [Outscraper](https://outscraper.com/) | Google Maps & business data extraction | Yes |
|
|
1533
|
-
|
|
1534
|
-
### **By Category**
|
|
1535
|
-
|
|
1536
|
-
**Context & Codebase:**
|
|
1537
|
-
|
|
1538
|
-
- [llm-tldr](https://github.com/parcadei/llm-tldr) - Semantic code analysis with 95% token savings ([details below](#llm-tldr---semantic-code-analysis))
|
|
1539
|
-
- [Context7](https://context7.com/) - Real-time documentation access for thousands of libraries
|
|
1540
|
-
- [Repomix](https://github.com/yamadashy/repomix) - Pack codebases into AI-friendly context
|
|
1541
|
-
- [OpenAPI Search](https://openapi-mcp.openapisearch.com/mcp) - Search and explore any OpenAPI specification (zero install, Cloudflare Worker)
|
|
1542
|
-
- [MCPorter](https://github.com/steipete/mcporter) - Discover, call, compose, and generate CLIs/typed clients for MCP servers
|
|
1543
|
-
|
|
1544
|
-
**Browser Automation** (browser tool suite + anti-detect stack, [benchmarked](#browser-automation)):
|
|
1545
|
-
|
|
1546
|
-
- **Auto-browse workflow** - `/auto-browse` orchestrates the tools below to learn messy browser tasks, choose the cheapest reliable path, preserve private profile/session state under `~/.aidevops/`, and graduate reusable private agents or sanitized `todo/` plans
|
|
1547
|
-
- [Playwright](https://playwright.dev/) - Fastest engine (0.9s form fill); standalone Brave is preferred for headed/headless work, while Microsoft's [Playwright Extension](https://chromewebstore.google.com/detail/playwright-extension/mmlmfjhmonkocbjadbfplnigmagldckm) is reserved for interactive access to approved user-owned tabs
|
|
1548
|
-
- [playwright-cli](https://github.com/microsoft/playwright-cli) - Microsoft official CLI for AI agents, `--session` isolation, built-in tracing
|
|
1549
|
-
- [dev-browser](https://github.com/nicholasgriffintn/dev-browser) - Persistent profile, stays logged in, ARIA snapshots, pairs with DevTools
|
|
1550
|
-
- [agent-browser](https://github.com/vercel-labs/agent-browser) - CLI/CI/CD, `--session` parallel, ref-based element targeting, **iOS Simulator support** (macOS)
|
|
1551
|
-
- [Crawl4AI](https://github.com/unclecode/crawl4ai) - Bulk extraction, `arun_many` parallel (1.7x), LLM-ready markdown
|
|
1552
|
-
- [WaterCrawl](https://github.com/watercrawl/watercrawl) - Self-hosted crawling with web search, sitemap generation, JS rendering, proxy support
|
|
1553
|
-
- [Playwright Recorder](https://chromewebstore.google.com/detail/playwright-recorder/bapaclfmcgookbglclacfgeemaehkkme) - Optional third-party, low-sensitivity human-flow capture into draft test code; pair with written acceptance criteria and review/redact output
|
|
1554
|
-
- [Stagehand](https://github.com/browserbase/stagehand) - Natural language automation, self-healing selectors
|
|
1555
|
-
- [browser-use](https://github.com/browser-use/browser-use) - AI-native browser automation, CLI 3.0 Browser Harness, packaged agent skill, Browser Use Cloud, 100-task upstream benchmark
|
|
1556
|
-
- [Chrome DevTools MCP](https://github.com/nicholasgriffintn/chrome-devtools-mcp) - Companion: Lighthouse, network throttling, CSS coverage (pairs with any tool)
|
|
1557
|
-
- [Cloudflare Browser Rendering](https://developers.cloudflare.com/browser-rendering/) - Server-side web scraping
|
|
1558
|
-
- [Peekaboo](https://github.com/steipete/Peekaboo) - macOS screen capture and GUI automation (pixel-accurate captures, AI vision analysis)
|
|
1559
|
-
- [Sweet Cookie](https://github.com/steipete/sweet-cookie) - Browser cookie extraction for API calls without launching a browser
|
|
1560
|
-
- **Anti-Detect Stack** ([details](#anti-detect-browser)):
|
|
1561
|
-
- [Camoufox](https://github.com/daijro/camoufox) (4.9k stars) - Firefox anti-detect, C++ fingerprint injection, WebRTC/Canvas/WebGL spoofing
|
|
1562
|
-
- [rebrowser-patches](https://github.com/nicedayfor/rebrowser-patches) (1.2k stars) - Chromium CDP leak prevention, automation signal removal
|
|
1563
|
-
- Multi-profile management - Persistent/clean/warm/disposable profiles (like AdsPower/GoLogin)
|
|
1564
|
-
- Proxy integration - Residential, SOCKS5, VPN per profile with geo-targeting
|
|
1565
|
-
|
|
1566
|
-
**Mobile & Simulator Testing:**
|
|
1567
|
-
|
|
1568
|
-
- [serve-sim](https://github.com/EvanBacon/serve-sim) - Apple Simulator browser preview/control for iOS, iPad, and Apple Watch simulators (setup offers global install on supported Macs)
|
|
1569
|
-
- [agent-device](.agents/tools/mobile/agent-device.md) - AI-driven mobile app interaction across iOS and Android
|
|
1570
|
-
- [Maestro](.agents/tools/mobile/maestro.md) - Repeatable YAML E2E flows for mobile apps
|
|
1571
|
-
|
|
1572
|
-
**SEO & Research:**
|
|
1573
|
-
|
|
1574
|
-
- [Google Search Console](https://developers.google.com/webmaster-tools) - Search performance insights (MCP)
|
|
1575
|
-
- [Grep by Vercel](https://grep.app/) - Search code snippets across GitHub repositories (MCP)
|
|
1576
|
-
- [Ahrefs](https://ahrefs.com/api) - SEO analysis, backlink research, keyword data (curl subagent)
|
|
1577
|
-
- [DataForSEO](https://dataforseo.com/) - Comprehensive SEO data APIs (curl subagent)
|
|
1578
|
-
- [Serper](https://serper.dev/) - Google Search API (curl subagent)
|
|
1579
|
-
- **SEO Audit** - Comprehensive technical SEO auditing: crawlability, indexation, Core Web Vitals, on-page optimization, E-E-A-T signals (imported skill from [marketingskills](https://github.com/coreyhaines31/marketingskills))
|
|
1580
|
-
- **Keyword Research** - Strategic keyword research with SERP weakness detection (via DataForSEO + Serper + Ahrefs)
|
|
1581
|
-
- **Site Crawler** - Screaming Frog-like SEO auditing: broken links, redirects, meta issues, structured data
|
|
1582
|
-
- **Domain Research** - DNS intelligence via THC (4.51B records) and Reconeer APIs: rDNS, subdomains, CNAMEs
|
|
1583
|
-
- [NeuronWriter](https://neuronwriter.com/) - Content optimization with NLP analysis, competitor research, and content scoring (curl subagent)
|
|
1584
|
-
|
|
1585
|
-
**Data Extraction:**
|
|
1586
|
-
|
|
1587
|
-
- [Outscraper](https://outscraper.com/) - Google Maps, business data, reviews extraction (curl subagent)
|
|
1588
|
-
- [curl-copy](.agents/tools/browser/curl-copy.md) - Authenticated scraping via DevTools "Copy as cURL" (no browser automation needed)
|
|
1589
|
-
|
|
1590
|
-
**Performance & Security:**
|
|
1591
|
-
|
|
1592
|
-
- [PageSpeed Insights](https://developers.google.com/speed/docs/insights/v5/get-started) - Website performance auditing
|
|
1593
|
-
- [Snyk](https://snyk.io/) - Security vulnerability scanning
|
|
1594
|
-
- [Cloudflare Code Mode](https://mcp.cloudflare.com/mcp) - Full Cloudflare API (2,500+ endpoints) via 2 tools in ~1,000 tokens (DNS, WAF, DDoS, R2, Workers, Zero Trust)
|
|
1595
|
-
- **IP Reputation** - Multi-provider IP reputation checking (Spamhaus, ProxyCheck, AbuseIPDB) for VPS/proxy vetting (`ip-reputation-helper.sh`)
|
|
1596
|
-
|
|
1597
|
-
**WordPress & Development:**
|
|
1598
|
-
|
|
1599
|
-
- [LocalWP](https://localwp.com/) - Direct WordPress database access
|
|
1600
|
-
- [WordPress MCP Adapter](https://github.com/WordPress/mcp-adapter) - Official WordPress MCP for content management (STDIO, HTTP, and SSH transports)
|
|
1601
|
-
- [Next.js DevTools](https://nextjs.org/docs) - React/Next.js development assistance
|
|
1602
|
-
|
|
1603
|
-
**CRM & Marketing:**
|
|
1604
|
-
|
|
1605
|
-
- [FluentCRM](https://fluentcrm.com/) - WordPress CRM: contacts, tags, lists, campaigns, automations, smart links, webhooks
|
|
1606
|
-
|
|
1607
|
-
**Accounts & Finance:**
|
|
1608
|
-
|
|
1609
|
-
- **Provider-neutral accounting** - Bookkeeping, statement imports,
|
|
1610
|
-
reconciliation, classifications, chart evolution, debtors/creditors,
|
|
1611
|
-
management and investor reports, statutory-return workpapers, and cash-flow
|
|
1612
|
-
forecasts with approval and read-back controls (`business/accounting.md`)
|
|
1613
|
-
- **Accounting software catalogue** - Truthful support states and export
|
|
1614
|
-
fallbacks across QuickFile, Xero, QuickBooks, FreeAgent, Sage, Zoho Books,
|
|
1615
|
-
FreshBooks, Wave, KashFlow, Clear Books, MYOB, Odoo, and others
|
|
1616
|
-
(`business/accounting-software.md`)
|
|
1617
|
-
- [QuickFile](https://github.com/marcusquinn/quickfile-mcp) - First executable
|
|
1618
|
-
reference adapter, activated on demand through `@quickfile`
|
|
1619
|
-
- [Amazon Order History](https://github.com/marcusquinn/amazon-order-history-csv-download-mcp) - Order data extraction (MCP)
|
|
1620
|
-
|
|
1621
|
-
**Document Processing & OCR:**
|
|
1622
|
-
|
|
1623
|
-
- [LibPDF](https://libpdf.dev/) - PDF form filling, digital signatures, encryption, merge/split (via helper script)
|
|
1624
|
-
- [Unstract](https://github.com/Zipstack/unstract) - LLM-powered structured data extraction from PDFs, images, DOCX (MCP)
|
|
1625
|
-
- [GLM-OCR](https://ollama.com/library/glm-ocr) - Local OCR via Ollama for document text extraction (subagent)
|
|
1626
|
-
|
|
1627
|
-
### **Quick Setup**
|
|
1628
|
-
|
|
1629
|
-
```bash
|
|
1630
|
-
# Install all MCP integrations
|
|
1631
|
-
bash .agents/scripts/setup-mcp-integrations.sh all
|
|
1632
|
-
|
|
1633
|
-
# Install specific integration
|
|
1634
|
-
bash .agents/scripts/setup-mcp-integrations.sh stagehand # JavaScript version
|
|
1635
|
-
bash .agents/scripts/setup-mcp-integrations.sh stagehand-python # Python version
|
|
1636
|
-
bash .agents/scripts/setup-mcp-integrations.sh stagehand-both # Both versions
|
|
1637
|
-
bash .agents/scripts/setup-mcp-integrations.sh chrome-devtools
|
|
1638
|
-
```
|
|
1639
|
-
|
|
1640
|
-
### OpenCode LSP Configuration
|
|
1641
|
-
|
|
1642
|
-
OpenCode includes [built-in LSP servers](https://opencode.ai/docs/lsp/) for 35+ languages. For aidevops projects that use Markdown and TOON extensively, add these optional LSP servers to your `opencode.json` for real-time diagnostics during editing:
|
|
1643
|
-
|
|
1644
|
-
```json
|
|
1645
|
-
{
|
|
1646
|
-
"lsp": {
|
|
1647
|
-
"markdownlint": {
|
|
1648
|
-
"command": ["markdownlint-language-server", "--stdio"],
|
|
1649
|
-
"extensions": [".md"]
|
|
1650
|
-
},
|
|
1651
|
-
"toon-lsp": {
|
|
1652
|
-
"command": ["toon-lsp"],
|
|
1653
|
-
"extensions": [".toon"]
|
|
1654
|
-
}
|
|
1655
|
-
}
|
|
1656
|
-
}
|
|
1657
|
-
```
|
|
1658
|
-
|
|
1659
|
-
**Install the servers:**
|
|
1660
|
-
|
|
1661
|
-
```bash
|
|
1662
|
-
npm install -g markdownlint-language-server # Markdown diagnostics
|
|
1663
|
-
cargo install toon-lsp # TOON syntax validation
|
|
1664
|
-
```
|
|
1665
|
-
|
|
1666
|
-
These catch formatting and syntax issues during editing, reducing preflight/postflight fix cycles.
|
|
1667
|
-
|
|
1668
|
-
## **Browser Automation**
|
|
1669
|
-
|
|
1670
|
-
Browser tool suite + anti-detect stack + device emulation, benchmarked and integrated for AI-assisted web automation, dev testing, mobile/responsive testing, data extraction, and bot detection evasion. Agents automatically select the optimal tool based on task requirements.
|
|
1671
|
-
|
|
1672
|
-
For repeatable browser operations and web data mining, use `/auto-browse`. It runs an intake and learning loop that starts with cheap fetch/API/crawler options, escalates to deterministic or high-agency browser tools only when needed, and then graduates the workflow into a private custom agent, helper, schema, or sanitized `todo/` plan. Account-specific workflows, cookies, profile state, downloads, and traces stay in private aidevops user data; only generalized plans should be committed to the repo.
|
|
1673
|
-
|
|
1674
|
-
### Performance Benchmarks
|
|
1675
|
-
|
|
1676
|
-
Tested on macOS ARM64, all headless, warm daemon:
|
|
1677
|
-
|
|
1678
|
-
| Test | Playwright | playwright-cli | dev-browser | agent-browser | Crawl4AI | Stagehand | browser-use |
|
|
1679
|
-
|------|-----------|----------------|-------------|---------------|----------|-----------|-------------|
|
|
1680
|
-
| **Navigate + Screenshot** | **1.43s** | ~1.9s | 1.39s | 1.90s | 2.78s | 7.72s | Agentic; not in local deterministic suite |
|
|
1681
|
-
| **Form Fill** (4 fields) | **0.90s** | ~1.4s | 1.34s | 1.37s | N/A | 2.58s | Agentic; use for fuzzy forms |
|
|
1682
|
-
| **Data Extraction** (5 items) | 1.33s | ~1.5s | **1.08s** | 1.53s | 2.53s | 3.48s | Agentic; compress to deterministic when stable |
|
|
1683
|
-
| **Multi-step** (click + nav) | **1.49s** | ~2.0s | 1.49s | 3.06s | N/A | 4.48s | Upstream BU Bench covers 100 real-world tasks |
|
|
1684
|
-
| **Parallel** (3 sessions) | **1.6s** | ~2.0s | N/A | 2.0s | 3.0s | Slow | Prefer Browser Use Cloud for scale |
|
|
1685
|
-
|
|
1686
|
-
### Feature Matrix
|
|
1687
|
-
|
|
1688
|
-
| Feature | Playwright | playwright-cli | dev-browser | agent-browser | Crawl4AI | Stagehand | browser-use |
|
|
1689
|
-
|---------|-----------|----------------|-------------|---------------|----------|-----------|-------------|
|
|
1690
|
-
| **Headless** | Yes; extension mode headed | Yes (default) | Yes | Yes (default) | Yes | Yes | Yes |
|
|
1691
|
-
| **Proxy/VPN** | Full or existing browser | No | Via args | No | Full | Via args | Cloud/profiles |
|
|
1692
|
-
| **Extensions** | Persistent context or interactive approved user tabs | No in normal mode | Yes (profile) | No | No | Possible | Profile/browser dependent |
|
|
1693
|
-
| **Password managers** | Interactive approved user tabs only | No | Partial | No | No | No | Profile/browser dependent |
|
|
1694
|
-
| **Device emulation** | **Full** (100+ devices) | No | No | No | No | Via Playwright | Profile/browser dependent |
|
|
1695
|
-
| **Parallel sessions** | 5 standalone contexts/2.1s; interactive extension tab groups only | --session | Shared | 3 sess/2.0s | arun_many 1.7x | Per-instance | Cloud for scale |
|
|
1696
|
-
| **Session persistence** | storageState/profile/existing browser | Profile dir | Profile dir | state save/load | user_data_dir | Per-instance | BrowserProfile / Cloud |
|
|
1697
|
-
| **Tracing** | Full API | Built-in CLI | Via Playwright | Via Playwright | No | Via Playwright | History + Browser Harness CLI |
|
|
1698
|
-
| **Natural language** | No | No | No | No | LLM extraction | Yes | Yes |
|
|
1699
|
-
| **Self-healing** | No | No | No | No | No | Yes | Yes |
|
|
1700
|
-
| **Agent skill** | No | No | No | No | No | No | `browser-use skill` |
|
|
1701
|
-
| **iOS Simulator** | No | No | No | **Yes** (macOS) | No | No | No |
|
|
1702
|
-
| **Maintainer** | Microsoft | Microsoft | Community | Vercel | Community | Browserbase | Browser Use |
|
|
1703
|
-
|
|
1704
|
-
### Tool Selection
|
|
1705
|
-
|
|
1706
|
-
| Need | Tool | Why |
|
|
1707
|
-
|------|------|-----|
|
|
1708
|
-
| **Repeatable browser workflow** | `/auto-browse` | Learns, optimizes, preserves private profile state, and graduates reusable workflows |
|
|
1709
|
-
| **Fastest automation** | Standalone Playwright with Brave preferred | 0.9s form fill, parallel isolated contexts without disturbing user activity |
|
|
1710
|
-
| **AI agent (CLI)** | playwright-cli | Microsoft official, `--session` isolation, built-in tracing |
|
|
1711
|
-
| **Stay logged in** | dev-browser | Profile persists across restarts |
|
|
1712
|
-
| **Interactive access to your browser** | Playwright Extension | User-present selected-tab access to an existing Chrome/Edge/Chromium session; never for workers/CI, and Brave extension support is unverified |
|
|
1713
|
-
| **Record expected human flow** | Playwright Recorder (optional) | Produces draft test code for low-sensitivity flows; pair with written acceptance criteria and review/redact output |
|
|
1714
|
-
| **Bulk extraction** | Crawl4AI | Purpose-built, parallel, LLM-ready output |
|
|
1715
|
-
| **Self-hosted crawling** | WaterCrawl | Docker deployment, web search, sitemap generation |
|
|
1716
|
-
| **CLI/CI/CD** | playwright-cli or agent-browser | No server needed, `--session` isolation |
|
|
1717
|
-
| **iOS mobile testing** | agent-browser | Real Safari in iOS Simulator (macOS only) |
|
|
1718
|
-
| **Apple Simulator streaming** | serve-sim | Browser-visible iOS/iPad/watch simulator stream and control (macOS Apple Silicon) |
|
|
1719
|
-
| **Unknown pages** | Stagehand | Natural language, self-healing |
|
|
1720
|
-
| **High-agency browser tasks** | browser-use | AI-native browser agent, CLI 3.0, Browser Harness, cloud/stealth/CAPTCHA options |
|
|
1721
|
-
| **Performance debugging** | Chrome DevTools MCP | Companion tool, pairs with any browser |
|
|
1722
|
-
| **Mobile/tablet emulation** | Playwright | 100+ device presets, viewport, touch, geolocation, locale |
|
|
1723
|
-
| **Authenticated one-off scrape** | curl-copy | DevTools "Copy as cURL" → paste to terminal/AI |
|
|
1724
|
-
| **Bot detection evasion** | Anti-detect stack | Camoufox (full) or rebrowser-patches (quick) |
|
|
1725
|
-
| **Multi-account** | Browser profiles | Persistent fingerprint + proxy per account |
|
|
1726
|
-
|
|
1727
|
-
### AI Page Understanding
|
|
1728
|
-
|
|
1729
|
-
Agents use lightweight methods instead of expensive vision API calls:
|
|
1730
|
-
|
|
1731
|
-
| Method | Speed | Token Cost | Use For |
|
|
1732
|
-
|--------|-------|-----------|---------|
|
|
1733
|
-
| ARIA snapshot | ~0.01s | 50-200 tokens | Forms, navigation, interactive elements |
|
|
1734
|
-
| Text extraction | ~0.002s | Text length | Reading content |
|
|
1735
|
-
| Element scan | ~0.002s | ~20/element | Form filling, clicking |
|
|
1736
|
-
| Screenshot | ~0.05s | ~1K tokens (vision) | Visual debugging only |
|
|
1737
|
-
|
|
1738
|
-
See [`.agents/tools/browser/browser-automation.md`](.agents/tools/browser/browser-automation.md) for the full decision tree, [`browser-use.md`](.agents/tools/browser/browser-use.md) for Browser Use CLI 3.0 guidance, and [`browser-benchmark.md`](.agents/tools/browser/browser-benchmark.md) for reproducible benchmark scripts.
|
|
1739
|
-
|
|
1740
|
-
### Device Emulation
|
|
1741
|
-
|
|
1742
|
-
Test responsive layouts and mobile-specific behavior using Playwright's built-in device emulation. Supports 100+ device presets with viewport, user agent, touch events, device scale factor, geolocation, locale/timezone, permissions, color scheme, offline mode, and network throttling.
|
|
1743
|
-
|
|
1744
|
-
**Common device presets:**
|
|
1745
|
-
|
|
1746
|
-
| Device | Viewport | Scale | Touch |
|
|
1747
|
-
|--------|----------|-------|-------|
|
|
1748
|
-
| `iPhone 15` | 393x852 | 3 | Yes |
|
|
1749
|
-
| `iPad Pro 11` | 834x1194 | 2 | Yes |
|
|
1750
|
-
| `Pixel 7` | 412x915 | 2.625 | Yes |
|
|
1751
|
-
| `Galaxy S9+` | 320x658 | 4.5 | Yes |
|
|
1752
|
-
| `Desktop Chrome` | 1280x720 | 1 | No |
|
|
1753
|
-
|
|
1754
|
-
**Emulation capabilities:**
|
|
1755
|
-
|
|
1756
|
-
| Feature | Example |
|
|
1757
|
-
|---------|---------|
|
|
1758
|
-
| **Device presets** | `devices['iPhone 13']` - viewport, UA, touch, scale |
|
|
1759
|
-
| **Viewport/HiDPI** | `viewport: { width: 2560, height: 1440 }, deviceScaleFactor: 2` |
|
|
1760
|
-
| **Geolocation** | `geolocation: { longitude: -74.006, latitude: 40.7128 }` |
|
|
1761
|
-
| **Locale/timezone** | `locale: 'de-DE', timezoneId: 'Europe/Berlin'` |
|
|
1762
|
-
| **Color scheme** | `colorScheme: 'dark'` |
|
|
1763
|
-
| **Offline mode** | `offline: true` |
|
|
1764
|
-
| **Permissions** | `permissions: ['geolocation', 'notifications']` |
|
|
1765
|
-
| **Network throttling** | CDP-based Slow 3G / Fast 3G emulation |
|
|
1766
|
-
|
|
1767
|
-
**Recipes included:** Responsive breakpoint testing, multi-device parallel testing, touch gesture testing, geolocation-dependent features, dark mode visual regression, and network condition emulation.
|
|
1768
|
-
|
|
1769
|
-
See [`.agents/tools/browser/playwright-emulation.md`](.agents/tools/browser/playwright-emulation.md) for complete documentation with code examples.
|
|
1770
|
-
|
|
1771
|
-
### Anti-Detect Browser
|
|
1772
|
-
|
|
1773
|
-
Open-source alternative to AdsPower, GoLogin, and OctoBrowser for multi-account automation and bot detection evasion.
|
|
1774
|
-
|
|
1775
|
-
**Architecture:**
|
|
1776
|
-
|
|
1777
|
-
```text
|
|
1778
|
-
Layer 4: CAPTCHA Solving → CapSolver (existing)
|
|
1779
|
-
Layer 3: Network Identity → Proxies (residential/SOCKS5/VPN per profile)
|
|
1780
|
-
Layer 2: Browser Identity → Camoufox (C++ fingerprint injection)
|
|
1781
|
-
Layer 1: Automation Stealth → rebrowser-patches (CDP leak prevention)
|
|
1782
|
-
Layer 0: Browser Engine → Playwright (existing)
|
|
1783
|
-
```
|
|
1784
|
-
|
|
1785
|
-
**Profile Types:**
|
|
1786
|
-
|
|
1787
|
-
| Type | Cookies | Fingerprint | Use Case |
|
|
1788
|
-
|------|---------|-------------|----------|
|
|
1789
|
-
| **Persistent** | Saved | Fixed per profile | Account management, stay logged in |
|
|
1790
|
-
| **Clean** | None | Random each launch | Scraping, one-off tasks |
|
|
1791
|
-
| **Warm** | Saved | Fixed | Pre-warmed accounts (browsing history) |
|
|
1792
|
-
| **Disposable** | None | Random | Single-use, maximum anonymity |
|
|
1793
|
-
|
|
1794
|
-
**Quick Start:**
|
|
1795
|
-
|
|
1796
|
-
```bash
|
|
1797
|
-
# Setup
|
|
1798
|
-
anti-detect-helper.sh setup
|
|
1799
|
-
|
|
1800
|
-
# Create profile with proxy
|
|
1801
|
-
anti-detect-helper.sh profile create "my-account" --type persistent --os macos
|
|
1802
|
-
|
|
1803
|
-
# Launch (Camoufox with auto-generated fingerprint)
|
|
1804
|
-
anti-detect-helper.sh launch --profile "my-account" --headless
|
|
1805
|
-
|
|
1806
|
-
# Test detection (BrowserScan, SannyBot)
|
|
1807
|
-
anti-detect-helper.sh test --profile "my-account"
|
|
1808
|
-
|
|
1809
|
-
# Warm up profile with browsing history
|
|
1810
|
-
anti-detect-helper.sh warmup "my-account" --duration 30m
|
|
1811
|
-
```
|
|
1812
|
-
|
|
1813
|
-
**Engine Selection:**
|
|
1814
|
-
|
|
1815
|
-
| Engine | Stealth Level | Speed | Best For |
|
|
1816
|
-
|--------|---------------|-------|----------|
|
|
1817
|
-
| **Camoufox** (Firefox) | High (C++ level) | Medium | Full anti-detect, fingerprint rotation |
|
|
1818
|
-
| **rebrowser-patches** (Chromium) | Medium (CDP patches) | Fast | Quick stealth on existing Playwright code |
|
|
1819
|
-
|
|
1820
|
-
See [`.agents/tools/browser/anti-detect-browser.md`](.agents/tools/browser/anti-detect-browser.md) for the full decision tree and subagent index.
|
|
1821
|
-
|
|
1822
|
-
## **Repomix - AI Context Generation**
|
|
1823
|
-
|
|
1824
|
-
[Repomix](https://repomix.com/) packages your codebase into AI-friendly formats for sharing with AI assistants. This framework includes optimized Repomix configuration for consistent context generation.
|
|
1825
|
-
|
|
1826
|
-
### Why Repomix?
|
|
1827
|
-
|
|
1828
|
-
| Use Case | Tool | When to Use |
|
|
1829
|
-
|----------|------|-------------|
|
|
1830
|
-
| **Interactive coding** | Augment Context Engine | Real-time semantic search during development |
|
|
1831
|
-
| **Share with external AI** | Repomix | Self-contained snapshot for ChatGPT, Claude web, etc. |
|
|
1832
|
-
| **Architecture review** | Repomix (compress) | 80% token reduction, structure only |
|
|
1833
|
-
| **CI/CD integration** | GitHub Action | Automated context in releases |
|
|
1834
|
-
|
|
1835
|
-
### Quick Usage
|
|
1836
|
-
|
|
1837
|
-
```bash
|
|
1838
|
-
# Pack current repo with configured defaults
|
|
1839
|
-
npx repomix
|
|
1840
|
-
|
|
1841
|
-
# Compress mode (~80% smaller, structure only)
|
|
1842
|
-
npx repomix --compress
|
|
1843
|
-
|
|
1844
|
-
# Or use the helper script
|
|
1845
|
-
.agents/scripts/context-builder-helper.sh pack # Full context
|
|
1846
|
-
.agents/scripts/context-builder-helper.sh compress # Compressed
|
|
1847
|
-
```
|
|
1848
|
-
|
|
1849
|
-
### Configuration Files
|
|
1850
|
-
|
|
1851
|
-
| File | Purpose |
|
|
1852
|
-
|------|---------|
|
|
1853
|
-
| `repomix.config.json` | Default settings (style, includes, security) |
|
|
1854
|
-
| `.repomixignore` | Additional exclusions beyond .gitignore |
|
|
1855
|
-
| `repomix-instruction.md` | Custom AI instructions included in output |
|
|
1856
|
-
|
|
1857
|
-
### Key Design Decisions
|
|
1858
|
-
|
|
1859
|
-
- **No pre-generated files**: Outputs are generated on-demand to avoid staleness
|
|
1860
|
-
- **Inherits .gitignore**: Security patterns automatically respected
|
|
1861
|
-
- **Secretlint enabled**: Scans for exposed credentials before output
|
|
1862
|
-
- **Symlinks excluded**: Avoids duplicating `.agents/` content
|
|
1863
|
-
|
|
1864
|
-
### MCP Integration
|
|
1865
|
-
|
|
1866
|
-
Repomix runs as an MCP server for direct AI assistant integration:
|
|
1867
|
-
|
|
1868
|
-
```json
|
|
1869
|
-
{
|
|
1870
|
-
"repomix": {
|
|
1871
|
-
"type": "local",
|
|
1872
|
-
"command": ["repomix", "--mcp"],
|
|
1873
|
-
"enabled": true
|
|
1874
|
-
}
|
|
1875
|
-
}
|
|
1876
|
-
```
|
|
1877
|
-
|
|
1878
|
-
> Install globally first: `bun install -g repomix` (done automatically by `setup.sh`)
|
|
1879
|
-
|
|
1880
|
-
See `.agents/tools/context/context-builder.md` for complete documentation.
|
|
1881
|
-
|
|
1882
|
-
### llm-tldr - Semantic Code Analysis
|
|
1883
|
-
|
|
1884
|
-
[llm-tldr](https://github.com/parcadei/llm-tldr) extracts code structure and semantics, saving ~95% tokens compared to raw code. From the [Continuous-Claude](https://github.com/parcadei/Continuous-Claude-v3) project.
|
|
1885
|
-
|
|
1886
|
-
```bash
|
|
1887
|
-
# Install
|
|
1888
|
-
pip install llm-tldr
|
|
1889
|
-
|
|
1890
|
-
# CLI usage
|
|
1891
|
-
tldr tree ./src # File structure with line counts
|
|
1892
|
-
tldr structure src/auth.py # Code skeleton (classes, functions)
|
|
1893
|
-
tldr context src/auth.py # Full semantic analysis
|
|
1894
|
-
tldr search "authentication" ./src # Semantic code search
|
|
1895
|
-
tldr impact src/auth.py validate # What would change affect?
|
|
1896
|
-
```
|
|
1897
|
-
|
|
1898
|
-
**MCP Integration:**
|
|
1899
|
-
|
|
1900
|
-
```json
|
|
1901
|
-
{
|
|
1902
|
-
"llm-tldr": {
|
|
1903
|
-
"command": "tldr-mcp",
|
|
1904
|
-
"args": ["--project", "${workspaceFolder}"]
|
|
1905
|
-
}
|
|
1906
|
-
}
|
|
1907
|
-
```
|
|
1908
|
-
|
|
1909
|
-
| Feature | Token Savings | Use Case |
|
|
1910
|
-
|---------|---------------|----------|
|
|
1911
|
-
| Structure extraction | 90% | Understanding code layout |
|
|
1912
|
-
| Context analysis | 95% | Comprehensive code understanding |
|
|
1913
|
-
| Semantic search | N/A | Finding code by meaning |
|
|
1914
|
-
| Impact analysis | N/A | Change risk assessment |
|
|
1915
|
-
|
|
1916
|
-
See `.agents/tools/context/llm-tldr.md` for complete documentation.
|
|
1917
|
-
|
|
1918
|
-
## **Cross-Tool Compatibility**
|
|
1919
|
-
|
|
1920
|
-
### Agent Skills Standard
|
|
1921
|
-
|
|
1922
|
-
aidevops implements the [Agent Skills](https://agentskills.io/) standard for cross-tool compatibility. Skills are auto-discovered by compatible AI assistants.
|
|
1923
|
-
|
|
1924
|
-
**Generated SKILL.md files** in `~/.aidevops/agents/` provide skill metadata following the [Agent Skills standard](https://agentskills.io/specification). These are discoverable by any compatible tool.
|
|
1925
|
-
|
|
1926
|
-
### Claude Code Plugin Marketplace
|
|
1927
|
-
|
|
1928
|
-
aidevops is registered as a **Claude Code plugin marketplace**. Install with two commands:
|
|
1929
|
-
|
|
1930
|
-
```bash
|
|
1931
|
-
/plugin marketplace add marcusquinn/aidevops
|
|
1932
|
-
/plugin install aidevops@aidevops
|
|
1933
|
-
```
|
|
1934
|
-
|
|
1935
|
-
This installs the complete framework: 14 main agents, 2,200+ sub agents, and 2,010+ helper scripts, including callable skill/reference modules and supporting production script code.
|
|
1936
|
-
|
|
1937
|
-
### Importing External Skills
|
|
1938
|
-
|
|
1939
|
-
Import skills from GitHub or ClawdHub using the `aidevops skill` CLI:
|
|
1940
|
-
|
|
1941
|
-
```bash
|
|
1942
|
-
# Import from GitHub (auto-detects format)
|
|
1943
|
-
aidevops skill add owner/repo
|
|
1944
|
-
|
|
1945
|
-
# Import from ClawdHub (skill registry with vector search)
|
|
1946
|
-
aidevops skill add clawdhub:caldav-calendar
|
|
1947
|
-
aidevops skill add https://clawdhub.com/owner/slug
|
|
1948
|
-
|
|
1949
|
-
# More examples
|
|
1950
|
-
aidevops skill add anthropics/skills/pdf # Specific skill from multi-skill repo
|
|
1951
|
-
aidevops skill add vercel-labs/agent-skills # All skills from a repo
|
|
1952
|
-
aidevops skill add expo/skills --name expo-dev # Custom name
|
|
1953
|
-
aidevops skill add owner/repo --dry-run # Preview without changes
|
|
1954
|
-
```
|
|
1955
|
-
|
|
1956
|
-
**Supported sources:**
|
|
1957
|
-
- GitHub repos (`owner/repo` or full URL) — fetched via `git clone`
|
|
1958
|
-
- [ClawdHub](https://clawdhub.com) (`clawdhub:slug` or full URL) — fetched via Playwright browser automation
|
|
1959
|
-
|
|
1960
|
-
**Supported formats:**
|
|
1961
|
-
- `SKILL.md` - [Agent Skills standard](https://agentskills.io/specification) (preferred)
|
|
1962
|
-
- `AGENTS.md` - Claude Code agents format
|
|
1963
|
-
- `.cursorrules` - Cursor rules format (auto-converted)
|
|
1964
|
-
|
|
1965
|
-
**Features:**
|
|
1966
|
-
- Auto-detection of skill format and category placement
|
|
1967
|
-
- Conflict detection with merge/replace/rename options
|
|
1968
|
-
- Upstream commit tracking for update detection (`aidevops skill check`)
|
|
1969
|
-
- Conversion to aidevops subagent format with YAML frontmatter
|
|
1970
|
-
- Registry stored in `.agents/configs/skill-sources.json`
|
|
1971
|
-
- Telemetry disabled (no data sent to skills.sh or other services)
|
|
1972
|
-
|
|
1973
|
-
**How it differs from `npx add-skill`:**
|
|
1974
|
-
|
|
1975
|
-
| | `aidevops skill add` | `npx add-skill` |
|
|
1976
|
-
|---|---|---|
|
|
1977
|
-
| **Target** | Converts to aidevops format in `.agents/` | Copies SKILL.md to agent-specific dirs |
|
|
1978
|
-
| **Tracking** | Git commit-based upstream tracking | Lock file with content hashes |
|
|
1979
|
-
| **Telemetry** | Disabled | Sends anonymous install counts |
|
|
1980
|
-
| **Scope** | OpenCode-first | 22+ agents |
|
|
1981
|
-
| **Updates** | `aidevops skill check` (GitHub API) | `npx skills check` (Vercel API) |
|
|
1982
|
-
|
|
1983
|
-
See `.agents/scripts/add-skill-helper.sh` for implementation details.
|
|
1984
|
-
|
|
1985
|
-
## **AI Agents & Subagents**
|
|
1986
|
-
|
|
1987
|
-
**Agents are specialized AI personas with focused knowledge and tool access.** Instead of giving your AI assistant access to everything at once (which wastes context tokens), agents provide targeted capabilities for specific tasks.
|
|
1988
|
-
|
|
1989
|
-
Call them in your AI assistant conversation with a simple @mention
|
|
1990
|
-
|
|
1991
|
-
### **How Agents Work**
|
|
1992
|
-
|
|
1993
|
-
| Concept | Description |
|
|
1994
|
-
|---------|-------------|
|
|
1995
|
-
| **Main Agent** | Domain-focused assistant (e.g., WordPress, SEO, DevOps) |
|
|
1996
|
-
| **Subagent** | Specialized assistant for specific services (invoked with @mention) |
|
|
1997
|
-
| **MCP Tools** | Only loaded when relevant agent is invoked (saves tokens) |
|
|
1998
|
-
|
|
1999
|
-
### **Main Agents**
|
|
2000
|
-
|
|
2001
|
-
Primary agents live at `.agents/<name>.md`. Each is a domain expert with its own system prompt, tool permissions, and subagent roster. MCPs are loaded on-demand per subagent, not per primary agent.
|
|
2002
|
-
|
|
2003
|
-
| Name | File | Purpose | Model Tier |
|
|
2004
|
-
|------|------|---------|------------|
|
|
2005
|
-
| Build+ | `build-plus.md` | Code: features, bug fixes, refactors, CI, full-loop delivery (default) | thinking |
|
|
2006
|
-
| Automate | `automate.md` | Scheduling, dispatch, monitoring, background orchestration | standard |
|
|
2007
|
-
| Aidevops | `aidevops.md` | Framework development — meta-agent for improving aidevops itself | thinking |
|
|
2008
|
-
| Business | `business.md` | Company orchestration, provider-neutral accounting, finance, invoicing, strategy | standard |
|
|
2009
|
-
| Content | `content.md` | Content creation across blog, video, audio, image, social | thinking |
|
|
2010
|
-
| Health | `health.md` | Health and wellness content, fitness, nutrition | thinking |
|
|
2011
|
-
| Legal | `legal.md` | Legal compliance, terms, privacy, GDPR | thinking |
|
|
2012
|
-
| Marketing-Sales | `marketing-sales.md` | Email campaigns, CRM, outreach, paid ads, direct response, CRO | thinking |
|
|
2013
|
-
| Product | `product.md` | Product management, PRDs, roadmaps, requirements capture | thinking |
|
|
2014
|
-
| Research | `research.md` | Technical and market research, competitive analysis | standard |
|
|
2015
|
-
| SEO | `seo.md` | SEO audits, keyword research, GSC, schema, technical SEO | thinking |
|
|
2016
|
-
|
|
2017
|
-
**Specialist subagents** (e.g. `@wordpress`, `@seo`, Build-Agent, Build-MCP, etc.) live under `.agents/tools/` or as `mode: subagent` files and are invoked via `@mention` when domain expertise is needed. See `subagent-index.toon` for the full roster. For read-only macOS Activity Monitor and background-efficiency audits, use `@macos-activity-cleaner` or `/aidevops-macos-activity-cleaner`.
|
|
2018
|
-
|
|
2019
|
-
#### How to invoke a main agent
|
|
2020
|
-
|
|
2021
|
-
Launch terminal clients directly with Build+ selected by default, or name a main agent:
|
|
2022
|
-
|
|
2023
|
-
```bash
|
|
2024
|
-
aidevops codex
|
|
2025
|
-
aidevops codex automate
|
|
2026
|
-
aidevops claude seo
|
|
2027
|
-
aidevops opencode research
|
|
2028
|
-
```
|
|
2029
|
-
|
|
2030
|
-
These shortcuts apply each CLI's supported full-access options for the session.
|
|
2031
|
-
They also support Cursor Agent, Gemini, Continue, Kilo, Kiro CLI, Aider, Amp, Kimi,
|
|
2032
|
-
Qwen and Droid (which retains its configured interactive autonomy). Use
|
|
2033
|
-
`aidevops codex --list-agents` to list main agents, `--dry-run` to preview a launch,
|
|
2034
|
-
and `--native` for native subcommands without injected defaults. See
|
|
2035
|
-
[interactive runtime launchers](.agents/tools/ai-assistants/runtime-launchers.md)
|
|
2036
|
-
for aliases, argument forwarding and runtime limitations.
|
|
2037
|
-
|
|
2038
|
-
| Client | Invocation |
|
|
2039
|
-
|---|---|
|
|
2040
|
-
| **OpenCode** | Tab through the agent picker in the UI — Build+ is the default. Main agents are registered as top-level agents in OpenCode's config. |
|
|
2041
|
-
| **Claude Code / Codex / Cursor / Droid / Kiro / Continue / Kimi / Qwen / Amp / Windsurf / Gemini CLI** | Slash command, namespaced with the `aidevops-` prefix: `/aidevops-build-plus`, `/aidevops-automate`, `/aidevops-seo`, etc. |
|
|
2042
|
-
| **Aider** | No native slash command support — use a shell alias: `alias aider-build='aider --message-file ~/.aidevops/agents/build-plus.md'`. |
|
|
2043
|
-
|
|
2044
|
-
The `aidevops-` prefix differentiates framework commands from each client's native slash commands and groups them alphabetically in the command picker. It applies to **every** aidevops slash command — not just main agents — so `/aidevops-preflight`, `/aidevops-release`, `/aidevops-commit` etc. all sort together in your `/` menu.
|
|
2045
|
-
|
|
2046
|
-
Codex setup/update also installs global `AGENTS.md` guidance, native workflow
|
|
2047
|
-
skills and compatible lifecycle hooks. Build+ loads by default; use `/skills`
|
|
2048
|
-
for workflows and `/hooks` to review/trust new hooks. Existing personal settings
|
|
2049
|
-
are preserved. For full-access launch flags and runtime differences, see
|
|
2050
|
-
[Codex CLI integration](.agents/tools/ai-assistants/codex-cli.md).
|
|
2051
|
-
|
|
2052
|
-
#### Supported AI clients (14)
|
|
2053
|
-
|
|
2054
|
-
The framework installs itself across these clients. Slash commands, agent definitions, and (optionally) session-memory mining are wired up per-client by `setup.sh`, gated on per-client feature flags in `.agents/scripts/runtime-registry.sh`.
|
|
2055
|
-
|
|
2056
|
-
| Client | Slash commands | Agent dir | Memory mining | Notes |
|
|
2057
|
-
|---|---|---|---|---|
|
|
2058
|
-
| OpenCode | ✅ `~/.config/opencode/command/` | config-based | ✅ default | Native tab-through primary agents |
|
|
2059
|
-
| Claude Code | ✅ `~/.claude/commands/` | ✅ `~/.claude/agents/` | ✅ default | Full feature parity |
|
|
2060
|
-
| Codex CLI | ✅ native skills + legacy `~/.codex/prompts/` | Workflow skills | ✅ default | `$aidevops-<name>`; legacy `/prompts:aidevops-<name>` |
|
|
2061
|
-
| Cursor | ✅ `~/.cursor/commands/` (≥1.6) | ✅ `~/.cursor/agents/` | ✅ default | Frontmatter stripped (not supported) |
|
|
2062
|
-
| Droid (Factory) | ✅ `~/.factory/commands/` | — | opt-in | — |
|
|
2063
|
-
| Gemini CLI | ✅ `~/.gemini/commands/` | — | opt-in | Converted to TOML (`prompt = """..."""`) |
|
|
2064
|
-
| Kimi CLI | ✅ `~/.kimi/skills/<name>/SKILL.md` | ✅ `~/.kimi/agents/` | opt-in | Directory-per-skill + auto `name:` matching |
|
|
2065
|
-
| Qwen Code | ✅ `~/.qwen/commands/` | ✅ `~/.qwen/agents/` | opt-in | Sub-agents + skills |
|
|
2066
|
-
| Continue | ✅ `~/.continue/prompts/` | — | opt-in | `.prompt` ext + `invokable: true` |
|
|
2067
|
-
| Kiro | ✅ `~/.kiro/steering/` | — | opt-in | `inclusion: manual` for slash access |
|
|
2068
|
-
| Kilo Code | custom modes | — | opt-in | Uses modes instead of commands |
|
|
2069
|
-
| Windsurf | repo-local `.windsurf/workflows/` | — | ❌ (protobuf) | Symlinked by `aidevops init` |
|
|
2070
|
-
| Amp (Sourcegraph) | repo-local `.agents/commands/` | ✅ `~/.amp/agents/` | ❌ (cloud) | Path match is native |
|
|
2071
|
-
| Aider | shell alias workaround | — | ❌ (per-repo md) | Native custom commands open upstream |
|
|
2072
|
-
|
|
2073
|
-
**Feature flags** per client (`agents` / `commands` / `memory`) live in `runtime-registry.sh` and can be overridden at install time via environment variables:
|
|
2074
|
-
|
|
2075
|
-
```bash
|
|
2076
|
-
AIDEVOPS_FEATURE_MEMORY_CLAUDE_CODE=no setup.sh
|
|
2077
|
-
AIDEVOPS_FEATURE_COMMANDS_CURSOR=no setup.sh
|
|
2078
|
-
```
|
|
2079
|
-
|
|
2080
|
-
Memory mining defaults are deliberately conservative: only OpenCode, Claude Code, Codex, and Cursor are opted in by default. All other clients default to off — enable them case-by-case after reviewing what the mining job will read.
|
|
2081
|
-
|
|
2082
|
-
#### Endgame: progressive disclosure
|
|
2083
|
-
|
|
2084
|
-
The long-term direction is to make slash commands and `@mentions` unnecessary altogether. A progressive disclosure layer should load the right domain agents and tools into context based on the nature of the conversation — you should never have to remember agent names or prefix commands. The `aidevops-` slash commands documented above are a stepping stone: they standardise routing across every client we support, and will eventually be auto-invoked by the router rather than typed by hand.
|
|
2085
|
-
|
|
2086
|
-
### **Example Subagents with MCP Integration**
|
|
2087
|
-
|
|
2088
|
-
These are examples of subagents that have supporting MCPs enabled. See `.agents/` for 2,200+ sub agents, including callable skill, workflow and reference modules organized by domain.
|
|
2089
|
-
|
|
2090
|
-
| Agent | Purpose | MCPs Enabled |
|
|
2091
|
-
|-------|---------|--------------|
|
|
2092
|
-
| `@hostinger` | Hosting, WordPress, DNS, domains | hostinger-api |
|
|
2093
|
-
| `@hetzner` | Cloud servers, firewalls, volumes | hetzner-* (multi-account) |
|
|
2094
|
-
| `@wordpress` | Local dev, MainWP management | localwp, context7 |
|
|
2095
|
-
| `@seo` | Search Console, keyword research, domain intelligence | gsc, ahrefs, serper, context7 |
|
|
2096
|
-
| `@dataforseo` | SERP, keywords, backlinks, on-page analysis | (curl subagent) |
|
|
2097
|
-
| `@domain-research` | DNS intelligence: rDNS, subdomains, CNAMEs (THC + Reconeer) | (API-based) |
|
|
2098
|
-
| `@serper` | Google Search API (web, images, news, places) | serper |
|
|
2099
|
-
| `@list-keys` | List all configured API keys and storage locations | (read-only) |
|
|
2100
|
-
| `@code-standards` | Quality standards reference, compliance checking | context7 |
|
|
2101
|
-
| `@browser-automation` | Testing, scraping, DevTools | chrome-devtools, context7 |
|
|
2102
|
-
| `@performance` | Core Web Vitals, network analysis, accessibility | chrome-devtools |
|
|
2103
|
-
| `@git-platforms` | GitHub, GitLab, Gitea | context7 |
|
|
2104
|
-
| `@posthog` | Product analytics, feature flags, experiments, errors, and support | posthog |
|
|
2105
|
-
| `@sentry` | Error monitoring, Next.js SDK setup | sentry |
|
|
2106
|
-
| `@socket` | Dependency security scanning | socket |
|
|
2107
|
-
| `@security-analysis` | AI-powered vulnerability detection (OSV, Ferret, git history) | osv-scanner, gemini-cli-security |
|
|
2108
|
-
| `@secretlint` | Detect exposed secrets in code | (Docker-based) |
|
|
2109
|
-
| `@snyk` | Security vulnerability scanning | (API-based) |
|
|
2110
|
-
| `@auditing` | Code auditing services and security analysis | (API-based) |
|
|
2111
|
-
| `@agent-review` | Session analysis, agent improvement (under build-agent/) | (read/write only) |
|
|
2112
|
-
|
|
2113
|
-
### **Setup for OpenCode**
|
|
2114
|
-
|
|
2115
|
-
```bash
|
|
2116
|
-
# Install aidevops agents for OpenCode
|
|
2117
|
-
.agents/scripts/generate-opencode-agents.sh
|
|
2118
|
-
|
|
2119
|
-
# Check status
|
|
2120
|
-
.agents/scripts/generate-opencode-agents.sh # Shows status after generation
|
|
2121
|
-
```
|
|
2122
|
-
|
|
2123
|
-
### **Claude Marketplace**
|
|
2124
|
-
|
|
2125
|
-
aidevops is available in the Claude marketplace:
|
|
2126
|
-
|
|
2127
|
-
```bash
|
|
2128
|
-
/plugin marketplace add marcusquinn/aidevops
|
|
2129
|
-
/plugin install aidevops-all@aidevops
|
|
2130
|
-
```
|
|
2131
|
-
|
|
2132
|
-
**Agent Skills (SKILL.md):** Auto-discovered from `~/.aidevops/agents/` after running `setup.sh`. Compatible with any tool that supports the [Agent Skills standard](https://agentskills.io/specification).
|
|
2133
|
-
|
|
2134
|
-
### **Continuous Improvement with @agent-review**
|
|
2135
|
-
|
|
2136
|
-
**End every session by calling `@agent-review`** to analyze what worked and what didn't:
|
|
2137
|
-
|
|
2138
|
-
```text
|
|
2139
|
-
@agent-review analyze this session and suggest improvements to the agents used
|
|
2140
|
-
```
|
|
2141
|
-
|
|
2142
|
-
The review agent will:
|
|
2143
|
-
1. Identify which agents were used
|
|
2144
|
-
2. Evaluate missing, incorrect, or excessive information
|
|
2145
|
-
3. Suggest specific improvements to agent files
|
|
2146
|
-
4. Generate ready-to-apply edits
|
|
2147
|
-
5. **Optionally compose a PR** to contribute improvements back to aidevops
|
|
2148
|
-
|
|
2149
|
-
**This creates a feedback loop:**
|
|
2150
|
-
|
|
2151
|
-
```text
|
|
2152
|
-
Session → @agent-review → Improvements → Better Agents → Better Sessions
|
|
2153
|
-
↓
|
|
2154
|
-
PR to aidevops repo (optional)
|
|
2155
|
-
```
|
|
2156
|
-
|
|
2157
|
-
**Contributing improvements:**
|
|
2158
|
-
|
|
2159
|
-
```text
|
|
2160
|
-
@agent-review create a PR for improvement #2
|
|
2161
|
-
```
|
|
2162
|
-
|
|
2163
|
-
The agent will create a safe linked worktree, apply changes, and submit a PR to `marcusquinn/aidevops` with a structured description. Your real-world usage helps improve the framework for everyone.
|
|
2164
|
-
|
|
2165
|
-
**Code quality learning loop:**
|
|
2166
|
-
|
|
2167
|
-
The `@code-quality` agent also learns from issues. After fixing violations from SonarCloud, Codacy, ShellCheck, etc., it analyzes patterns and updates framework guidance to prevent recurrence:
|
|
2168
|
-
|
|
2169
|
-
```text
|
|
2170
|
-
Quality Issue → Fix Applied → Pattern Identified → Framework Updated → Issue Prevented
|
|
2171
|
-
```
|
|
2172
|
-
|
|
2173
|
-
## **Slash Commands (OpenCode)**
|
|
2174
|
-
|
|
2175
|
-
**Slash commands provide quick access to common workflows directly from the OpenCode prompt.** Type `/` to see available commands.
|
|
2176
|
-
|
|
2177
|
-
### **Available Commands**
|
|
2178
|
-
|
|
2179
|
-
**Planning & Task Management**:
|
|
2180
|
-
|
|
2181
|
-
| Command | Purpose |
|
|
2182
|
-
|---------|---------|
|
|
2183
|
-
| `/list-todo` | List tasks with sorting, filtering, and grouping |
|
|
2184
|
-
| `/save-todo` | Save discussion as task or plan (auto-detects complexity) |
|
|
2185
|
-
| `/plan-status` | Check status of plans in `TODO.md` and `todo/PLANS.md` |
|
|
2186
|
-
| `/create-prd` | Create a Product Requirements Document for complex features |
|
|
2187
|
-
| `/generate-tasks` | Generate implementation tasks from a PRD |
|
|
2188
|
-
| `/log-time-spent` | Log time spent on a task for tracking |
|
|
2189
|
-
| `/ready` | Show tasks with no open blockers (Beads integration) |
|
|
2190
|
-
| `/sync-beads` | Sync TODO.md/PLANS.md with Beads task graph |
|
|
2191
|
-
| `/remember` | Store knowledge for cross-session recall |
|
|
2192
|
-
| `/recall` | Search memories from previous sessions |
|
|
2193
|
-
|
|
2194
|
-
Plans are tracked in `TODO.md` (all tasks) and `todo/PLANS.md` (complex execution plans). Task dependencies are visualized with [Beads](https://github.com/steveyegge/beads).
|
|
2195
|
-
|
|
2196
|
-
**`/list-todo` options:**
|
|
2197
|
-
|
|
2198
|
-
| Option | Example | Purpose |
|
|
2199
|
-
|--------|---------|---------|
|
|
2200
|
-
| `--priority` | `/list-todo -p` | Sort by priority (high → low) |
|
|
2201
|
-
| `--estimate` | `/list-todo -e` | Sort by time estimate (shortest first) |
|
|
2202
|
-
| `--tag` | `/list-todo -t seo` | Filter by tag |
|
|
2203
|
-
| `--owner` | `/list-todo -o marcus` | Filter by assignee |
|
|
2204
|
-
| `--estimate` | `/list-todo --estimate "<2h"` | Filter by estimate range |
|
|
2205
|
-
| `--group-by` | `/list-todo -g tag` | Group by tag, owner, status, or estimate |
|
|
2206
|
-
| `--plans` | `/list-todo --plans` | Include full plan details |
|
|
2207
|
-
| `--compact` | `/list-todo --compact` | One-line per task |
|
|
2208
|
-
|
|
2209
|
-
**Time Tracking**: Tasks support time estimates as active session time (excluding AFK gaps) with the format `~4h started:2025-01-15T10:30Z`. The `session-time-helper.sh` analyses real session data to calibrate estimates vs actuals.
|
|
2210
|
-
|
|
2211
|
-
**Risk Levels**: Tasks support `risk:low/med/high` indicating human oversight needed:
|
|
2212
|
-
|
|
2213
|
-
| Risk | Oversight | Example |
|
|
2214
|
-
|------|-----------|---------|
|
|
2215
|
-
| `low` | Autonomous | Docs, formatting, simple refactors |
|
|
2216
|
-
| `med` | Supervised | Feature implementation, API changes |
|
|
2217
|
-
| `high` | Engaged | Security, data migrations, infrastructure |
|
|
2218
|
-
|
|
2219
|
-
Configure time tracking per-repo via `.aidevops.json`.
|
|
2220
|
-
|
|
2221
|
-
**Development Workflow** (typical order):
|
|
2222
|
-
|
|
2223
|
-
| Command | Purpose |
|
|
2224
|
-
|---------|---------|
|
|
2225
|
-
| `/context` | Build AI context with Repomix for complex tasks |
|
|
2226
|
-
| `/feature` | Start a new feature linked-worktree workflow |
|
|
2227
|
-
| `/bugfix` | Start a bugfix linked-worktree workflow |
|
|
2228
|
-
| `/hotfix` | Start an urgent hotfix workflow |
|
|
2229
|
-
| `/linters-local` | Run local linting (shfmt, ShellCheck, secretlint) |
|
|
2230
|
-
| `/code-audit-remote` | Run remote auditing (CodeRabbit, Codacy, SonarCloud) |
|
|
2231
|
-
| `/code-standards` | Check against documented quality standards |
|
|
2232
|
-
| `/code-simplifier` | Simplify and refine code for clarity and maintainability |
|
|
2233
|
-
| `/testing-setup` | Interactive per-repo testing infrastructure setup with bundle-aware defaults |
|
|
2234
|
-
| `/list-keys` | List all configured API keys and their storage locations |
|
|
2235
|
-
| `/performance` | Web performance audit (Core Web Vitals, Lighthouse, PageSpeed) |
|
|
2236
|
-
| `/pr` | Unified PR workflow (orchestrates all checks) |
|
|
2237
|
-
| `/review` | Review an issue, PR, local patch, branch, or commit through the shared review core |
|
|
2238
|
-
| `/cross-review` | Dispatch prompt to multiple AI models, diff results, auto-score |
|
|
2239
|
-
| `/tech-stack` | Detect technology stacks of URLs or find sites using specific technologies |
|
|
2240
|
-
| `/mission` | Scope a high-level goal into milestones and features for autonomous execution |
|
|
2241
|
-
| `/budget-analysis` | Analyze AI model spend, burn rate, and cost optimization opportunities |
|
|
2242
|
-
| `/report-token-use` | Generate a local per-session token, model, compaction, and MCP-use report |
|
|
2243
|
-
|
|
2244
|
-
**Content Workflow**:
|
|
2245
|
-
|
|
2246
|
-
| Command | Purpose |
|
|
2247
|
-
|---------|---------|
|
|
2248
|
-
| `/humanise` | Remove AI writing patterns, make text sound human |
|
|
2249
|
-
|
|
2250
|
-
**Media**:
|
|
2251
|
-
|
|
2252
|
-
| Command | Purpose |
|
|
2253
|
-
|---------|---------|
|
|
2254
|
-
| `/yt-dlp` | Download YouTube videos/audio/playlists, extract transcripts, convert local files |
|
|
2255
|
-
|
|
2256
|
-
**SEO Workflow**:
|
|
2257
|
-
|
|
2258
|
-
| Command | Purpose |
|
|
2259
|
-
|---------|---------|
|
|
2260
|
-
| `/keyword-research` | Seed keyword expansion with volume, CPC, difficulty |
|
|
2261
|
-
| `/autocomplete-research` | Google autocomplete long-tail discovery |
|
|
2262
|
-
| `/keyword-research-extended` | Full SERP analysis with weakness detection |
|
|
2263
|
-
| `/webmaster-keywords` | Keywords from GSC + Bing for your verified sites |
|
|
2264
|
-
| `/neuronwriter` | Content optimization with NLP term recommendations and scoring |
|
|
2265
|
-
| `/seo-export` | Export SEO data from GSC, Bing, Ahrefs, DataForSEO to TOON format |
|
|
2266
|
-
| `/seo-analyze` | Analyze exported data for quick wins, striking distance, low CTR |
|
|
2267
|
-
| `/seo-opportunities` | Combined export + analysis workflow |
|
|
2268
|
-
| `/seo-audit` | Comprehensive SEO audit: technical, on-page, content, E-E-A-T |
|
|
2269
|
-
|
|
2270
|
-
**SEO Debugging & Auditing** (subagents in `seo/`):
|
|
2271
|
-
|
|
2272
|
-
| Subagent | Purpose |
|
|
2273
|
-
|----------|---------|
|
|
2274
|
-
| `@seo-audit` | Comprehensive SEO audit: technical, on-page, content quality, E-E-A-T |
|
|
2275
|
-
| `@debug-opengraph` | Validate Open Graph meta tags, preview social sharing |
|
|
2276
|
-
| `@debug-favicon` | Validate favicon setup across platforms (ico, apple-touch, manifest) |
|
|
2277
|
-
|
|
2278
|
-
**Email Deliverability**:
|
|
2279
|
-
|
|
2280
|
-
| Command | Purpose |
|
|
2281
|
-
|---------|---------|
|
|
2282
|
-
| `/email-health-check` | Check SPF/DKIM/DMARC/MX records and blacklist status |
|
|
2283
|
-
|
|
2284
|
-
**Release Workflow** (in order):
|
|
2285
|
-
|
|
2286
|
-
| Command | Purpose |
|
|
2287
|
-
|---------|---------|
|
|
2288
|
-
| `/preflight` | Run quality checks before release |
|
|
2289
|
-
| `/changelog` | Update CHANGELOG.md with recent changes |
|
|
2290
|
-
| `/version-bump` | Bump version following semver |
|
|
2291
|
-
| `/release` | Full release workflow (bump, tag, GitHub release, auto-changelog) |
|
|
2292
|
-
| `/postflight` | Verify release health after deployment |
|
|
2293
|
-
|
|
2294
|
-
**Auto-Task Completion**: The release workflow automatically marks tasks as complete when commit messages reference them (e.g., `Closes t037`, `Fixes t042`). Tasks in `TODO.md` are updated with `completed:` timestamps.
|
|
2295
|
-
|
|
2296
|
-
**Documentation**:
|
|
2297
|
-
|
|
2298
|
-
| Command | Purpose |
|
|
2299
|
-
|---------|---------|
|
|
2300
|
-
| `/readme` | Create or update README.md (supports `--sections` for partial updates) |
|
|
2301
|
-
|
|
2302
|
-
**Meta/Improvement**:
|
|
2303
|
-
|
|
2304
|
-
| Command | Purpose |
|
|
2305
|
-
|---------|---------|
|
|
2306
|
-
| `/add-skill` | Import external skills from GitHub repos (SKILL.md, AGENTS.md, .cursorrules) |
|
|
2307
|
-
| `/agent-review` | Analyze session and suggest agent improvements |
|
|
2308
|
-
| `/session-analysis` | Find evidence-backed harness, model-routing, and repository optimisation opportunities |
|
|
2309
|
-
| `/session-review` | Review session for completeness and capture learnings |
|
|
2310
|
-
| `/full-loop` | End-to-end development loop (task → preflight → PR → postflight → deploy) |
|
|
2311
|
-
| `/preflight-loop` | Run preflight checks iteratively until all pass |
|
|
2312
|
-
| `/runners` | Batch dispatch tasks to parallel agents (task IDs, PR URLs, or descriptions) |
|
|
2313
|
-
| `/log-issue-aidevops` | Report issues with aidevops (gathers diagnostics, checks duplicates, creates GitHub issue) |
|
|
2314
|
-
|
|
2315
|
-
**AI Model Comparison**:
|
|
2316
|
-
|
|
2317
|
-
| Command | Purpose |
|
|
2318
|
-
|---------|---------|
|
|
2319
|
-
| `/compare-models` | Compare AI models by pricing, context, capabilities (with live web data) |
|
|
2320
|
-
| `/compare-models-free` | Compare AI models using offline embedded data only (no web fetches) |
|
|
2321
|
-
| `/score-responses` | Score and compare actual model responses with structured criteria |
|
|
2322
|
-
| `/route` | Suggest optimal model tier for a task description |
|
|
2323
|
-
|
|
2324
|
-
### Ralph Loop - Iterative AI Development
|
|
2325
|
-
|
|
2326
|
-
The **Ralph Loop** (named after Ralph Wiggum's persistent optimism) enables autonomous iterative development. The AI keeps working on a task until it's complete, automatically resolving issues that arise.
|
|
2327
|
-
|
|
2328
|
-
**How it works:**
|
|
2329
|
-
|
|
2330
|
-
```text
|
|
2331
|
-
Task → Implement → Check → Fix Issues → Re-check → ... → Complete
|
|
2332
|
-
↑ ↓
|
|
2333
|
-
└────────────────────┘ (loop until done)
|
|
2334
|
-
```
|
|
2335
|
-
|
|
2336
|
-
**Usage:**
|
|
2337
|
-
|
|
2338
|
-
```bash
|
|
2339
|
-
# Run quality checks iteratively until all pass
|
|
2340
|
-
/preflight-loop --auto-fix --max-iterations <MAX_ITERATIONS>
|
|
2341
|
-
|
|
2342
|
-
# Or run changed-file checks directly (the default)
|
|
2343
|
-
.agents/scripts/linters-local.sh
|
|
2344
|
-
|
|
2345
|
-
# Run every broad gate at a release boundary
|
|
2346
|
-
.agents/scripts/linters-local.sh --full
|
|
2347
|
-
```
|
|
2348
|
-
|
|
2349
|
-
**Note:** Store any API credentials securely via environment variables or `.env` files (never commit credentials to version control).
|
|
2350
|
-
|
|
2351
|
-
**Key features:**
|
|
2352
|
-
- Automatic issue detection and resolution
|
|
2353
|
-
- Configurable max iterations (prevents infinite loops)
|
|
2354
|
-
- Works with any quality check (linting, tests, builds)
|
|
2355
|
-
- Detailed logging of each iteration
|
|
2356
|
-
|
|
2357
|
-
See `.agents/workflows/ralph-loop.md` for the full workflow guide.
|
|
2358
|
-
|
|
2359
|
-
### Full Loop - End-to-End Development Automation
|
|
2360
|
-
|
|
2361
|
-
The **Full Loop** chains all development phases into a single automated workflow:
|
|
2362
|
-
|
|
2363
|
-
```text
|
|
2364
|
-
Task Development → Preflight → PR Create → PR Review → Postflight → Deploy
|
|
2365
|
-
```
|
|
2366
|
-
|
|
2367
|
-
**Usage:**
|
|
2368
|
-
|
|
2369
|
-
```bash
|
|
2370
|
-
# Start a full development loop
|
|
2371
|
-
/full-loop "Implement feature X with tests"
|
|
2372
|
-
|
|
2373
|
-
# With options
|
|
2374
|
-
/full-loop "Fix bug Y" --max-task-iterations 30 --skip-postflight
|
|
2375
|
-
```
|
|
2376
|
-
|
|
2377
|
-
**Options:**
|
|
2378
|
-
|
|
2379
|
-
| Option | Description |
|
|
2380
|
-
|--------|-------------|
|
|
2381
|
-
| `--max-task-iterations N` | Max iterations for task (default: 50) |
|
|
2382
|
-
| `--skip-preflight` | Skip preflight checks |
|
|
2383
|
-
| `--skip-postflight` | Skip postflight monitoring |
|
|
2384
|
-
| `--no-auto-pr` | Pause for manual PR creation |
|
|
2385
|
-
|
|
2386
|
-
The loop pauses for human input at merge approval, rollback decisions, and scope changes.
|
|
2387
|
-
|
|
2388
|
-
See `.agents/scripts/commands/full-loop.md` for complete documentation.
|
|
2389
|
-
|
|
2390
|
-
### Git Worktrees - Parallel Branch Development
|
|
2391
|
-
|
|
2392
|
-
Work on multiple branches simultaneously without stashing or switching. Each branch gets its own directory.
|
|
2393
|
-
|
|
2394
|
-
**Recommended: [Worktrunk](https://worktrunk.dev)** (`wt`) - Git worktree management with shell integration, CI status, and PR links:
|
|
2395
|
-
|
|
2396
|
-
```bash
|
|
2397
|
-
# Install (macOS/Linux)
|
|
2398
|
-
brew install max-sixty/worktrunk/wt && wt config shell install
|
|
2399
|
-
# Restart your shell for shell integration to take effect
|
|
2400
|
-
|
|
2401
|
-
# Create worktree + cd into it
|
|
2402
|
-
wt switch -c feature/my-feature
|
|
2403
|
-
|
|
2404
|
-
# Create worktree + start any AI CLI (-x runs command after switch)
|
|
2405
|
-
wt switch -c -x claude feature/ai-task
|
|
2406
|
-
|
|
2407
|
-
# List worktrees with CI status and PR links
|
|
2408
|
-
wt list
|
|
2409
|
-
|
|
2410
|
-
# Merge + cleanup (squash/rebase options)
|
|
2411
|
-
wt merge
|
|
2412
|
-
```
|
|
2413
|
-
|
|
2414
|
-
**Fallback** (no dependencies):
|
|
2415
|
-
|
|
2416
|
-
```bash
|
|
2417
|
-
~/.aidevops/agents/scripts/worktree-helper.sh add feature/my-feature
|
|
2418
|
-
# Creates: ~/Git/{repo}-feature-my-feature/ (cd there manually)
|
|
2419
|
-
~/.aidevops/agents/scripts/worktree-helper.sh list
|
|
2420
|
-
~/.aidevops/agents/scripts/worktree-helper.sh clean
|
|
2421
|
-
# Read-only count/byte inventory of retained recovery archives
|
|
2422
|
-
~/.aidevops/agents/scripts/worktree-helper.sh recovery
|
|
2423
|
-
```
|
|
2424
|
-
|
|
2425
|
-
Recovery inventory classifies attributable archives as protected or unknown and
|
|
2426
|
-
never deletes them. OpenCode session history can aid reconstruction, but it does
|
|
2427
|
-
not replace archive integrity evidence or authorize cleanup.
|
|
2428
|
-
|
|
2429
|
-
**Benefits:**
|
|
2430
|
-
- Run tests on one branch while coding on another
|
|
2431
|
-
- Compare implementations side-by-side
|
|
2432
|
-
- No context switching or stash management
|
|
2433
|
-
- Each AI session can work on a different branch
|
|
2434
|
-
|
|
2435
|
-
**Worktree-first workflow:** The pre-edit check now **enforces** worktrees as the default when creating branches, keeping your main directory on `main`. This prevents uncommitted changes from blocking branch switches and ensures parallel sessions don't inherit wrong branch state.
|
|
2436
|
-
|
|
2437
|
-
See `.agents/workflows/worktree.md` for the complete guide and `.agents/tools/git/worktrunk.md` for Worktrunk documentation.
|
|
2438
|
-
|
|
2439
|
-
### Session Management - Parallel AI Sessions
|
|
2440
|
-
|
|
2441
|
-
Spawn new AI sessions for parallel work or fresh context. The framework detects natural session completion points and suggests next steps.
|
|
2442
|
-
|
|
2443
|
-
**Completion signals:**
|
|
2444
|
-
|
|
2445
|
-
| Signal | Meaning |
|
|
2446
|
-
|--------|---------|
|
|
2447
|
-
| PR merged | Branch work complete |
|
|
2448
|
-
| Release published | Version shipped |
|
|
2449
|
-
| All tests passing | Quality gates satisfied |
|
|
2450
|
-
| User says "done" | Explicit completion |
|
|
2451
|
-
|
|
2452
|
-
**Spawning options:**
|
|
2453
|
-
|
|
2454
|
-
```bash
|
|
2455
|
-
# Background session (same terminal)
|
|
2456
|
-
opencode --non-interactive --prompt "Continue with feature X" &
|
|
2457
|
-
|
|
2458
|
-
# New terminal tab (macOS)
|
|
2459
|
-
osascript -e 'tell application "Terminal" to do script "cd ~/Git/project && opencode"'
|
|
2460
|
-
|
|
2461
|
-
# Worktree-based (isolated branch) - recommended
|
|
2462
|
-
wt switch -c -x opencode feature/next-feature # Worktrunk: create + start AI CLI
|
|
2463
|
-
# Or fallback:
|
|
2464
|
-
# ~/.aidevops/agents/scripts/worktree-helper.sh add feature/next-feature
|
|
2465
|
-
# cd ~/Git/{repo}-feature-next-feature && opencode
|
|
2466
|
-
```
|
|
2467
|
-
|
|
2468
|
-
**Session handoff pattern:**
|
|
2469
|
-
|
|
2470
|
-
When ending a session, the AI provides a continuation prompt for the next session:
|
|
2471
|
-
|
|
2472
|
-
```markdown
|
|
2473
|
-
## Continuation Prompt
|
|
2474
|
-
[Copy this to start a new session with full context]
|
|
2475
|
-
```
|
|
2476
|
-
|
|
2477
|
-
See `.agents/workflows/session-manager.md` for the complete guide.
|
|
2478
|
-
|
|
2479
|
-
### Cross-Session Memory System
|
|
2480
|
-
|
|
2481
|
-
**"Compound, then clear"** - Sessions should build on each other. The memory system stores knowledge, patterns, and learnings for future sessions using SQLite FTS5 for fast full-text search, with opt-in semantic similarity search via vector embeddings.
|
|
2482
|
-
|
|
2483
|
-
**Slash commands:**
|
|
2484
|
-
|
|
2485
|
-
| Command | Purpose |
|
|
2486
|
-
|---------|---------|
|
|
2487
|
-
| `/remember {content}` | Store a memory with AI-assisted categorization |
|
|
2488
|
-
| `/recall {query}` | Search memories by keyword |
|
|
2489
|
-
| `/recall --recent` | Show 10 most recent memories |
|
|
2490
|
-
| `/recall --auto-only` | Search only auto-captured memories |
|
|
2491
|
-
| `/recall --stats` | Show memory statistics |
|
|
2492
|
-
| `/memory-log` | Show recent auto-captured memories |
|
|
2493
|
-
| `/patterns {task}` | Show success/failure patterns for a task type |
|
|
2494
|
-
| `/route {task}` | Suggest optimal model tier for a task |
|
|
2495
|
-
|
|
2496
|
-
**Memory types:**
|
|
2497
|
-
|
|
2498
|
-
| Type | Use For |
|
|
2499
|
-
|------|---------|
|
|
2500
|
-
| `WORKING_SOLUTION` | Fixes that worked |
|
|
2501
|
-
| `FAILED_APPROACH` | What didn't work (avoid repeating) |
|
|
2502
|
-
| `CODEBASE_PATTERN` | Project conventions |
|
|
2503
|
-
| `USER_PREFERENCE` | Developer preferences |
|
|
2504
|
-
| `TOOL_CONFIG` | Tool setup notes |
|
|
2505
|
-
| `DECISION` | Process, workflow, or policy choices (naming, release cadence, branching) |
|
|
2506
|
-
| `CONTEXT` | Background info |
|
|
2507
|
-
| `ARCHITECTURAL_DECISION` | System-level architecture (service boundaries, data flow, tech stack) |
|
|
2508
|
-
| `ERROR_FIX` | Bug fixes and patches |
|
|
2509
|
-
| `OPEN_THREAD` | Unresolved questions or follow-ups |
|
|
2510
|
-
| `SUCCESS_PATTERN` | Approaches that consistently work |
|
|
2511
|
-
| `FAILURE_PATTERN` | Approaches that consistently fail |
|
|
2512
|
-
|
|
2513
|
-
**Semantic search (opt-in):**
|
|
2514
|
-
|
|
2515
|
-
```bash
|
|
2516
|
-
# Enable semantic similarity search (~90MB model download)
|
|
2517
|
-
memory-embeddings-helper.sh setup
|
|
2518
|
-
|
|
2519
|
-
# Search by meaning, not just keywords
|
|
2520
|
-
memory-helper.sh recall "how to optimize queries" --semantic
|
|
2521
|
-
```
|
|
2522
|
-
|
|
2523
|
-
**Pattern tracking:**
|
|
2524
|
-
|
|
2525
|
-
```bash
|
|
2526
|
-
# Record what worked (via memory system)
|
|
2527
|
-
memory-helper.sh store --type SUCCESS_PATTERN --content "Structured debugging found root cause" --tags "bugfix,standard"
|
|
2528
|
-
|
|
2529
|
-
# Record what failed
|
|
2530
|
-
memory-helper.sh store --type FAILURE_PATTERN --content "Blind refactor without tests caused regressions" --tags "refactor"
|
|
2531
|
-
|
|
2532
|
-
# Get suggestions for a new task
|
|
2533
|
-
memory-helper.sh recall "refactor auth middleware" --semantic
|
|
2534
|
-
```
|
|
2535
|
-
|
|
2536
|
-
**Auto-capture:** AI agents automatically store memories using `--auto` flag when they detect working solutions, failed approaches, or decisions. Privacy filters strip `<private>` tags and reject secret patterns.
|
|
2537
|
-
|
|
2538
|
-
**CLI usage:**
|
|
2539
|
-
|
|
2540
|
-
```bash
|
|
2541
|
-
# Store a memory
|
|
2542
|
-
~/.aidevops/agents/scripts/memory-helper.sh store --type "WORKING_SOLUTION" --content "Fixed CORS with nginx headers" --tags "cors,nginx"
|
|
2543
|
-
|
|
2544
|
-
# Store auto-captured memory (from AI agent)
|
|
2545
|
-
~/.aidevops/agents/scripts/memory-helper.sh store --auto --content "Fixed CORS with nginx headers" --type WORKING_SOLUTION
|
|
2546
|
-
|
|
2547
|
-
# Recall memories (keyword search - default)
|
|
2548
|
-
~/.aidevops/agents/scripts/memory-helper.sh recall "cors"
|
|
2549
|
-
|
|
2550
|
-
# Recall memories (semantic similarity - opt-in)
|
|
2551
|
-
~/.aidevops/agents/scripts/memory-helper.sh recall "cors" --semantic
|
|
2552
|
-
|
|
2553
|
-
# Show auto-capture log
|
|
2554
|
-
~/.aidevops/agents/scripts/memory-helper.sh log
|
|
2555
|
-
|
|
2556
|
-
# View statistics (includes auto-capture counts)
|
|
2557
|
-
~/.aidevops/agents/scripts/memory-helper.sh stats
|
|
2558
|
-
|
|
2559
|
-
# Maintenance
|
|
2560
|
-
~/.aidevops/agents/scripts/memory-helper.sh validate # Check for stale entries
|
|
2561
|
-
~/.aidevops/agents/scripts/memory-helper.sh prune # Remove stale memories
|
|
2562
|
-
|
|
2563
|
-
# Namespaces (per-runner memory isolation)
|
|
2564
|
-
~/.aidevops/agents/scripts/memory-helper.sh --namespace my-runner store --content "Runner learning"
|
|
2565
|
-
~/.aidevops/agents/scripts/memory-helper.sh --namespace my-runner recall "query" --shared
|
|
2566
|
-
~/.aidevops/agents/scripts/memory-helper.sh namespaces # List all namespaces
|
|
2567
|
-
```
|
|
2568
|
-
|
|
2569
|
-
**Storage:** `~/.aidevops/.agent-workspace/memory/memory.db` (+ optional `embeddings.db` for semantic search, `namespaces/` for per-runner isolation)
|
|
2570
|
-
|
|
2571
|
-
#### Session mining (cross-client)
|
|
2572
|
-
|
|
2573
|
-
Beyond explicit `/remember` calls, aidevops can harvest structured session data from each supported AI client's on-disk conversation history. This turns every prior session — regardless of which tool you were using — into searchable context for future sessions.
|
|
2574
|
-
|
|
2575
|
-
Per-client storage paths and formats (see `runtime-registry.sh`):
|
|
2576
|
-
|
|
2577
|
-
| Client | Storage path | Format | Default |
|
|
2578
|
-
|---|---|---|---|
|
|
2579
|
-
| OpenCode | `~/.local/share/opencode/opencode.db` | SQLite | ✅ on |
|
|
2580
|
-
| Claude Code | `~/.claude/projects/` | JSONL per project | ✅ on |
|
|
2581
|
-
| Codex CLI | `~/.codex/sessions/` | JSONL, date-partitioned | ✅ on |
|
|
2582
|
-
| Cursor | `~/Library/Application Support/Cursor/User/workspaceStorage/` | SQLite (`state.vscdb`) | ✅ on |
|
|
2583
|
-
| Droid | `~/.factory/sessions/` | JSONL per session | opt-in |
|
|
2584
|
-
| Gemini CLI | `~/.gemini/tmp/` | JSON per session | opt-in |
|
|
2585
|
-
| Continue | `~/.continue/sessions/` | JSON per session | opt-in |
|
|
2586
|
-
| Kilo Code | `~/Library/.../kilocode.kilo-code/tasks/` | JSON (Anthropic schema) | opt-in |
|
|
2587
|
-
| Kiro | `~/Library/Application Support/Kiro/User/workspaceStorage/` | SQLite | opt-in |
|
|
2588
|
-
| Kimi CLI | `~/.kimi/sessions/<id>/context.jsonl` | JSONL | opt-in |
|
|
2589
|
-
| Qwen Code | `~/.qwen/tmp/` | JSON per session | opt-in |
|
|
2590
|
-
| Windsurf | `~/.codeium/windsurf/cascade/` | protobuf (opaque) | ❌ unsupported |
|
|
2591
|
-
| Amp | server-side (cloud) | needs API auth | ❌ unsupported |
|
|
2592
|
-
| Aider | `<repo>/.aider.chat.history.md` | markdown transcript | ❌ unsupported |
|
|
2593
|
-
|
|
2594
|
-
**Defaults are deliberately conservative.** Only the four tier-1 clients — OpenCode, Claude Code, Codex, and Cursor — have memory mining enabled by default. They have the most mature, stable, documented formats and are the ones most likely to contain the full interactive history you'd want to search.
|
|
2595
|
-
|
|
2596
|
-
For every other client, memory mining is **opt-in per runtime**. Enable it with:
|
|
2597
|
-
|
|
2598
|
-
```bash
|
|
2599
|
-
AIDEVOPS_FEATURE_MEMORY_GEMINI_CLI=yes setup.sh
|
|
2600
|
-
AIDEVOPS_FEATURE_MEMORY_CONTINUE=yes setup.sh
|
|
2601
|
-
```
|
|
2602
|
-
|
|
2603
|
-
**Privacy note.** Session files contain everything you typed — including secrets, credentials, and file contents pasted into prompts. The mining pipeline runs secretlint-style scrubbing at ingestion and defaults to local-only storage. Never sync the memory DB to a shared or cloud location without reviewing what's in it.
|
|
2604
|
-
|
|
2605
|
-
See `.agents/memory/README.md` for complete documentation.
|
|
2606
|
-
|
|
2607
|
-
### **Installation**
|
|
2608
|
-
|
|
2609
|
-
Slash commands are automatically installed by `setup.sh` for both OpenCode and Claude Code:
|
|
2610
|
-
|
|
2611
|
-
```bash
|
|
2612
|
-
# OpenCode commands deployed to:
|
|
2613
|
-
~/.config/opencode/command/
|
|
2614
|
-
|
|
2615
|
-
# Claude Code commands deployed to:
|
|
2616
|
-
~/.claude/commands/
|
|
2617
|
-
|
|
2618
|
-
# Regenerate commands manually:
|
|
2619
|
-
.agents/scripts/generate-opencode-commands.sh
|
|
2620
|
-
.agents/scripts/generate-claude-commands.sh
|
|
2621
|
-
```
|
|
2622
|
-
|
|
2623
|
-
Both generators read from the same source (`.agents/scripts/commands/*.md`), ensuring command parity across tools.
|
|
2624
|
-
|
|
2625
|
-
### **Usage**
|
|
2626
|
-
|
|
2627
|
-
In OpenCode or Claude Code, type the command at the prompt:
|
|
2628
|
-
|
|
2629
|
-
```text
|
|
2630
|
-
/preflight
|
|
2631
|
-
/release minor
|
|
2632
|
-
/feature add-user-authentication
|
|
2633
|
-
```
|
|
2634
|
-
|
|
2635
|
-
Commands invoke the corresponding workflow subagent with appropriate context.
|
|
2636
|
-
|
|
2637
|
-
---
|
|
2638
|
-
|
|
2639
|
-
### **Agent Lifecycle (Three Tiers)**
|
|
2640
|
-
|
|
2641
|
-
User-created agents survive `aidevops update`. Agents progress through tiers as they mature:
|
|
2642
|
-
|
|
2643
|
-
| Tier | Location | Purpose | Survives Update |
|
|
2644
|
-
|------|----------|---------|-----------------|
|
|
2645
|
-
| **Draft** | `~/.aidevops/agents/draft/` | R&D, experimental, auto-created by orchestration tasks | Yes |
|
|
2646
|
-
| **Custom** | `~/.aidevops/agents/custom/` | User's permanent private agents | Yes |
|
|
2647
|
-
| **Shared** | `.agents/` in repo | Open-source, distributed to all users | Managed by repo |
|
|
2648
|
-
|
|
2649
|
-
**Promotion workflow:** Draft agents that prove useful can be promoted to custom (private) or shared (open-source via PR). Orchestration agents can create drafts in `draft/` for reusable parallel processing context.
|
|
2650
|
-
|
|
2651
|
-
### **Creating Custom Agents**
|
|
2652
|
-
|
|
2653
|
-
Create a markdown file in `~/.config/opencode/agent/` (OpenCode) or reference in your AI's system prompt:
|
|
2654
|
-
|
|
2655
|
-
```markdown
|
|
2656
|
-
---
|
|
2657
|
-
description: Short description of what this agent does
|
|
2658
|
-
mode: subagent
|
|
2659
|
-
temperature: 0.2
|
|
2660
|
-
tools:
|
|
2661
|
-
bash: true
|
|
2662
|
-
specific-mcp_*: true
|
|
2663
|
-
---
|
|
2664
|
-
|
|
2665
|
-
# Agent Name
|
|
2666
|
-
|
|
2667
|
-
Detailed instructions for the agent...
|
|
2668
|
-
```
|
|
2669
|
-
|
|
2670
|
-
See `.agents/opencode-integration.md` for complete documentation.
|
|
2671
|
-
|
|
2672
|
-
---
|
|
2673
|
-
|
|
2674
|
-
## **Usage Examples**
|
|
2675
|
-
|
|
2676
|
-
### **Server Management**
|
|
2677
|
-
|
|
2678
|
-
```bash
|
|
2679
|
-
# List all servers across providers
|
|
2680
|
-
./.agents/scripts/servers-helper.sh list
|
|
2681
|
-
|
|
2682
|
-
# Connect to specific servers
|
|
2683
|
-
./.agents/scripts/hostinger-helper.sh connect example.com
|
|
2684
|
-
./.agents/scripts/hetzner-helper.sh connect main web-server
|
|
2685
|
-
|
|
2686
|
-
# Execute commands remotely
|
|
2687
|
-
./.agents/scripts/hostinger-helper.sh exec example.com "uptime"
|
|
2688
|
-
```
|
|
2689
|
-
|
|
2690
|
-
### **Monitoring & Uptime (Updown.io)**
|
|
2691
|
-
|
|
2692
|
-
```bash
|
|
2693
|
-
# List all monitors
|
|
2694
|
-
./.agents/scripts/updown-helper.sh list
|
|
2695
|
-
|
|
2696
|
-
# Add a new website check
|
|
2697
|
-
./.agents/scripts/updown-helper.sh add https://example.com "My Website"
|
|
2698
|
-
```
|
|
2699
|
-
|
|
2700
|
-
### **Domain & DNS Management**
|
|
2701
|
-
|
|
2702
|
-
```bash
|
|
2703
|
-
# Purchase and configure domain
|
|
2704
|
-
./.agents/scripts/spaceship-helper.sh purchase example.com
|
|
2705
|
-
./.agents/scripts/dns-helper.sh cloudflare add-record example.com A 192.168.1.1
|
|
2706
|
-
|
|
2707
|
-
# Check domain availability
|
|
2708
|
-
./.agents/scripts/101domains-helper.sh check-availability example.com
|
|
2709
|
-
```
|
|
2710
|
-
|
|
2711
|
-
### **Strategic Keyword Research**
|
|
2712
|
-
|
|
2713
|
-
```bash
|
|
2714
|
-
# Basic keyword research with volume, CPC, difficulty
|
|
2715
|
-
./.agents/scripts/keyword-research-helper.sh research "seo tools" --limit 20
|
|
2716
|
-
|
|
2717
|
-
# Google autocomplete long-tail discovery
|
|
2718
|
-
./.agents/scripts/keyword-research-helper.sh autocomplete "how to" --provider both
|
|
2719
|
-
|
|
2720
|
-
# Extended research with SERP weakness detection
|
|
2721
|
-
./.agents/scripts/keyword-research-helper.sh extended "keywords" --quick
|
|
2722
|
-
|
|
2723
|
-
# Competitor keyword research
|
|
2724
|
-
./.agents/scripts/keyword-research-helper.sh extended --competitor ahrefs.com --limit 50
|
|
2725
|
-
|
|
2726
|
-
# Keyword gap analysis (find keywords competitor ranks for but you don't)
|
|
2727
|
-
./.agents/scripts/keyword-research-helper.sh extended --gap semrush.com,ahrefs.com
|
|
2728
|
-
|
|
2729
|
-
# Domain research (all keywords a domain ranks for)
|
|
2730
|
-
./.agents/scripts/keyword-research-helper.sh extended --domain example.com --limit 100
|
|
2731
|
-
```
|
|
2732
|
-
|
|
2733
|
-
**Features:**
|
|
2734
|
-
|
|
2735
|
-
- **6 Research Modes**: Keyword expansion, autocomplete, domain research, competitor research, keyword gap, extended SERP analysis
|
|
2736
|
-
- **17 SERP Weaknesses**: Low domain score, no backlinks, thin content, UGC-heavy, non-HTTPS, and more
|
|
2737
|
-
- **KeywordScore Algorithm**: 0-100 score based on weakness count, volume, and difficulty
|
|
2738
|
-
- **Multi-Provider**: DataForSEO (primary), Serper (autocomplete), Ahrefs (domain ratings)
|
|
2739
|
-
- **Locale Support**: US/UK/CA/AU/DE/FR/ES with saved preferences
|
|
2740
|
-
- **Output Formats**: Markdown tables (TUI) and CSV export to ~/Downloads
|
|
2741
|
-
|
|
2742
|
-
### **Quality Control & Performance**
|
|
2743
|
-
|
|
2744
|
-
```bash
|
|
2745
|
-
# Run quality analysis with auto-fixes
|
|
2746
|
-
bash .agents/scripts/qlty-cli.sh check 10
|
|
2747
|
-
bash .agents/scripts/qlty-cli.sh fix
|
|
2748
|
-
|
|
2749
|
-
# Run chunked Codacy analysis for large repositories
|
|
2750
|
-
bash .agents/scripts/codacy-cli-chunked.sh quick # Fast analysis
|
|
2751
|
-
bash .agents/scripts/codacy-cli-chunked.sh chunked # Full analysis
|
|
2752
|
-
|
|
2753
|
-
# AI coding assistance
|
|
2754
|
-
bash .agents/scripts/ampcode-cli.sh scan ./src
|
|
2755
|
-
bash .agents/scripts/continue-cli.sh review
|
|
2756
|
-
|
|
2757
|
-
# Audit website performance
|
|
2758
|
-
./.agents/scripts/pagespeed-helper.sh wordpress https://example.com
|
|
2759
|
-
```
|
|
2760
|
-
|
|
2761
|
-
## **Documentation & Resources**
|
|
2762
|
-
|
|
2763
|
-
**Wiki Guides:**
|
|
2764
|
-
|
|
2765
|
-
- **[Getting Started](.wiki/Getting-Started.md)** - Installation and setup
|
|
2766
|
-
- **[Configuration Reference](.agents/reference/configuration.md)** - All JSONC/JSON config options, types, defaults, and examples
|
|
2767
|
-
- **[CLI Reference](.wiki/CLI-Reference.md)** - aidevops command documentation
|
|
2768
|
-
- **[MCP Integrations](.wiki/MCP-Integrations.md)** - MCP servers setup
|
|
2769
|
-
- **[Providers](.wiki/Providers.md)** - Service provider configurations
|
|
2770
|
-
- **[Workflows Guide](.wiki/Workflows-Guide.md)** - Development workflows
|
|
2771
|
-
- **[The Agent Directory](.wiki/The-Agent-Directory.md)** - Agent file structure
|
|
2772
|
-
- **[Understanding AGENTS.md](.wiki/Understanding-AGENTS-md.md)** - How agents work
|
|
2773
|
-
|
|
2774
|
-
**Agent Guides** (in `.agents/`):
|
|
2775
|
-
|
|
2776
|
-
- **[API Integrations](.agents/aidevops/api-integrations.md)** - Service APIs
|
|
2777
|
-
- **[Browser Automation](.agents/tools/browser/browser-automation.md)** - 8 tools + anti-detect stack: decision tree, parallel, extensions, fingerprinting
|
|
2778
|
-
- **[Device Emulation](.agents/tools/browser/playwright-emulation.md)** - Mobile/tablet testing: 100+ device presets, viewport, geolocation, locale, dark mode
|
|
2779
|
-
- **[serve-sim](.agents/tools/mobile/serve-sim.md)** - Apple Simulator browser preview/control for mobile app QA
|
|
2780
|
-
- **[Anti-Detect Browser](.agents/tools/browser/anti-detect-browser.md)** - Multi-profile management, fingerprint rotation, proxy integration
|
|
2781
|
-
- **[Web Performance](.agents/tools/performance/performance.md)** - Core Web Vitals, network dependencies, accessibility (Chrome DevTools MCP)
|
|
2782
|
-
- **[PageSpeed](.agents/tools/browser/pagespeed.md)** - Lighthouse CLI and PageSpeed Insights API
|
|
2783
|
-
- **[Pandoc](.agents/tools/conversion/pandoc.md)** - Document format conversion
|
|
2784
|
-
- **[Security](.agents/aidevops/security.md)** - Enterprise security standards
|
|
2785
|
-
|
|
2786
|
-
**Provider-Specific Guides:** Hostinger, Hetzner, Cloudflare, WordPress, Git platforms, Vercel CLI, Coolify CLI, and more in `.agents/`
|
|
2787
|
-
|
|
2788
|
-
## **Architecture**
|
|
2789
|
-
|
|
2790
|
-
```text
|
|
2791
|
-
aidevops/
|
|
2792
|
-
├── setup.sh # Main setup script
|
|
2793
|
-
├── AGENTS.md # AI agent guidance (dev)
|
|
2794
|
-
├── .agents/ # Agents and documentation
|
|
2795
|
-
│ ├── AGENTS.md # User guide (deployed to ~/.aidevops/agents/)
|
|
2796
|
-
│ ├── *.md # 14 main agents, plus excluded root guides
|
|
2797
|
-
│ ├── scripts/ # 2,010+ helper scripts (including modules; tests excluded)
|
|
2798
|
-
│ ├── tools/ # Cross-domain utilities (video, browser, git, etc.)
|
|
2799
|
-
│ ├── services/ # External service integrations
|
|
2800
|
-
│ └── workflows/ # Development process guides
|
|
2801
|
-
├── configs/ # Configuration templates
|
|
2802
|
-
├── ssh/ # SSH key management
|
|
2803
|
-
└── templates/ # Reusable templates
|
|
2804
|
-
```
|
|
2805
|
-
|
|
2806
|
-
## **Configuration & Setup**
|
|
2807
|
-
|
|
2808
|
-
aidevops is configured through two JSONC/JSON files that control framework behaviour, model routing, quality gates, and user preferences. Both are optional -- sensible defaults apply out of the box.
|
|
2809
|
-
|
|
2810
|
-
| File | Purpose | CLI |
|
|
2811
|
-
|------|---------|-----|
|
|
2812
|
-
| [`~/.config/aidevops/config.jsonc`](.agents/reference/configuration.md#configjsonc--full-reference) | Framework config: updates, models, safety, quality, orchestration, paths | `aidevops config` |
|
|
2813
|
-
| [`~/.config/aidevops/settings.json`](.agents/reference/configuration.md#settingsjson--full-reference) | User preferences: onboarding, UI, model routing defaults | `settings-helper.sh` |
|
|
2814
|
-
|
|
2815
|
-
**Quick examples:**
|
|
2816
|
-
|
|
2817
|
-
```bash
|
|
2818
|
-
# Disable automatic updates
|
|
2819
|
-
aidevops config set updates.auto_update false
|
|
2820
|
-
|
|
2821
|
-
# Use thinking-tier verification for destructive operations
|
|
2822
|
-
aidevops config set safety.verification_tier thinking
|
|
2823
|
-
|
|
2824
|
-
# View all current config values
|
|
2825
|
-
aidevops config list
|
|
2826
|
-
|
|
2827
|
-
# Validate config against schema
|
|
2828
|
-
aidevops config validate
|
|
2829
|
-
```
|
|
2830
|
-
|
|
2831
|
-
**Precedence:** Environment variables (`AIDEVOPS_*`) > config file > built-in defaults. See the **[full configuration reference](.agents/reference/configuration.md)** for every option, type, default, and example.
|
|
2832
|
-
|
|
2833
|
-
### Service Credentials
|
|
2834
|
-
|
|
2835
|
-
Service-specific credentials (hosting, DNS, Git platforms, etc.) use a separate template system:
|
|
2836
|
-
|
|
2837
|
-
```bash
|
|
2838
|
-
# 1. Copy and customize configuration templates
|
|
2839
|
-
cp configs/hostinger-config.json.txt configs/hostinger-config.json
|
|
2840
|
-
cp configs/hetzner-config.json.txt configs/hetzner-config.json
|
|
2841
|
-
# Edit with your actual credentials
|
|
2842
|
-
|
|
2843
|
-
# 2. Test connections
|
|
2844
|
-
./.agents/scripts/servers-helper.sh list
|
|
2845
|
-
|
|
2846
|
-
# 3. Install MCP integrations (optional)
|
|
2847
|
-
bash .agents/scripts/setup-mcp-integrations.sh all
|
|
2848
|
-
```
|
|
2849
|
-
|
|
2850
|
-
See [.agents/reference/configuration.md](.agents/reference/configuration.md#service-configuration-templates) for details on the template system and credential security.
|
|
2851
|
-
|
|
2852
|
-
## **Security & Best Practices**
|
|
2853
|
-
|
|
2854
|
-
**Credential Management:**
|
|
2855
|
-
|
|
2856
|
-
- Store API tokens in separate config files (never hardcode)
|
|
2857
|
-
- Use Ed25519 SSH keys (modern, secure, fast)
|
|
2858
|
-
- Set proper file permissions (600 for configs)
|
|
2859
|
-
- Regular key rotation and access audits
|
|
2860
|
-
|
|
2861
|
-
### Multi-Tenant Credential Storage
|
|
2862
|
-
|
|
2863
|
-
Manage multiple accounts/clients per service with isolated credential sets:
|
|
2864
|
-
|
|
2865
|
-
```bash
|
|
2866
|
-
# Create a new tenant
|
|
2867
|
-
credential-helper.sh create client-acme
|
|
2868
|
-
|
|
2869
|
-
# Switch active tenant
|
|
2870
|
-
credential-helper.sh switch client-acme
|
|
2871
|
-
|
|
2872
|
-
# Set credentials for current tenant
|
|
2873
|
-
credential-helper.sh set GITHUB_TOKEN ghp_xxx
|
|
2874
|
-
|
|
2875
|
-
# Per-project override (gitignored)
|
|
2876
|
-
echo "client-acme" > .aidevops-tenant
|
|
2877
|
-
|
|
2878
|
-
# Export for scripts
|
|
2879
|
-
source <(credential-helper.sh export)
|
|
2880
|
-
```
|
|
2881
|
-
|
|
2882
|
-
**Resolution priority:** Project `.aidevops-tenant` → Global active tenant → Default
|
|
2883
|
-
|
|
2884
|
-
See `.agents/tools/credentials/multi-tenant.md` for complete documentation.
|
|
2885
|
-
|
|
2886
|
-
**Quality Assurance:**
|
|
2887
|
-
|
|
2888
|
-
- Multi-platform analysis (SonarCloud, CodeFactor, Codacy, CodeRabbit, Qlty, Snyk)
|
|
2889
|
-
- Automated security monitoring and vulnerability detection
|
|
2890
|
-
|
|
2891
|
-
## **Contributing & License**
|
|
2892
|
-
|
|
2893
|
-
**Contributing:**
|
|
2894
|
-
|
|
2895
|
-
1. Fork the repository
|
|
2896
|
-
2. Create safe linked worktree for your contribution
|
|
2897
|
-
3. Add provider support or improvements
|
|
2898
|
-
4. Test with your infrastructure
|
|
2899
|
-
5. Submit pull request
|
|
2900
|
-
|
|
2901
|
-
**License:** MIT License - see [LICENSE](LICENSE) file for details
|
|
2902
|
-
**Created by Marcus Quinn** - Copyright © 2025-2026
|
|
2903
|
-
|
|
2904
|
-
---
|
|
2905
|
-
|
|
2906
|
-
## **What This Framework Achieves**
|
|
2907
|
-
|
|
2908
|
-
**For You:**
|
|
2909
|
-
|
|
2910
|
-
- Autonomous project management — dispatch a mission and let AI agents handle milestones, validation, and delivery across days
|
|
2911
|
-
- Cross-domain operations — code, automation, business, marketing, legal, sales, content, video, research, SEO, social media, health, and accounts managed through one platform
|
|
2912
|
-
- Multi-model safety — destructive operations verified by a second AI provider before execution
|
|
2913
|
-
- Enterprise-grade quality — multi-platform analysis, automated security monitoring, continual improvement loops
|
|
2914
|
-
- Infrastructure management — 30+ service integrations with standardized commands across all providers
|
|
2915
|
-
|
|
2916
|
-
**For Your AI Agents:**
|
|
2917
|
-
|
|
2918
|
-
- Autonomous supervisor — pulse runs every 2 minutes, merging PRs, dispatching workers, killing stuck processes, advancing missions
|
|
2919
|
-
- Operational intelligence — struggle-ratio detection, orphaned PR recovery, circuit breaker, dynamic concurrency
|
|
2920
|
-
- Cost-aware routing — provider-aware model selection across OpenAI, Anthropic, Gemini, Cursor, Grok, and local models with budget tracking
|
|
2921
|
-
- Progressive context — 2,200+ sub agents available on demand, project bundles auto-configuring quality gates and model tiers
|
|
2922
|
-
- Self-improving — session mining extracts learnings, quality findings auto-create tasks, patterns feed back into agent prompts
|
|
2923
|
-
|
|
2924
|
-
**Get Started:**
|
|
2925
|
-
|
|
2926
|
-
```bash
|
|
2927
|
-
# npm (recommended)
|
|
2928
|
-
npm install -g aidevops && aidevops update
|
|
2929
|
-
|
|
2930
|
-
# Bun (fast alternative)
|
|
2931
|
-
bun install -g aidevops && aidevops update
|
|
2932
|
-
|
|
2933
|
-
# Homebrew
|
|
2934
|
-
brew install marcusquinn/tap/aidevops && aidevops update
|
|
2935
|
-
|
|
2936
|
-
# Direct from source
|
|
2937
|
-
bash <(curl -fsSL https://aidevops.sh/install)
|
|
2938
|
-
```
|
|
2939
|
-
|
|
2940
|
-
**An AI operations platform for launching and managing projects across every business domain — from code to content, infrastructure to invoicing.**
|
|
2941
|
-
|
|
2942
|
-
## Star History
|
|
646
|
+
This project was created and is maintained with
|
|
647
|
+
[aidevops.sh](https://aidevops.sh).
|
|
2943
648
|
|
|
2944
|
-
|
|
649
|
+
[View marcusquinn on GitHub](https://github.com/marcusquinn) ·
|
|
650
|
+
[aidevops repository](https://github.com/marcusquinn/aidevops)
|
|
651
|
+
<!-- aidevops:managed-readme:end -->
|