Skip to content

docs: add draft agent awareness to orchestration agents #411

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcusquinn merged 1 commit into from
Feb 7, 2026
+16 −0
Merged

docs: add draft agent awareness to orchestration agents #411

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .agents/build-plus.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,8 @@ opencode run "Test query" --agent Build+

See `tools/opencode/opencode.md` for CLI testing patterns.

**Draft Agents**: When you discover reusable patterns during orchestration (parallel Task tool calls, repeated prompts, domain-specific instructions), create a draft agent in `~/.aidevops/agents/draft/` instead of duplicating context. Include `status: draft` in frontmatter. Log a TODO for review. Useful drafts can be promoted to `custom/` (private) or `.agents/` (shared via PR). See `tools/build-agent/build-agent.md` "Agent Lifecycle Tiers".

<!-- AI-CONTEXT-END -->

## Build Workflow
Expand Down
12 changes: 12 additions & 0 deletions .agents/tools/ai-assistants/runners/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,18 @@ A good runner AGENTS.md has four sections:

Keep it under 500 words. Runners get the full prompt on every dispatch, so brevity matters.

## Evolving Runners into Shared Agents

When a runner proves valuable across multiple projects, consider promoting it:

1. **Draft** -- Save to `~/.aidevops/agents/draft/` with `status: draft` in frontmatter
2. **Custom** -- Move to `~/.aidevops/agents/custom/` for permanent private use
3. **Shared** -- Refine to framework standards and submit a PR to `.agents/` in the aidevops repo

Log a TODO item when a runner has reuse potential: `- [ ] tXXX Review runner {name} for promotion #agent-review`

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

@gemini-code-assist gemini-code-assist bot Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.


## Parallel vs Sequential

See the [decision guide](../headless-dispatch.md#parallel-vs-sequential) in headless-dispatch.md.
2 changes: 2 additions & 0 deletions .agents/workflows/ralph-loop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ The loop creates a **self-referential feedback loop** where:
- Each iteration sees modified files and git history
- Claude autonomously improves by reading its own past work

**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".
Copy link

@gemini-code-assist gemini-code-assist bot Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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".


## Quick Start

### v2: Fresh Sessions (Recommended)
Expand Down
Loading