Skip to content

Commit addd04f

Browse files
welsirwelsir
committed
Add spec subagent orchestrator skill
1 parent 3344e97 commit addd04f

4 files changed

Lines changed: 216 additions & 0 deletions

File tree

‎skills/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Here is a complete list of AI Skills available in this repository.
88
| **Long Article Visualization** | 自媒体内容生成 | 将长文章转换为手绘风格的信息图。基于深度阅读、主题规划和视觉设计，最终调用 image-generation skill 生成图片。 | [Source](./long-article-visualization/SKILL.md) |
99
| **Pic Search** | 图片搜索 | Wallhaven 高清壁纸搜索引擎。支持按关键词、颜色、分类搜索高质量图片素材。 | [Source](./pic-search/SKILL.md) |
1010
| **Skill Creator** | 技能开发 | Skill 创建向导。通过交互式 SOP 流程，辅助用户从零创建高质量的 AI Skill。 | [Source](./skill-creator/SKILL.md) |
11+
| **Spec Subagent Orchestrator** | Agent 编排 | 在执行前先锁定 spec-kit 阶段，再把复杂任务路由到合适的 subagent 工作流，避免过早委派和边界漂移。 | [Source](./spec-subagent-orchestrator/SKILL.md) |
1112
| **Visual Discord Briefing** | 视觉内容生成 | 生成结构化视觉简报（5 模板）并输出 Discord webhook JSON（embed + 可点击按钮）及 IM Markdown companion。 | [Source](./visual-discord-briefing/SKILL.md) |
1213
| **Viral Article Rewriter** | 自媒体内容生成 | 爆款长文改写助手。通过“澄清目标-搭建框架-接地气改写-迭代优化”四步法，将长文转化为爆款文案。 | [Source](./viral-article-rewriter/SKILL.md) |
1314
| **Xianyu Post Gen** | 自媒体内容生成 | 闲鱼帖子生成器。基于产品文档一键生成闲鱼标题、正文、封面提示词、竞品借鉴与发布检查清单。 | [Source](./xianyu-post-gen/SKILL.md) |

‎skills/spec-subagent-orchestrator/SKILL.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
name: spec-subagent-orchestrator
3+
description: Orchestrate complex work by combining spec-kit artifacts with the right subagent execution workflow. Use when a task should be structured through `spec.md`, `plan.md`, or `tasks.md` before implementation; when Codex needs to decide whether to fill missing spec-kit stages first; or when execution should be routed between direct work, `subagent-driven-development`, and `subagent-supervisor-constitution`. Triggers on requests to combine spec with subagents, run large multi-step delivery with explicit routing, or turn a spec-driven process into a governed execution system.
4+
---
5+
6+
# Spec Subagent Orchestrator
7+
8+
## Overview
9+
10+
Use this skill as a thin orchestration layer. Do not replace spec-kit or existing subagent skills; decide when to invoke them, in what order, and with which verification gates.
11+
12+
Core rule: lock the right spec artifact first, then choose the lightest execution model that still protects quality and coordination.
13+
Execution model rule: assume a single master orchestrator with no recursive agent tree. To get value from subagents, slice work into atomic executor tasks and dispatch them in multiple rounds.
14+
15+
## Workflow
16+
17+
1. Inspect what already exists.
18+
Look for `spec.md`, `plan.md`, `tasks.md`, or equivalent spec-kit outputs before doing new work.
19+
2. Close the earliest missing artifact.
20+
If the work is still ambiguous, route to spec first.
21+
If the spec exists but execution shape does not, route to plan.
22+
If the plan exists but actionable slices are missing, route to tasks.
23+
3. Classify execution risk and coupling.
24+
Judge independence, write-scope overlap, review churn risk, blast radius, and whether the task can be expressed as an atomic executor unit.
25+
4. Route to the execution mode.
26+
Use direct execution for small, tightly scoped work.
27+
Use [$subagent-driven-development](/Users/welsir/.codex/superpowers/skills/subagent-driven-development/SKILL.md) when tasks are mostly independent and can be executed as separate atomic slices in the current session.
28+
Use [$subagent-supervisor-constitution](/Users/welsir/.codex/skills/subagent-supervisor-constitution/SKILL.md) when the work is medium/high risk, cross-module, drift-prone, or expensive to review incorrectly.
29+
5. Enforce closure gates.
30+
No task is complete until spec alignment, quality review, and local verification all pass.
31+
32+
## Routing Rules
33+
34+
Use this decision order:
35+
36+
1. Is the task still underspecified?
37+
Route to the missing spec-kit stage instead of delegating early.
38+
2. Is the next step blocked on one tightly coupled change?
39+
Stay local only long enough to create atomic slices or dispatch a boundary-locking subagent. Do not keep the whole implementation on the master by default.
40+
3. Can the next work be written as one or more atomic executor tasks?
41+
If not, keep narrowing boundaries until it can.
42+
4. Are there task slices with clean ownership and low overlap?
43+
Route to `subagent-driven-development`.
44+
5. Are there repeated alignment loops, strict boundaries, or high regression risk?
45+
Route to `subagent-supervisor-constitution`.
46+
6. Are both true?
47+
Lock constitution first, then let the supervisor pattern govern dispatch.
48+
49+
Default heuristics:
50+
51+
- Prefer direct work when there are fewer than 3 short steps and no meaningful branch risk.
52+
- Prefer `subagent-driven-development` when tasks are already decomposed into atomic executor slices and write scopes are largely disjoint.
53+
- Prefer `subagent-supervisor-constitution` when task count is not the main problem but coordination risk is.
54+
- Prefer one boundary-locking subagent over long local reasoning when context pressure is rising but execution slices are not yet ready.
55+
56+
Read [workflow-routing.md](references/workflow-routing.md) when the routing choice is not obvious.
57+
58+
## Atomic Executor Rule
59+
60+
Never dispatch a generic worker with a vague brief. Dispatch only atomic executor tasks.
61+
62+
An atomic executor task must have:
63+
64+
- One concrete goal
65+
- One primary deliverable
66+
- Explicit file or module boundaries
67+
- Explicit acceptance checks
68+
- Enough context to execute without re-discovering the whole project
69+
70+
If a task fails these checks, it is not ready for delegation. Narrow it first or use a scoping pass to create smaller slices.
71+
72+
## Lifecycle Slots
73+
74+
Use fixed lifecycle slots, not a fixed cast of agent types:
75+
76+
- `scope`
77+
Lock boundaries, ownership, and dependency edges.
78+
- `execute`
79+
Produce one atomic deliverable.
80+
- `review`
81+
Check spec alignment or quality for one slice.
82+
- `integrate`
83+
Combine accepted slices and resolve seams.
84+
- `repair`
85+
Fix a concrete failed gate.
86+
87+
Each slot can be instantiated multiple times across rounds. Do not assume one broad executor can safely absorb multiple slots.
88+
89+
## Operating Procedure
90+
91+
### 1. Stabilize the artifact chain
92+
93+
- Confirm which of these exists: problem statement, spec, plan, tasks, validation targets.
94+
- Do not let subagents invent scope that should have been locked in spec-kit artifacts.
95+
- If the user already has `spec.md`, `plan.md`, and `tasks.md`, treat those as the source of truth.
96+
97+
### 2. Choose the execution wrapper
98+
99+
- For independent implementation slices in the current session, invoke `subagent-driven-development`.
100+
- For high-risk or cross-boundary work, invoke `subagent-supervisor-constitution` first and follow its constitution, ownership, and gate rules.
101+
- If the task is exploratory, ambiguous, or mostly design, stay local only until a scoping pass can define the next atomic slice.
102+
- If context compression is already hurting the master, dispatch a scoping subagent before doing more local analysis.
103+
104+
### 3. Preserve ownership clarity
105+
106+
- Give each executor a precise write scope.
107+
- Keep the main agent responsible for routing, integration, and final verification.
108+
- Do not let executors redefine acceptance criteria.
109+
- Do not hand one executor multiple unrelated deliverables just because they touch nearby files.
110+
111+
### 4. Dispatch in rounds, not trees
112+
113+
- Assume subagents do not recursively spawn their own child graph.
114+
- Use the master to simulate depth through multiple dispatch rounds.
115+
- Typical pattern: `scope -> execute -> review -> repair -> integrate`.
116+
- Add more executors only when the extra slice lowers total coordination cost.
117+
118+
### 5. Close with explicit gates
119+
120+
- Spec gate: output matches `spec.md` and task scope.
121+
- Quality gate: code or deliverable is maintainable and regression-aware.
122+
- Command gate: rerun the important checks locally before claiming success.
123+
124+
## Non-Goals
125+
126+
- Do not rewrite spec-kit prompts or artifacts.
127+
- Do not duplicate the internal procedures of the subagent skills.
128+
- Do not dispatch vague, multi-goal executor tasks.
129+
- Do not force subagents into tiny tasks where the overhead is larger than the work.
130+
- Do not delegate before task boundaries are real.
131+
- Do not assume recursive subagent trees are available.
132+
133+
## Outputs
134+
135+
When using this skill, produce a short orchestration decision:
136+
137+
1. Current artifact state
138+
Which spec-kit artifacts exist and which are missing.
139+
2. Chosen route
140+
Direct work, `subagent-driven-development`, or `subagent-supervisor-constitution`.
141+
3. Why this route
142+
Independence, risk, coupling, or review-cost reasoning.
143+
4. Next concrete action
144+
The exact next command, skill, or task slice to run.
145+
5. Atomic slice definition
146+
If delegating, state the exact deliverable, write boundary, and acceptance check for the next executor.

‎skills/spec-subagent-orchestrator/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Spec Subagent Orchestrator"
3+
short_description: "Route specs and subagents safely."
4+
default_prompt: "Use this skill to route complex work through the right spec-kit stage and the right subagent workflow before execution."

‎skills/spec-subagent-orchestrator/references/workflow-routing.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Workflow Routing
2+
3+
Use this reference when the correct path is not obvious.
4+
5+
Assume a single master orchestrator. Do not depend on recursive subagent trees.
6+
7+
## Artifact-first ladder
8+
9+
1. No stable problem statement:
10+
Stay local and clarify scope.
11+
2. Problem exists but success is not locked:
12+
Route to spec.
13+
3. Spec exists but implementation shape is vague:
14+
Route to plan.
15+
4. Plan exists but execution slices are not concrete:
16+
Route to tasks.
17+
5. Tasks exist:
18+
Choose the execution wrapper.
19+
6. Tasks exist but are still too broad:
20+
Run a scoping pass to create atomic executor slices.
21+
22+
## Execution wrapper matrix
23+
24+
| Situation | Route |
25+
| --- | --- |
26+
| One small, tightly coupled change | Direct local execution |
27+
| Context pressure is high but boundaries are not fully locked | Dispatch one scoping pass |
28+
| Multiple mostly independent atomic slices, same session | `subagent-driven-development` |
29+
| Cross-module or high-regression task | `subagent-supervisor-constitution` |
30+
| Unclear boundaries plus high risk | Lock constitution, then supervise dispatch |
31+
32+
## Signals for `subagent-driven-development`
33+
34+
- A real task list already exists.
35+
- Slices can be handed off one at a time.
36+
- Each slice has a narrow write scope.
37+
- Each slice has one primary deliverable.
38+
- Review order matters more than parallel throughput.
39+
40+
## Signals for `subagent-supervisor-constitution`
41+
42+
- Ownership drift has happened before.
43+
- Review churn is expensive.
44+
- Multiple modules or teams are implicated.
45+
- Hidden constraints or red lines matter.
46+
- Verification must be rerun locally before merge.
47+
48+
## Refusal conditions
49+
50+
Do not delegate yet when:
51+
52+
- The user is still choosing what to build.
53+
- The acceptance criteria are still moving.
54+
- Every next action depends on the same unresolved design question.
55+
- The work is so small that routing overhead dominates execution.
56+
57+
## Atomic executor checklist
58+
59+
Dispatch only when the next slice has all of:
60+
61+
- One goal
62+
- One deliverable
63+
- Explicit boundaries
64+
- Explicit validation
65+
- No hidden dependency on an unresolved design question

0 commit comments

Comments
 (0)