From shinpr-claude-code-workflows
Guides subagent coordination through implementation workflows. Use when orchestrating multiple agents, managing workflow phases, or determining autonomous execution mode.
npx claudepluginhub joshuarweaver/cascade-code-general-misc-1 --plugin shinpr-claude-code-workflowsThis skill uses the workspace's default tool permissions.
**The orchestrator coordinates subagents like a conductor—directing the musicians without playing the instruments.**
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
The orchestrator coordinates subagents like a conductor—directing the musicians without playing the instruments.
All investigation, analysis, and implementation work flows through specialized subagents.
When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result.
During flow execution, monitor user responses for scope-expanding signals:
When any signal is detected → Restart from requirement-analyzer with integrated requirements
The following subagents are available:
The orchestrator passes what to accomplish and where to work. Each specialist determines how to execute autonomously.
Pass to specialists (what/where/constraints):
Let specialists determine (how):
| Bad (orchestrator prescribes how) | Good (orchestrator passes what) | |
|---|---|---|
| quality-fixer | "Run these checks: 1. lint 2. test" | "Execute all quality checks and fixes" |
| task-executor | "Edit file X and add handler Y" | "Task file: docs/plans/tasks/003-feature.md" |
Decision precedence when outputs conflict:
When specialist output contradicts orchestrator expectations, verify against objective repo state (item 3). If repo state confirms the specialist, follow the specialist. Override specialist output only when it conflicts with items 1 or 2.
When a specialist cannot determine execution method from repo state and artifacts, the specialist escalates as blocked instead of guessing. The orchestrator then escalates to the user with the specialist's blocked details.
Assign work based on each subagent's responsibilities:
What to delegate to task-executor:
What to delegate to quality-fixer:
Important: Subagents cannot directly call other subagents—all coordination flows through the orchestrator.
Autonomous execution MUST stop and wait for user input at these points. Use AskUserQuestion to present confirmations and questions.
| Phase | Stop Point | User Action Required |
|---|---|---|
| Requirements | After requirement-analyzer completes | Confirm requirements / Answer questions |
| PRD | After document-reviewer completes PRD review | Approve PRD |
| UI Spec | After document-reviewer completes UI Spec review (frontend/fullstack) | Approve UI Spec |
| ADR | After document-reviewer completes ADR review (if ADR created) | Approve ADR |
| Design | After design-sync completes consistency verification | Approve Design Doc |
| Work Plan | After work-planner creates plan | Batch approval for implementation phase |
After batch approval: Autonomous execution proceeds without stops until completion or escalation
| Scale | File Count | PRD | ADR | Design Doc | Work Plan |
|---|---|---|---|---|---|
| Small | 1-2 | Update※1 | Not needed | Not needed | Simplified |
| Medium | 3-5 | Update※1 | Conditional※2 | Required | Required |
| Large | 6+ | Required※3 | Conditional※2 | Required | Required |
※1: Update if PRD exists for the relevant feature ※2: When there are architecture changes, new technology introduction, or data flow changes ※3: New creation/update existing/reverse PRD (when no existing PRD)
All subagent invocation uses the Agent tool with:
subagent_type: Agent name (e.g., "task-executor")description: Concise task description (3-5 words)prompt: Specific instructions including deliverable pathsThe orchestrator coordinates work using only the following tools:
| Tool | Purpose |
|---|---|
| Agent | Invoke subagents |
| AskUserQuestion | User confirmations and questions |
| TaskCreate / TaskUpdate | Progress tracking |
| Bash | Shell operations (git commit, ls, verification commands) |
| Read | Deliverable documents for information bridging between subagents |
All implementation work (Edit, Write, MultiEdit) is performed by subagents, not the orchestrator.
Every subagent prompt must include:
Construct the prompt from the agent's Input Parameters section and the deliverables available at that point in the flow.
Subagents respond in JSON format. Key fields for orchestrator decisions:
code_paths scoped to changed files)task_file (path to current task file — always pass this in orchestrated flows). Status: approved/stub_detected/blocked. stub_detected → route back to task-executor with incompleteImplementations[] details for completion, then re-run quality-fixer. blocked → discriminate by reason field: "Cannot determine due to unclear specification" → read blockingIssues[] for specification details; "Execution prerequisites not met" → read missingPrerequisites[] with resolutionSteps — present these to the user as actionable next stepsrequirement-analyzer follows the "completely self-contained" principle and processes requirement changes as new input.
Important: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user.
Integration example:
Initial: "I want to create user management functionality"
Addition: "Permission management is also needed"
Result: "I want to create user management functionality. Permission management is also needed.
Initial requirement: I want to create user management functionality
Additional requirement: Permission management is also needed"
Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in update mode.
Criteria for timing when to call each agent:
Always start with requirement-analyzer, then select the minimum document flow required by scale and affected layers.
| Scale | Required flow |
|---|---|
| Large | requirement-analyzer → PRD → PRD review → optional UI Spec → optional ADR → codebase-analyzer → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer |
| Medium | requirement-analyzer → codebase-analyzer → optional UI Spec → optional ADR → Design Doc → code-verifier → document-reviewer → design-sync → acceptance-test-generator → work-planner → task-decomposer |
| Small | requirement-analyzer → work-planner → direct implementation |
Rules:
references/monorepo-flow.mddesign-sync is required whenever multiple Design Docs existtask-decomposer begins only after work-planner batch approvalPrinciple: Verify subagents can complete their responsibilities
Required environments:
If critical environment unavailable: Escalate with specific missing component before entering autonomous mode If detectable by subagent: Proceed (subagent will escalate with detailed context)
After environment check passes:
After "batch approval for entire implementation phase" with work-planner, autonomously execute the following processes without human approval:
graph TD
START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode]
AUTO --> TD[task-decomposer: Task decomposition]
TD --> LOOP[Task execution loop]
LOOP --> TE[task-executor: Implementation]
TE --> ESCJUDGE{Escalation judgment}
ESCJUDGE -->|escalation_needed/blocked| USERESC[Escalate to user]
ESCJUDGE -->|requiresTestReview: true| ITR[integration-test-reviewer]
ESCJUDGE -->|No issues| QF
ITR -->|needs_revision| TE
ITR -->|approved| QF
QF[quality-fixer: Quality check and fixes] --> QFJUDGE{quality-fixer result}
QFJUDGE -->|stub_detected| TE
QFJUDGE -->|approved| COMMIT[Orchestrator: Execute git commit]
QFJUDGE -->|blocked| USERESC
COMMIT --> CHECK{Any remaining tasks?}
CHECK -->|Yes| LOOP
CHECK -->|No| VERIFY[Post-implementation verification]
VERIFY --> CV[code-verifier: DD consistency check]
VERIFY --> SEC[security-reviewer: Security review]
CV --> VRESULT{Verification results}
SEC --> VRESULT
VRESULT -->|All passed| REPORT[Completion report]
VRESULT -->|Any failed| VFIX[task-executor: Verification fixes]
VFIX --> QF2[quality-fixer: Quality check]
QF2 --> REVERIFY[Re-run failed verifiers only]
REVERIFY --> VRESULT
VRESULT -->|blocked| USERESC
LOOP --> INTERRUPT{User input?}
INTERRUPT -->|None| TE
INTERRUPT -->|Yes| REQCHECK{Requirement change check}
REQCHECK -->|No change| TE
REQCHECK -->|Change| STOP[Stop autonomous execution]
STOP --> RA[Re-analyze with requirement-analyzer]
| Verifier | Pass | Fail | Blocked |
|---|---|---|---|
| code-verifier | status is consistent or mostly_consistent | status is needs_review or inconsistent | — |
| security-reviewer | status is approved or approved_with_notes | status is needs_revision | status is blocked → Escalate to user |
Re-run rule: After fix cycle, re-run only verifiers that returned fail. Verifiers that passed on the previous run are not re-run.
Stop autonomous execution and escalate to user in the following cases:
Escalation from subagent
status: "escalation_needed"status: "blocked"When requirement change detected
When work-planner update restriction is violated
When user explicitly stops
Per-task cycle:
status: escalation_needed or blocked → Escalate to userrequiresTestReview is true → Execute integration-test-reviewer
needs_revision → Return to step 1 with requiredFixesapproved → Proceed to step 3task_file
stub_detected → Return to step 1 with incompleteImplementations[] detailsblocked → Escalate to userapproved → Proceed to step 4approved)Register overall phases using TaskCreate. Update each phase with TaskUpdate as it completes.
State Management: Grasp current phase, each subagent's state, and next action
Information Bridging: Data conversion and transmission between subagents
requirement_analysis, prd_path (if exists), original user requirementsfocusAreas → canonical disposition-target list for the Fact Disposition TabledataModel, dataTransformationPipelines, qualityAssurance → Existing Codebase Analysis / Verification Strategy / Quality Assurance sectionsdoc_type: design-doc)code_paths; code-verifier discovers scope from the documentcode_verification JSON and the same codebase_analysis JSON previously given to the designerfocusAreasreferences/monorepo-flow.mdprior_layer_verificationdiscrepancies[] as known issues to address or escalate. Do not infer verified claims that are not explicitly present in the verifier output.Pass to work-planner: Design Doc path. Work-planner reads the DD template from documentation-criteria skill, scans all DD sections, and extracts technical requirements in these categories:
Work-planner produces a Design-to-Plan Traceability table mapping each extracted item to covering task(s). Items without a covering task must be marked as gap with justification. Unjustified gaps are errors. Justified gaps require user confirmation before plan approval.
Pass to acceptance-test-generator:
Orchestrator verification items:
generatedFiles.integration is a valid path (when not null) and the file existsgeneratedFiles.e2e is a valid path (when not null) and the file existsgeneratedFiles.e2e is null, verify e2eAbsenceReason is present — this is intentional absence, not an errorPass to work-planner:
On error: Escalate to user if integration file generation failed unexpectedly (status != completed). E2E being null with a valid absence reason is not an error.
ADR Status Management: Update ADR status after user decision (Accepted/Rejected)
references/monorepo-flow.md: Fullstack (monorepo) orchestration flow