agno-planner

name	agno-planner
description	Plan implementations of new agents, teams, workflows, and capabilities for AgentOS (Agno + Postgres + pgvector). Use when architecting or scoping before coding. Covers agent shape, DB isolation, guardrails, evals, promotion.
argument-hint	["describe the agent","team","workflow","or capability to plan"]

Agno Implementation Planner

Architect and plan new agents, teams, workflows, and capabilities for the AgentOS system before any code is written. Produces a single implementation plan doc grounded in the repo's real conventions.

When to use this skill

• Planning a new production agent or experiment
• Designing a multi-agent team or a deterministic workflow
• Scoping a new capability (tool, knowledge base, context provider, interface)
• Deciding agent vs team vs workflow for a requirement

Step 1 — Classify the request

Map the request to one of four shapes. The shape determines the plan's skeleton.

Request	Shape	Lives in	Registered via
Single autonomous agent	Agent	agents/production/<slug>.py	app/main.py
Disposable / exploratory agent	Experiment	agents/experiments/<slug>.py	auto-discovery (INCLUDE_EXPERIMENTS=true)
Multi-agent coordination	Team	teams/<slug>.py	app/main.py
Deterministic multi-step pipeline	Workflow	goals/workflows/ or tasks/	app/main.py

If the request is a capability (tool, KB, context provider, interface, model), classify it as an Agent-shape extension — the plan describes which existing agent/file it attaches to.

Step 2 — Understand the use case (ask why before what)

Before researching solutions, ask the user why they want this. What problem are they solving? What's the use case? What constraints matter? Do not assume the reason — the user may not realize there are options that shape the implementation.

Use the discovery questions reference to find the right questions for the capability type. Ask them via #tool:vscode/askQuestions.

Example: A user asks to plan a RAG implementation. Before researching chunking strategies or embedding models, ask:

• What will the RAG be used for? (Q&A, summarization, code search?)
• What content types will be ingested? (Markdown, PDFs, code?)
• What's the query pattern? (Short keywords, long natural-language?)

The chunking strategy follows from the use case — agentic chunking for mixed content, header-aware for structured Markdown, fixed-size for uniform text. Without knowing the use case, the planner would pick a default that may not fit.

The user's answers shape which options you surface and which trade-offs matter in Step 6.

Step 3 — Gather repo context (ground every decision)

Read before deciding. Never plan from memory.

• AGENTS.md — the source of truth for conventions, env vars, file map.
• agents/production/web_search.py — direct-tools reference agent.
• agents/production/code_search.py — context-provider reference agent.
• app/main.py — registration, conditional Slack/JWT, experiment discovery.
• app/settings.py — default_model() factory.
• app/guardrails.py — pre/post hook guardrail inventory.
• db/session.py, db/experiment.py — DB + knowledge factories.
• evals/cases.py, evals/__main__.py — eval patterns.

Use #tool:search/textSearch and #tool:read/readFile to confirm the current shape of any file you reference. Cite the file path + line range in the plan so the implementer can verify.

Step 4 — Verify Agno APIs against docs

For any toolkit, workflow, team, or interface API the plan relies on, fetch the relevant Agno docs page and confirm the signature. Do not reproduce APIs from memory — they drift.

• Toolkits: https://docs.agno.com/tools/toolkits
• Teams: https://docs.agno.com/teams/overview
• Workflows: https://docs.agno.com/workflows/overview
• Interfaces: https://docs.agno.com/agent-os/interfaces/overview
• Models: https://docs.agno.com/models

Use #tool:web/fetch or the agno-docs MCP server on the specific page. Record the doc URL + the exact signature in the plan's "Verified APIs" section.

Step 5 — Scout for blind spots

Invoke the Improvement Scout subagent (#tool:agent) with the planning request and key files found during research. It returns a findings report covering:

• Reusable patterns (existing agents, context providers, guardrails)
• Guardrail & eval gaps
• API mismatches (verified against agno-docs MCP)
• Risks & failure modes
• Simpler alternatives

Fold these findings into the options you present to the user.

Step 6 — Surface options and ask the user

Synthesize research + scout findings into 2-4 concrete options, each with trade-offs (shape choice, tool set, DB tier, complexity, risk). Present them with #tool:vscode/askQuestions — one question per decision point. Include the scout's simpler-alternative finding as an option if relevant.

Do not write the plan until the user answers. The plan reflects their choices, not the planner's defaults.

Step 7 — Draft the plan

Using the user's answers, write the draft plan to project-docs/plans/<slug>-plan.md using the plan template. Every section is required; if a section doesn't apply, state "N/A — " rather than omitting it.

Run the request through the capability checklist to catch gaps the four shapes don't cover.

The plan MUST cover, at minimum:

1. Summary — one paragraph: what, why, the chosen shape.
2. Shape decision — agent / experiment / team / workflow, with rationale and the rejected alternatives.
3. Files — every file to create or edit, with full path and a one-line description of the change.
4. Agent/workflow skeleton — the Agent(...) / Team(...) / Workflow(...) constructor call with every kwarg filled in, following the convention in AGENTS.md ("Agent pattern").
5. Tools — each tool listed with the step that justifies it. Apply the tool-scoping rule: if no step needs it, it's not in the list.
6. DB & knowledge — which factory (get_postgres_db, experiment_db, experiment_knowledge, experiment_sqlite, create_knowledge, create_studio_knowledge) and why. See the DB isolation tier table in AGENTS.md.
7. Guardrails — pre-hooks and post-hooks, mapped to the guardrail inventory in app/guardrails.py. Every production agent gets PromptInjectionGuardrail; teams with PII get PIIDetectionGuardrail.
8. Evals — at least one Case in evals/cases.py with a judge rubric and/or reliability assertion. Reference the eval runner.
9. Config & prompts — app/config.yaml entries keyed by agent id.
10. Registration — the exact line to add in app/main.py (production) or the auto-discovery note (experiment).
11. Verified APIs — doc URL + signature for every Agno API used.
12. Open questions — anything the implementer must confirm before coding.
13. AGENTS.md update — exactly what to add and where (section-to-content mapping). Required finalization step for the implementer.
14. Implementation report — the implementer writes a report to project-docs/reports/<slug>-report.md covering what was implemented, issues encountered, and a guide for next agents. Required finalization step.

Step 8 — Critic and revise

Invoke the Plan Critic subagent (#tool:agent) with the draft plan path. It returns a six-category review (plan-vs-repo drift, guardrails, evals, API correctness, tool scoping & DB isolation, summary).

Address every BLOCKER before finalizing. Re-write the plan with the fixes. Note any SUGGESTIONs you accepted or rejected and why. Re-run the critic only if a BLOCKER fix changed the plan materially.

Step 9 — Hand off

The plan is the deliverable. Do not implement. Suggest the implementer handoff so a coding agent can execute the plan.

Gotchas

• Agent instances are silently dropped from tools=[]. Never plan an agent-as-tool. Use a context provider, a team with members=[], or a @tool wrapper. See db/goals_context_provider.py, db/systems_design_context_provider.py for the provider pattern.
• Experiments never import from production in reverse. Production may not import experiments; experiments may import production.
• docker compose restart agentos-api is required for newly-registered agents — uvicorn hot-reload is unreliable for new modules.
• output_schema agents return Pydantic models, not JSON strings. Flag this in the plan when a workflow step consumes another step's output — the executor must normalise before string ops.
• Reranking is opt-in via CO_API_KEY and is wired at the CompositeKnowledge level, not per-PgVector. Don't plan per-KB rerankers.
• Studio KBs need contents_db or AgentOS skips them during registry population. Use create_studio_knowledge(), not create_knowledge(), for anything selectable in Studio.

References

• Discovery questions: references/discovery-questions.md
• Capability checklist: references/capability-checklist.md
• Plan template: references/plan-template.md
• Improvement Scout subagent: ../agents/improvement-scout.agent.md
• Plan Critic subagent: ../agents/plan-critic.agent.md
• Repo conventions: AGENTS.md
• Agno docs: https://docs.agno.com