autonomous-agent-design
Use when designing or evaluating an autonomous agent workflow. Covers task decomposition, tool scoping, result contracts, failure modes, and the shadow → draft → autonomous maturity sequence.
- License 许可
- MIT
- 所属仓库
- pixeloven/crew
- 最近更新
- 2026-11-07
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- autonomous-agent-design
- tier
- concept
- requires
- []
- description
- Use when designing or evaluating an autonomous agent workflow. Covers task decomposition, tool scoping, result contracts, failure modes, and the shadow → draft → autonomous maturity sequence.
- expects-local
- [ "agent-runtime" ]
03 SKILL.md 正文
Core design principles
Behavioral specialization → skills. Operational specialization → agents. Most specialization pressure resolves into a skill file, not a new agent. Only add an agent when the role genuinely requires a different stance or different tool scope.
Generic role agents, domain knowledge in skills. Six role agents (Lead, Triage, Investigator, Researcher, Implementer, Reviewer) cover the work modes. A consumer with a genuinely different work mode adds its own role in its overlay — curation, for instance, is a Librarian in one deployment and nothing at all in another. Specificity flows through skill composition.
Privilege gradient. Read-only and draft-only agents cover most work. Implementer is the deliberate write path. Design new capabilities at the lowest privilege level that accomplishes the task.
Task decomposition
Well-designed autonomous tasks are:
- Bounded — a clear start state, end state, and definition of done
- Single-purpose — one agent, one responsibility per task
- Checkable — acceptance criteria that are machine-verifiable, not "looks right"
- Recoverable — a defined action if the task fails (retry, escalate, or skip)
Complex work that spans multiple tasks belongs in a plan, not a single agent invocation.
Tool scoping
Give each agent the minimum tools needed for its role:
| Agent | Write tools? | Cluster access? |
|---|---|---|
| Triage | Labels and comments only | No |
| Researcher | Research note and issue comments; reply drafts in its response, never posted | No |
| Investigator | Issues and comments | Read-only |
| Reviewer | PR comments only | No |
| Implementer | Code, manifests, PRs | No (via the GitOps controller) |
| Lead | Issues, plans, dispatch | No |
Don't give an agent write access it doesn't need. A Researcher that can push code is a liability.
Result contracts
Every autonomous agent produces a structured result. The result must be:
- Written to a structured result file at a path the runtime defines
- Parseable by the orchestrator (Lead or the runtime's exit handler)
- Sufficient for the next phase to proceed without re-reading the agent's full output
Minimum result fields: summary, status (success/partial/failed), list of artifacts produced.
Failure modes
Design for three failure classes:
| Class | Handling |
|---|---|
| Transient | Retry with backoff — network, rate limit, temporary unavailability |
| Structural | No retry — escalate to human; task is broken |
| Success | Proceed to next phase |
The concrete signaling (exit codes, result-file status fields) is the runtime's contract — see the project's agent-runtime local skill. A common mapping uses 75 / 1 / 0 for transient / structural / success, but the local contract is authoritative.
A task that silently succeeds while producing wrong output is worse than a clean failure. Validate output before signaling success.
Maturity sequence
Shadow → Draft → Autonomous. Never skip stages.
| Stage | Agent behavior | Human role |
|---|---|---|
| Shadow | Runs, produces output, takes no action | Reviews output manually |
| Draft | Produces artifacts (PRs, issue drafts, comments) but does not publish | Reviews and approves before publish |
| Autonomous | Runs and publishes without review | Reviews asynchronously; intervenes on escalation |
Earn autonomy on narrow, well-understood surfaces before expanding. A reviewer that auto-merges PRs is not a reviewer — it's a rubber stamp.
Idempotency
Autonomous agents run repeatedly — scheduled sweeps, retries, re-triggers. Every agent action must be safe to run twice:
- Opening an issue: check for duplicates before filing
- Writing a vault note: check the substrate first (see the project's knowledge-capture local skill Read Routing) so you don't duplicate prior analysis
- Applying labels: idempotent by nature
- Writing code: operate on a fresh branch per task
04 同仓库更多 Skills
orchard-gh-runs
Use when reading a failed GitHub Actions run with the gh CLI in this project, before re-running it or reporting a CI failure, so the failing step's log is read instead of the whole run.
orchard-gh
Hand-edited after promotion; the learned marker was dropped, so Doctor and check_skills --local can no longer see it.
demo-topology
Use when exercising the inventory contract fixture so that this fixture description comfortably clears the schema-v2 minimum length.
helper-jq
Use when exercising the inventory contract fixture so that this fixture description comfortably clears the schema-v2 minimum length.
user-notes
Use when exercising the inventory contract fixture so that this fixture description comfortably clears the schema-v2 minimum length.
toolkit-gh
Use when exercising the inventory contract fixture so that this fixture description comfortably clears the schema-v2 minimum length.