From jtbd-tools
Runs end-to-end JTBD workflow on topic map-based repos like OpenShift docs: analyzes maps, generates TOCs, compares structures, consolidates reports. Batch processes multiple books.
npx claudepluginhub redhat-documentation/redhat-docs-agent-tools --plugin jtbd-toolsThis skill is limited to using the following tools:
End-to-end JTBD analysis workflow for OpenShift documentation repositories that use `_topic_maps/_topic_map.yml`. Runs all 4 steps in sequence:
Extracts JTBD records from OpenShift docs repos using _topic_map.yml structure. Parses topic maps for books/assemblies, reduces AsciiDoc assemblies, runs analysis.
Creates new Angular apps using Angular CLI with flags for routing, SSR, SCSS, prefixes, and AI config. Follows best practices for modern TypeScript/Angular development. Use when starting Angular projects.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Share bugs, ideas, or general feedback.
End-to-end JTBD analysis workflow for OpenShift documentation repositories that use _topic_maps/_topic_map.yml. Runs all 4 steps in sequence:
# Single book
/jtbd-workflow-topicmap path/to/repo --book installing_gitops --distro openshift-gitops
# With domain-specific research personas
/jtbd-workflow-topicmap path/to/repo --book installing_gitops --distro openshift-gitops --research-file ~/my-project/research.yaml
# List books
/jtbd-workflow-topicmap path/to/repo --list-books --distro openshift-gitops
# Batch (max 10 per invocation)
/jtbd-workflow-topicmap path/to/repo --books-file books.txt --distro openshift-enterprise --batch --batch-size 5
_topic_maps/_topic_map.yml--list-books or --batch): Book directory name (e.g., installing_gitops)openshift-gitops, openshift-enterprise)--books-file)analysis/<distro>/ or analysis/topicmap/asciidoctor-reducer must be installed:
gem install asciidoctor-reducer
If Ruby/gem is not available:
brew install ruby # macOS
The target repo must have _topic_maps/_topic_map.yml
This step is identical to the /jtbd-analyze-topicmap skill. Full details are in that skill; the key steps are summarized here.
_topic_maps/_topic_map.yml in the repo root--- document separators (multi-document YAML)Name, Dir, Distros, Topics--distro is specified, filter to books whose Distros field contains that distro--list-books, display a table of books and stop---
Name: Installing GitOps # Book display name
Dir: installing_gitops # Directory containing assemblies
Distros: openshift-gitops # Comma-separated distro list
Topics: # Ordered list of topics
- Name: Preparing to install # Topic display name
File: preparing-gitops-install # Assembly filename (without .adoc)
- Name: Nested section
Dir: sub_directory
Topics:
- Name: Sub-topic
File: sub-topic-file
--- document = one bookDistros can be a single string or comma-separatedDir and TopicsName + File = leaf topic (assembly)Name + Topics = section grouping (no file)<repo>/<book-Dir>/<File>.adoc or <repo>/<book-Dir>/<sub-Dir>/<File>.adoc--- (YAML document separator)Name:, Dir:, Distros:, Topics: fieldsFile references with resolved pathsDir matches --bookTopics recursively to collect all File entries<repo>/<book-Dir>/<File>.adocCRITICAL: Working Directory — asciidoctor-reducer must run from the book directory, not the repo root:
cd <repo>/<book-Dir> && asciidoctor-reducer <file>.adoc -o <output-dir>/<file>-reduced.adoc
For nested topics with a subdirectory:
cd <repo>/<book-Dir> && asciidoctor-reducer <sub-Dir>/<file>.adoc -o <output-dir>/<file>-reduced.adoc
Verify reduction: check output file has no remaining include:: directives.
= <Topic Name> heading and append content<output-dir>/<book>-combined.adocinclude:: directives from unreduced assemblies<output-dir>/<book>-include-graph.jsoncon-*.adoc = CONCEPTproc-*.adoc = PROCEDUREref-*.adoc = REFERENCEsnip-*.adoc = SNIPPET=, ==, ===, ====)| Combined File Size | Strategy |
|---|---|
| < 500 lines | Single pass |
| >= 500 lines | Chunked subagent processing |
If --research-file is provided:
If --research-file is NOT provided, use generic persona detection from methodology.md.
Read entire combined file, apply methodology from methodology.md (plus research overlay if provided), generate all records, write JSONL.
== headings)Task(subagent_type="general-purpose", prompt=chunk_analysis_prompt)
methodology.md (read the reference file)schema.md (read the reference file)--research-file was provided)Match each record's section to the include graph, update evidence and notes with module paths and types.
Save to <output-dir>/:
<book>-jtbd.jsonl — JTBD records (one JSON per line)<book>-jtbd.csv — CSV version (array fields joined with ; )<book>-include-graph.json — Include graph<book>-topicmap.json — Extracted topic map structure<file>-reduced.adoc files<book>-combined.adoc — Concatenated reduced content--distro: analysis/<distro>/<book>/--distro: analysis/topicmap/<book>/Read toc-guidelines.md and example-toc.md for the complete formatting rules.
<book>-jtbd.jsonl from the output directorytoc-guidelines.md<output-dir>/<book>-toc-new_taxonomy.md-> Lines X-Y: Section Title format=/==/=== not #/##/###. Map = Title to chapters.Read comparison-guide.md for the complete formatting rules.
.adoc file (<book>-combined.adoc) as the "source document"=, ==, ===)<book>-jtbd.jsonl for proposed structurecomparison-guide.md<output-dir>/<book>-comparison.md= Title headings map to document/book title== Chapter headings map to chapters=== Section headings map to sections# headingsRead consolidation-guide.md for the complete formatting rules.
<book>-jtbd.jsonl — JTBD records<book>-toc-new_taxonomy.md — TOC (for proposed structure)<book>-comparison.md — Comparison (for current structure context)<book>-combined.adoc — Source documentconsolidation-guide.md<output-dir>/<book>-consolidation-report.md.adoc headings/jtbd-workflow-topicmap path/to/repo --books-file books.txt --distro openshift-enterprise --batch --batch-size 5
books.txt lists book directory names, one per line:
installing_gitops
configuring_gitops
monitoring_gitops
--batch-size N controls how many to process (default 5, max 10)| # | Book | Records | Main Jobs | Status |
|---|------|---------|-----------|--------|
| 1 | installing_gitops | 45 | 12 | Done |
| 2 | configuring_gitops | 38 | 10 | Done |
| 3 | monitoring_gitops | 22 | 8 | Done |
For processing more than 10 books, use the Python batch-runner script:
python3 plugins/jtbd-workflow-topicmap/scripts/batch-runner.py \
--repo ~/Documents/openshift-docs \
--books-file books.txt \
--distro openshift-enterprise \
--batch-size 5
This splits items into groups and invokes claude for each group, handling failures and providing resume capability.
For each book processed, the following files are produced:
| File | Step | Description |
|---|---|---|
<book>-jtbd.jsonl | 1 | JTBD records |
<book>-jtbd.csv | 1 | CSV version of records |
<book>-combined.adoc | 1 | Concatenated reduced content |
<book>-include-graph.json | 1 | Include graph with module types |
<book>-topicmap.json | 1 | Topic map structure |
*-reduced.adoc | 1 | Individual reduced assemblies |
<book>-toc-new_taxonomy.md | 2 | JTBD-oriented TOC |
<book>-comparison.md | 3 | Current vs proposed comparison |
<book>-consolidation-report.md | 4 | Stakeholder consolidation report |
include:: directives)= Topic Name headings between assemblies.adoc headingsThe --research-file flag lets you provide a YAML file with domain-specific personas, schema extensions, and canonical jobs. Without it, the skill uses generic persona detection from the documentation content.
name: "My Project"
version: "1.0"
description: "Research overlay for My Project documentation"
# Domain-specific personas (override generic role detection)
personas:
- id: sysadmin
name: "Sam the Systems Administrator"
role: "Manages hosts, patching, and content lifecycle"
archetype: "THE OPERATOR" # optional
loop: "outer" # inner | outer | cross-cutting (optional)
key_skills: # optional
- "Host management"
- "Content views"
- "Patching"
pain_points: # optional
- "Complex content management workflows"
- "Slow patching cycles across large fleets"
key_quote: "I need to patch 500 hosts and I can't afford downtime." # optional
- id: deveng
name: "Dana the Developer"
role: "Builds and deploys applications on the platform"
archetype: "THE BUILDER"
loop: "inner"
key_skills:
- "Application development"
- "CI/CD pipelines"
pain_points:
- "Disconnected from operational environment constraints"
# Additional fields added to every JTBD record
schema_extensions:
- field: "compliance_framework"
type: "enum"
values: ["STIG", "CIS", "PCI-DSS", "HIPAA", "none"]
description: "Applicable compliance framework for this job"
- field: "operational_impact"
type: "enum"
values: ["high", "medium", "low"]
description: "Impact on production operations if this job fails"
- field: "teams_involved"
type: "array"
description: "Teams that collaborate on this job"
# Canonical jobs from research for matching/validation
canonical_jobs:
setup:
- "Register and provision hosts"
- "Configure content sources"
operations:
- "Patch hosts across environments"
- "Monitor compliance status"
lifecycle:
- "Promote content across environments"
# Jobs flagged as strategic priorities
strategic_priorities:
- "Patch hosts across environments"
- "Monitor compliance status"
# Pain point patterns to detect in documentation
pain_point_patterns:
- pattern: "manual"
maps_to: "Automation opportunity"
- pattern: "drift"
maps_to: "Compliance monitoring gap"
- pattern: "complex"
maps_to: "Simplification opportunity"
When --research-file is provided, the skill:
strategic_priority: true on matching records.pain_points field.| Section | Required | Purpose |
|---|---|---|
name, version | Yes | Config identity |
description | No | Human-readable description |
personas | No | Domain-specific persona definitions |
schema_extensions | No | Additional fields for JTBD records |
canonical_jobs | No | Reference jobs from research for alignment |
strategic_priorities | No | Jobs to flag as high-priority |
pain_point_patterns | No | Text patterns to detect and capture |
All sections except name and version are optional. You can provide just personas, just schema extensions, or any combination.
This skill uses shared methodology and guideline files in the reference/ directory:
methodology.md — JTBD extraction rules (from /jtbd-analyze-adoc)schema.md — Record schema (from /jtbd-analyze-adoc)toc-guidelines.md — TOC formatting rules (from /jtbd-toc)example-toc.md — Example TOC output (from /jtbd-toc)comparison-guide.md — Comparison rules (from /jtbd-compare)consolidation-guide.md — Consolidation rules (from /jtbd-consolidate)