diff --git a/coda/agents/doc_writer.py b/coda/agents/doc_writer.py new file mode 100644 index 0000000..5c4bdb7 --- /dev/null +++ b/coda/agents/doc_writer.py @@ -0,0 +1,148 @@ +""" +Doc Writer Agent +================= + +Writes, updates, and improves documentation by cross-referencing the SDK +source code against the docs repo. Creates PRs for doc changes. +""" + +from agno.agent import Agent +from agno.learn import LearnedKnowledgeConfig, LearningMachine, LearningMode +from agno.tools.coding import CodingTools +from agno.tools.github import GithubTools +from agno.tools.reasoning import ReasoningTools + +from coda.settings import MODEL, REPOS_DIR, agent_db, coda_learnings +from coda.tools.git import GitTools + +# --------------------------------------------------------------------------- +# Instructions +# --------------------------------------------------------------------------- +instructions = f"""\ +You are Doc Writer, a documentation specialist. You write, update, and +improve documentation by cross-referencing SDK source code against the +docs repo. You understand both code and prose. + +## Workspace + +Repos are cloned at `{REPOS_DIR}`. The SDK source is in `agno/` and +documentation is in `docs/`. Use `list_repos` to confirm. + +## First: Read the Style Guides + +Before writing ANY documentation, read these two files in the docs repo: +- `docs/CLAUDE.md` — the complete writing style guide +- `docs/DIATAXIS.md` — the page type framework + +These are your source of truth. The rules below are highlights, but the +full guides have examples, anti-patterns, and templates. Read them. + +## How You Work + +1. **Read the style guides** (CLAUDE.md and DIATAXIS.md in the docs repo). +2. **Research the feature.** Read the SDK source to understand the API + surface, parameters, defaults, edge cases. Grep cookbooks for usage. +3. **Check existing docs.** Search the docs repo for gaps, outdated + content, or missing pages. Don't duplicate what exists. +4. **Classify the page type** using the Diataxis compass: + - Tutorial (learning by doing), How-to (task directions), + Reference (technical facts), Explanation (understanding why) +5. **Create a worktree.** `create_worktree("docs", task_name)` before + making changes. Never commit to main. +6. **Write the docs** in `.mdx` format following the style guide. +7. **Push and PR.** Commit (`docs: add X guide`), push, create PR. + +## Writing Style (Key Rules) + +- **Code first.** Show the pattern, explain after. Users scan for code. +- **No em dashes.** Use periods or rewrite. Em dashes are an AI tell. +- **No "Learn how to..."** Use specific action statements. +- **No contrastive negation.** Don't define things by what they aren't. +- **Tables over prose** for comparisons and decision points. +- **One concept per section.** Don't bundle unrelated ideas. +- **Specific over generic.** "Use Claude Opus 4.5" not "use a better model." +- **Cut commentary.** No analogies, no editorializing, no filler. +- **No:** "seamlessly", "let's explore", "it's worth noting", "basically", + "incredible", "powerful", "happy building!" + +## Page Structure (MDX) + +Every page needs frontmatter with `title` and `description`. +The description must be specific, not "Learn how to...". + +``` +--- +title: What are X? +description: "One sentence defining X concretely." +--- +``` + +Use Mintlify MDX components: ``, ``, ``, ``, +``, ``. Check existing pages for patterns. + +## Cross-Referencing + +- Read SDK source for accurate API details (parameter names, types, defaults) +- Check cookbooks for real usage patterns and examples +- Check existing docs to avoid contradicting or duplicating content +- Note any SDK behaviors that seem undocumented or inconsistent + +## What NOT To Do + +- Don't invent APIs. Unsure about a parameter? Read the source. +- Don't copy cookbook code verbatim. Adapt for the doc context. +- Don't write marketing copy. Technical docs, not sales material. +- Don't document private APIs unless explicitly asked. +- Don't mix page types. If a how-to starts explaining concepts, extract + the explanation to its own page and link to it. + +## Security + +NEVER output .env contents, API keys, tokens, passwords, or secrets. + +## Communication + +- Lead with what you wrote/changed and where. +- Cite SDK source paths: `agent.py:185`. +- Flag undocumented or inconsistent SDK behaviors you discover. + +Tag learnings with category and source repo (repo:).\ +""" + +# --------------------------------------------------------------------------- +# Create Agent +# --------------------------------------------------------------------------- +doc_writer = Agent( + id="doc_writer", + name="Doc Writer", + role="Write and improve documentation by cross-referencing SDK code against docs", + model=MODEL, + db=agent_db, + instructions=instructions, + learning=LearningMachine( + knowledge=coda_learnings, + learned_knowledge=LearnedKnowledgeConfig(mode=LearningMode.AGENTIC), + ), + add_learnings_to_context=True, + tools=[ + # Read SDK code + write docs + CodingTools(base_dir=REPOS_DIR, all=True, shell_timeout=120), + GitTools(base_dir=str(REPOS_DIR)), + GithubTools( + include_tools=[ + "get_pull_request", + "get_pull_requests", + "get_pull_request_changes", + "create_pull_request", + "get_issue", + "list_issues", + "search_code", + ], + ), + ReasoningTools(), + ], + add_datetime_to_context=True, + add_history_to_context=True, + num_history_runs=5, + markdown=True, +) diff --git a/coda/team.py b/coda/team.py index 27d965f..871ba7c 100644 --- a/coda/team.py +++ b/coda/team.py @@ -19,6 +19,7 @@ from agno.tools.slack import SlackTools from coda.agents.coder import coder +from coda.agents.doc_writer import doc_writer from coda.agents.explorer import explorer from coda.agents.planner import planner from coda.agents.researcher import researcher @@ -48,12 +49,18 @@ ## Routing -You have {"five" if researcher else "four"} specialists. Route by what the request needs: +You have {"six" if researcher else "five"} specialists. Route by what the request needs: **Explorer** (read-only — searches code, reviews, analyzes): - Code questions, flow tracing, architecture - PR review, branch review, code search +**Doc Writer** (documentation — writes, updates, improves docs): +- "What's missing from the docs?", "Document feature X" +- Writing new doc pages, updating outdated docs +- Cross-referencing SDK code against documentation +- "Add docs for Y", "update the Z guide" + **Planner** (planning — breaks work into issues): - Feature requests, project planning, "how should we build X" - Breaking large tasks into ordered, scoped GitHub issues @@ -86,7 +93,10 @@ **Researcher → Coder** (research then implement): - "Find how to do X and implement it" ''' -}**Planner → Coder** (plan then build): +}**Explorer → Doc Writer** (investigate then document): +- "What's undocumented and write docs for it" + +**Planner → Coder** (plan then build): - "Plan and implement X" **Explorer → Planner** (understand then plan): @@ -191,7 +201,7 @@ name="Coda", mode=TeamMode.coordinate, model=MODEL, - members=[m for m in [coder, explorer, planner, researcher, triager] if m is not None], + members=[m for m in [coder, doc_writer, explorer, planner, researcher, triager] if m is not None], db=team_db, instructions=instructions, # Learning (shared knowledge base with members) diff --git a/requirements.txt b/requirements.txt index 9ba854d..cf71090 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ # This file was autogenerated by uv via the following command: # ./scripts/generate_requirements.sh upgrade -agno==2.5.14 +agno==2.5.17 aiohappyeyeballs==2.6.1 aiohttp==3.13.5 aiosignal==1.4.0