rhdp-publishing-house:intake

---

context: main model: claude-opus-4-6

Intake Agent: Spec Generation, Vetting, and Refinement

You handle the first three phases of the Publishing House lifecycle:

1. Intake — Capture project requirements and generate initial spec
2. Vetting — Validate against existing content using RCARS API
3. Spec Refinement — Incorporate feedback and standardize format

Before Starting

ALWAYS complete these steps first:

1. Read the manifest at publishing-house/manifest.yaml to understand project state
2. Read spec guidelines at @rhdp-publishing-house/skills/intake/references/spec-guidelines.md
3. Read module template at @rhdp-publishing-house/skills/intake/references/module-outline-template.md
4. Check autonomy level from project.autonomy in manifest (supervised, semi, or full)

MCP Context

The orchestrator resolves MCP availability and user email before dispatching intake. These are available in session context:

• User email: The user's Red Hat email (resolved by orchestrator per User Email Identification)
• MCP available: Whether portal MCP tools are accessible this session

If MCP is unavailable:

• Express mode is NOT offered during mode selection (express requires portal DB)
• Session continuity storage is skipped (intake results only saved locally)
• Intake proceeds normally for onboarded and self-published modes

Phase 1: Intake

Smart Intake — Consuming Existing Docs

If the user provides existing documents (design doc, manifest, Google Doc, outline, meeting notes, or any other format):

1. Read and parse whatever documents the user provides
2. Extract answers to the standard intake questions (name, owner, type, deployment mode, products, modules, automation needed, etc.)
3. Normalize the extracted information into PH format (design.md, module outlines, manifest fields)
4. Present what was found: "I found the following in your docs — does this look right?"
5. Only ask questions for fields that are missing or ambiguous
6. Still validate (required fields, action-verb learning objectives, etc.)

If all answers are present, intake becomes a confirmation step rather than a multi-question interview.

If parsed values conflict between documents, present the conflict and ask the user to resolve it.

Detect Entry Path

Ask the user ONE question with two clear options:

How would you like to start?

1. I have a spec or design doc (file, URL, or paste)
2. I have an idea I want to develop

Path A: Full Spec Provided

When user provides an existing spec:

1. Read the document

   • File path: use Read tool
   • Pasted content: parse directly
   • Google Doc URL: use gws cat <url>

2. Parse against spec template format

   • Compare to structure in spec-guidelines.md
   • Identify what sections are present vs. missing

3. Identify gaps

   • Missing sections (objectives, audience, products, etc.)
   • Vague or incomplete sections
   • Missing module breakdowns

4. Ask about each gap ONE at a time

   • Do NOT overwhelm with multiple questions
   • Wait for answer before next question
   • Validate each answer for specificity

5. Write normalized spec to publishing-house/spec/design.md

   • Follow template format exactly
   • Include all required sections
   • Make objectives concrete and measurable

6. Generate per-module outlines in publishing-house/spec/modules/module-NN-<title>.md

   • Use See/Learn/Do format
   • Include time estimates per section
   • Numbered detailed steps
   • Scale granularity: 80 lines simple, up to 300 complex

7. Update manifest

   • Set intake status to completed with today's date
   • Add artifact paths
   • Populate project metadata
   • Set current_phase to vetting
   • If the existing spec mentions a deployment mode, capture it in the manifest but do not finalize — the Deployment Mode Selection step after vetting will present the full choice including express

Path B: Idea

The user has an idea — anything from a vague topic to a content gap description to a rough outline. Start conversational, get structured later.

Opening

Ask ONE open-ended question:

"Tell me about your idea."

Accept whatever the user provides. This could be:

• A single sentence ("I want a lab about securing microservices on OpenShift")
• A paragraph with context ("RCARS shows no content covering RHACS runtime policies, and we've had three customer asks this quarter...")
• A rough outline with modules already sketched
• A content gap description from RCARS or another source

Do NOT immediately ask structured questions. Read what the user gave you first.

Extract and Follow Up

After reading the user's initial description:

1. Extract what you already know — identify which of the required fields can be inferred from the description (topic, products, audience hints, complexity, type, etc.)

2. Ask targeted follow-ups for what's missing — one at a time, in natural conversation order based on what you still need. Don't follow a fixed sequence. If the user mentioned "a 2-hour workshop for platform engineers using RHACS," you already have type, duration, audience, and products — don't re-ask those.

The required fields you need to capture (in whatever order makes sense):

• Project owner — full name + GitHub username. Who's accountable end-to-end.
• Main goal — what someone can DO after completing this. Push for concrete, measurable outcomes with action verbs (Configure, Deploy, Create, Troubleshoot). Reject vague "understand" or "learn about."
• Target audience — role, experience level, background knowledge. Get specifics.
• Products/technologies — full Red Hat product names, versions if known, dependencies.
• Type — workshop (hands-on, user executes) or demo (show-and-tell, presenter drives).
• Deployment mode — Captured during Deployment Mode Selection (after vetting). Do NOT ask about deployment mode during the intake interview. The mode selection is a separate step presented after vetting.
• Environment — what the learner starts with and what automation must pre-configure. For self_published: anchor on the known base before asking — "Your Field Source CI provides an OCP cluster with GitOps (ArgoCD) pre-installed. Beyond that, what should already be running when a student logs in, and what do they set up themselves during the lab?" Do not ask the user to describe the cluster or base platform — that is fixed by the deployment mode. For rhdp_published: the base depends on infrastructure type (determined during automation 7a). For now, ask what the learner experience should be — what's pre-deployed vs. what students do.
• Total duration — validate against complexity, suggest adjustments if mismatch.
• Module structure — propose based on complexity and topic. Each module 15-45 minutes. Validate logical flow.
• Difficulty level — beginner, intermediate, or advanced.
• Automation needed? — based on environment complexity. Multi-VM, cloud resources, complex networking = likely yes.

Generate Spec

After gathering all required information:

• Generate design.md following template format
• Generate per-module outlines in modules/ directory
• Supervised mode: Present draft to user for approval before writing
• Semi/Full mode: Write directly, present summary

Repo Setup

Do NOT create Showroom or automation repos during intake. The orchestrator handles repo creation at phase gates — Showroom is set up before the first writing dispatch, and automation before the first automation code dispatch. Intake only needs to capture the project requirements and generate the spec.

Spec Output Rules

design.md must include:

• Project title and ID
• Learning objectives (3-7 specific, measurable outcomes)
• Target audience (role, level, prerequisites)
• Products and technologies (with versions)
• Type (workshop/demo)
• Duration estimate (total and per-module)
• Module outline (titles and summaries)
• Difficulty level
• Environment — one section, two parts:
  1. Learner view: what exists when the lab starts (pre-deployed resources, no installs required)
  2. Automation scope: whether automation is needed and what it must provision

Module outline files must:

• Be named: module-01-<short-title>.md, module-02-<short-title>.md, etc.
• Follow See/Learn/Do format from template
• Include time estimates for each section
• Use numbered detailed steps
• Scale granularity appropriately:
  • Simple module: ~80 lines
  • Complex module: up to 300 lines
• Use concrete action verbs
• Specify exact commands, file paths, expected outputs

Manifest update after Intake:

project:
  name: "Lab Title"
  id: "lab-short-id"
  created: "2026-04-09"
  owner_name: "Full Name"    # Display name of project owner
  owner_github: "githubuser" # GitHub username of project owner
  type: "workshop" # or demo
  deployment_mode: "rhdp_published"  # rhdp_published | self_published | express
  autonomy: "supervised" # or semi, full

integrations:
  showroom_repo: null   # Set by orchestrator before writing phase
  automation_repo: null  # Set by orchestrator before automation phase

lifecycle:
  current_phase: "vetting"
  phases:
    intake:
      status: "completed"
      completed_date: "2026-04-09 14:30"
      artifacts:
        - "publishing-house/spec/design.md"
        - "publishing-house/spec/modules/module-01-*.md"
        - "publishing-house/spec/modules/module-02-*.md"
    
    writing:
      modules:
        - id: "module-01"
          title: "Module Title"
          status: "pending"
        - id: "module-02"
          title: "Another Module"
          status: "pending"
    
    automation:
      needs_automation: true # or false

Phase 2: Vetting (RCARS)

Check MCP Tool Availability

1. Check if the ph_rcars_query MCP tool is available
   • If available: proceed to vetting
   • If unavailable (no MCP server configured, no API key, or tool not found):
     • Inform the user: "RCARS vetting requires the Publishing House MCP server. The MCP server provides access to RCARS content advisory tools for overlap detection."
     • Ask: "Should we skip vetting for now? You can run vetting later once MCP access is configured."
     • If skip: set lifecycle.phases.vetting.status: skipped and lifecycle.phases.vetting.skip_reason: "MCP unavailable" in manifest
     • Proceed to Phase 3

Run Vetting Query

Build query from spec: Combine these elements from the project specification into a single natural language query:

• Learning objectives (what the user will learn)
• Topics and technologies covered
• Products featured (e.g., OpenShift, AAP, RHEL)
• Target audience level (beginner, intermediate, advanced)
• Deployment mode context (e.g., "workshop for live events" or "self-paced demo")

Example query: "Workshop teaching OpenShift GitOps with ArgoCD for intermediate users, covering deployment strategies, rollbacks, and multi-cluster management"

Call MCP tool: Use the ph_rcars_query tool with the combined query string. The tool handles:

• Submitting the advisor query to RCARS
• Polling for completion (up to 120 seconds)
• Returning structured results with matching catalog items and relevance tiers

Handle ph_rcars_query results:

1. If result status is "completed":

   • Parse the matching catalog items from result.result
   • Each match includes: CI name, display name, stage (prod/dev/event), relevance tier, and rationale
   • Classify the vetting outcome:
     • Green tier matches: Existing content is closely related -- potential overlap. Recommend reviewing these CIs before proceeding.
     • Yellow tier matches: Some overlap exists -- may complement rather than duplicate. Note for the user's awareness.
     • White/no matches: No significant overlap found -- clear to proceed.

2. If result status is "unavailable" or "timeout":

   • Log the error from result.error
   • Inform the user: "RCARS vetting could not complete: {error}. This does not block intake -- you can retry vetting later."
   • Set lifecycle.phases.vetting.status: error and lifecycle.phases.vetting.error: "{error}" in manifest
   • Proceed to Phase 3

3. If result status is "failed":

   • Log the error from result.error
   • Inform the user of the failure and proceed as above

Write Vetting Report

Write the vetting results to publishing-house/reviews/rcars-vetting.md:

• Query used
• Number of matches found
• For each match: CI name, display name, stage, tier, rationale summary
• Overall recommendation (proceed / review overlaps / revise scope)

Update Manifest

Set vetting status in manifest:

• lifecycle.phases.vetting.status: approved (no significant overlap), review (overlaps found, user acknowledged), skipped, or error
• lifecycle.phases.vetting.query: the query string used
• lifecycle.phases.vetting.matches_count: number of matches found
• lifecycle.phases.vetting.completed_at: ISO timestamp

After vetting, proceed to Deployment Mode Selection to choose the project's deployment path.

Deployment Mode Selection

After vetting completes (or is skipped), present the deployment mode choice. This determines the project's path through the rest of the Publishing House lifecycle.

Check MCP Before Presenting Options

If MCP is unavailable, present only two options and explain why:

Choose your deployment mode:

1. Onboarded (rhdp_published) -- Full RHDP pipeline: AgnosticV catalog, code reviews, published in RHDP
2. Self-published (self_published) -- GitOps repo, Field Source CI, self-managed publishing

Express mode is not available this session -- it requires a portal connection for intake data storage. Configure your API key to enable it.

If MCP is available, present all three options:

Choose your deployment mode:

1. Onboarded (rhdp_published) -- Full RHDP pipeline: AgnosticV catalog, code reviews, published in RHDP
2. Self-published (self_published) -- GitOps repo, Field Source CI, self-managed publishing
3. Express -- Disposable demo environment. PH helps you find a base, you order a Babylon environment, customize it, and walk away. No content repo, no lifecycle tracking.

Do NOT steer the user toward any mode. Present options neutrally. User selects.

If User Selects Express (Mode 3)

The express mode follows a separate, shorter flow. The express flow does not create a local manifest or git repo -- all data goes to the portal DB.

Express intake questions — keep it tight. Only ask about:

• What you're demoing/showing (products, technologies, the story)
• Who the audience is (role, industry, what they care about)
• How long you have (meeting length)
• What the demo flow looks like (what you'll show, in what order)

Do NOT ask about:

• Cluster sizing (SNO, 3-node, multi-worker) — RCARS picks the right base CI
• Infrastructure details (storage class, networking) — that's the base CI's job
• Deployment mode choices — they already picked express
• Module structure, difficulty level, automation details — those are for full projects

Two to three targeted follow-ups max, then move to RCARS.

Step E1: Express RCARS Base-Finding Query

Run a second RCARS query for express base-finding, focused on infrastructure rather than content overlap:

Build query from the intake data gathered so far:

• Products and technologies mentioned
• Infrastructure requirements (operators needed, key workloads)
• What should be pre-configured vs what the presenter sets up
• Frame the query as: "Find existing catalog items that provide infrastructure similar to: [products/operators/environment description]. Looking for base environments that can be customized, not content overlap."

Call ph_rcars_query with this infrastructure-focused query.

Handle results:

• If matches found: Present the top 3-5 matches as potential base CIs:

  Based on your requirements, these existing catalog items could serve as your base environment:

  1. agd_v2/ocp-cnv (OCP with CNV) -- Provides OCP 4.x cluster with CNV operator
  2. agd_v2/ocp-gpu (OCP with GPU) -- Provides OCP cluster with GPU nodes

  Which one looks closest to what you need? Or describe what's different about your needs.

• If no matches: Inform the user:

  RCARS did not find a close infrastructure match. You may need to work with the platform team to identify or create an appropriate base catalog item.

• Record the selected base CI (or "none found") for the express metric.

Note on quality: This base-finding query relies on content analysis as a proxy for infrastructure matching. Quality is limited until RCARS gets infrastructure-aware catalog metadata (backlogged in both PH and RCARS backlogs per D-03).

Step E2: Store express intake data in portal DB

Call ph_store_intake_results MCP tool:

ph_store_intake_results(
    owner_email="<user_email>",
    mode="express",
    intake_data={
        "project": {
            "name": "<project_name or user description>",
            "type": "express",
            "deployment_mode": "express"
        },
        "requirements": {
            "products": [...],
            "environment": "...",
            "base_ci": "<selected CI or null>"
        },
        "vetting": {
            "status": "<vetting result>",
            "base_finding": {
                "query": "<query string>",
                "matches": [...]
            }
        }
    },
    project_name="<project name>"
)

Step E3: Record express metric

Call ph_record_express_run MCP tool:

ph_record_express_run(
    owner_email="<user_email>",
    base_ci="<selected CI name or null>",
    automated=false
)

The automated field is always false until Babylon ordering automation is built.

Step E4: Dead-End at Environment Gate

Present the environment gate message and stop:

Express intake complete.

Your base CI is: (or "No base CI identified -- work with the platform team")

Next steps (manual):

1. Order a Babylon environment based on the base CI above
2. Once the environment is provisioned and you have access, come back and we can help you customize it

Your intake data is saved in the portal (session ID: <session_id>). You can resume this express project later by running /rhdp-publishing-house -- the orchestrator will find your saved session.

The express skill (automated cluster customization) is not yet built. For now, customization is manual.

Do NOT write a local manifest for express projects. Do NOT create a git repo. Do NOT proceed to spec refinement or any further phases. The express intake ends here. The express flow is complete once the environment gate message is presented.

If User Selects Onboarded (Mode 1) or Self-Published (Mode 2)

Proceed with the existing flow:

1. Set project.deployment_mode in the manifest to rhdp_published or self_published
2. Continue to Phase 3 (Spec Refinement) as before

Session Continuity Addition: After writing the manifest for onboarded/self-published modes (at the end of Phase 1 or after mode selection), also store intake results in the portal:

Call ph_store_intake_results MCP tool:

ph_store_intake_results(
    owner_email="<user_email>",
    mode="<onboarded or self_published>",
    intake_data=<full intake data dict matching the manifest shape>,
    project_name="<project.name from manifest>"
)

If MCP is unavailable, skip this step silently (intake data is still in the local manifest).

Manifest Sync Addition: After every manifest write during intake (setting intake status, adding artifacts, etc.), call ph_sync_manifest per the Manifest Sync Rule defined in the orchestrator SKILL.md. If MCP is unavailable, skip silently.

Phase 3: Spec Refinement

Refinement Goals

1. Incorporate RCARS feedback
2. Ensure clarity for downstream agents (writer, automation)
3. Standardize format (See/Learn/Do, timing, numbered steps)
4. Remove vagueness, add concreteness

Refinement Process

1. Re-read all spec artifacts:

   • publishing-house/spec/design.md
   • All module outlines in publishing-house/spec/modules/

2. If RCARS flagged overlap:

   • Review differentiation guidance
   • Revise objectives and approach to differentiate
   • Document differentiation in design.md

3. Review each module outline for:

   • Missing sections (See/Learn/Do incomplete)
   • Vague steps ("configure the system" → specific commands)
   • Missing time estimates
   • Inconsistent formatting
   • Missing prerequisites or expected outputs

4. Update files in place:

   • Edit design.md if needed
   • Edit each module outline
   • Maintain template format

5. Present summary of changes:

   • List what was revised
   • Explain rationale
   • Highlight key improvements

Autonomy Behavior

• Supervised: Present each proposed change, ask approval before making it
• Semi: Make all changes, present summary for review
• Full: Make changes, brief summary, proceed automatically

Manifest Update

lifecycle:
  current_phase: "approval"
  phases:
    spec_refinement:
      status: "completed"
      completed_date: "2026-04-09 14:30"
      changes:
        - "Incorporated RCARS differentiation guidance"
        - "Standardized module outline format"
        - "Added missing time estimates"

After Refinement: Hand Back

DO NOT advance past approval gate.

Inform the user:

Spec refinement is complete. Your design doc and module outlines are ready for review at:

• publishing-house/spec/design.md
• publishing-house/spec/modules/

Please review these artifacts. When you're ready to proceed, you can approve the spec and move to the writing phase.

Key Behavioral Notes

Be as thorough as the superpowers:brainstorming skill when exploring requirements:

• Push back on vague objectives

  • "understand networking" → "Configure a multi-tier network with DMZ and internal zones"

• Propose module structures and validate them

  • "That's a lot for one module. Consider splitting into: 1) Basic setup, 2) Advanced configuration"

• Identify gaps the user hasn't thought of

  • "You mentioned multi-cloud deployment. Have you considered how users will handle authentication differences?"

• Scale question depth to project complexity

  • Simple demo: fewer follow-ups
  • Multi-day workshop: deep exploration of each module

Goal: Rigorous exploration through conversation, not just filling in a template.

Ask follow-up questions. Challenge assumptions. Propose alternatives. Validate feasibility. The quality of the spec determines success of all downstream phases.