You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* docs: update README.md for v0.3.0 release
Update agent count from 17 to 21, replace stale cloudmcp-manager
reference with Serena + Forgetful memory system, add quality gates
and skills to core capabilities, update agent catalog table with
spec-generator and debug agents, bump installer version examples
to v0.3.0.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add Quick Start examples and release notes style guide
Add Simple Scenarios (6 examples) and Advanced Scenarios (5 examples)
to README Quick Start section showing agent capabilities from single
agent tasks through multi-agent orchestrator pipelines. Add release
notes style guide at docs/release-notes-styleguide.md codifying
the Home Assistant conversational format for future releases.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Update README.md
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: Richard Murillo <6811113+rjmurillo@users.noreply.github.com>
* Update README.md
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Signed-off-by: Richard Murillo <6811113+rjmurillo@users.noreply.github.com>
---------
Signed-off-by: Richard Murillo <6811113+rjmurillo@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Richard Murillo <6811113+rjmurillo@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
AI Agents is a coordinated multi-agent system for software development. It provides specialized AI agents that handle different phases of the development lifecycle, from research and planning through implementation and quality assurance.
51
49
52
-
The orchestrator is the hub of operations. Within it has logic from taking everything from a "vibe" or a "shower thought" and building out a fully functional spec with acceptance criteria and user stories, to taking a well defined idea as input and executing on it. There are 17 agents that cover the roles of software development, from vision and strategy, to architecture, implementation, and verification. Each role looks at something specific, like the critic that just looks to poke holes in other agents' (or your own) work, or DevOps that's concerned about how you deploy and operate the thing you just built.
50
+
The orchestrator is the hub of operations. Within it has logic from taking everything from a "vibe" or a "shower thought" and building out a fully functional spec with acceptance criteria and user stories, to taking a well defined idea as input and executing on it. There are 21 agents that cover the roles of software development, from vision and strategy, to architecture, implementation, and verification. Each role looks at something specific, like the critic that just looks to poke holes in other agents' (or your own) work, or DevOps that's concerned about how you deploy and operate the thing you just built.
53
51
54
52
The agents themselves use the platform specific handoffs to invoke subagents, keeping the orchestrator context clean. A great example of this is orchestrator facilitating creating and debating an [Architectural Decision Record](https://adr.github.io/) from research and drafting, to discussion, iterating on the issues, tie breaking when agents don't agree. And then extracting persistent knowledge to steer future agents to adhere. Artifacts are stored in your memory system if you have one enabled, and Markdown files for easy reference to both agents and humans.
55
53
56
54
### Core Capabilities
57
55
58
-
-**17 specialized agents** for different development phases (analysis, architecture, implementation, QA, etc.)
56
+
-**21 specialized agents** for different development phases (analysis, architecture, implementation, QA, etc.)
59
57
-**Explicit handoff protocols** between agents with clear accountability
60
58
-**Multi-Agent Impact Analysis Framework** for comprehensive planning
61
-
-**Cross-session memory**using cloudmcp-manager for persistent context
59
+
-**Cross-session memory**with citation verification, graph traversal, and health reporting via Serena + Forgetful
62
60
-**Self-improvement system** with skill tracking and retrospectives
61
+
-**Quality gates** with pre-PR validation, session protocol enforcement, and automated CI checks
62
+
-**50+ reusable skills** for common development workflows (git, PR management, testing, linting)
63
63
-**TUI-based installation** via [skill-installer](https://github.com/rjmurillo/skill-installer)
64
64
-**AI-powered CI/CD** with issue triage, PR quality gates, and spec validation
65
65
@@ -104,8 +104,8 @@ Without installing (one-liner)
@@ -133,104 +133,77 @@ After installing the agents with the method of your choice, you can either selec
133
133
134
134
### Examples
135
135
136
-
#### Multi-Step Coordination Pattern
136
+
Here are prompts you can copy and paste. Prefix with the agent name to route directly, or use the orchestrator for multi-step workflows.
137
137
138
-
> orchestrator: merge your branch with main, then find other items that are in non-compliance with @path/to/historical-reference-protocol.md and create a plan to correct each. Store the plan in @path/to/plans/historical-reference-protocol-remediation.md and validate with critic, correcting all identified issues. After the plan is completed, start implementor to execute the plan and use critic, qa, and security to review the results, correcting all critical and major issues recursively. After the work is completed and verified, open a PR.
138
+
#### Simple Scenarios
139
139
140
-
This demonstrates the orchestrator's strengths in chaining operations together and routing between agents.
140
+
Review code quality:
141
141
142
-
#### Recursive Fix Loop Pattern
142
+
> critic: review @src/auth/login-handler.ts for coupling, error handling gaps, and test coverage. Deliver an APPROVE or REJECT verdict with specific line references.
143
143
144
-
> orchestrator: fix all items identified by the critic agent, then repeat the cycle recursively until no items are found.
144
+
Shows the critic agent doing a focused code review.
145
145
146
-
This keeps agents honest. Agents will try to be _helpful_ by declaring they're done sooner, skipping steps, or not reading all documentation. Having another agent validate work product makes the system stronger. A typical flow:
146
+
Investigate a bug:
147
147
148
-
1. Do work
149
-
2. Validate that work against a spec (issue, plan, design, test, documentation)
150
-
3. Send to another agent (QA)
151
-
4. Repeat on down the line
148
+
> analyst: the /api/users endpoint returns 500 when the email contains a plus sign. Trace the request through the handler, identify the root cause, and propose a fix.
152
149
153
-
Chain different workflows together as subagents to keep orchestration context alive longer. If you develop software, you probably have some form of "write code, make it work, refactor" cycle. Orchestrator is great at that.
150
+
Shows the analyst doing root cause analysis on a specific bug.
154
151
155
-
#### Implementation with Validation Gate
152
+
Scan for vulnerabilities:
156
153
157
-
> orchestrator: implement Task E2 session validation and E4 pre-commit memory evidence checks. Run the QA agent to verify the implementation meets the PRD acceptance criteria.
154
+
> security: scan @src/api/ for OWASP Top 10 vulnerabilities. Focus on injection, broken auth, and data exposure. Output a threat matrix with CWE identifiers and severity ratings.
158
155
159
-
#### PR Coordination Workflow
156
+
Shows the security agent doing a targeted scan.
160
157
161
-
> orchestrator: review the PR comments, address each reviewer's feedback, then run the code-reviewer agent to verify fixes before requesting re-review
158
+
Write tests for existing code:
162
159
163
-
#### Direct Agent Invocation
160
+
> qa: write pytest tests for @scripts/validate_session_json.py. Cover happy path, malformed input, missing required fields, and boundary conditions. Target 95% line coverage.
164
161
165
-
You do not need the orchestrator for focused tasks. Invoke any agent directly by name:
162
+
Shows the QA agent generating tests with specific coverage targets.
166
163
167
-
```text
168
-
analyst: assess the feasibility of the v0.4.0 extraction plan. Verify the
169
-
inventory data, calibrate session estimates against historical velocity, and
170
-
identify the top 3 dependency risks with quantitative evidence.
171
-
```
164
+
Document a module:
172
165
173
-
```text
174
-
security: produce a threat matrix for the plugin security model in
175
-
@.agents/projects/v0.4.0/PLAN.md. Include CWE identifiers, CVSS ratings,
176
-
and specific mitigation recommendations for each threat.
177
-
```
166
+
> explainer: document @scripts/memory_enhancement/ as a user guide. Include purpose, installation, CLI usage with examples, and architecture overview. Write for developers who have never seen this codebase.
178
167
179
-
```text
180
-
critic: review the implementation plan at @.agents/planning/feature-plan.md.
181
-
Stress-test for gaps, missing rollback strategy, and integration testing
182
-
coverage. Deliver an APPROVE / APPROVE WITH CONDITIONS / REJECT verdict.
183
-
```
168
+
Shows the explainer creating developer documentation.
184
169
185
-
```text
186
-
roadmap: evaluate whether feature X aligns with the product roadmap. Score
187
-
it using RICE framework and compare opportunity cost against the current backlog.
188
-
```
189
-
190
-
```text
191
-
high-level-advisor: we are stuck between approach A and approach B. Cut through
192
-
the analysis and give a GO / NO-GO verdict with clear conditions.
193
-
```
170
+
Plan a feature:
194
171
195
-
```text
196
-
independent-thinker: challenge the core assumptions of the framework extraction
197
-
proposal. Present the strongest case against it with at least 3 concrete
198
-
alternatives.
199
-
```
172
+
> milestone-planner: break down "add webhook retry with exponential backoff" into milestones. Include acceptance criteria, estimated complexity, dependencies, and a suggested implementation order.
200
173
201
-
Direct invocation is best when you know which expertise you need. Use orchestrator when the task requires routing between multiple agents or when you are unsure which agent to start with.
174
+
Shows the planner creating structured work packages.
202
175
203
-
#### Multi-Agent Deep Dive
176
+
#### Advanced Scenarios
204
177
205
-
Route a single artifact through every relevant agent to build a complete picture before committing to a direction:
178
+
End-to-end feature pipeline:
206
179
207
-
> orchestrator: conduct a full review of @.agents/projects/v0.4.0/PLAN.md. Route it through analyst to verify data accuracy and calibrate estimates, architect to evaluate structural decisions and coupling, security to produce a threat matrix with CWE/CVSS ratings, critic to stress-test for gaps and deliver a verdict, independent-thinker to challenge assumptions and propose alternatives, roadmap to score strategic alignment using RICE, devops to assess operational and CI/CD implications, and high-level-advisor to deliver a go/no-go recommendation. Synthesize all findings into a single summary with consensus areas and open disagreements.
180
+
> orchestrator: build the webhook retry system described in @.agents/specs/webhook-retry.md. Start with analyst to verify requirements. Then milestone-planner to create work packages. Run critic to stress-test the plan. Then implementer to write code and tests. Run qa to verify coverage meets acceptance criteria. Run security to scan for injection and replay risks. Fix all critical findings recursively until critic, qa, and security pass. Open a PR.
208
181
209
-
The orchestrator delegates to each agent in turn, collecting independent assessments of the same artifact. Each agent analyzes through its own lens: security looks for threats, critic looks for gaps, independent-thinker looks for blind spots. The orchestrator synthesizes findings into a unified view that highlights where agents agree and where they diverge. This pattern is especially useful for architectural decisions, milestone plans, and pre-implementation due diligence.
182
+
The orchestrator chains seven agents into a full development pipeline with quality gates at each stage.
210
183
211
-
#### Due Diligence Before a Major Decision
184
+
Architecture review:
212
185
213
-
Before adopting a new framework, migrating a system, or making an irreversible architectural change, run structured due diligence across multiple dimensions:
186
+
> orchestrator: conduct a full review of @docs/architecture/service-mesh.md. Route through analyst for data accuracy, architect for structural decisions, security for threat modeling with CWE/CVSS ratings, critic to stress-test for gaps, and independent-thinker to challenge assumptions. Synthesize all findings into a single summary highlighting consensus and disagreements.
214
187
215
-
> orchestrator: we are considering migrating from REST to gRPC for our internal service mesh. Route this through analyst to research performance benchmarks, ecosystem maturity, and team skill gaps. Then architect to evaluate the impact on our current @docs/architecture/service-contracts.md contracts and propose a migration boundary. Then security to threat-model the new transport layer. Then devops to estimate CI/CD pipeline changes and rollback complexity. Then independent-thinker to argue the strongest case for staying with REST. Then high-level-advisor to deliver a GO / CONDITIONAL GO / NO-GO verdict with specific conditions. Store the consolidated analysis in @.agents/analysis/grpc-migration-due-diligence.md.
188
+
Five agents examine the same artifact through different lenses. The orchestrator synthesizes their independent assessments.
216
189
217
-
The orchestrator builds a decision package by routing through six agents. Analyst provides the quantitative foundation. Architect maps the blast radius. Security identifies new attack surface. DevOps estimates operational cost. Independent-thinker forces the team to confront the best argument against the change. High-level-advisor synthesizes everything into an actionable verdict. The stored artifact becomes a reference for the team and future agents.
190
+
Debug, fix, and ship:
218
191
219
-
#### End-to-End Feature Pipeline
192
+
> orchestrator: the payment webhook handler drops events when Redis is unavailable. Have analyst investigate the failure pattern in the logs. Then architect propose a resilient design with fallback queuing. Then implementer build the fix with tests. Run qa and security to validate. Open a PR when all checks pass.
220
193
221
-
Take a feature from zero to pull request with built-in quality gates at each stage:
194
+
Turns an incident report into a shipped fix through structured agent collaboration.
222
195
223
-
> orchestrator: build the webhook retry system described in @.agents/specs/requirements/webhook-retry.md. Start with analyst to verify the requirements are complete and flag ambiguities. Then milestone-planner to break it into milestones with acceptance criteria. Then critic to stress-test the plan for gaps and missing edge cases, correcting all issues before proceeding. Then implementer to write the code and tests. Then qa to verify test coverage meets the acceptance criteria. Then security to scan for injection, replay, and SSRF risks in the webhook handler. Fix all critical and major findings recursively until critic, qa, and security all pass. Open a PR with the full agent trail in the description.
196
+
Technology migration evaluation:
224
197
225
-
This is the orchestrator's most powerful pattern: a full development pipeline with quality gates. Each agent acts as a checkpoint. Critic validates the plan before any code is written. QA validates the implementation against the spec. Security validates against threat categories. The recursive fix loop ensures issues found late in the pipeline get resolved, not deferred.
198
+
> orchestrator: we are considering migrating from REST to gRPC for internal services. Route through analyst to research benchmarks and ecosystem maturity. Then architect to map impact on existing contracts. Then security to threat-model the new transport layer. Then devops to estimate CI/CD changes. Then independent-thinker to argue the strongest case for staying with REST. Then high-level-advisor to deliver a GO or NO-GO verdict with conditions.
226
199
227
-
#### Strategic Prioritization and Roadmap Alignment
200
+
Six agents build a decision package. Each contributes a different dimension of analysis. The advisor synthesizes everything into an actionable verdict.
228
201
229
-
When the backlog is overloaded and the team needs to decide what to build next, use the orchestrator to run a structured prioritization:
202
+
Strategic prioritization:
230
203
231
-
> orchestrator: we have three candidate features for the next quarter: plugin marketplace, offline mode, and admin audit logging. For each candidate, route through analyst to estimate effort and risk, roadmap to score with RICE and classify with KANO, security to flag compliance or threat implications, and devops to estimate operational burden. Then independent-thinker to argue which one the team is most likely to regret skipping. Then high-level-advisor to rank all three with a clear recommendation. Store the output in @.agents/analysis/q3-prioritization.md.
204
+
> orchestrator: we have three candidate features for next quarter: plugin marketplace, offline mode, and admin audit logging. For each, run analyst for effort and risk, roadmap to score with RICE and KANO, security for compliance implications, and devops for operational burden. Then independent-thinker to argue which one we will most regret skipping. Then high-level-advisor to rank all three with a clear recommendation.
232
205
233
-
The orchestrator runs the same evaluation pipeline across all three candidates, producing comparable data. Roadmap scores each on Reach, Impact, Confidence, and Effort. Security flags compliance obligations. DevOps estimates maintenance tax. Independent-thinker surfaces opportunity cost the team might overlook. High-level-advisor delivers the final ranking with a defensible basis for the quarterly plan.
206
+
The orchestrator runs the same evaluation pipeline across all candidates, producing comparable data for a defensible quarterly plan.
234
207
235
208
---
236
209
@@ -259,6 +232,10 @@ The orchestrator runs the same evaluation pipeline across all three candidates,
259
232
|**high-level-advisor**| Strategic decisions, unblocking | Verdicts: GO / CONDITIONAL GO / NO-GO |
260
233
|**independent-thinker**| Challenge assumptions, devil's advocate | Counter-arguments with alternatives |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?v=4&size=40){kind=avatar}
0 commit comments