epic-04/06: restructure SKILL.md as orchestrator with subagent delegation by mtalvi · Pull Request #29 · rh-ai-quickstart/quickstart-factory

mtalvi · 2026-07-28T07:42:05Z

Summary

Rewrites rh-qs-discovery/SKILL.md from a flat instruction file into a phased orchestrator that delegates focused work to subagents and references all supporting documents created in PRs 01-05.

What changed

The original SKILL.md was a single flat document with interview questions, requirement mappings, and a simple 7-step workflow checklist. The rewrite restructures it into an 8-phase orchestrator:

Phase	What happens	New capability
1. Initial Input	Accept input, classify type (document/conversation/raw_idea)	Input type detection
2. Backlog Check	Spawn backlog-matcher subagent	Subagent delegation (PR-03)
3. Issue Destination	Ask user where to track work	Preserved from original
4. Generate Spec	Read spec-template.md, produce discovery-spec.yaml	Spec-as-contract (PR-04)
5. Interview / Structuring	Run interview OR spawn prd-structurer subagent for docs	Subagent delegation (PR-02)
6. Requirement Mapping	Map vague ideas to concrete requirements	Preserved from original
7. PRD Validation	Read reasoning-guardrails.md, validate + uncapped refinement	Guardrails (PR-05)
8. Write PRD	Read output-templates.md, write final PRD	Template-driven output (PR-01)

Key design decisions

Orchestrator, not monolith. SKILL.md coordinates phases and delegates heavy lifting (document parsing, backlog comparison) to subagents via the Agent tool. It never reads subagent prompts directly -- passes them by file path.
All domain content preserved. The interview questions table (lines 130-141), requirement mapping table (lines 155-161), issue destinations table (lines 90-95), and gap analysis mode (lines 198-212) are carried forward from the original SKILL.md unchanged.
Supporting Documents table (lines 28-42) makes explicit which files the main agent reads vs which are delegated to subagents. This prevents the orchestrator from loading unnecessary context.
Uncapped refinement (lines 178-185) -- the user can refine the PRD as many times as they want with no iteration limit.

Test plan

SKILL.md frontmatter includes name, description, argument-hint, allowed-tools
All 8 phases are present and in correct order (Input → Backlog Check → Issue Destination → Spec → Interview → Mapping → Validation → Write PRD)
Subagent invocations pass prompt files by path (not inline content) -- check lines 67-76 and 113-123
Supporting Documents table correctly separates "main agent reads" from "subagent reads"
All 6 file references resolve to existing files: reasoning-guardrails.md, spec-template.md, output-templates.md, references/gap-analysis-template.md, subagents/prd-structurer-prompt.md, subagents/backlog-matcher-prompt.md
Original domain content preserved: interview questions (10 topics), requirement mapping (4 patterns), issue destinations (3 options), gap analysis mode
Gap analysis mode references references/gap-analysis-template.md (not output-templates.md)
No references to files outside rh-qs-discovery/ except gh-backlog-reader script path

Define the YAML structure for .rhoai-qs/pipeline/discovery-spec.yaml, the interview plan contract between initial input analysis and PRD generation. Includes spec_version header, acceptance criteria (all user-approved), validation rules, and a concrete example. Co-authored-by: Cursor <cursoragent@cursor.com>

Discovery runs in the factory repo where multiple quickstart ideas may coexist. Use .rhoai-qs/<slug>/pipeline/ instead of .rhoai-qs/pipeline/ so specs don't overwrite each other. Added exception note to pipeline-convention.md. Co-authored-by: Cursor <cursoragent@cursor.com>

Five concern areas the agent reasons about organically during PRD generation: scope creep, technology bias, GPU assumptions, completeness without over-specification, and user voice fidelity. Follows the concern-area format from docs/foundation/reasoning-guardrails-template.md. Co-authored-by: Cursor <cursoragent@cursor.com>

Rewrite discovery SKILL.md from a flat skill into an orchestrator with 8 workflow phases, subagent delegation via file-path passing, and spec-as-contract integration. Preserves all domain content (interview questions, requirement mapping, issue destinations, gap analysis mode) while delegating document parsing and backlog matching to subagents. Co-authored-by: Cursor <cursoragent@cursor.com>

Point SKILL.md gap analysis mode at references/gap-analysis-template.md instead of output-templates.md, following the split in the 01 branch. Co-authored-by: Cursor <cursoragent@cursor.com>

List references/gap-analysis-template.md in the main agent reads table so the document inventory is complete after the split. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

YosiElias

Thanks @mtalvi !
I've left a few comments, but besides that, it looks great! 🚀

Just a small question - do you happen to remember the token usage for this run, including the sub-agents? I think we should start tracking it so we keep agents in their context window "sweet spot".

YosiElias · 2026-07-28T14:20:40Z

- [ ] 6. Write PRD to data/prds/<slug>.md
- [ ] 7. Confirm with user before rh-qs-architect
-```
+### Phase 7: PRD Validation and Refinement


I really like that you performed validation before writing the PRD, that's great and will save tokens.
I highly recommend splitting this validation into a sub-agent since the main agent is already biased in this phase. Of course, the sub-agent will not be allowed to change the draft, but only make recommendations to the main agent - this way, we ensure changes are made with a broader perspective (main agent) and reviews are done from a clean context (sub-agent).

YosiElias · 2026-07-28T16:59:47Z

-**Gap questions (always ask when relevant):**
+**Gap questions (ask when relevant to the idea):**

 - Will this need RAG?


This one feels like a specific question rather than a general gap.
Also, just a suggestion, but maybe we could give the agent a bit more freedom to choose its own questions in this gap part (like a "grill-me" style)? We could just instruct it to ask whenever something is unclear rather than specific questions. WDYT?

YosiElias · 2026-07-28T17:02:48Z

+|------|------|
+| [reasoning-guardrails.md](./reasoning-guardrails.md) | Phase 7 — PRD validation and refinement |
+| [spec-template.md](./spec-template.md) | Phase 4 — generating the discovery spec |
+| [output-templates.md](./output-templates.md) | Phase 8 — writing the final PRD |


prd-structurer subagent also read this file

YosiElias · 2026-07-28T17:04:14Z

-## Trigger
+## Goal
+
+Produce a validated Product Requirements Document (PRD) at `data/prds/<slug>.md` that is ready for handoff to `rh-qs-architect`. The PRD captures the user's quickstart idea with enough detail for architectural design without pre-deciding implementation choices.


Same as here

mtalvi marked this pull request as ready for review July 28, 2026 08:27

mtalvi requested review from JoshSalomon, YosiElias and sauagarwa July 28, 2026 08:27

mtalvi and others added 6 commits July 28, 2026 16:34

update gap analysis reference to new template location

20706a9

Point SKILL.md gap analysis mode at references/gap-analysis-template.md instead of output-templates.md, following the split in the 01 branch. Co-authored-by: Cursor <cursoragent@cursor.com>

add gap-analysis-template to supporting documents table

46e9735

List references/gap-analysis-template.md in the main agent reads table so the document inventory is complete after the split. Co-authored-by: Cursor <cursoragent@cursor.com>

update SKILL.md spec path to use slug-namespaced directory

b6caafa

Co-authored-by: Cursor <cursoragent@cursor.com>

mtalvi force-pushed the epic-04/06-orchestrator-skill branch from eef719c to b6caafa Compare July 28, 2026 13:36

YosiElias reviewed Jul 28, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

epic-04/06: restructure SKILL.md as orchestrator with subagent delegation - #29

epic-04/06: restructure SKILL.md as orchestrator with subagent delegation#29
mtalvi wants to merge 7 commits into
rh-ai-quickstart:mainfrom
mtalvi:epic-04/06-orchestrator-skill

mtalvi commented Jul 28, 2026 •

edited

Loading

Uh oh!

YosiElias left a comment

Uh oh!

YosiElias Jul 28, 2026

Uh oh!

YosiElias Jul 28, 2026

Uh oh!

YosiElias Jul 28, 2026

Uh oh!

YosiElias Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

mtalvi commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Key design decisions

Test plan

Uh oh!

YosiElias left a comment

Choose a reason for hiding this comment

Uh oh!

YosiElias Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

YosiElias Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

YosiElias Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

YosiElias Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mtalvi commented Jul 28, 2026 •

edited

Loading