Skip to content

[docs] Spec: let an agent create and edit other agents - #7392

Closed
mmabrouk wants to merge 1 commit into
release/v0.122.3from
docs/cross-agent-config-editing-spec
Closed

mmabrouk wants to merge 1 commit into
release/v0.122.3from
docs/cross-agent-config-editing-spec

Conversation

@mmabrouk

@mmabrouk mmabrouk commented Oct 6, 2026

Copy link
Copy Markdown
Member

What

Adds the OpenSpec change openspec/changes/cross-agent-config-editing/ plus an implementation handoff. Documentation only; no code changes.

The feature

An agent can list, read, create and edit other agents in its project, through two capabilities shown in the playground build kit and in the Agenta tools section:

  • List agents: list_agents
  • Agent config: read_agent_config, create_agent, edit_agent_config

Each capability is one toggle, and each tool keeps its own allow/ask/off control.

Decisions (made by Mahmoud)

  1. Reach: any agent in the project.
  2. Two capabilities as above. Test-running another agent is out of scope (add it as a subagent).
  3. On by default, every tool allow, in the build kit and in DEFAULT_AGENTA_TOOLS.
  4. No extra limit on what an edit may grant; the existing self-edit scope (AGENT_COMMIT_SCOPE) still applies.
  5. create_agent starts from the "New agent" catalog template, with optional ordered operations.
  6. Four new tools; read_config and commit_revision are unchanged.
  7. Attribution goes in the commit message: (by agent "<name>" <id>, session <id>), built from run context only.

Accepted risks are recorded in design.md.

Files

  • proposal.md, design.md (today's behavior with file:line evidence on this branch), tasks.md
  • specs/agent-directory/spec.md, specs/agent-config-management/spec.md: 9 requirements, 29 scenarios
  • HANDOFF.md: a self-contained brief for the implementing agent

Validation

openspec validate cross-agent-config-editing --strict passes.

Adds the cross-agent-config-editing OpenSpec change: two capabilities
(List agents; Agent config) with four platform tools that let an agent
list, read, create and edit other agents in its project, plus an
implementation handoff.
@coderabbitai

coderabbitai Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

📝 Summary

Summary by CodeRabbit

  • Documentation
    • Added specifications for planned project-wide agent listing and configuration tools, including reading, creating, and editing agent configurations.
    • Documented permission controls, target restrictions, revision checks, attribution, and deployment behavior.
    • Added implementation handoff details, testing requirements, and live QA steps. These documents describe proposed behavior; they do not indicate that the tools are available.

Walkthrough

The change adds an OpenSpec proposal, design, specifications, task plan, and implementation handoff for cross-agent tools to list, read, create, and edit agents within a project.

Changes

Cross-agent configuration

Layer / File(s) Summary
Capabilities and agent listing
openspec/changes/cross-agent-config-editing/proposal.md, openspec/changes/cross-agent-config-editing/design.md, openspec/changes/cross-agent-config-editing/specs/agent-directory/spec.md, openspec/changes/cross-agent-config-editing/specs/agent-config-management/spec.md
Defines the four tools, capability toggles, permission defaults, and project-scoped agent listing behavior.
Reading, creating, and editing agent configuration
openspec/changes/cross-agent-config-editing/design.md, openspec/changes/cross-agent-config-editing/specs/agent-config-management/spec.md
Specifies target validation, configuration reads, catalog-based creation, ordered edits, revision checks, and deployment exclusions.
Attribution, previews, and delivery
openspec/changes/cross-agent-config-editing/design.md, openspec/changes/cross-agent-config-editing/specs/agent-config-management/spec.md, openspec/changes/cross-agent-config-editing/tasks.md, openspec/changes/cross-agent-config-editing/HANDOFF.md
Specifies revision attribution and chat previews. The task plan and handoff list implementation areas, tests, QA steps, and delivery constraints.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🔵 Low · up to 49f18

The documentation-only change is low risk, but its attribution and archived-listing rules should be clarified before implementation.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the documentation change and its main focus: enabling an agent to create and edit other agents.
Description check ✅ Passed The description explains the proposed capabilities, permissions, design decisions, and documentation-only scope.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Actionable comments posted: 2


ℹ️ Review info
⚙️ Run configuration
  • Configuration used: Repository YAML (base), Organization UI (inherited)
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 663490d8-870d-4515-bf9e-f8ade0186e1b
📥 Commits

Reviewing files that changed from the base of the PR and between 30c36d6 and 49f1844.

📒 Files selected for processing (6)
  • openspec/changes/cross-agent-config-editing/HANDOFF.md
  • openspec/changes/cross-agent-config-editing/design.md
  • openspec/changes/cross-agent-config-editing/proposal.md
  • openspec/changes/cross-agent-config-editing/specs/agent-config-management/spec.md
  • openspec/changes/cross-agent-config-editing/specs/agent-directory/spec.md
  • openspec/changes/cross-agent-config-editing/tasks.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 4 remain after this review.

set parameters.agent.instructions.agents_md (by agent "Support Triage" 019f…, session 01a1…)
```

`create_agent` writes `Created by agent "<name>" <id>, session <id>` as the first revision's message, followed by the derived clauses when operations were sent.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

🔎 Supported by static analysis

🏁 Script executed:

sed -n '115,140p' openspec/changes/cross-agent-config-editing/specs/agent-config-management/spec.md
sed -n '115,134p' openspec/changes/cross-agent-config-editing/design.md

Repository: Agenta-AI/agenta

Length of output: 2971


Put creation attribution after the derived clauses.

When create_agent receives operations, the design puts the attribution before the derived clauses. That conflicts with the requirement that every revision message end with attribution. Update the creation scenario to require the same ending.

🐛 Suggested fix
--- a/openspec/changes/cross-agent-config-editing/specs/agent-config-management/spec.md
+++ b/openspec/changes/cross-agent-config-editing/specs/agent-config-management/spec.md
@@
-- **THEN** the new agent's first revision message starts with `Created by agent "Support Triage" <id>, session S`
+- **THEN** the new agent's first revision message ends with `Created by agent "Support Triage" <id>, session S`
--- a/openspec/changes/cross-agent-config-editing/design.md
+++ b/openspec/changes/cross-agent-config-editing/design.md
@@
-`create_agent` writes `Created by agent "<name>" <id>, session <id>` as the first revision's message, followed by the derived clauses when operations were sent.
+`create_agent` writes the derived clauses first when operations were sent, then appends `Created by agent "<name>" <id>, session <id>` to the first revision's message.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
`create_agent` writes `Created by agent "<name>" <id>, session <id>` as the first revision's message, followed by the derived clauses when operations were sent.
`create_agent` writes the derived clauses first when operations were sent, then appends `Created by agent "<name>" <id>, session <id>` to the first revision's message.


### Requirement: List agents in the project

The `list_agents` tool SHALL return the agents in the caller's project, with each agent's id, slug, name, description, latest revision version and last update time. It SHALL include only workflows flagged `is_agent`, exclude archived agents unless asked, and exclude static platform workflows.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

🔎 Supported by static analysis

🏁 Script executed:

rg -n -C 3 'archiv|list_agents|include_archived|includeArchived' openspec/changes/cross-agent-config-editing

Repository: Agenta-AI/agenta

Length of output: 17304


🏁 Script executed:

set -eu
base=30c36d60e173d8d0d692659f44b15518efd0ef48
head=49f18440082a412159a5e009230f0371995b427a
files='openspec/changes/cross-agent-config-editing/specs/agent-directory/spec.md openspec/changes/cross-agent-config-editing/design.md openspec/changes/cross-agent-config-editing/proposal.md openspec/changes/cross-agent-config-editing/HANDOFF.md openspec/changes/cross-agent-config-editing/tasks.md'
printf '%s\n' '--- PR diff ---'
git diff --unified=3 "$base" "$head" -- $files
printf '%s\n' '--- Directory spec ---'
nl -ba openspec/changes/cross-agent-config-editing/specs/agent-directory/spec.md
printf '%s\n' '--- Related design ---'
nl -ba openspec/changes/cross-agent-config-editing/design.md | sed -n '120,140p'
printf '%s\n' '--- Proposal ---'
nl -ba openspec/changes/cross-agent-config-editing/proposal.md | sed -n '1,25p'
printf '%s\n' '--- Handoff ---'
nl -ba openspec/changes/cross-agent-config-editing/HANDOFF.md | sed -n '1,35p'
printf '%s\n' '--- Tasks ---'
nl -ba openspec/changes/cross-agent-config-editing/tasks.md | sed -n '1,18p'

Repository: Agenta-AI/agenta

Length of output: 39874


Remove the undefined archived-agent opt-in.

The no-argument scenario sets exclusion as the default, but no caller input for including archived agents is defined. The implementation task says list_agents excludes archived agents. Remove “unless asked” to match that behavior.

🐛 Suggested fix
-The `list_agents` tool SHALL return the agents in the caller's project, with each agent's id, slug, name, description, latest revision version and last update time. It SHALL include only workflows flagged `is_agent`, exclude archived agents unless asked, and exclude static platform workflows.
+The `list_agents` tool SHALL return the agents in the caller's project, with each agent's id, slug, name, description, latest revision version and last update time. It SHALL include only workflows flagged `is_agent`, exclude archived agents, and exclude static platform workflows.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
The `list_agents` tool SHALL return the agents in the caller's project, with each agent's id, slug, name, description, latest revision version and last update time. It SHALL include only workflows flagged `is_agent`, exclude archived agents unless asked, and exclude static platform workflows.
The `list_agents` tool SHALL return the agents in the caller's project, with each agent's id, slug, name, description, latest revision version and last update time. It SHALL include only workflows flagged `is_agent`, exclude archived agents, and exclude static platform workflows.

@mmabrouk

mmabrouk commented Nov 3, 2026

Copy link
Copy Markdown
Member Author

🤖 The AI agent says: Closing as marked Out on the v0.128.4 release dashboard. The implementation PR #7409 carries the same spec files, so the spec lands with it.

@mmabrouk mmabrouk closed this Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant