docs: add draft agent awareness to orchestration agents

[marcusquinn]

Summary

• Build+, Ralph loop, and runners now know they can create and evolve draft agents
• Closes the gap where the lifecycle tiers existed in build-agent.md but orchestration agents had no awareness of them
• Agents can now propose useful drafts for inclusion in aidevops via PR

Changes

build-plus.md

• Added draft agent guidance to the AI-CONTEXT block (seen on every Build+ invocation)
• Tells Build+ to create drafts when it discovers reusable patterns during orchestration

ralph-loop.md

• Added "Evolving draft agents" note after the "How It Works" section
• Loop iterations can capture domain patterns as drafts for future loops to reference

runners/README.md

• Added "Evolving Runners into Shared Agents" section
• Documents the promotion path: runner -> draft -> custom/shared

Context

Follow-up to #409 which added the three-tier agent lifecycle (draft, custom, shared) to build-agent.md and setup.sh. That PR added the mechanism but the orchestration agents that would use it had no awareness. This PR closes that gap.

Testing

• markdownlint: zero errors across all 3 files
• No code changes, documentation only

[coderabbitai]

Warning

Rate limit exceeded

@marcusquinn has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 16 minutes and 19 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/orchestration-draft-agent-awareness

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Summary of Changes

Hello @marcusquinn, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the documentation for Build+, Ralph loop, and runners to incorporate the concept of draft agents. It provides explicit guidance within these agent definitions on how to identify, create, and evolve draft agents, thereby integrating the previously established three-tier agent lifecycle directly into the operational understanding of the orchestration agents. This change aims to formalize the process of capturing and promoting reusable patterns into structured agents.

Highlights

• Orchestration Agent Awareness: Documentation for Build+, Ralph loop, and runners now includes explicit guidance on understanding and utilizing the draft agent lifecycle.
• Bridging the Gap: This pull request closes the gap where agent lifecycle tiers were defined but orchestration agents lacked awareness or instructions to interact with them.
• Streamlined Agent Promotion: Agents are now guided to propose useful draft agents for potential promotion to custom or shared agents via pull requests, formalizing the process of capturing reusable patterns.

Changelog

• .agents/build-plus.md
  • Instructions added to the AI-CONTEXT block guiding Build+ to create draft agents when reusable patterns are identified during orchestration.
• .agents/tools/ai-assistants/runners/README.md
  • A new section, "Evolving Runners into Shared Agents," was added, detailing the three-step promotion path from runner to draft, custom, and ultimately shared agents.
• .agents/workflows/ralph-loop.md
  • Guidance inserted into the "How It Works" section, advising the Ralph loop to capture reusable domain patterns as draft agents for future reference and promotion.

Activity

• The pull request primarily consists of documentation updates across three markdown files.
• It serves as a follow-up to PR feat: add three-tier agent lifecycle (draft, private, shared) #409, which introduced the agent lifecycle tiers.
• The changes ensure that orchestration agents are aware of and can interact with the draft agent mechanism.
• All modified files passed markdownlint checks without errors.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

🔍 Code Quality Report

�[0;35m[MONITOR]�[0m Code Review Monitoring Report

�[0;34m[INFO]�[0m Latest Quality Status:
SonarCloud: 0 bugs, 0 vulnerabilities, 25 code smells

�[0;34m[INFO]�[0m Recent monitoring activity:
Sat Feb 7 01:27:44 UTC 2026: Code review monitoring started
Sat Feb 7 01:27:44 UTC 2026: SonarCloud - Bugs: 0, Vulnerabilities: 0, Code Smells: 25
Sat Feb 7 01:27:44 UTC 2026: Qlty - 0 issues found, auto-formatting applied
Sat Feb 7 01:27:46 UTC 2026: Codacy analysis completed with auto-fixes

📈 Current Quality Metrics

• BUGS: 0
• CODE SMELLS: 25
• VULNERABILITIES: 0

Generated on: Sat Feb 7 01:27:49 UTC 2026

---

Generated by AI DevOps Framework Code Review Monitoring

[gemini-code-assist]

Code Review

This pull request effectively adds awareness of 'draft agents' to the orchestration agent documentation, closing a gap from a previous change. The explanations are clear and consistent across the modified files. I've identified a couple of incorrect relative links in the new documentation which should be corrected to ensure proper navigation. My detailed feedback is in the review comments.

[gemini-code-assist]

The relative link to build-agent.md appears to be incorrect. Based on this file's location within the directory structure, the path tools/build-agent/build-agent.md will not resolve correctly. To ensure the link works as intended, it should be updated to ../../build-agent/build-agent.md.

Suggested change

	See `tools/build-agent/build-agent.md` "Agent Lifecycle Tiers" for the full promotion workflow.
	See `../../build-agent/build-agent.md` "Agent Lifecycle Tiers" for the full promotion workflow.

[gemini-code-assist]

The relative link to build-agent.md seems incorrect. Given this file's location, the path tools/build-agent/build-agent.md will not resolve to the correct document. The path should be adjusted to ../tools/build-agent/build-agent.md to be a correct relative link.

Suggested change

**Evolving draft agents**: When a loop iteration discovers reusable domain patterns (validation rules, API conventions, testing strategies), capture them as a draft agent in `~/.aidevops/agents/draft/`. Subsequent iterations and future loops can reference the draft instead of rediscovering the pattern. After the loop completes, log a TODO to review the draft for promotion to `custom/` (private) or `.agents/` (shared via PR). See `tools/build-agent/build-agent.md` "Agent Lifecycle Tiers".

**Evolving draft agents**: When a loop iteration discovers reusable domain patterns (validation rules, API conventions, testing strategies), capture them as a draft agent in `~/.aidevops/agents/draft/`. Subsequent iterations and future loops can reference the draft instead of rediscovering the pattern. After the loop completes, log a TODO to review the draft for promotion to `custom/` (private) or `.agents/` (shared via PR). See `../tools/build-agent/build-agent.md` "Agent Lifecycle Tiers".

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud