agno-implementer

name	agno-implementer
description	Execute an AgentOS implementation plan to completion — create/edit files, register agents, add evals, validate, smoke-test, update AGENTS.md, write a report. Use when a plan exists and you want it built. Covers Agno conventions and AGENTS.md update mapping.
argument-hint	["path to the plan doc in project-docs/plans/","or describe what to implement"]

Agno Implementer

Execute an AgentOS implementation plan doc to completion. Creates and edits the files the plan specifies, registers the agent/team/workflow, adds eval cases, validates, smoke-tests, then performs two finalization steps: a surgical update to AGENTS.md and a written implementation report.

When to use this skill

• A plan doc exists at project-docs/plans/<slug>-plan.md
• You want to build what the plan specifies
• You need to know which AGENTS.md section to update and how
• You need to write the implementation report

Step 1 — Read and verify the plan

Read the plan doc. If it doesn't exist or is incomplete (missing sections, no verified APIs), stop and tell the user to run the Agno Planner first.

For each Agno API the plan uses, verify it against the agno-docs MCP server. If the plan's recorded signature conflicts with the MCP server, trust the MCP server and flag the discrepancy.

Step 2 — Implement the plan

Follow the plan's "Files" section. Create each new file, edit each existing file. Follow the plan's skeleton exactly — the Agent(...) / Team(...) / Workflow(...) constructor, INSTRUCTIONS, tools, DB factory, guardrails. Use the todo tool to track progress — one item per file plus items for verify, register, evals, validate, format, smoke-test, AGENTS.md update, report.

Step 3 — Validate and smoke-test

1. Run ./scripts/format.sh to format new and edited files.
2. Run ./scripts/validate.sh. Fix any errors in scope. Do not declare done until it passes.
3. Smoke-test: docker compose restart agentos-api, then confirm the new agent/workflow loads (check logs or hit the agents endpoint). Per AGENTS.md, a restart is required for newly-registered modules.

Step 4 — Update AGENTS.md

This is a required finalization step, not optional. The plan's section 13 specifies what to update. Follow the AGENTS.md update guide for the section-to-content mapping and surgical edit conventions.

Key rules:

• Read the current AGENTS.md before editing. Match the existing format of the section you're updating (table rows, bullet lists, prose).
• Add the minimum entry that makes the new capability discoverable — a Key Files row, a Domain Modules entry, an Environment Variables row, or a Guardrails row. Don't rewrite sections.
• If the capability introduces a new env var, add it to the Environment Variables table.
• If the capability introduces a new guardrail, add it to the Guardrails table.
• Run ./scripts/format.sh after editing AGENTS.md (it's Markdown, but the repo formatter keeps prose consistent).

Step 5 — Write the implementation report

Write the report to project-docs/reports/<slug>-report.md using the report template. The report is the handoff artifact for the next agent or human who needs to implement a similar plan.

The report MUST cover:

1. What was implemented — files created/edited, one line each.
2. Issues encountered — plan-vs-repo drift, API mismatches, validation failures, smoke-test problems, and how each was resolved.
3. Guide for next agents — patterns that worked, gotchas hit, things to check before starting a similar plan, links to the plan doc and any reference files that were useful.

Step 6 — Report to the user

Summarize: files created/edited, validation result, smoke-test result, AGENTS.md sections updated, report path, and any plan discrepancies flagged. Do not deploy.

Gotchas

• AGENTS.md is the source of truth. If the implementation changes what's configured (new agent, new env var, new guardrail), AGENTS.md MUST reflect it. The environment manifest (app/environment.py) is the machine truth; AGENTS.md is the human narrative. Both must stay in sync.
• Don't rewrite AGENTS.md sections. Add entries to existing tables and lists. Preserve the existing format and ordering.
• The report is not optional. It's how knowledge compounds across implementations. Skip it and the next agent starts from scratch.
• docker compose restart agentos-api is required for newly-registered agents — uvicorn hot-reload is unreliable for new modules.

References

• AGENTS.md update guide: references/agents-md-update-guide.md
• Report template: references/report-template.md
• Plan template: ../agno-planner/references/plan-template.md
• Repo conventions: AGENTS.md
• Agno docs MCP server: configured in .mcp.json as agno-docs