qrspi-cli-workflow - SKILL.md Agent Skill

name: qrspi-cli-workflow description: Use when the user wants to initialize, inspect, advance, reject, rewind, export prompts, or auto-run a QRSPI workflow via the `qrspi` CLI. Covers `qrspi init`, `qrspi list`, `qrspi status`, `qrspi stage`, `qrspi prompt render`, `qrspi prompt export`, `qrspi advance`, `qrspi run`, `qrspi approve`, `qrspi reject`, `qrspi rewind`, `qrspi slice`, `qrspi context`, `qrspi budget`, and feature selection via `--feature <id>`. Do NOT manually simulate stage management when the CLI can handle it.

QRSPI CLI Workflow

When to use

Trigger this skill when any of the following is true:

The user wants to start or resume a QRSPI feature workflow in a project
The user wants to check current stage, full status, context strategy, or budget
The user wants to render a stage prompt for an external agent or runner, or export base prompt templates for review
The user wants to advance stages, approve or reject gates, rewind to an earlier stage, add slices, or auto-run multi-stage flows
The user explicitly mentions qrspi, .qrspi/, feature workflow, stage advancement, gate, or runner

If the discussion is about QRSPI methodology without real CLI operations, this skill is NOT the right choice.

Core principles

Prefer calling the qrspi CLI; do NOT manually simulate the state machine
Read the current .qrspi/ state first before deciding the next command
Follow the CLI-defined stages and gates; do NOT skip approve
Use --feature <id> when the project has multiple workflows
If the CLI can already do something, do NOT invent temporary file conventions or custom flows

Installation

Important:

Installing this skill only installs the skill instructions
It does NOT guarantee that the qrspi CLI is already available on the machine
If qrspi is missing, install the npm package qrspi-agent

If the qrspi command is not available after the skill is installed, install the CLI package separately:

npm install -g qrspi-agent
qrspi --help

Or use it without a global install:

npx qrspi-agent --help

Default workflow

1. Check if already initialized

Prefer checking:

The current project root
Whether .qrspi/ exists
Whether there is already a feature state

Common commands:

qrspi list --root .
qrspi status --root .
qrspi stage --root .

If the CLI reports not initialized (list is empty or status errors), then use:

qrspi init <feature_id> --root .

If more than one workflow exists, feature-scoped commands intentionally fail until you select a workflow:

qrspi status --root . --feature <feature_id>
qrspi stage --root . --feature <feature_id>
qrspi context --root . --feature <feature_id>

2. View current stage

Use:

qrspi stage --root .
qrspi status --root .

# If multiple workflows exist
qrspi stage --root . --feature <feature_id>
qrspi status --root . --feature <feature_id>

Convention:

stage shows the current stage summary
status shows the full stage state and runner state

3. Get the current stage prompt

Let the CLI render the prompt rather than rewriting stage instructions inside the skill.

Use:

qrspi prompt render Q --root . --input "requirement description"
qrspi prompt render D --root .

# If multiple workflows exist
qrspi prompt render D --root . --feature <feature_id>

Rules:

Pass --input when there is a raw user requirement
prompt render is for workflow-aware prompts; use prompt export for base templates
Stage codes must be one of Q/R/D/S/P/W/I/PR

To export base prompt templates without workflow-specific context or user input:

qrspi prompt export --root . --out qrspi-prompts.md
qrspi prompt export Q --root . --out Q_prompt.md
qrspi prompt export --root . --lang zh --split --out qrspi-prompts/

4. Advance a stage

Confirm the current stage artifact exists before calling:

qrspi advance --root .

# If multiple workflows exist
qrspi advance --root . --feature <feature_id>

Only consider:

qrspi advance --root . --force

when the user explicitly accepts the risk.

Do NOT default to --force.

5. Hit a gate

For gate stages (D, S, PR), pause and let the user review.

After confirmation, use:

qrspi approve --root .

# If multiple workflows exist
qrspi approve --root . --feature <feature_id>

To explicitly specify a stage:

qrspi approve D --root .

Do NOT bypass approve by directly modifying state.

6. Reject or rewind

Use reject when the current gate-stage artifact is not acceptable and should be regenerated:

qrspi reject --root . --feature <feature_id> --comment "needs changes"

Use rewind when an upstream assumption changed and the workflow should restart from an earlier stage:

qrspi rewind R --root . --feature <feature_id> --reason "redo research"

Rules:

reject is only for gate stages (D, S, PR) that are waiting for approval
rewind cannot move to a future stage
Do NOT manually edit engine_state.json or state.json to emulate either operation

7. Auto-run

Use:

qrspi run --root . --input "requirement description"

# If multiple workflows exist
qrspi run --root . --feature <feature_id> --input "requirement description"

If the user wants to specify a runner:

qrspi run --root . --runner codex --model gpt-5.4
qrspi run --root . --runner mock

Additional rules:

Do NOT enable --no-stop-at-gate by default
Unless the user requests it, do NOT blindly run across many stages
For controlled execution, prefer using --max-stages
Long-running real runner tasks do not have a default timeout
To inspect live runner output while a stage is running, read:
- .qrspi/<feature_id>/runs/<STAGE>_<timestamp>_attempt<N>/live_stdout.txt
- .qrspi/<feature_id>/runs/<STAGE>_<timestamp>_attempt<N>/live_stderr.txt

8. Manage vertical slices

Use:

qrspi slice list --root . --feature <feature_id>
qrspi slice add mock-api --desc "Create mock API" --order 1 --checkpoint "curl passes" --root . --feature <feature_id>

Requirements:

Slice names should be concise and stable
order must be explicit
checkpoint must be verifiable

9. View constraint information

Use:

qrspi context --root . --feature <feature_id>
qrspi budget

Good for confirming context loading scope and instruction budget before entering a new stage.

10. Switch language

Use:

# Explicit Chinese
qrspi run --root . --input "requirement" --lang zh

# Or rely on system LANG auto-detection
export LANG=zh_CN.UTF-8
qrspi run --root . --input "requirement"

Default language is English. Override via --lang or system LANG.

Output and state conventions

The CLI uses:

.qrspi/<feature>/state.json
.qrspi/<feature>/artifacts/
.qrspi/<feature>/structured/
.qrspi/<feature>/slices/
.qrspi/<feature>/runs/

Base decisions on these real directories, not assumptions.

Feature-scoped commands resolve the workflow as follows:

If --feature <id> is provided, that exact workflow must exist
If no feature is provided and exactly one workflow exists, the CLI uses it
If no feature is provided and multiple workflows exist, the CLI stops and asks for --feature <id>

When to stop

Pause and inform the user when:

qrspi is not yet initialized and feature_id is unclear
Multiple workflows exist and the user has not identified the target feature
The current stage lacks an artifact, making advance unsafe
A gate stage is reached and requires human confirmation
The runner does not exist or the command fails
CLI output conflicts with user expectations; align on working directory or feature first

What NOT to do

Do NOT manually modify .qrspi/ state when the CLI can handle stages
Do NOT assume the current feature without running status/stage
Do NOT ignore a multiple-workflow error; rerun with --feature <id>
Do NOT default to --force
Do NOT treat methodology explanations as CLI execution results
Do NOT pretend a gate stage has already been approved