From nexus
Run a multi-agent pipeline to produce detailed technical requirements and a ticket-ready summary. Creates a feature branch, persists session state, and supports resume. Optionally seeds from a prior brainstorm session.
npx claudepluginhub nexus-a1/claude-skills --plugin nexusThis skill is limited to using the following tools:
Create comprehensive, step-by-step technical requirements documentation for a given task or feature. Establishes persistent work context that enables `/implement` and `/resume-work` to continue seamlessly.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Create comprehensive, step-by-step technical requirements documentation for a given task or feature. Establishes persistent work context that enables /implement and /resume-work to continue seamlessly.
This skill produces REQUIREMENTS DOCUMENTS. It does NOT implement anything.
/implement when they are ready to implementThis skill supports two execution modes, controlled by execution_mode in .claude/configuration.yml:
| Mode | Value | Deep-Dive Behavior | Token Cost | Best For |
|---|---|---|---|---|
| Team | "team" (default) | Agent teammates with cross-pollination via SendMessage | Higher quality | Most features — agents collaborate |
| Sub-agent | "subagent" | Parallel Task calls, independent agents | Lower token cost | Quick iterations, cost-sensitive |
Team mode adds: Agents can read each other's outputs during deep-dive, enabling cross-pollination of findings. The lead monitors progress and notifies agents when peer findings become available.
This skill produces the canonical Spec-Driven Development triad — three artifacts with distinct audiences:
state.json — State file for resume capabilitycontext/ — Cached agent outputs for referencespec.md — WHAT & WHY. User stories + Given/When/Then acceptance criteria. Product-facing, no implementation details.plan.md — HOW. Technical approach, files to touch, data model, integrations, risks. Implementer-facing.tasks.md — EXECUTE. Dependency-ordered, AC-linked task list. Agent-/engineer-executable.{identifier}-JIRA_TICKET.md — Derived view of spec.md for pasting into a tracker. Not a peer artifact.All saved to $WORK_DIR/{identifier}/.
Layer boundary rule: If a statement answers HOW or references specific code, it belongs in plan.md — never in spec.md. tasks.md entries MUST cite at least one acceptance-criterion ID from spec.md.
Read .claude/configuration.yml for project-specific paths and execution mode. If the file doesn't exist or a key is missing, use defaults:
| Config Key | Default | Purpose |
|---|---|---|
execution_mode | "team" | Agent execution mode ("subagent" or "team") |
storage.artifacts.work | location: local, subdir: work | Work state and context |
Optional integrations (only if artifact exists in configuration.yml):
| Config Key | Enables |
|---|---|
storage.artifacts.requirements | archivist agent |
storage.artifacts.product-knowledge | product-expert agent |
# Source resolve-config: marketplace installs get ${CLAUDE_PLUGIN_ROOT} substituted
# inline before bash runs; ./install.sh users fall back to ~/.claude. If neither
# path resolves, fail loudly rather than letting resolve_artifact be undefined.
if [ -f "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh" ]; then
source "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh"
elif [ -f "$HOME/.claude/shared/resolve-config.sh" ]; then
source "$HOME/.claude/shared/resolve-config.sh"
else
echo "ERROR: resolve-config.sh not found. Install via marketplace or run ./install.sh" >&2
exit 1
fi
WORK_DIR=$(resolve_artifact work work)
REQUIREMENTS_DIR=$(resolve_artifact requirements requirements)
EXEC_MODE=$(resolve_exec_mode requirements_deep_dive team)
Use $WORK_DIR instead of hardcoded .claude/work throughout this workflow.
Use $EXEC_MODE to determine team vs sub-agent behavior at stages 2, 3, 4, 4.5, and 4.6.
Important: All path references in this skill MUST use $WORK_DIR. Never use hardcoded .claude/work/ paths.
Agents working in parallel MUST NOT write to the same file. Follow these conventions:
$WORK_DIR/{identifier}/context/{agent-name}.md (e.g., context/archaeologist.md, context/data-modeler.md). Agents NEVER write to another agent's output file.state.json and final output documents (spec.md, plan.md, tasks.md, {identifier}-JIRA_TICKET.md).${WORK_DIR}/manifest.json.context/discovery.json.See ~/.claude/shared/write-safety.md for the full conventions.
If $ARGUMENTS begins with --light, strip the flag and enable lightweight mode:
This reduces cost for the analysis/synthesis phase. In most cases the deep-dive agents are already Sonnet, so the savings come from the business-analyst downgrade.
Before collecting any input, scan for active requirements sessions.
if [[ -f "${WORK_DIR}/manifest.json" ]]; then
jq -r '.items[] | select(.type == "requirements" and .status != "completed") | "\(.identifier)\t\(.title)\t\(.current_phase)\t\(.progress)\t\(.updated_at)"' "${WORK_DIR}/manifest.json"
fi
If active sessions found, display them and ask:
Active requirements sessions:
[1] PROJ-123 — User Export Feature
Stage: deep_dive (Stage 3/4) — last updated 3 hours ago
[2] PROJ-456 — SSO Integration
Stage: setup (Stage 1/4) — last updated 2 days ago
[n] Start new session
Select session to resume, or [n] to start fresh:
Use AskUserQuestion. On selection: load state from $WORK_DIR/{identifier}/state.json and resume from the recorded stage. On n: proceed to Stage 1.
If no active sessions: Proceed directly to Stage 1.
Goal: Establish work identifier, create feature branch, initialize state.
Use AskUserQuestion:
What is the ticket number for this work?
Format: PROJECT-NUMBER (e.g., JIRA-123, PROJ-456, SKILLS-001)
VALIDATION: The ticket MUST match pattern [A-Z]+-[0-9]+ (e.g., JIRA-123, SKILLS-001).
If user provides a slug instead of ticket number, ask them to provide the ticket number.
Store as {ticket}. The full {identifier} is composed in §1.4 after the feature context is known.
If not provided in $ARGUMENTS, use AskUserQuestion:
Describe the feature or task to create requirements for:
Store as {feature_description}.
Goal: Clarify ambiguous requirements before running heavy agent pipeline.
Ask 3-5 targeted questions to refine the user's requirements. Use AskUserQuestion with multi-select where appropriate.
Question categories (select relevant ones based on feature description):
Scope clarification:
What should be IN scope for this feature?
- [ ] New API endpoints
- [ ] Database changes
- [ ] UI changes
- [ ] Background jobs
- [ ] External integrations
- [ ] Other: ___
User/Actor identification:
Who will use this feature?
- [ ] End users (customers)
- [ ] Admin users
- [ ] System/automated processes
- [ ] External services
- [ ] Other: ___
Edge cases & constraints:
Are there specific constraints or edge cases to consider?
- Performance requirements (e.g., must handle X requests/sec)
- Data volume expectations
- Backward compatibility needs
- Security/compliance requirements
- Other: ___
Success criteria:
How will we know this feature is complete?
Describe the key acceptance criteria:
Dependencies & blockers:
Are there any dependencies or blockers?
- Waiting on external API access
- Depends on another feature
- Needs design approval
- Other: ___
Output: Store refined requirements as {refined_requirements} with:
Skip refinement if: User provides comprehensive requirements upfront (includes scope, acceptance criteria, and constraints). Use judgment.
If $ARGUMENTS contains --from-brainstorm {slug}, extract the slug. Otherwise, ask:
AskUserQuestion:
Do you have a prior brainstorm session for this feature?
Enter the brainstorm slug (e.g., "user-data-export"), or leave blank to skip.
If a slug is provided:
$WORK_DIR/{brainstorm-slug}/state.json exists and has "type": "brainstorm".BRAINSTORM_CONTEXT_DIR="$WORK_DIR/{brainstorm-slug}/context"
BRAINSTORM_STATE="$WORK_DIR/{brainstorm-slug}/state.json"
{brainstorm_slug} and {has_brainstorm_context: true}.# Update brainstorm state: mark promoted
jq --arg tid "{identifier}" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
'.status = "promoted" | .promoted_to = $tid | .updated_at = $ts' \
"$WORK_DIR/{brainstorm-slug}/state.json" > /tmp/bs-tmp.json \
&& mv /tmp/bs-tmp.json "$WORK_DIR/{brainstorm-slug}/state.json"
# Update manifest entry for brainstorm (if manifest exists)
if [[ -f "$WORK_DIR/manifest.json" ]]; then
jq --arg slug "{brainstorm-slug}" --arg tid "{identifier}" \
'(.items[] | select(.identifier == $slug)) |= (.status = "promoted" | .promoted_to = $tid)' \
"$WORK_DIR/manifest.json" > /tmp/mf-tmp.json && mv /tmp/mf-tmp.json "$WORK_DIR/manifest.json"
fi
{promoted_from: "{brainstorm-slug}"} — this will be written into the requirements state file at Stage 1.6."Loading brainstorm context from: {brainstorm_slug} (marking as promoted → {identifier})"If blank / not found: Set {has_brainstorm_context: false}. Continue normally.
Brainstorm context is injected at two points downstream:
With {ticket} (from §1.1) and the refined requirements (§1.3) now in hand, derive a kebab-case slug (2–5 meaningful words, lowercase, ASCII, joined with -) from the refined requirements. Drop filler words. Confirm with the user via AskUserQuestion:
Derived slug: {slug}
Proposed work identifier: {ticket}-{slug}
Accept, or enter a different slug?
Compose {identifier} = {ticket}-{slug} (per the Work Directory Naming Convention in CLAUDE.md).
This will be used for:
feature/{identifier}$WORK_DIR/{identifier}/[{ticket}] type(scope): description (commit prefix stays ticket-only)spec.md, plan.md, tasks.md, {identifier}-JIRA_TICKET.mdFetch available branches and present options:
git fetch origin
git branch -r | grep -E 'origin/(master|main|release/)' | head -10
Use AskUserQuestion:
Select base branch for this work:
[1] origin/master (default)
[2] origin/main
[3] origin/release/v{latest}
...
[Other] Enter custom branch
Store as {base_branch}.
CRITICAL: This step MUST complete successfully before proceeding.
Create the branch locally. Remote push is deferred to Stage 2 (after initial context has been gathered).
Run inline — local branch creation has no hook restrictions beyond the existing guard:
git checkout -b feature/{identifier} {base_branch}
VERIFICATION (required):
# Verify we're on the feature branch
current_branch=$(git branch --show-current)
if [[ "$current_branch" != "feature/{identifier}" ]]; then
echo "ERROR: Not on expected branch. Expected: feature/{identifier}, Actual: $current_branch"
exit 1
fi
echo "✓ On feature branch: $current_branch"
If branch creation fails: See Error Handling section.
mkdir -p $WORK_DIR/{identifier}/context
Write $WORK_DIR/{identifier}/state.json:
{
"schema_version": 1,
"type": "requirements",
"identifier": "{identifier}",
"title": "{feature_description_summary}",
"status": "in_progress",
"created_at": "{ISO_TIMESTAMP}",
"updated_at": "{ISO_TIMESTAMP}",
"execution_mode": "{EXEC_MODE}",
"branches": {
"base": "{base_branch}",
"feature": "feature/{identifier}",
"remote_pushed": false
},
"requirements": {
"original": "{feature_description}",
"refined": {
"scope": ["..."],
"actors": ["..."],
"constraints": ["..."],
"acceptance_criteria": ["..."],
"dependencies": ["..."]
}
},
"brainstorm": {
"promoted_from": "{brainstorm_slug or null}",
"has_context": "{has_brainstorm_context}"
},
"stages": {
"setup": {"stage": 1, "status": "completed"},
"discovery": {"stage": 2, "status": "pending", "agent": "context-builder"},
"deep_dive": {"stage": 3, "status": "pending", "agents_to_run": []},
"synthesis": {"stage": 4, "status": "pending", "agent": "business-analyst"},
"resolve_flags": {"stage": 4.5, "status": "pending", "conditional": true},
"re_synthesis": {"stage": 4.6, "status": "pending", "conditional": true},
"architecture_validation":{"stage": 4.7, "status": "pending", "conditional": true},
"skeptic_validation": {"stage": 4.8, "status": "pending", "conditional": true}
},
"team": {
"name": null,
"created": false
},
"outputs": {
"technical_requirements": null,
"jira_ticket": null
},
"updates": []
}
If {has_brainstorm_context} is false, omit the brainstorm key or set both fields to null.
VERIFICATION (required):
# Verify state file was created successfully
if [[ ! -f "$WORK_DIR/{identifier}/state.json" ]]; then
echo "ERROR: Failed to create state file"
echo "Location: $WORK_DIR/{identifier}/state.json"
exit 1
fi
# Verify it's valid JSON
if jq empty "$WORK_DIR/{identifier}/state.json" 2>/dev/null; then
echo "✓ State file created and validated"
else
echo "ERROR: State file is not valid JSON"
cat "$WORK_DIR/{identifier}/state.json"
exit 1
fi
After creating the state file, upsert into ${WORK_DIR}/manifest.json (see docs/manifest-system.md).
Read or initialize manifest, then upsert item using identifier as unique key:
{
"identifier": "{identifier}",
"title": "{feature_description_summary}",
"type": "requirements",
"status": "in_progress",
"created_at": "{ISO_TIMESTAMP}",
"updated_at": "{ISO_TIMESTAMP}",
"current_phase": "setup",
"progress": "Stage 1/4",
"branch": "feature/{identifier}",
"tags": [],
"path": "{identifier}/"
}
Update last_updated and total_items in the envelope.
if [ -n "${CLAUDE_SESSION_ID:-}" ] && command -v jq >/dev/null 2>&1; then
mkdir -p "$WORK_DIR"
touch "$WORK_DIR/.active-sessions.lock"
(
flock -x -w 2 200 || exit 0
[ -s "$WORK_DIR/.active-sessions" ] || echo '{}' > "$WORK_DIR/.active-sessions"
jq --arg s "$CLAUDE_SESSION_ID" --arg w "{identifier}" \
'. + {($s): $w}' "$WORK_DIR/.active-sessions" \
> "$WORK_DIR/.active-sessions.tmp.$$" \
&& mv "$WORK_DIR/.active-sessions.tmp.$$" "$WORK_DIR/.active-sessions" \
|| rm -f "$WORK_DIR/.active-sessions.tmp.$$"
) 200>"$WORK_DIR/.active-sessions.lock"
fi
No-op when CLAUDE_SESSION_ID is unset or jq is missing. Enables the optional auto-context.sh PostToolUse hook to route entries to this session's state.json. Cleared at Stage 4.11 completion.
Goal: Verify that an existing implementation doesn't already satisfy the ticket before running the full pipeline.
After setup completes, run a quick feasibility check:
Search for existing implementations matching the feature description:
# Use Grep to search for existing implementations matching the feature description
# Search for key terms from the feature description in controllers, services, endpoints
If a match is found, present it to the user:
Use AskUserQuestion:
Existing implementation found that may satisfy this requirement:
File: {path}
Match: {brief description of what was found}
Does this already satisfy the requirement?
[y] Yes — halt pipeline and document the finding
[n] No — continue with full requirements pipeline
[p] Partial — continue but note existing implementation as context
If YES: Halt the pipeline. Update state:
{
"status": "completed",
"completed_at": "{ISO_TIMESTAMP}",
"resolution": "existing_implementation",
"existing_path": "{path}",
"note": "Existing implementation already satisfies requirement"
}
Report to the user and stop.
If PARTIAL: Save the existing implementation path to $WORK_DIR/{identifier}/context/existing-implementation.md and continue to Stage 2. This context will inform downstream agents.
If NO or no match found: Continue to Stage 2.
Goal: Build structured context inventory using context-builder agent. If team mode, also create the agent team.
Skip this step if EXEC_MODE == "subagent".
Read references/team-mode-protocol.md § "Stage 2.1" for the TeamCreate call, task graph definition (T1–T9), and TaskUpdate dependency wiring.
Sub-agent mode — Use Task tool with subagent_type: "context-builder":
Team mode — Use Task tool with subagent_type: "context-builder", team_name: "req-{identifier}", name: "context-builder":
Prompt (same for both modes):
Build a structured context inventory for the following feature.
Feature: {feature_description}
Repository: {current_repo}
{IF has_brainstorm_context: "Prior brainstorm context available at: $WORK_DIR/{brainstorm_slug}/context/exploration.md and context/business-context.md — use these as your starting inventory and verify/extend rather than re-discovering from scratch."}
Create an inventory of:
1. Endpoints - existing API endpoints that may be affected
2. Services - service classes involved
3. Entities - database entities related to this feature
4. Config - environment variables and configuration
5. External APIs - third-party integrations
6. Documentation - existing docs (README, Swagger, etc.)
7. Gaps - areas where documentation is missing
Return a structured JSON inventory that downstream agents can use.
Team mode extra: Add to prompt: "Save your output to $WORK_DIR/{identifier}/context/discovery.json. Mark task T1 as completed when done."
Save output to $WORK_DIR/{identifier}/context/discovery.json
Push the branch to remote for team visibility and resume capability, now that initial context has been gathered.
Run inline. No new commits have been made yet — we're pushing the branch pointer only — so security-auditor state from the base branch's HEAD applies. Record it first:
bash "${CLAUDE_PLUGIN_ROOT}/hooks/record-audit.sh"
git push -u origin feature/{identifier}
VERIFICATION (required):
if ! git rev-parse --verify origin/feature/{identifier} &>/dev/null; then
echo "WARNING: Failed to push feature branch to remote"
echo "Branch exists locally but not on origin"
echo "Continuing with local branch only - remote push can be retried later"
else
echo "✓ Branch pushed to remote: origin/feature/{identifier}"
fi
Note: Remote push failure is a WARNING, not a blocker. Requirements gathering can continue with a local branch. Update state:
{
"updated_at": "{ISO_TIMESTAMP}",
"branches": {
"remote_pushed": true
}
}
Update state.json:
{
"updated_at": "{ISO_TIMESTAMP}",
"stages": {
"discovery": {"stage": 2, "status": "completed", "agent": "context-builder"},
"deep_dive": {
"stage": 3,
"status": "in_progress",
"agents_to_run": ["archaeologist", ...]
}
}
}
Goal: Run specialized agents based on what the feature involves.
IMPORTANT: Run all applicable agents in parallel using multiple Task tool calls in a single message. This significantly reduces execution time.
Based on discovery findings, determine which agents to run.
Always run:
| Agent | Purpose |
|---|---|
archaeologist | Analyze code patterns, data flow, modification risks |
architect | Map architectural constraints any implementation must satisfy |
Conditionally run based on discovery findings:
| Condition | Agent | Purpose |
|---|---|---|
| If DB entities found in discovery | data-modeler | Analyze schema and relationships |
| If external APIs found in discovery | integration-analyst | Map API contracts |
| If AWS/cloud resources detected | aws-architect | Infrastructure requirements |
| If auth/sensitive data involved | security-requirements | Security requirements |
Conditionally run based on project configuration:
Check .claude/configuration.yml for optional integrations:
# CONFIG already resolved in the Configuration section above
# Check for requirements artifact config (enables archivist)
yq -e '.storage.artifacts.requirements' "$CONFIG" 2>/dev/null
# Check for product knowledge artifact config (enables product-expert)
yq -e '.storage.artifacts.product-knowledge' "$CONFIG" 2>/dev/null
| Condition | Agent | Purpose |
|---|---|---|
storage.artifacts.requirements exists in configuration.yml | archivist | Search historical requirements for similar work |
storage.artifacts.product-knowledge exists in configuration.yml | product-expert | Product-specific patterns and context |
Execute in a single message with multiple Task tool calls.
Sub-agent mode: Each agent runs as an independent sub-agent via Task(subagent_type=...).
Team mode: Each agent runs as a teammate via Task(subagent_type=..., team_name="req-{identifier}", name="{agent-name}"). Each agent's prompt gets this extra instruction:
Check $WORK_DIR/{identifier}/context/ for files from other agents.
If files exist from agents that completed before you, incorporate relevant findings into your analysis.
After completing your analysis, save your output to $WORK_DIR/{identifier}/context/{agent-name}.md as your FINAL action before returning.
Mark your task as completed when done.
Before launching agents, distill discovery gaps into targeted questions.
Review context-builder's discovery output for flagged gaps, inconsistencies, or open questions. Inject these as additional targeted questions into the relevant agent prompts:
This prevents broad, undirected analysis and eliminates second-pass supplements.
Agent prompts (shared between both modes):
Read references/deep-dive-agent-prompts.md for the complete prompt templates for each deep-dive agent (Tasks 1-7). Each prompt includes the template variables to fill from Stage 1-2 outputs.
Skip this step if EXEC_MODE == "subagent".
Read references/team-mode-protocol.md § "Stage 3.3" for the TaskList monitoring loop, 10-line distillation rule, and SendMessage format for cross-pollinating completed agent findings.
For each agent that completed, verify its output file exists on disk. In team mode, agents save their own files. In sub-agent mode, the orchestrator saves them. In both modes, verify with Glob.
Verification loop — run for each agent that was launched:
for agent in archaeologist architect data-modeler integration-analyst aws-architect security-requirements archivist product-expert; do
expected="$WORK_DIR/{identifier}/context/${agent}.md"
if [[ agent was run ]]; then
# Glob check — lightweight verification
if [[ ! -f "$expected" ]] || [[ ! -s "$expected" ]]; then
echo "WARNING: ${agent} output missing or empty — saving from agent response"
# Save agent's returned content using Write tool (fallback)
else
echo " ✓ ${agent}.md"
fi
fi
done
Note: Only discovery.json (context-builder) is JSON. All other agent outputs are markdown.
Priority: File verification MUST complete before proceeding to Stage 4 (Synthesis). Business-analyst reads files from disk — missing files cause gaps in synthesis.
VERIFICATION (required):
# Verify required agent outputs were saved
if [[ ! -f "$WORK_DIR/{identifier}/context/archaeologist.md" ]]; then
echo "WARNING: Missing archaeologist output (required agent)"
echo "This may cause issues in implementation phase"
fi
# Verify discovery.json is valid JSON (only context-builder outputs JSON)
if [[ -f "$WORK_DIR/{identifier}/context/discovery.json" ]]; then
if ! jq empty "$WORK_DIR/{identifier}/context/discovery.json" 2>/dev/null; then
echo "WARNING: Invalid JSON in discovery.json"
fi
fi
# List saved context files
for file in $WORK_DIR/{identifier}/context/*; do
if [[ -f "$file" ]] && [[ -s "$file" ]]; then
echo " ✓ $(basename $file)"
fi
done
echo "✓ Agent outputs verified and saved"
Update state.json:
{
"updated_at": "{ISO_TIMESTAMP}",
"stages": {
"deep_dive": {"stage": 3, "status": "completed", "agents_run": ["archaeologist", ...]},
"synthesis": {"stage": 4, "status": "in_progress", "agent": "business-analyst"}
}
}
Before moving on to Stage 4, produce a ≤10-line stage summary of the Stage 3 deep-dive and carry ONLY this summary forward in the orchestration context. Drop the verbose per-agent outputs (archaeologist, architect, data-modeler, integration-analyst, aws-architect, security-requirements, archivist, product-expert) from working memory — they remain on disk at $WORK_DIR/{identifier}/context/.
The summary should cover:
context/archaeologist.md, context/architect.md, ... — the business-analyst prompt below already tells the agent to Read() these directly, so the orchestrator does NOT need to carry their full contentsThe business-analyst agent (Stage 4.1) reads the full files from disk via its prompt. The orchestrator does not need the full outputs in context to run Stage 4; the summary is enough to monitor progress and answer follow-ups. If Stage 4 deadlocks or produces re-synthesis questions, Re-Read() specific context files only for the question at hand — do not re-include all of them.
Alongside the ≤10-line orchestrator summary above (which lives only in working memory), write per-agent disk summaries so /resume-work and /load-context don't reload full deep-dive outputs on restart.
For each Stage 3 file that exists under $WORK_DIR/{identifier}/context/ (archaeologist.md, architect.md, data-modeler.md, integration-analyst.md, aws-architect.md, security-requirements.md, archivist.md, product-expert.md):
Read() the full filePATTERNS: 3 stable / 2 risky, SCHEMA: compatible with proposed FK, SEC: 1 control gap)file:line or table/column referencesWrite() to $WORK_DIR/{identifier}/context/{agent}-summary.mdThe full .md files remain the authoritative source. Stage 4.1 (business-analyst) still reads the full files via its prompt because synthesis needs the complete reasoning. Summaries are strictly for cheaper downstream resume — consumers (/resume-work, /load-context) fall back to the full file when the summary is absent.
Goal: Consolidate all findings into final requirements documents.
Sub-agent mode — Use Task tool with subagent_type: "business-analyst".
Team mode — Use Task tool with subagent_type: "business-analyst", team_name: "req-{identifier}", name: "business-analyst".
IMPORTANT: Do NOT inline all agent outputs into the prompt. Instead, tell the business-analyst where to find them. This avoids token overflow when many agents ran.
Prompt (same for both modes):
Consolidate all agent findings into final requirements.
Feature: {feature_description}
Refined Requirements: {refined_requirements}
Work directory: $WORK_DIR/{identifier}/
Agent findings are saved in the context directory. Read each file that exists:
- $WORK_DIR/{identifier}/context/discovery.json (context-builder inventory — JSON format)
- $WORK_DIR/{identifier}/context/archaeologist.md (code patterns, data flow, risks)
- $WORK_DIR/{identifier}/context/architect.md (architectural constraints, layer rules, patterns)
- $WORK_DIR/{identifier}/context/data-modeler.md (if exists - DB schema analysis)
- $WORK_DIR/{identifier}/context/integration-analyst.md (if exists - external API mapping)
- $WORK_DIR/{identifier}/context/aws-architect.md (if exists - infrastructure requirements)
- $WORK_DIR/{identifier}/context/security-requirements.md (if exists - security needs)
- $WORK_DIR/{identifier}/context/archivist.md (if exists - historical context from similar work)
- $WORK_DIR/{identifier}/context/product-expert.md (if exists - product-specific patterns)
Tasks:
1. Read all available context files above
2. **Mechanism verification (mandatory pre-check before writing MUST requirements):**
For each implementation mechanism you intend to state as a MUST requirement, verify it appears in `discovery.json` (or another agent's findings) with a compatible API signature. If a mechanism is asserted without supporting evidence — or if the discovered signature is incompatible with the intended use (e.g., per-record accessor used as a batch query) — flag it as `BLOCKER: unverified mechanism` instead of writing it as a MUST. This prevents downstream rework from QA-gate-detected structural flaws.
3. Resolve any conflicts between agent findings
4. Prioritize requirements (MoSCoW)
5. Identify risks (Technical, Business, Timeline)
6. **Business decisions table:** For each open business decision (defaults, opt-in/out, scope, rollout), produce a table with columns `Decision | Options | Stakeholder Implications | Recommended Default`. Include this table even if `product-expert` did not run.
7. Validate against user's acceptance criteria from refinement phase
8. Note any performance considerations (queries, caching, scalability)
Produce FOUR documents, separated by the exact markers shown below. This follows **Spec-Driven Development**: spec describes WHAT/WHY, plan describes HOW, tasks describe EXECUTION, jira is a derived summary.
**Layer boundary — enforce strictly:**
- `SPEC` contains NO file paths, class names, library choices, or code. Only user stories and observable behavior.
- `PLAN` contains the HOW — file paths, patterns, data schemas, integration contracts, risks.
- `TASKS` is a numbered, dependency-ordered list. Every task MUST cite one or more AC IDs from SPEC (format: `Covers: AC-1.2, AC-3.1`).
- `JIRA_TICKET` is a light paste-ready summary derived from SPEC — no HOW details.
Token budgets: SPEC ≤1500, PLAN ≤2500, TASKS ≤1200, JIRA_TICKET ≤800.
Use this EXACT format:
---BEGIN SPEC---
# {Feature Title}
## Summary
(One paragraph: WHAT the feature is and WHY it matters. No HOW.)
## User Stories
- **US-1**: As a {role}, I want {capability}, so that {outcome}.
- **US-2**: ...
## Acceptance Criteria
Each AC is a Given/When/Then scenario, grouped under its user story. Assign stable IDs (AC-{story}.{n}).
### AC for US-1
- **AC-1.1**
- Given {precondition}
- When {action}
- Then {observable outcome}
- **AC-1.2** ...
### AC for US-2
...
## Security & Compliance Criteria
(From `security-requirements` if present — expressed as Given/When/Then, e.g. authn/authz, data handling, audit.)
- **AC-SEC-1** ...
## Out of Scope
- {explicit exclusions}
## Open Questions
- {surfaced by synthesis or skeptic — or "None" }
---END SPEC---
---BEGIN PLAN---
# Technical Plan — {Feature Title}
## Approach
(2–3 paragraphs: narrative of the chosen approach and WHY it fits the existing architecture.)
## Files to Touch
(From archaeologist; `path — purpose`.)
- `src/...` — ...
## Architecture Constraints
(From architect: layer rules, DI patterns, SOLID concerns, dependency direction.)
## Data Model
(From data-modeler if present: entity changes, migrations, indices, query patterns. Omit section if N/A.)
## External Integrations
(From integration-analyst if present: API contracts, webhook patterns, resilience. Omit if N/A.)
## Security & Infrastructure Notes
(Implementation-level notes from security-requirements / aws-architect. Do NOT restate AC — cross-ref `AC-SEC-*`.)
## Risks & Mitigations (MoSCoW)
| Priority | Risk | Mitigation |
|----------|------|------------|
| Must | ... | ... |
## Decision Log
(Conflict resolutions from synthesis — format: `Decision | Options | Chosen | Rationale`.)
---END PLAN---
---BEGIN TASKS---
# Implementation Tasks — {Feature Title}
Ordered by dependency. Every task cites one or more AC IDs from SPEC.
## Wave 1 (no dependencies)
- [ ] **T-1** — {Short title}
- Scope: {1–2 lines — what this task produces}
- Covers: AC-1.1, AC-1.2
- [ ] **T-2** — ...
- Covers: AC-2.1
## Wave 2 (depends on Wave 1)
- [ ] **T-3** — ...
- Depends on: T-1
- Covers: AC-1.3
## Parallelization
Tasks safe to run concurrently: {T-1, T-2}; {T-4, T-5}.
## Coverage Check
Every AC in SPEC maps to at least one task:
- AC-1.1 → T-1
- AC-1.2 → T-1
- ...
---END TASKS---
---BEGIN JIRA_TICKET---
# {Feature Title}
**Summary** (1 paragraph — paste-ready for ticket body)
**Background**
- Problem:
- Impact:
- Solution (at a glance):
**Acceptance Criteria**
- AC-1.1: {one-line collapsed form of the Given/When/Then}
- AC-1.2: ...
**Out of Scope**
- ...
**Links**
- Full spec: `spec.md`
- Technical plan: `plan.md`
- Task breakdown: `tasks.md`
---END JIRA_TICKET---
IMPORTANT: Use the exact ---BEGIN/END--- markers. They are used to extract each document into separate files. Do NOT include HOW details in SPEC or JIRA_TICKET. Do NOT restate AC content in PLAN — reference by ID.
Team mode extra: Add to prompt: "Mark your task as completed when done."
Note: Performance review is deferred to implementation phase where code-reviewer can analyze actual code changes.
Save all synthesis outputs to the work directory:
# Save business-analyst raw output
# Write to: $WORK_DIR/{identifier}/context/business-analyst.md
# Save the four triad documents
# Write to: $WORK_DIR/{identifier}/spec.md
# Write to: $WORK_DIR/{identifier}/plan.md
# Write to: $WORK_DIR/{identifier}/tasks.md
# Write to: $WORK_DIR/{identifier}/{identifier}-JIRA_TICKET.md
Extract the four documents using the ---BEGIN/END--- markers:
---BEGIN SPEC--- and ---END SPEC--- → save as $WORK_DIR/{identifier}/spec.md---BEGIN PLAN--- and ---END PLAN--- → save as $WORK_DIR/{identifier}/plan.md---BEGIN TASKS--- and ---END TASKS--- → save as $WORK_DIR/{identifier}/tasks.md---BEGIN JIRA_TICKET--- and ---END JIRA_TICKET--- → save as $WORK_DIR/{identifier}/{identifier}-JIRA_TICKET.md$WORK_DIR/{identifier}/context/business-analyst.mdIf markers are missing: The business-analyst did not follow the output contract. Save the entire response as $WORK_DIR/{identifier}/context/business-analyst.md, log an ERROR naming which marker(s) were missing, and re-invoke the business-analyst with the prompt appended: "Your previous output was missing block(s): {LIST}. Re-emit using the exact four-block format." Do not proceed past Stage 4.2 without all four files present.
VERIFICATION (required):
missing=0
for f in spec.md plan.md tasks.md "{identifier}-JIRA_TICKET.md"; do
if [[ ! -f "$WORK_DIR/{identifier}/$f" ]]; then
echo "ERROR: $f not saved"
missing=1
fi
done
[[ $missing -eq 1 ]] && exit 1
# Verify business-analyst raw output was saved
if [[ ! -f "$WORK_DIR/{identifier}/context/business-analyst.md" ]]; then
echo "WARNING: Business analyst raw output not saved to context/"
fi
# Lightweight triad coherence checks
if ! grep -qE '^##? *Acceptance Criteria' "$WORK_DIR/{identifier}/spec.md"; then
echo "WARNING: spec.md has no Acceptance Criteria section"
fi
if ! grep -qE 'AC-[0-9A-Z]' "$WORK_DIR/{identifier}/tasks.md"; then
echo "WARNING: tasks.md does not cite any AC IDs — tasks must link back to spec"
fi
echo "✓ Triad (spec/plan/tasks) + JIRA view saved"
Goal: If the business-analyst flagged contradictions, coverage gaps, or unresolved assumptions in its output, resolve them by spawning targeted re-analysis agents.
Read references/resolve-flagged-issues.md for the complete conditional re-analysis protocol — flag detection, sub-agent and team mode variants, example prompts, verification, and state updates.
Goal: Re-run business-analyst to incorporate targeted re-analysis findings. Only runs if Stage 4.5 (Resolve Flagged Issues) executed.
If Stage 4.5 was skipped: Skip this stage too.
{
"updated_at": "{ISO_TIMESTAMP}",
"stages": {
"re_synthesis": {"stage": 4.6, "status": "skipped", "reason": "no flags to resolve"}
}
}
If Stage 4.5 ran: Continue with re-synthesis.
Update state:
{
"updated_at": "{ISO_TIMESTAMP}",
"stages": {
"re_synthesis": {"stage": 4.6, "status": "in_progress", "agent": "business-analyst"}
}
}
Read references/re-synthesis-prompt.md for the complete re-synthesis business-analyst prompt template. Use it with sub-agent or team mode as appropriate.
Overwrite the original synthesis outputs with the updated versions:
# Overwrite business-analyst raw output
# Write to: $WORK_DIR/{identifier}/context/business-analyst.md
# Overwrite the four triad documents
# Write to: $WORK_DIR/{identifier}/spec.md
# Write to: $WORK_DIR/{identifier}/plan.md
# Write to: $WORK_DIR/{identifier}/tasks.md
# Write to: $WORK_DIR/{identifier}/{identifier}-JIRA_TICKET.md
Extract using the same four-block ---BEGIN/END--- marker logic as Stage 4.2 (SPEC, PLAN, TASKS, JIRA_TICKET).
If markers are missing: Use the same recovery as Stage 4.2 — re-invoke business-analyst with an explicit list of missing blocks.
VERIFICATION (required):
missing=0
for f in spec.md plan.md tasks.md "{identifier}-JIRA_TICKET.md"; do
if [[ ! -f "$WORK_DIR/{identifier}/$f" ]]; then
echo "ERROR: Re-synthesized $f not saved"
missing=1
fi
done
[[ $missing -eq 1 ]] && exit 1
echo "✓ Re-synthesis outputs saved (overwriting initial synthesis)"
{
"updated_at": "{ISO_TIMESTAMP}",
"stages": {
"re_synthesis": {"stage": 4.6, "status": "completed", "agent": "business-analyst"}
}
}
One pass only. If issues persist after re-synthesis, they are documented in the requirements as "REQUIRES HUMAN DECISION" sections. No further iteration occurs.
Goal: For requirements that touch shared/core services, introduce new injection patterns, or modify global config scope — validate the business-analyst's conflict resolutions before declaring requirements complete.
When to run: Check plan.md. If any of these conditions are true, run this step:
If none of the conditions are met: Skip this stage.
Use Task tool with subagent_type: "architect":
Prompt: Validate the architectural decisions in this technical plan.
Plan: $WORK_DIR/{identifier}/plan.md
(Reference only — do NOT propose changes to) Spec: $WORK_DIR/{identifier}/spec.md
Focus on:
1. Are conflict resolutions between agents architecturally sound?
2. Do proposed patterns align with existing codebase architecture?
3. Are there hidden coupling or scaling concerns?
4. Does the plan respect the architecture constraints it claims to follow?
Do NOT challenge WHAT/WHY — that belongs to spec.md and is out of scope here.
If you find HOW-level issues, recommend specific corrections to plan.md.
Return: Validation result (APPROVED / CONCERNS) with details.
If CONCERNS raised: Present to user via AskUserQuestion with the architect's feedback. Allow the user to accept, modify, or override.
Save architect output to $WORK_DIR/{identifier}/context/architect-validation.md.
Goal: Challenge the synthesized requirements through an independent adversarial review before declaring them complete.
Use Task tool with subagent_type: "quality-guard":
Prompt: Review the Spec-Driven triad as a skeptic challenger.
Spec (WHAT/WHY): $WORK_DIR/{identifier}/spec.md
Plan (HOW): $WORK_DIR/{identifier}/plan.md
Tasks (EXECUTE): $WORK_DIR/{identifier}/tasks.md
JIRA view: $WORK_DIR/{identifier}/{identifier}-JIRA_TICKET.md
Agent context files: $WORK_DIR/{identifier}/context/
Report findings per layer — do NOT conflate layers:
1. **Spec gates** — unstated assumptions, vague/unfalsifiable acceptance criteria, missing edge cases, scope gaps, HOW-leakage (any file path, class name, or library choice in spec.md is a violation).
2. **Plan gates** — unverified mechanisms, file paths that don't exist, patterns that conflict with the codebase, hidden coupling, missing risk mitigations, claims not backed by an agent context file.
3. **Tasks gates** — every AC in spec.md must be covered by at least one task; every task must cite AC IDs; dependency ordering sound; no task silently introduces scope not in spec.
4. **Cross-layer gates** — JIRA view accurately reflects spec; plan covers every AC; decision log justifies HOW choices against spec intent.
Cross-reference claims against the actual codebase — verify file paths, patterns, and assumptions.
Focus on Level 1 (Requirements Validation). Do NOT review implementation code — there is none yet.
Return a Quality Review Gates report grouped by the four categories above.
Process the skeptic's verdict:
"skeptic_verdict": "approved"Max iterations: 2. If skeptic raises gates, agents address them, and skeptic still has concerns after a second pass, document remaining concerns in the ## Open Questions section of spec.md (for WHAT/WHY gaps) or the ## Risks & Mitigations section of plan.md (for HOW concerns), then proceed.
Save skeptic output to $WORK_DIR/{identifier}/context/quality-guard.md.
Update state:
{
"updated_at": "{ISO_TIMESTAMP}",
"stages": {
"skeptic_validation": {
"stage": 4.8,
"status": "completed",
"verdict": "approved|conditional_override|conditional_resolved",
"gates_raised": 3,
"gates_resolved": 3,
"iterations": 1
}
}
}
Skip this step if EXEC_MODE == "subagent".
Read references/team-mode-protocol.md § "Stage 4.8.5" for the SendMessage shutdown sequence, TeamDelete call, and state update.
Update state.json:
{
"status": "completed",
"completed_at": "{ISO_TIMESTAMP}",
"updated_at": "{ISO_TIMESTAMP}",
"stages": {
"setup": {"stage": 1, "status": "completed"},
"discovery": {"stage": 2, "status": "completed"},
"deep_dive": {"stage": 3, "status": "completed", "agents_run": [...]},
"synthesis": {"stage": 4, "status": "completed"},
"resolve_flags": {"stage": 4.5, "status": "completed|skipped"},
"re_synthesis": {"stage": 4.6, "status": "completed|skipped"},
"architecture_validation": {"stage": 4.7, "status": "completed|skipped", "conditional": true},
"skeptic_validation": {"stage": 4.8, "status": "completed", "verdict": "..."}
},
"outputs": {
"spec": "spec.md",
"plan": "plan.md",
"tasks": "tasks.md",
"jira_ticket": "{identifier}-JIRA_TICKET.md"
}
}
Update the work manifest to reflect completion (see docs/manifest-system.md).
Upsert item using identifier as unique key with updated fields:
{
"identifier": "{identifier}",
"title": "{feature_description_summary}",
"type": "requirements",
"status": "completed",
"created_at": "{from_state}",
"updated_at": "{ISO_TIMESTAMP}",
"current_phase": "completed",
"progress": "Stage 4/4 (feedback loop: completed|skipped)",
"branch": "feature/{identifier}",
"tags": [],
"path": "{identifier}/"
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Requirements Complete: {identifier}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Feature: {title}
Branch: feature/{identifier}
Base: {base_branch}
Mode: {EXEC_MODE} {if team: "(cross-pollination enabled)"}
Work Directory: $WORK_DIR/{identifier}/
Output Files (Spec-Driven triad):
- spec.md ← WHAT / WHY (user stories + Given/When/Then AC)
- plan.md ← HOW (technical approach, files, data, risks)
- tasks.md ← EXECUTE (dependency-ordered, AC-linked)
- {identifier}-JIRA_TICKET.md ← derived view for ticket paste
Agents Used:
✓ context-builder (discovery) {if team: "[teammate]"}
┌ ✓ archaeologist (code analysis) {if team: "[teammate]"}
│ {✓ data-modeler - if used}
│ {✓ integration-analyst - if used}
│ {✓ aws-architect - if used} [PARALLEL]
│ {✓ security-requirements - if used}
│ {✓ archivist - if used}
└ {✓ product-expert - if used}
✓ business-analyst (synthesis) {if team: "[teammate]"}
{if feedback loop ran:}
┌ {✓ agent-name (re-analysis: contradiction) - for each}
└ {✓ agent-name (re-analysis: gap/assumption) - for each} [FEEDBACK]
✓ business-analyst (re-synthesis)
{end if}
✓ quality-guard (validation: {verdict})
Gates: {gates_resolved}/{gates_raised} resolved
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Requirements are complete. This skill has finished.
Next Steps (for YOU to run when ready):
1. Implement: /implement $WORK_DIR/{identifier}/
2. Resume later: /resume-work {identifier}
STOP HERE. Do not enter plan mode. Do not propose implementation. Do not ask to proceed with implementation. The user will invoke /implement when ready.
# Clear auto-context sentinel on completion
if [ -n "${CLAUDE_SESSION_ID:-}" ] \
&& [ -f "$WORK_DIR/.active-sessions" ] \
&& command -v jq >/dev/null 2>&1; then
(
flock -x -w 2 200 || exit 0
jq --arg s "$CLAUDE_SESSION_ID" 'del(.[$s])' "$WORK_DIR/.active-sessions" \
> "$WORK_DIR/.active-sessions.tmp.$$" \
&& mv "$WORK_DIR/.active-sessions.tmp.$$" "$WORK_DIR/.active-sessions" \
|| rm -f "$WORK_DIR/.active-sessions.tmp.$$"
) 200>"$WORK_DIR/.active-sessions.lock"
fi
Read references/error-handling.md for error recovery procedures (branch creation fails, agent fails, team creation fails, remote push fails). All error recovery uses AskUserQuestion.
Read references/quality-checklist.md for the full stage-by-stage verification checklist.