From qe-framework
Sequential task executor for non-atomic checklists with ordering dependencies. Reads TASK_REQUEST and VERIFY_CHECKLIST documents, delegates code to Qcode-run-task.
How this skill is triggered — by the user, by Claude, or both
Slash command
/qe-framework:Qrun-taskThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Execute tasks based on spec documents. This is a **secondary execution engine** within the `/Qplan` PSE Chain, used when tasks cannot be fully atomized for `/Qatomic-run`.
Execute tasks based on spec documents. This is a secondary execution engine within the /Qplan PSE Chain, used when tasks cannot be fully atomized for /Qatomic-run.
MANDATORY: All user confirmations MUST use the
AskUserQuestiontool. Do NOT output options as plain text — always call the tool.
/Qplan -> /Qgs -> /Qatomic-run -> /Qcode-run-task./Qatomic-run whenever the checklist can be partitioned; use /Qrun-task when tasks are non-atomic, long-form, or explicitly routed for remediation./Qcode-run-task to maintain the verification and supervision gate./Qgenerate-spec → /Qrun-task → Read → Summarize → Approve → Execute → Verify → ✅ Done
.qe/tasks/{pending,in-progress,completed,on-hold}/TASK_REQUEST_*.md
.qe/checklists/{pending,in-progress,completed,on-hold}/VERIFY_CHECKLIST_*.md
.qe/tasks/remediation/REMEDIATION_REQUEST_*.md
Before executing task items, check SIVS engine configuration:
.qe/sivs-config.json from the project root (via scripts/lib/codex_bridge.mjs → loadSivsConfig()).implement.engine value for the Implement stage (actual coding):
"claude" (default): Proceed with the standard execution workflow. No changes."codex": Delegate implementation to Codex via codex-plugin-cc:
resolveEngine("implement", config) to check availability./codex:rescue with --write flag, passing the TASK_REQUEST checklist items as the task description. Codex will modify files directly.verify.engine value for the Verify stage (validation only):
"claude" (default): Claude validates implementation results against VERIFY_CHECKLIST."codex": Codex validates via /codex:rescue --verify.detectLegacyConfig(). If non-null, display migration warning.Codex Implement Delegation:
codex:codex-rescue subagent (via Agent tool) for autonomous execution--write mode (can modify files)Codex Materialization Check (Mandatory after Codex Done):
Codex may return Done before files are actually written (async companion pattern). The notification hook (notification.mjs) handles initial detection and writes state to unified-state.json under the codex_materialization key.
After every Codex Done, execute this sequence:
Read unified state — check .qe/state/unified-state.json → codex_materialization field:
status: "completed" → notification hook already confirmed files written. Run git diff --stat and proceed to Verify.status: "failed" → report error to user, offer retry or Claude fallback.status: "running" → poll watcher is active, proceed to step 2.Read signal file — cat .qe/agent-results/codex-ready.signal 2>/dev/null:
"detected": true → files written. Run git diff --stat, proceed to Verify."timeout": true → no changes after 1h. Go to step 3.Fallback — use AskUserQuestion:
Results are logged to .qe/agent-results/codex-materialization.md automatically.
Fallback guarantee: Missing .qe/sivs-config.json → all stages default to Claude. Zero impact on existing workflows.
When checklist has 5+ items, delegate to Etask-executor agent. Main agent tracks progress, state transitions, and verification. After delegation, update timestamps: - [x] item ✅ (HH:MM).
Model selection when spawning Etask-executor:
Read the TASK_REQUEST checklist for <!-- complexity: ... --> tags, then pick the model:
| Condition | Model |
|---|---|
Any item tagged complexity: high | sonnet |
All items tagged complexity: low | haiku |
| No tags, ≤ 3 items, single-file scope | haiku |
| No tags, 4–7 items | sonnet |
| No tags, 8+ items OR cross-cutting architecture | sonnet |
Pass the selected model as the model parameter when spawning Etask-executor.
parseClaudeTaskTable(cwd) from hooks/scripts/lib/state.mjs. It now prefers .qe/TASK_LOG.md and falls back to the legacy CLAUDE.md task table..qe/tasks/{pending,in-progress,on-hold}/*.md for TASK_REQUEST files.qe/tasks/ missingRead TASK_REQUEST + VERIFY_CHECKLIST, show summary: ... (omitted summary table) ...
Chained execution skip: If TASK_REQUEST contains <!-- chained-from: Qgenerate-spec -->, skip the approval prompt (user already approved in Qgenerate-spec). Remove the comment after reading.
Otherwise, use AskUserQuestion for approval. On approve:
in-progress/updateClaudeStatus(cwd, uuid, "🔶"). This updates the active task registry, preferring .qe/TASK_LOG.md.Execute checklist items in order. Report: ✅ [1/N] desc - done. Record - [x] item ✅ (HH:MM).
Code task: After Step 3, ask whether to run /Qcode-run-task quality loop.
Intermediate verification: Every 3 items (or per <!-- verify-interval: N -->), check relevant VERIFY_CHECKLIST items. Fix failures before continuing.
Verify each VERIFY_CHECKLIST item with a concrete action — "build passed" alone is NOT sufficient.
| Item type | Verification action |
|---|---|
| File exists | Glob for the path |
| Code behavior | Grep for expected pattern or run test |
| Build/compile | tsc --noEmit or project build command |
| No regression | Run existing test suite |
| Security | Invoke Esecurity-officer (see below) |
| Visual/UI | Screenshot via chrome tools if available |
Report per item: ✅ PASS or ❌ FAIL (reason). All pass → Step 5. Failures → fix and re-verify (max 2 retries, then escalate).
Cross-Phase Regression: For type: code tasks, also run the Cross-Phase Regression Gate (see Qcode-run-task Step 4.8) to ensure prior phases have not regressed before marking completion.
When type: code AND TASK_REQUEST contains any of: auth, crypto, payment, JWT, password, secret, token, credential, bcrypt:
Esecurity-officer agent with git diff HEAD contextThis is mandatory, not a recommendation.
After verification, run the Supervision Gate to get expert-level quality assessment.
skip-supervision conditions (skip if ALL true):
type: docs or type: analysis with fewer than 5 itemsnever skip-supervision for type: code tasks — code always goes through the gate.
Track supervision_iteration counter in .qe/state/session-stats.json to persist across session compactions. Increment on each supervision round.
Esupervision-orchestrator with task context and verification resultsWhen role-separated orchestration is active:
review-report.md and implementation-report.md in the supervision packet.qe/ai-team/artifacts/verification-report.mdAgent Trigger Check: After supervision, check .qe/agent-triggers/ for trigger files written by agents during execution:
.qe/agent-triggers/*.trigger.mdSkip agent triggers if no trigger files exist.
[x] in TASK_REQUEST and VERIFY_CHECKLISTcompleted/updateClaudeStatus(cwd, uuid, "✅"). This updates the active task registry, preferring .qe/TASK_LOG.md.type: code → call Ecode-doc-writer; type: docs → call Edoc-generator/Qarchive in background.qe/agent-results/ (delete result files older than current task)Report: UUID, items completed, verification passed, changed files.
After completion, check for remaining tasks:
.qe/TASK_LOG.md or equivalent active task tracker); use the legacy CLAUDE.md task table only as backward compatibility fallback.qe/tasks/pending/ for queued TASK_REQUEST filesAskUserQuestion to prompt:
/Qrun-task {UUID}."After task completion (Step 5), resolve the active plan's ROADMAP before rendering handoff:
.qe/state/current-session.json → session_id → .qe/planning/.sessions/{session_id}.json → activePlanSlug..qe/planning/ACTIVE_PLAN..qe/planning/plans/{slug}/ROADMAP.md, falling back to flat .qe/planning/ROADMAP.md for legacy projects.Use the standard handoff format from QE_CONVENTIONS.md (vertical table, [x]/[>]/[ ] markers, single code block, lines under 60 chars).
type: code{slug} · Phase {X}: {PhaseName} — Implementation complete
Roadmap
[x] Phase 1: {Name1}
[>] Phase {X}: {PhaseName}
[ ] Phase {X+1}: {NextName}
PSE: [x] Plan [x] Spec [x] Execute [>] Verify
{TaskDescription — 다음 작업 내용 한 줄 요약}
Next: /Qcode-run-task {UUID}
type: docs / type: analysis / deletion-heavyAfter performing SIVS verification inline:
{slug} · Phase {X}: {PhaseName} — Complete
Roadmap
[x] Phase 1: {Name1}
[>] Phase {X+1}: {NextName}
[ ] Phase {X+2}: {FutureName}
PSE: [x] Plan [x] Spec [x] Execute [x] Complete
{NextPhaseDescription — 다음 Phase 작업 내용 한 줄 요약}
{Next label — 사용자 입력 언어로, 예: "다음:" / "Next:"}: /Qgs {slug}: {짧은 별칭, 최대 6단어}
(Fallback line 금지 — /Qgs는 /Qgenerate-spec의 alias이므로 중복이다. Legacy flat-file projects drop the {slug} · prefix and use /Qgs Phase {X+1}: {짧은 별칭}.)
When all Phases are complete:
All phases done. Finalize with /Qcommit
| Situation | Action |
|---|---|
| No documents | Suggest /Qgenerate-spec |
| Task interrupted | Save progress with timestamps, leave in in-progress/ |
| On hold | Move to on-hold/, set ⏸️ |
| Resume | Move to in-progress/, continue from last unchecked item |
| Etask-executor crash | Offer Resume/Retry/Abort |
| No project instruction file or legacy task table | Proceed without context, notify user |
Parallel by default. When multiple UUIDs are passed (space-separated), spawn one Etask-executor Agent per UUID concurrently.
/Qrun-task {UUID1} {UUID2} {UUID3}
│
├─ Read all TASK_REQUESTs → check for inter-dependencies
│
├─ No dependencies found (default):
│ ├─ Agent spawn: Etask-executor(UUID1) ─┐
│ ├─ Agent spawn: Etask-executor(UUID2) ─┼─ parallel
│ └─ Agent spawn: Etask-executor(UUID3) ─┘
│ Each runs Steps 2-5 independently
│
└─ Dependencies found (fallback):
└─ Sequential: UUID1 → UUID2 → UUID3
(only when task B's input is task A's output)
pending → in-progress → completedBefore spawning, scan each TASK_REQUEST for:
depends: {UUID} in notesIf dependencies exist, topologically sort and execute in waves (parallel within each wave, sequential across waves).
When .qe/state/ultra{work,qa}-state.json is active:
--ultraqa: auto-run code quality loopReference skills/coding-experts/ for language/framework best practices. Catalog: skills/coding-experts/CATALOG.md.
/Qgenerate-spec to create specsnpx claudepluginhub inho-team/qe-framework --plugin qe-frameworkCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.