Imported from opendatahub-io/rfe-creator (AGENTS.md). Install upstream with npx skills add opendatahub-io/rfe-creator. Copyright stays with the author.

RFE Creator

Skills for creating, reviewing, and submitting RFEs to the RHAIRFE Jira project and Initiatives to the RHOAIENG Jira project.

Artifact Conventions

All skills read from and write to the artifacts/ directory in the working directory.

artifacts/
  rfe-rubric.md             # Written by assess-rfe plugin (if installed) — rubric reference
  rfes.md                   # Generated index — rebuilt from frontmatter, not a source of truth

  rfe-tasks/                # Individual RFE files with YAML frontmatter
    RHAIRFE-1595.md          # Existing Jira issue (keyed by Jira key)
    RHAIRFE-1595-comments.md # Companion: stakeholder comment history
    RHAIRFE-1595-removed-context.yaml  # Companion: structured removed content with type classification
    RHAIRFE-1595-removed-context.md  # Legacy companion (markdown, being phased out)
    RFE-001.md               # New RFE (pre-submission, renamed on submit)

  rfe-originals/            # Raw Jira descriptions at time of fetch (not templated)
    RHAIRFE-1595.md          # Baseline for before/after analysis and submit-time conflict detection

  rfe-reviews/              # Per-issue review files with YAML frontmatter
    RHAIRFE-1595-review.md
    RFE-001-review.md

  initiatives/              # Individual Initiative files with YAML frontmatter
    INIT-001.md              # New Initiative (pre-submission, renamed on submit)
    RHOAIENG-12345.md        # Existing Jira Initiative (keyed by Jira key)

  initiative-originals/     # Raw Jira descriptions at time of fetch
    RHOAIENG-12345.md        # Baseline for conflict detection

  initiative-reviews/       # Per-Initiative review files with YAML frontmatter
    INIT-001-review.md
    RHOAIENG-12345-review.md

Frontmatter

All task and review files use YAML frontmatter for structured metadata. Skills must use scripts/frontmatter.py to read schemas, set fields, and read validated data — never write YAML by hand.

# Get schema for a file type
python3 scripts/frontmatter.py schema rfe-task
python3 scripts/frontmatter.py schema rfe-review
python3 scripts/frontmatter.py schema initiative-task
python3 scripts/frontmatter.py schema initiative-review

# Set/update frontmatter on a file
python3 scripts/frontmatter.py set <path> field=value field=value ...

# Read validated frontmatter as JSON
python3 scripts/frontmatter.py read <path>

# Rebuild rfes.md index from all frontmatter
python3 scripts/frontmatter.py rebuild-index

Invoke scripts/*.py by the relative path exactly as written above, even when the working directory is given to you as an absolute path. The headless permission allowlist matches command text literally, so expanding scripts/frontmatter.py to /abs/path/to/scripts/frontmatter.py is denied and costs a retry.

State Persistence

Long-running skills use scripts/state.py to persist state to tmp/ files so it survives context compression. All skills must use this utility instead of inline bash commands (cat, echo, mkdir) to avoid unnecessary auth prompts.

python3 scripts/state.py init <file> key=value ...    # Create config file
python3 scripts/state.py set <file> key=value ...     # Update keys in place
python3 scripts/state.py set-default <file> key=value ...  # Set only if key absent (cycle counters)
python3 scripts/state.py read <file>                  # Print file contents
python3 scripts/state.py write-ids <file> ID ...      # Write ID list (one per line, deduped)
python3 scripts/state.py read-ids <file>              # Print IDs space-separated
python3 scripts/state.py timestamp                    # Print current UTC time (ISO 8601)
python3 scripts/state.py clean                        # Reset tmp/ directory

Each skill uses distinct file prefixes to avoid collisions during nested calls: autofix-, review-, split-, speedrun-, initiative-review-.

File Naming

• Existing Jira issues: Use Jira key as filename and rfe_id (e.g., RHAIRFE-1595.md with rfe_id: RHAIRFE-1595)
• New RFEs (pre-submission): Use RFE-NNN.md naming with rfe_id: RFE-NNN
• On submit: RFE-NNN.md files are renamed to RHAIRFE-NNNN.md, and rfe_id is updated to the Jira key
• Companion files: Same prefix as main file with -comments.md or -removed-context.md suffix
• Archived RFEs: Set status: Archived in frontmatter (no filename changes)
• Initiatives: Use INIT-NNN.md naming with initiative_id: INIT-NNN; renamed to RHOAIENG-NNNN.md on submit

Jira Integration

Write Operations (submit, update, comment)

All write operations use the Jira REST API directly via Python scripts (scripts/submit.py, scripts/split_submit.py). This ensures the exact sequence of Jira API calls is deterministic and not dependent on LLM tool-calling decisions — critical for operations like split submissions that require multi-step transactional workflows (archive, create, link, close).

Required environment variables:

JIRA_SERVER=https://your-site.atlassian.net
JIRA_USER=your-email@example.com
JIRA_TOKEN=your-api-token

To create an API token: https://id.atlassian.com/manage-profile/security/api-tokens

Read Operations (fetch issues, comments)

Read operations support two modes:

1. Atlassian MCP server (preferred when available) — used by /rfe.review and /rfe.split when fetching issues from Jira
2. REST API fallback — if the MCP server is unavailable, skills fall back to python3 scripts/fetch_issue.py using the same JIRA_SERVER/JIRA_USER/JIRA_TOKEN env vars

Skills that only work with local artifacts (/rfe.create) do not require Jira access.

Jira Field Mappings

RHAIRFE Project (RFEs)

• Project: RHAIRFE
• Issue Type: Feature Request
• Priority values (use these exactly): Blocker, Critical, Major, Normal, Minor, Undefined
• Status on creation: New

RHOAIENG Project (Initiatives)

• Project: RHOAIENG
• Issue Type: Initiative (id: 10103)
• Priority values (use these exactly): Blocker, Critical, Major, Normal, Minor, Undefined
• Status on creation: New
• Parent field: Set to a RHAISTRAT Outcome key to link the Initiative to a strategic outcome
• Submission script: scripts/submit.py --type initiative

Work Item Types

Each work item type (RFE, Initiative) is described by a data-only descriptor at types/<type>/type.yaml, validated against types/_schema/type.schema.json. types/README.md is the field reference and docs/type-provider-guide.md the provider guide (adding a type, the gates, the drop-in seam). Scripts adopt the registry one PR at a time (the "Adoption status" table in types/README.md lists which read it): an adopted script derives its per-type table from the descriptors at import, and a pending script's table is pinned by test to the descriptors so the two cannot drift. When a per-type value changes, update the descriptor — and, for a pending script, its table — in the same PR.

python3 scripts/type_registry.py list              # Registered type names
python3 scripts/type_registry.py show rfe          # Full descriptor
python3 scripts/type_registry.py get rfe conventions.labels.rubric_pass
python3 scripts/validate_types.py                  # Descriptor lint (part of make lint)
python3 scripts/lint_prefix_predicates.py          # Literal key-prefix predicates in scripts/
python3 scripts/generate_eval_config.py --check    # Generated eval configs in sync (part of make lint)

eval.yaml and eval-initiative.yaml are generated: scripts/generate_eval_config.py renders each type's config from eval/config/skeleton.yaml (shared structure, every check, shared judge prose), types/<type>/eval/fragment.yaml (typed prose) and the descriptor (identity, dirs, score fields, the authoritative eval.thresholds). Never edit a config by hand — change the skeleton or the fragment and rerun the generator; --check fails make lint and CI with the diff otherwise.

Do not add new literal key-prefix predicates (startswith("RHAIRFE-"), RFE-\d+ regexes, snapshot file prefixes) to scripts/: lint_prefix_predicates.py fails on any file whose count exceeds its baseline in tests/data/prefix_predicate_baseline.json, and the baseline only shrinks.

Snapshot System

Before modifying scripts/snapshot_fetch.py, scripts/bootstrap_snapshot.py, or scripts/submit.py (snapshot-related code), read docs/snapshot-incremental-fetch.md — especially the Design Invariants section. Changes must preserve all invariants.

Pipeline Execution Constraint

When tmp/pipeline-state.yaml exists and the phase is not DONE:

1. A text-only response (no tool call) ends your turn and hands control back. You will only run again if an agent-completion notification wakes you, so if the work you are waiting on cannot produce one, the run is over. Never end a turn to "wait" — block on the barrier in rule 2 instead.
2. After launching each wave of agents, your next Bash call MUST be python3 scripts/pipeline_state.py wait-for-wave. This is a blocking synchronization barrier that reads artifact files on disk. On exit 3, re-run the same command. An exit 0 preceded by a wait-for-wave: STALL line on stderr is normal: the barrier has re-dispatched or escalated the stuck ids itself (docs/wave-stall-guard.md); continue with next-action.
3. Do not wait for agent-completion notifications — the wait-for-wave command is unrelated to the Agent tool's notification system.

Eval Dataset Policy

Files under eval/dataset/ must be anonymized before commit. Never commit real customer names, individual names, email addresses, or other personally identifiable information (PII). Replace them with fictional equivalents (e.g., "Acme Corp", "Example Industries"). This applies to test inputs, annotations, and any reference files.

Architecture Context

/rfe.review automatically fetches architecture context from opendatahub-io/architecture-context into .context/architecture-context/ and detects the latest RHOAI version. No manual setup needed.

Architecture context is used during /rfe.review (technical feasibility fork).

Architecture context is NOT used during /rfe.create — RFEs describe business needs, not implementation.