feat: add assemble skill — PM-orchestrated parallel team execution#683
feat: add assemble skill — PM-orchestrated parallel team execution#683LakshmiSravyaVedantham wants to merge 1 commit intoobra:mainfrom
Conversation
Adds a new /assemble skill that acts as an AI Project Manager, organizing cross-functional teams around a problem statement and executing work in dependency-based waves via real parallel subagents. Key features: - Smart intake: reads README, CLAUDE.md, package manifests, and git history before asking any questions — only asks what it can't infer - Wave-based execution: groups teams by dependency; each wave runs in parallel, locked behind user approval before advancing - 8 default teams in team library: Research, Product, Design, Engineering, Infra, QA, Analysis, Program Management - Structured team contracts: defined input/output artifact schema so agents hand off cleanly between waves - Retry logic: blocked teams get one re-spawn with adjusted scope; persistent blockers surface to the user with hold/continue choice - Live querying: user can ask "what is [team] doing?" at any point - Phase 4 close: writes executive-summary.md on completion Files added: - skills/assemble/SKILL.md — main PM skill - skills/assemble/team-library.md — 8 default team definitions - skills/assemble/team-agent.md — team agent contract and instructions - skills/assemble/status-schema.md — data contracts between PM and agents
📝 WalkthroughWalkthroughIntroduces a new Assemble skill with four Markdown documentation files defining a structured Project Manager capability. The skill organizes cross-functional teams into dependency-based waves across four phases (Intake, Organize, Execute, Close) with specific hard rules, data contracts, and team library definitions. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
skills/assemble/SKILL.md (1)
214-214: Minor redundancy: docs/ directory already created.Line 132 in Phase 3 already creates the
docs/directory withmkdir -p docs. This line duplicates that operation, though it's harmless due to the-pflag making it idempotent.Consider removing this line to reduce redundancy:
## Phase 4 — Close When all waves are complete: -1. Create `docs/` if it does not exist: `mkdir -p docs` -2. Write `docs/executive-summary.md` using the Write tool. Use this format: +1. Write `docs/executive-summary.md` using the Write tool. Use this format:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/assemble/SKILL.md` at line 214, Remove the duplicate "Create `docs/` if it does not exist: `mkdir -p docs`" entry in SKILL.md since Phase 3 already contains the same `mkdir -p docs` step; locate the redundant line text and delete it so the docs/ creation appears only once to avoid redundancy.skills/assemble/team-agent.md (2)
69-73: Consider varying the sentence structure for improved readability.The five hard rules all begin with "Do not," which can feel repetitive. Consider rephrasing some rules using positive constructions or varied openings.
📝 Alternative phrasing suggestions
## Hard Rules -- Do not contact other agents directly. -- Do not do work outside your mission scope. -- Do not write to paths not listed in your output_artifacts. -- Do not return a report without writing all output artifacts first. -- If you write partial output, set status to `partial` and list what was completed in completed_tasks. +- Contact other agents directly is prohibited. +- Work only within your mission scope. +- Write only to paths listed in your output_artifacts. +- Always write all output artifacts before returning a report. +- When writing partial output, set status to `partial` and list what was completed in completed_tasks.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/assemble/team-agent.md` around lines 69 - 73, The list of five hard rules in team-agent.md is repetitive because each line starts with "Do not"; please rephrase some rules to vary sentence structure and improve readability by using positive or alternative openings (e.g., change "Do not contact other agents directly" to "Contact other agents only through the coordinator" or "Avoid contacting other agents directly", reword "Do not do work outside your mission scope" to "Limit work to the defined mission scope", convert "Do not write to paths not listed in your output_artifacts" into "Write only to paths listed in output_artifacts", and clarify the partial-output rule by rephrasing and referencing status and completed_tasks). Ensure the semantics remain identical and update the five hard rules block around the existing mentions of output_artifacts, status, and completed_tasks.
67-73: Be aware of conflicting escalation patterns across skills.The Assemble hard rules enforce strict agent isolation ("Do not contact other agents directly") and a single-retry model with adjusted missions. This differs from the subagent-driven-development skill, which allows interactive escalation where agents can report BLOCKED or NEEDS_CONTEXT and the controller can provide additional context or re-dispatch.
If agents are trained on multiple skills, these conflicting behavioral expectations could cause confusion about when and how to escalate blockers. Consider documenting which skill takes precedence when a project uses multiple orchestration patterns, or ensure skills are mutually exclusive in practice.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/assemble/team-agent.md` around lines 67 - 73, The Assemble skill's Hard Rules (e.g., "Do not contact other agents directly", output_artifacts, status, completed_tasks) conflict with the subagent-driven-development escalation flow (BLOCKED / NEEDS_CONTEXT and interactive controller re-dispatch); update the documentation and/or skill config to resolve this by either (a) explicitly stating precedence when both skills are present (mentioning the Assemble hard rules take precedence over subagent-driven-development escalation), or (b) gating the skills so they are mutually exclusive at runtime, and add a clear note in the Assemble skill docs and any orchestration README describing which escalation pattern (Assemble vs subagent-driven-development) applies and how status values (partial, completed_tasks, BLOCKED, NEEDS_CONTEXT) should be interpreted.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/assemble/SKILL.md`:
- Around line 167-180: The current instructions around a team returning
`blocked` or `partial` and the user choosing "(hold / continue)" lack behavior
for downstream teams; update the workflow where the blocked-after-retry prompt
("🔴 [Team Name] — blocked after retry: [reason] ... (hold / continue)") handles
"continue" by automatically skipping all downstream teams that list the blocked
team in their dependencies (i.e., any team that references the blocked team's
input_artifacts), and clearly inform the user which teams will be skipped and
why before proceeding; ensure the message and decision flow mention the skipped
teams and that their expected input_artifacts will be unavailable.
- Line 16: The documentation uses absolute plugin-cache paths that don't exist;
update the links in SKILL.md to use repository-relative paths by replacing
occurrences of
"~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/status-schema.md",
".../team-library.md", and ".../team-agent.md" with
"skills/assemble/status-schema.md", "skills/assemble/team-library.md", and
"skills/assemble/team-agent.md" respectively so the references point to the
local repo files.
---
Nitpick comments:
In `@skills/assemble/SKILL.md`:
- Line 214: Remove the duplicate "Create `docs/` if it does not exist: `mkdir -p
docs`" entry in SKILL.md since Phase 3 already contains the same `mkdir -p docs`
step; locate the redundant line text and delete it so the docs/ creation appears
only once to avoid redundancy.
In `@skills/assemble/team-agent.md`:
- Around line 69-73: The list of five hard rules in team-agent.md is repetitive
because each line starts with "Do not"; please rephrase some rules to vary
sentence structure and improve readability by using positive or alternative
openings (e.g., change "Do not contact other agents directly" to "Contact other
agents only through the coordinator" or "Avoid contacting other agents
directly", reword "Do not do work outside your mission scope" to "Limit work to
the defined mission scope", convert "Do not write to paths not listed in your
output_artifacts" into "Write only to paths listed in output_artifacts", and
clarify the partial-output rule by rephrasing and referencing status and
completed_tasks). Ensure the semantics remain identical and update the five hard
rules block around the existing mentions of output_artifacts, status, and
completed_tasks.
- Around line 67-73: The Assemble skill's Hard Rules (e.g., "Do not contact
other agents directly", output_artifacts, status, completed_tasks) conflict with
the subagent-driven-development escalation flow (BLOCKED / NEEDS_CONTEXT and
interactive controller re-dispatch); update the documentation and/or skill
config to resolve this by either (a) explicitly stating precedence when both
skills are present (mentioning the Assemble hard rules take precedence over
subagent-driven-development escalation), or (b) gating the skills so they are
mutually exclusive at runtime, and add a clear note in the Assemble skill docs
and any orchestration README describing which escalation pattern (Assemble vs
subagent-driven-development) applies and how status values (partial,
completed_tasks, BLOCKED, NEEDS_CONTEXT) should be interpreted.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 71d0a39a-4846-4f2d-89d8-670231316e91
📒 Files selected for processing (4)
skills/assemble/SKILL.mdskills/assemble/status-schema.mdskills/assemble/team-agent.mdskills/assemble/team-library.md
| - You never proceed to the next wave without user approval. | ||
| - Never read, write, or analyze project artifacts directly — always delegate to team agents. | ||
|
|
||
| Read `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/status-schema.md`, `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/team-library.md`, and `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/team-agent.md` before starting. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if the referenced files exist at the absolute path vs relative path
echo "=== Checking absolute path (as written in SKILL.md) ==="
ls -la ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/*.md 2>&1 | head -5
echo ""
echo "=== Checking relative path (where files actually are) ==="
fd --type f --extension md . skills/assemble/Repository: obra/superpowers
Length of output: 441
🏁 Script executed:
#!/bin/bash
echo "=== Checking lines 16 and context (lines 10-20) ==="
sed -n '10,20p' skills/assemble/SKILL.md
echo ""
echo "=== Checking line 144 and context (lines 140-150) ==="
sed -n '140,150p' skills/assemble/SKILL.md
echo ""
echo "=== Confirming all three referenced files exist ==="
for file in status-schema.md team-library.md team-agent.md; do
if [ -f "skills/assemble/$file" ]; then
echo "✓ $file exists"
else
echo "✗ $file NOT found"
fi
doneRepository: obra/superpowers
Length of output: 1490
Use relative paths for documentation references.
Lines 16 and 144 contain references to an absolute plugin cache directory (~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/...) that does not exist. The files exist in the repository at skills/assemble/.
Fix
Line 16:
-Read `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/status-schema.md`, `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/team-library.md`, and `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/team-agent.md` before starting.
+Read `skills/assemble/status-schema.md`, `skills/assemble/team-library.md`, and `skills/assemble/team-agent.md` before starting.Line 144:
-Read: ~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/team-agent.md
+Read: skills/assemble/team-agent.md📝 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.
| Read `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/status-schema.md`, `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/team-library.md`, and `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/team-agent.md` before starting. | |
| Read `skills/assemble/status-schema.md`, `skills/assemble/team-library.md`, and `skills/assemble/team-agent.md` before starting. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/assemble/SKILL.md` at line 16, The documentation uses absolute
plugin-cache paths that don't exist; update the links in SKILL.md to use
repository-relative paths by replacing occurrences of
"~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.0/skills/assemble/status-schema.md",
".../team-library.md", and ".../team-agent.md" with
"skills/assemble/status-schema.md", "skills/assemble/team-library.md", and
"skills/assemble/team-agent.md" respectively so the references point to the
local repo files.
| **If any team returns `blocked` or `partial`:** | ||
|
|
||
| 1. Re-spawn that team once with an adjusted mission. Add to the mission: "Prior attempt was [blocked/partial] due to: [blocker]. Adjust scope — use a mock, a fallback, or a reduced scope if needed." | ||
| 2. If the retry also returns `blocked` or `partial`, halt. Show the user: | ||
|
|
||
| ``` | ||
| 🔴 [Team Name] — blocked after retry: [reason] | ||
| Downstream teams that depend on this: [list them by name, or write "none — this is a leaf team"] | ||
| Hold (wait for you to resolve) or continue (proceed without this team's output)? | ||
| (hold / continue) | ||
| ``` | ||
|
|
||
| Wait for user input before proceeding. |
There was a problem hiding this comment.
Clarify the impact of "continue" on downstream dependencies.
When a team is blocked after retry, the user can choose "continue (proceed without this team's output)." However, the workflow doesn't explicitly address what happens to downstream teams that depend on the blocked team's output artifacts.
If the user chooses to continue despite a blocker, downstream teams in subsequent waves may fail when they attempt to read the missing input_artifacts. This could cause cascading failures that waste execution time and confuse the user.
Consider one of these approaches:
-
Skip dependent teams: When continuing despite a blocker, automatically skip all downstream teams that list the blocked team in their dependencies, and inform the user which teams will be skipped.
-
Pass empty inputs with warning: Allow downstream teams to proceed but pass them a note that their expected input_artifacts are missing, so they can adapt or report blocked immediately.
-
Explicit user choice per dependent team: Show the user each affected downstream team and ask whether to run it with missing inputs or skip it.
Recommendation: Option 1 provides the safest and most predictable behavior without requiring complex adaptation logic in team agents.
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 172-172: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/assemble/SKILL.md` around lines 167 - 180, The current instructions
around a team returning `blocked` or `partial` and the user choosing "(hold /
continue)" lack behavior for downstream teams; update the workflow where the
blocked-after-retry prompt ("🔴 [Team Name] — blocked after retry: [reason] ...
(hold / continue)") handles "continue" by automatically skipping all downstream
teams that list the blocked team in their dependencies (i.e., any team that
references the blocked team's input_artifacts), and clearly inform the user
which teams will be skipped and why before proceeding; ensure the message and
decision flow mention the skipped teams and that their expected input_artifacts
will be unavailable.
1 participant
What this adds
A new
/assembleskill that acts as an AI Project Manager, organizing cross-functional teams around a problem statement and executing work in dependency-based waves via real parallel subagents.How it works
Phase 1 — Smart Intake
Before asking anything, the PM reads project context:
README.md,CLAUDE.md, package manifests, git history, and anydocs/files. It infers the 4 intake fields (Goal, Constraints, Done, Teams) with a confidence level per field. Only fields it can't determine are asked — everything it can infer is pre-filled and shown to the user for confirmation.Phase 2 — Organize
Selects the minimum set of teams needed. Groups them into waves by dependency. Outputs the full Team-by-Team Board upfront — all waves, all teams, all tasks visible — and waits for user approval before executing.
Phase 3 — Execute
Spawns one Task agent per team in the current wave, runs them in parallel. Handles blocked/partial reports with a retry (adjusted scope), and surfaces persistent blockers to the user with a
hold / continuechoice. Wave-gated: every wave requires user approval before unlocking the next.Phase 4 — Close
Writes
docs/executive-summary.mdand displays all artifacts written across all teams.Querying
At any point: "What is [team] doing?", "Why is [team] blocked?", "Show project status", etc. — answered from in-memory board state, no new agents spawned.
Files
skills/assemble/SKILL.mdskills/assemble/team-library.mdskills/assemble/team-agent.mdskills/assemble/status-schema.mdDefault team library
Research, Product, Design, Engineering, Infra, QA, Analysis, Program Management — PM picks the minimum set needed per project.
Test
Tested end-to-end on a real Python project. Smart intake correctly inferred goal and stack from
README.md+ git history without asking any questions.Built and tested by @LakshmiSravyaVedantham. Happy to adjust anything based on your feedback.