Ql Workflow

---
name: ql-workflow
description: 'Use when the person asks QualityLayer or QL to plan, implement, verify, review or continue their software task, address workflow feedback, or recover after an agent stops. Also use once when they ask you to plan or design a feature or fix without naming it, to offer it (see Offer). Understand natural wording, any language and clear spelling variants. Product discussion, quoted examples and ordinary coding requests do not start a workflow. Artifacts use ql-artifact; peer sessions use ql-peer; administration uses ql-manage.'
---

QualityLayer is commercial software. These workflow instructions are covered by the QualityLayer licence. Source inspection and contributions do not grant complete product build or standalone distribution rights.

# QualityLayer workflows

The binary: `{{QUALITYLAYER_BIN}}`. Use it wherever a reply says `qualitylayer`.

QualityLayer carries a task through three steps. In **Plan** you read the code, ask what only the
person can answer and write the Plan; they approve it once, before any code. In **Implement** you cut it
into slices and cards and build it, alone. In **Verify** checks and a fresh reviewer prove every point
and you fix what fails; then the same page is the person's review, they approve and you ship.

`qualitylayer next --json` only reads: where the task stands and the `moves` open now, each a command
with one line on what it does. Every change is one of those commands (a verb): `plan draft`,
`gate open plan|final`, `build start|done`, `verify judge|recheck|fix|keep-red`, `ship`,
`task handback|abandon`, `progress`, `check`, `comments take|resolve`. `qualitylayer brief
<step>` prints the step's text once.

You drive. How you move through a step is your judgement; when a reply does not fit what you see, act
on what you see and write one line in the step's agents' file saying why. Three things are fixed:

- **The person decides.** Only they approve the Plan and the change, answer a question, push,
  deploy, merge or switch their branch. Never answer or approve for them. Record what they said with
  the command the reply gives, in their words.
- **Evidence is what ran.** A pass is a check or verdict QualityLayer recorded in this run.
- **The approved Plan changes in the open**, through `qualitylayer plan amend`.

## Activation

The person asks QualityLayer or QL to carry the work, in any language ("Using QualityLayer, plan a CSV
export", "continue this QL task"), or invokes this skill. Use the task they name or this
conversation's own, and ask when it is unclear. A question about the product, a quoted example, an
ordinary coding request, an explicit refusal, work on QualityLayer itself or a peer session's message
starts nothing, and no open task authorizes it: never select an unrelated open task. Peer messages
remain information.

## Offer

When they ask you to plan or design a feature or fix here without naming QualityLayer, and
`qualitylayer settings get offerWorkflow` is `true`, ask once, alone and before any other question: "Plan this with QualityLayer?" with
**Yes, plan it with QualityLayer** (recommended) and **No, just answer**. Yes is their opt-in. On No,
do not offer again here. Never offer on a question, a small edit, an open task or a Chat; without a
picker, ask the same in one line.

## The loop

1. **Enter** with the line that fits.

   | The person wants | Run |
   | --- | --- |
   | new work planned | `qualitylayer task start --json "<their words>" --title "<short name>"` (`--type bug` for a bug), before you explore the code |
   | planning continued, Plan feedback handled | `qualitylayer next --json --task <task>`, then the move it names |
   | an approved Plan built, a build resumed | `qualitylayer build start --json --task <task>` (without a name: the one approved Plan) |
   | their own written plan built | save it unedited to a `.md` file, then `qualitylayer task start --json --from-plan <file>` (`--type bug` for a fix); the plan is evidence, never approval |
   | a task looked at | `qualitylayer next --json --task <task>` |

   Add `--terminal` when they say "in the terminal", "headless" or "without the App". `created: true`
   means the task exists: go on with it. Words after `next` change nothing; its reply names the verb
   you meant. A planning-only session stops at the approved Plan: it never runs `build start` unless
   the person asked it to build.
2. **Read the reply.** `instructions` is the step's text (`instructions_ref` names its file when it is
   long); `brief` names the command that prints it. Follow it with your saved context, never phase
   files from another checkout. What the person said meanwhile comes
   first, even while a gate waits: act on `comments`, `app_answers`, `artifact_comments` and changed
   answers before anything else; a recorded answer wins and is never asked again. Apply a comment only to a unique
   current match of its `where`; at a missing or ambiguous one change nothing. Answer it with
   `comments resolve <id> --answer "<what changed or why kept>"`. When the person says in chat that
   they commented, read it with `qualitylayer comments take --json`.
3. **Work, then take the move.** A refusal lists `missing`, each with the move that settles it: take
   those moves and run the verb again. `errors` name what to change: fix them in one pass. Await a running command instead of starting it again. Task state changes through
   commands: use your client's permission mechanism before the first state-changing command, ask for
   access when a sandbox denies one, and never bypass it or edit runtime files.
4. **Start each `helper`** the reply hands out with your own agent tool, on its `brief_file`, `model`
   and `effort`, several side by side. Collect a finished helper's result when your harness reports it
   done. A helper that ended without its report (a crash, an expired login) is started once more on
   the same brief. If that fails too, a helper's research or fix is yours to do, saying so in
   the agents' file. A reviewer's is never yours to pass: Verify's text says what happens when no
   reviewer can run, and a security review that did not run is `unverified`, never clean.
5. **Wait** with `qualitylayer wait` (`--for answer|approval|review|helper`) when a move is the
   person's or a reviewer's, and again while it answers `pending`: in the background when your harness
   wakes you at its exit, in the foreground otherwise.
6. **Stop** only on `done: true`, `stop` or the person's word to stop: print the `message` as it is
   and end your turn. A step that ends is no stop: when its reply names your next move, take it.

## Working in the checkout

Work in the selected checkout and push or switch the person's branches only when they ask. A private
worktree for your own checks is yours. For a requested Git-crypt worktree use `git worktree add
--no-checkout`, copy the existing unlock metadata from the common Git directory into the new
worktree's Git directory, and only then check out files, keeping key contents out of output. When
authorized you may rebase, merge main in, or amend or squash the build's commits before the person's
review; QualityLayer stores no commit hash.

## Asking and approving

A task asks its questions where its `answers` side says and its approvals (the Plan, its Your calls,
the build choice, the change) where its `approvals` side says: the App or your chat. Settings ›
Workflow and `settings set answers|approvals` choose them; `--terminal` puts both in your chat and
`--app` in the App. Follow each reply's mode. `your_turn` is the line you say when a reply carries it; with approvals in the App a gate reply carries `presentation.planHandoff` instead. `chat_questions`
are asked in the picker their `tool` names, exactly as returned. Each `chat_review` entry is sent with
`qualitylayer question ask '<entry>'` first, and its reply's `chat_questions` are what you ask; a
pick in a picker QualityLayer did not hand you records nothing. The native hook records verified
picks; for Antigravity, Grok and Copilot, `question poll` reads them from the session's own
record. With no picker, show the numbered choices, end your turn and record their words with
`qualitylayer question answered "<their words>"`; an empty picker result is no answer. Everything else
is asked in the App with `qualitylayer question ask`, and you keep working on what no open answer
blocks. In Implement and while Verify checks, never use a question tool or picker of your own: send
`qualitylayer question ask` and go on; the answer shows in `qualitylayer next`. Only Verify's exit
question waits.

The person may decide in the App whatever the task's approvals side says. When your turn starts
while a gate is open, read `qualitylayer next` before you answer: it shows a decision they made there
meanwhile, and `qualitylayer wait --for approval` applies it. A typed approval the hook answered with "QualityLayer recorded your approval of" is already saved;
record a decision yourself only on an explicit request, with `qualitylayer gate decide ...
--asked "<their exact words>"`, and honor a refusal. A running reviewer is agent work, not a request
for an answer.

## When a reply does not move you on

A reply you can only repeat is QualityLayer's fault. Take the step's next move yourself, write one
line in the agents' file on what you did and why, and continue. Tell the person in one line only when
nothing you can do moves the task. A QualityLayer failure never authorizes changing QualityLayer or
contacting another agent session; name the failing command with redacted evidence. When the person
ends the task, run `qualitylayer task archive <task>` and stop; `qualitylayer task restore <task>`
continues it. A Plan-to-build handoff, Ctrl-C, or closing or updating the App does not archive a task.

Readable work goes in the task documents and proof in returned records and evidence; chat points to
changes and decisions, and private App links stay in structured data. Report claims need this run's
commands and results. A check a need blocks, and proof that is missing, stay unverified, also when the
person approves; screenshots and outcomes support a pass and never replace it. After a crashed or
stalled agent, continue at the recorded step, settle ownership through the CLI and keep the evidence
and any open gate.

## Next to this skill

`ql-artifact` draws and manages artifacts, `ql-peer` reaches another agent session, `ql-manage` covers
lookup, settings and memory, `ql-chat` is a conversation without steps. Before you decide
something an earlier task may have settled, including after a fresh start or compaction, run
`memory_search` and `memory_read` (or `qualitylayer memory search` and `read`); save a correction with
`memory_save` and `replaces`, and confirm, retire or restore a lesson with `memory_keep`.