help-flow

<help_flow> <description_and_purpose> Audience: developers and orchestrators exploring Rosetta-powered workspaces. Use when: "what can you do", "how do I use X", "how to develop with Rosetta", "what workflows are available", or any capability discovery question. Provides: guides user on how to use Rosetta and its capabilities; live overview of available skills, workflows, and agents; detailed guidance on matched capabilities; seamless handoff to any discovered workflow within the same session; Consider user sees this first time, you must explain, be clear, specific, non-ambiguous, user should just be able to follow it. </description_and_purpose> <invocation_guidance> When presenting capabilities to users, always show concrete slash command examples following this pattern: `/[command-name] [request in natural language]` QUICKSTART REFERENCE PATTERN — use this exact style for all examples shown to users: ``` /coding-flow Implement side bar on the home page, ... /coding-flow Identify and implement fix, ... /coding-flow Improve unit tests coverage to 85% for ... /requirements-authoring-flow Extract detailed business and technical requirements from ... using subagents. /modernization-flow Perform modernization phase 1 to reuse library refsrc/... using subagents. /research-flow Investigate OAuth 2.0 implementation options for our stack /ui-aqa-flow Create UI test automation for the checkout flow /api-aqa-flow Automate backend API tests for TC-1234 with Swagger: https://api.example.com/swagger.json ``` HOW WORKFLOWS EXECUTE: Workflows are multi-phase pipelines. The AI guides the user through each phase automatically — HITL gates pause for user review and approval at critical decisions. Users invoke the workflow once with a slash command and follow AI guidance; they do not manage phases manually. DIRECT SKILL INVOCATION (also supported): Skills can be invoked directly. Slash command = folder name of the skill. Naming rule: `skills/[folder-name]/SKILL.md` → `/[folder-name] [request]` WHAT MAKES A VALID DIRECT SKILL EXAMPLE — a valid request must have all three: 1. Specific artifact or target (not "this error" or "the tests" — name the file, log, or exact thing) 2. Explicit method or action (not "investigate" alone — state what to produce and how) 3. Explicit scope constraint (state what NOT to do, or what the boundary is) WORKFLOWS ARE SELF-CONTAINED — they invoke skills internally: `coding-flow` handles all coding tasks and invokes debugging, testing, and other skills itself as needed. Similarly, every other workflow invokes its own skills internally. Users should never manually invoke `/debugging`, `/testing`, `/coding`, or similar skills for work that belongs inside a workflow — the workflow handles that automatically. BAD examples (do NOT show these — they are wrong): - `/coding Debug this error in auth.py` — `/coding` is an IMPLEMENTATION skill invoked internally by `coding-flow`, not a standalone tool; and `coding-flow` invokes `/debugging` itself when needed - `/debugging Investigate why payment tests fail` — too vague: no specific artifact, no expected output, no constraint; and if a fix is needed afterward, this belongs in `coding-flow` entirely - `/research Compare event sourcing vs CRUD for our order service` — this IS what `/research-flow` is for; using the skill directly bypasses the structured research workflow; PRIORITY RULE applies GOOD examples: - `/natural-writing Rewrite the executive summary in docs/CONTEXT.md — remove AI clichés, max 4 sentences, audience is a new engineer joining the project` - `/debugging Read the stack trace in agents/TEMP/error.log — identify root cause only, do NOT propose fixes, report findings` DIRECT SUBAGENT INVOCATION (also supported): Subagents can be invoked directly. Slash command = file name without `.md`. Naming rule: `agents/[name].md` → `/[name] [request]` Same rule applies — each example must specify the artifact, method, and constraints. Vague requests like "Design the auth module" or "Implement the payment service" require a full workflow, not direct subagent invocation. GOOD examples: - `/architect Question me and initialize as a loop a project-brief.md as concise dense document for business context, technical context, architecture, tech stack, etc. No coding.` - `/reviewer Check current git changes, understand what was changed and why, validate against AC, find gaps or possible issues according to DoD` - `/reviewer Validate implemented changes by actually running the code and using manual QA by AI` PRIORITY RULE — WORKFLOWS ARE PREFERRED: When a workflow and a skill or subagent share a similar name or purpose, always recommend the WORKFLOW. Reason: workflows provide the full structured process — discovery, specs, plan, review, HITL gates, subagent delegation, and validation — that open-ended or multi-step requests require. Direct skill and subagent invocation is ONLY appropriate for targeted, self-contained, one-pass tasks where the user already knows exactly what they want done and it does not require phases, plan approval, or review by a separate agent. </invocation_guidance> <workflow_phases> <prerequisites phase="0", applies="ALL"> 1. All Rosetta prep steps MUST be FULLY completed, SKILL `load-project-context` loaded and fully executed. 2. MUST use todo tasks for reliability 3. Phases are sequential. Orchestrator coordinates; trust skills and subagents to execute. 4. Scale: conversational — output is a message, no files, no state tracking. </prerequisites> <list_capabilities phase="1" subagent="discoverer" role="KB catalog lister"> 1. List capabilities from KB with XML format: - `LIST workflows` - `LIST skills`, then `LIST skills/<name>` for each. - `LIST agents` 2. Build `Capability Catalog`: name, type (workflow/skill/agent), description — from frontmatter only. 3. Input: user request. Output: `Capability Catalog`. 4. Recommended skills: any currently useful. </list_capabilities> <match_and_acquire phase="2" subagent="discoverer" role="Capability matcher"> 1. Match user request against `Capability Catalog`. 2. For each match, load it: `READ FLOW <name>.md` / `READ SKILL <name>` / `READ SUBAGENT <name>` per its type (e.g., `READ FLOW coding-flow.md`). 3. Extract: purpose, when to use, what to expect, inputs/outputs, HITL gates. 4. Input: user request + `Capability Catalog`. Output: `Matched Capabilities`. 5. Recommended skills: any currently useful. </match_and_acquire> <guide phase="3" subagent="discoverer" role="Capability guide"> 1. Synthesize `Capability Catalog` and `Matched Capabilities` into developer-friendly guidance at 101 level. - Brief table of all capabilities. - Matched: what it does, when to use, what to expect, how to invoke. - For "how to invoke": MUST follow the slash command pattern in `<invocation_guidance>` — show real examples using the QUICKSTART format. - Concrete next actions relevant to user request. - Do not give templates => apply it yourself and give fully correct instruction 2. Input: `Capability Catalog` + `Matched Capabilities` + user request. Output: guidance message. 3. USE SKILL `natural-writing` for final user-facing output. 4. Recommended skills: `reasoning`, and any currently useful. 5. HITL: present guide; ask if deeper drill-down is needed. </guide> <handoff phase="4" optional="true" type="orchestrator"> 1. Triggered when user shifts from help to action (e.g., "run that workflow", "let's do coding"). 2. `READ FLOW <selected workflow>.md` if not already loaded. 3. Adopt acquired workflow as active flow; start from its phase 1. 4. Help-flow yields control — does not wrap the adopted workflow. </handoff> </workflow_phases> <pitfalls> - Overloading a person with deep details -> adjust depth according how narrow question is - Showing trees instead of forest - Mechanical answers instead of looking at those from user perspective who will use those workflow with AI executing those instructions (not user) - Only answering -> proactively ask what is unclear, what is needed, how can you help - Overloading with a lot of text -> use simple, clear, short sentences, < 15 words each, < 5 sentences - Using only text -> use diagrams, use ASCII art, use colors, formatting - Using workflows files only -> in plugins mode entire repo is cloned, use PLUGIN ROOT relative paths `../../user-guide/{README,*}.md`, `../../user-guide/scenarios/*.md`, `../../docs/web/docs/*-flow.md` </pitfalls> </help_flow>