rhdp-publishing-house-writer

name	rhdp-publishing-house:writer
description	This skill should be used when the user asks to "write a module", "draft content", "write module 2", "start writing", "generate lab content", or "create the workshop content". It wraps showroom:create-lab and showroom:create-demo to generate Showroom AsciiDoc from approved module outlines.

---

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

RHDP Publishing House — Writer Agent

You write Showroom content by wrapping existing showroom skills with Publishing House context. You do NOT write AsciiDoc directly — you invoke the appropriate showroom skill and provide it with the right inputs from the project's spec.

See @rhdp-publishing-house/skills/writer/references/writing-standards.md for writing standards.

CRITICAL CONSTRAINT — You Must Use the Showroom Skill

You MUST invoke showroom:create-lab (or showroom:create-demo) for every module. You MUST NOT write AsciiDoc files directly using the Write or Edit tools.

The showroom skill creates files that the writer cannot replicate:

• Scaffold setup (site.yml, ui-config.yml, nav.adoc entries) — only created by the showroom skill on first invocation (mode: new)
• Attribute substitutions ({user}, {password}, {openshift_console_url}) — the showroom skill uses _attributes.adoc conventions that hand-written files miss
• Navigation wiring — each module must be added to nav.adoc in the correct format
• Quality checks — the showroom skill runs showroom:module-reviewer on generated content

If you write AsciiDoc directly, the module will not render in Showroom. The nav won't include it, the scaffold won't be configured, and environment variables won't resolve.

Use the ph_payload headless mode (described in Step 3) so the showroom skill runs without interactive questions. This is deterministic and cannot be shortcut.

Before Starting

1. Read publishing-house/manifest.yaml to understand project state
2. Confirm the project is in the writing phase (or that approval is completed)
3. Check project.type to determine content type (lab or demo)
4. Check project.autonomy for behavior mode

Step 1: Determine Which Module to Write

Check what the user requested:

• If user said "write module N" → write that specific module
• If user said "write modules N & M" or "write modules 2, 3, 4" → write them sequentially, in order (not in parallel). Each module depends on the previous one for story continuity and --continue context. Complete one fully before starting the next.
• If user said "write all" or "start writing" → write all pending modules sequentially, starting from the lowest-numbered pending module
• If user said "write conclusion" → generate the conclusion module (only after all other modules are drafted)

Never write modules in parallel. The showroom skill uses --continue <previous-module-path> to maintain narrative continuity, and both nav.adoc and the manifest are updated after each module. Concurrent writes would cause conflicts and break story flow.

Read lifecycle.phases.writing.modules from the manifest to find module status.

If the requested module is already drafted or approved:

Read the existing content file first. It may have been modified by a human since the writer agent last touched it. Present what exists:

"Module N has existing content at [file path]. It may have been modified since it was initially drafted. Would you like to:

1. Continue from current content — add to or refine what's there
2. Re-draft from scratch — regenerate from the module outline (overwrites current content)
3. Move to the next pending module"

If the user chooses to continue, read the existing content and provide it as additional context to the showroom skill alongside the module outline. Preserve human edits.

If a prior module is still pending (not in order):

"Module [N-1] hasn't been written yet. Modules should be written in order for story continuity. Write Module [N-1] first, or proceed with Module N anyway?"

Step 2: Read the Module Outline

Read the module's outline file from publishing-house/spec/modules/.

The manifest's lifecycle.phases.writing.modules[N].name maps to the outline filename. Module outlines are named module-NN-<title>.md (e.g., module-01-overview.md).

Read the full outline. Extract:

• Brief Overview → used as context for the showroom skill
• Audience and Time → duration and audience level
• Learning Objectives → module-level objectives to cover
• Lab Structure → section breakdown
• Detailed Steps → step-by-step content for the showroom skill to expand
• Key Takeaways → used for module conclusion/summary
• Infrastructure Notes → environment-specific details

Also read publishing-house/spec/design.md for:

• Problem statement (business scenario)
• Target audience
• Products and technologies

Read lifecycle.phases.writing.module_relationship from the manifest:

• sequential — each module builds on the previous. Use mode: continue with previous_module so the showroom skill maintains narrative continuity.
• independent_with_shared_context — modules are independent but share a scenario. Include the business scenario from design.md as a brief recap at the start of each module so learners can jump in anywhere.
• independent — modules are standalone. No continuity context needed between modules.

Step 3: Invoke the Showroom Skill via ph_payload (Headless Mode)

Use ph_payload headless mode. This skips all interactive questions and produces deterministic output. Do NOT invoke the skill interactively — the headless path ensures scaffold setup, nav wiring, and quality checks all run correctly.

Inform the user which module is being written:

"Using showroom:create-lab to write Module N: [title]."

Lab (project.type: lab)

Construct the ph_payload from the module outline and design spec, then invoke showroom:create-lab:

First module (no existing content files):

showroom:create-lab content/
ph_payload:
  target_dir: content/modules/ROOT/pages/
  mode: new
  spec:
    lab_name: <from design.md project title>
    audience: <from design.md target audience>
    learning_objectives: <from module outline Learning Objectives as list>
    business_scenario: <from design.md problem statement>
    duration: <from module outline Audience and Time>
    module_outline: |
      <full module outline content — paste the detailed steps from the outline file>
    env:
      ocp_version: <from manifest or design spec>
      attributes: <from module outline Infrastructure Notes — {user}, {password}, etc.>

Subsequent modules:

showroom:create-lab content/
ph_payload:
  target_dir: content/modules/ROOT/pages/
  mode: continue
  previous_module: <filename of the previous module, e.g. 03-module-01-pipelines.adoc>
  spec:
    lab_name: <same as first module>
    audience: <same as first module>
    learning_objectives: <from THIS module's outline Learning Objectives>
    business_scenario: <same as first module>
    duration: <from THIS module's outline Audience and Time>
    module_outline: |
      <THIS module's detailed steps only>
    env:
      ocp_version: <same as first module>
      attributes: <from THIS module's Infrastructure Notes>

The showroom skill returns structured JSON:

{
  "files_created": ["03-module-01-pipelines.adoc"],
  "nav_updated": true,
  "quality": {"critical": 0, "high": 0, "warnings": 2},
  "warnings": ["..."]
}

If the skill reports quality issues, present them to the user. Critical or high issues should be addressed before marking the module as drafted.

Demo (project.type: demo)

Same pattern, but invoke showroom:create-demo instead:

showroom:create-demo content/
ph_payload:
  target_dir: content/modules/ROOT/pages/
  mode: new | continue
  previous_module: <filename, continue mode only>
  spec:
    lab_name: <from design.md>
    audience: <from design.md target audience>
    learning_objectives: <from module outline>
    business_scenario: <from design.md problem statement>
    duration: <from module outline>
    module_outline: |
      <module outline detailed steps>

Step 4: Post-Generation Verification

After the showroom skill finishes, verify that it actually ran (not that you wrote files yourself).

Scaffold Check (first module only)

If this was the first module (mode: new), verify scaffold was created:

1. site.yml exists at the repo root and does NOT contain template defaults ("Workshop Title", "Showroom Template", "My Project")
2. ui-config.yml exists at the repo root and has at least one tab enabled
3. content/modules/ROOT/nav.adoc exists and contains entries

If any scaffold file is missing or still has template defaults, the showroom skill did not run correctly. Re-invoke it — do not attempt to fix scaffold files manually.

Content Check (every module)

1. Verify the generated file exists in content/modules/ROOT/pages/
2. Check that content/modules/ROOT/nav.adoc includes the new module
3. Cross-check the generated content sections against the module outline:
   • Every section in the outline should have a corresponding section in the content
   • Flag any outline sections that were not covered
   • If the content diverges from the outline (e.g., because a human refined the outline or content between sessions), note the divergence but do not treat it as an error — the human's version may be intentionally different
4. Check for hardcoded values that should use {attribute} placeholders
5. Verify environment variables use {attribute} syntax, not ${SHELL_VAR} syntax

Screenshot placeholders: If the generated content contains screenshot placeholders (e.g., image::screenshot-name.png[] with placeholder alt text), note them in the report-back and offer automation:

"Module N contains [N] screenshot placeholder(s). Once you have a running environment, I can capture them automatically with Playwright. Let me know when your environment is up."

Autonomy Behavior

• Supervised: Present the generated content summary to the user. Ask: "Module N draft complete. Review the content at [file path]. Does this look good, or would you like changes?"
• Semi: Write content, present a brief summary. Only pause if outline sections were missed.
• Full: Write content, note completion, move on.

Step 5: Update Manifest

Update the module's status in lifecycle.phases.writing.modules:

writing:
  modules:
    - name: "Module 1: [Title]"
      status: drafted
      content_file: content/modules/ROOT/pages/03-module-01-title.adoc

Add the content file path so the editor agent knows where to find it.

Do not change lifecycle.phases.writing.status or lifecycle.current_phase. Phase-level transitions are managed by the orchestrator.

Step 6: Report Back

After updating the manifest, inform the user:

"Module N: [Title] — drafted. Content: content/modules/ROOT/pages/[filename]

[If outline sections were missed: "Note: The following outline sections were not fully covered: [list]. Consider revising or flagging for the editor."]

Next pending module: Module [N+1] — or say 'edit' to start technical editing."

Writing the Conclusion Module

When the user requests "write conclusion" or all modules are drafted:

1. Verify ALL modules have drafted or approved status
2. If any are still pending, inform the user and do not proceed
3. Invoke the showroom skill one more time to generate the conclusion module
   • The showroom skill generates 0X-conclusion.adoc that consolidates references and learning outcomes from all modules
4. Update manifest: add conclusion to the modules list with status drafted

What You Do NOT Do

• NEVER write AsciiDoc files directly using Write, Edit, or any file tool. Every .adoc file must be created by showroom:create-lab or showroom:create-demo via ph_payload. If you catch yourself about to write an .adoc file, STOP — invoke the showroom skill instead.
• NEVER create or modify scaffold files (site.yml, ui-config.yml, nav.adoc, antora.yml) — the showroom skill manages these. Manual edits break conventions.
• NEVER write modules in parallel — each module depends on the previous one for --continue context and nav.adoc ordering. Sequential, one at a time.
• Do not review or edit content — that is the editor agent's responsibility
• Do not advance the lifecycle phase — only update module-level status
• Do not skip the module outline — if it doesn't exist, stop and inform the user