EN 한국어 日本語 中文
← INTRO (for beginners) REFERENCE (full)
inho-team · qe-framework · v6.5.0

QE Framework
System Architecture

Query & Execute — reduce all AI interactions to two actions, with Plan → Spec → Execute → Verify pipeline and SIVS quality gate running between. A Claude Code plugin.

SKILLS  ····  165
AGENTS  ····  21
CODING EXPERTS  ····  71
LICENSE  ····  MIT
USER SAYS
"What to do"
"Do that for me"
→
CONTEXTFolder Memory
QUALITYSIVS Loop
LIBRARY165 Skills
→
YOU GET
Precise Query
Verified Result
01

PSE Chain — User Workflow

4-STEP PIPELINE
User flow in 4 steps—big tasks or small bugs follow the same pipeline. Each stage has a default model, but you can change it freely via /Qsivs-config. If /Qplan marks a task Micro, it auto-hands off to /Qgs without creating a roadmap—no need to judge scope yourself.
STEP 01 / PLAN

Plan

/Qplan

Map the roadmap, phases, and requirements. Structure what you're building.

default Opus
→
STEP 02 / SPEC

Spec

/Qgs

Generate TASK_REQUEST + VERIFY_CHECKLIST. Refine into a precise Query.

default Sonnet
→
STEP 03 / EXECUTE

Execute

/Qatomic-run

Run parallel Waves with Haiku Teammates. Sequential fallback: /Qrun-task.

default Haiku (Wave)
→
STEP 04 / VERIFY

Verify

/Qcode-run-task

Test → Review → Fix quality loop. Repeat until it passes.

default Sonnet
💡 The engine (Claude / Codex) and model for each step are freely configurable via /Qsivs-config—defaults are shown above, but you can swap engines or models at any stage.
02

Layer Architecture — 6-Layer Stack

SYSTEM STRUCTURE
The framework has 6 layers. Upper (User) = user-visible, lower (Engine Bridge) = execution foundation. Layers communicate only via artifacts (files).

The framework is split into 6 clear layers. Upper layers (User) are user-facing, lower layers (Engine Bridge) handle execution. Each layer owns its responsibility and talks to adjacent layers only through artifacts (files).

LAYER 01 · INTERFACE

User Interface

Entry points you invoke directly: slash commands (/Qplan, /Qgs…) and PSE Chain user flow. Prompt context, CLAUDE.md, and session input belong here.

CLAUDE.md · prompts · /Q* commands
LAYER 02 · SKILLS

Skill Library

165+ self-contained skill definitions. Each skill is a Markdown with Role / Workflow / Handoff. User commands route to skills, which set up an execution plan but delegate implementation to agents.

skills/**/SKILL.md
LAYER 03 · AGENTS

Agent Fleet

21 background agents (E*). 3-tier responsibility split: Teammate (Haiku), Executor (Sonnet), Supervisor (Sonnet/Opus). The actual executors delegated by skills.

agents/E*.md
LAYER 04 · HOOKS

Hook System

Deterministic control layer. Auto-responds to events (SessionStart, PreToolUse, PostToolUse, Stop) to inject context, enforce permission gates, and sync state. Rule-based gates independent of LLM judgment.

hooks/scripts/*.mjs
LAYER 05 · STATE

State & Memory

Single source of truth: Unified State (.qe/state/unified-state.json) + Folder-Aware Context (.qe/context/). All hooks and agents share one version of state—no race conditions.

.qe/state/ · .qe/context/ · .qe/tasks/
LAYER 06 · ENGINE

Engine Bridge

SIVS stage-by-stage engine routing abstraction. Claude by default; optionally delegate to Codex via codex-plugin-cc. No direct external SDKs (OpenAI/Gemini)—dependency isolation.

scripts/lib/codex_bridge.mjs

# Layer communication is via artifacts—even when skills call agents, they go through files/state
# Hooks never modify any layer directly; they only write to the state layer (deterministic)

03

SIVS Loop & 3 Core Pillars

QUALITY GATE + SUPPORT SYSTEMS
SIVS is a quality gate running inside the PSE pipeline: Spec → Implement → Verify → Supervise in 4 steps. Verify (did it?) and Supervise (did it well?) are different jobs. On FAIL, loop back via REMEDIATION (max 3 times).

SIVS Loop — Quality Gate

INSIDE STEPS 03 & 04
S
Spec
I
Implement
V
Verify
S
Supervise
→ PASS
Done
→ FAIL
Remediate → Retry Spec

# Key: when Supervise runs on an independent engine, it avoids the "self-grading" trap
# Each stage can freely route between Claude / Codex

CORE PRINCIPLE

"Work without a spec is guesswork.
A spec without implementation is intent.
Implementation without verification is hope.
Verification without supervision is confirmation bias."

SPEC → IMPLEMENT

TASK_REQUEST becomes the contract for implementation. Without a contract, verification is impossible.

VERIFY ≠ SUPERVISE

Verify = "did it?" (yes/no). Supervise = "did it well?" (expert assessment: security, quality, docs).

REMEDIATE

On FAIL, don't fix on the spot. Create a new spec (REMEDIATION_REQUEST) and re-enter the loop. Max 3 times.

CROSS-PHASE

Before finishing Phase N, re-verify critical items from Phases 1–N-1. Regression prevention gate.

PILLAR 01

Context Memory Manager

Partition context by folder—load only what matches your working directory. Context distributed under .qe/context/ instead of a single CLAUDE.md.

context token savings
PILLAR 02

SIVS Loop Engine

Spec → Implement → Verify → Supervise. Multi-engine routing avoids self-grading; Supervisor makes PASS/FAIL calls.

Claude ↔ Codex independent routing
PILLAR 03

Skills & Agents Library

165 Skills (Q*, M*, coding-experts) + 21 Agents (E*). Specialized knowledge and execution power injected when needed.

165 skills · 21 agents · 71 experts
04

Design Philosophies — 5 Axioms

FOUNDATIONAL AXIOMS
5 axioms + 5 mandatory rules that all skills, agents, and hooks follow. Core: "token waste is drift," "parallel by default, sequential is fallback," "no execution without a spec."

Five axioms embedded throughout the framework beyond the SIVS loop. All skills, agents, and hooks are tuned via Ttune if they violate these.

AXIOM 01

Efficiency = Accuracy

Wasting tokens is not just a cost—it's a source of drift. Unnecessary I/O and duplicate reads scatter the model's focus, leading to wrong calls.

Applied via: ContextMemo · Semantic Compression · 140k/170k compression gate
AXIOM 02

Parallel-First

If two tasks have no data dependency, the default is parallel. Sequential is only a fallback when dependency is explicit. Flipping the default cuts round-trip time.

Applied via: Haiku Wave · multi-UUID Qrun-task · concurrent Test+Review
AXIOM 03

Spec-First

Execution without a spec is guesswork. If a request is ambiguous, create a TASK_REQUEST first, then move to execution. Even urgent requests demand a minimal contract.

Applied via: Qplan → Qgs forced order · Pre-execution Gate
AXIOM 04

Minimal Change

Change only the requested scope. Don't refactor surrounding code for aesthetics. A bug fix is only a fix; one task has one purpose.

Applied via: Qcommit atomic splits · reviewer boundary audit
AXIOM 05

Evidence-Based

Never guess. If uncertain, read the file and verify. Not "probably there" but "line 42." Validate memory and cache claims against current state.

Applied via: grep/Read pre-check · VERIFY_CHECKLIST strict yes/no judgment
▸ MANDATORY OBLIGATIONS (5) — expand
  1. Respect the spec — No execution without TASK_REQUEST. Create one first if missing.
  2. Do not skip verification — Never mark complete with an incomplete VERIFY_CHECKLIST.
  3. Parallel first — Two tasks without dependency must run in parallel.
  4. Remediation is a new spec — No ad-hoc fixes; create REMEDIATION_REQUEST.
  5. The loop is the product — Features, skills, and agents are means; the spec→implement→verify loop is the goal.
05

Multi-Engine Routing

/Qsivs-config
Independently assign each SIVS step to Claude or Codex. Avoid "self-rating bias" where the same engine scores its own output. Defaults are all Claude.

Independently assign Claude or Codex to each SIVS stage (Spec/Implement/Verify/Supervise). Avoids the problem of one engine grading its own work.

SPEC
Claude
or Codex
IMPLEMENT
Codex
or Claude
VERIFY
Claude
or Codex
SUPERVISE
Codex
or Claude

$ /Qsivs-config implement codex --effort high
$ /Qsivs-config set --all claude # restore defaults

06

Folder-Aware Context Memory

.qe/context/
Split project context by folder. Auto-load only files matching your working directory—context token savings vs. a single CLAUDE.md (varies by project; see BENCHMARK.md).
# Work location: src/frontend/components/Button.tsx
.qe/context/
├── _registry.json      # folder ↔ context mapping
├── root.md             # always load (project-wide rules)
├── frontend.md          # ✔ matches src/frontend/** → load
├── backend.md           # ✘ skip
└── scripts.md           # ✘ skip
RESULT → fewer context tokens (varies by project)
07

Skill Library — 165 Skills

Q* + M* + coding-experts
165+ skills organized into 12 categories: PSE Core, Meta, PM, Docs/Writing, Coding Experts (71), QA/Testing, Data/Analysis, and more. Each skill follows the 4-part standard: frontmatter + Role + Workflow + Handoff.
14
Backend
Django, FastAPI, Spring, Rails, NestJS…
12
Frontend
React, Vue, Next.js, Flutter, Angular…
13
Languages
Python, Rust, Go, TS, Kotlin, Swift…
14
Infra
K8s, Terraform, AWS, CI/CD, SRE…
12
Quality
Code review, security, debugging, E2E…
6
Data/ML
RAG, fine-tuning, ML pipelines, Spark…
Core Q-Skills · Main Commands
SKILL CATEGORIES — 12 Clusters

165+ skills organized into 12 categories by role. Each category maps to one user intent pattern

① PSE Core
4-step user workflow—backbone of plan, spec, execute, verify.
/Qplan · /Qgs · /Qatomic-run · /Qcode-run-task
② Meta (M*)
Manage the framework itself—versioning, skill creation, audit, testing.
/Mbump · /Mcreate-skill · /Mqe-audit · /Mtest-skill
③ PM / Strategy
Product and strategy docs—PRD, OKR, roadmap, retro, GTM.
/Qpm-prd · /Qpm-okr · /Qpm-roadmap · /Qpm-retro
④ Docs / Writing
Write and refine docs, emails, papers, and presentations.
/Qdocx · /Qpptx · /Qwriting-clearly · /Qdoc-comment
⑤ Coding Experts
71 experts per language/framework best practices (Java, Go, Rust…).
Qjava-specialist · Qreact · Qfastapi · Qkotlin…
⑥ QA / Testing
Test plans, scenarios, regression, security, visual QA.
/Qqa-test-planner · /Qscenario-test · /Qvisual-qa
⑦ Data / Analysis
Data exploration, stats, financial analysis, DB schema design.
/Qdata-analysis · /Qfinance-analyst · /Qdatabase-schema-designer
⑧ Research / Content
Deep research, fact verification, source verification, content writing.
Edeep-researcher · /Qfact-checker · /Qsource-verifier
⑨ Dev Env / Integration
MCP setup, Chrome, Stitch, Codex integration, secret management.
/Qmcp-setup · /Qchrome · /Qstitch-cli · /Qsecret
⑩ Browser / UI
Browser automation, UI design, style audit, visual redesign.
/Qagent-browser · /Qfrontend-design · /Qdesign-audit
⑪ Academic / Thesis
Paper writing, review responses, research planning, seminar prep.
/Qgrad-paper-write · /Qgrad-paper-review · /Qgrad-research-plan
⑫ Utility / Flow
Session management, context, handoff, cleanup, automation loops.
/Qcompact · /Qresume · /Qcommit · /Qcron · /Qutopia ⚠
SKILL COMPOSITION

What does one SKILL.md look like?

All skills follow the same 4-part structure. This standard lets us auto-generate new skills with /Mcreate-skill, and the routing and execution engines treat any skill the same way.

PART 01 — FRONTMATTER (YAML)
---
name: Qexample
description: One-line description. Use when user says "keyword1", "keyword2".
recommendedModel: sonnet         # haiku | sonnet | opus
invocation_trigger: When to invoke. Typical user phrasing.
---
PART 02 — ROLE (One paragraph)
# Skill Name

## Role
You are [X]. Your job is to [Y]. [Z constraint].
Match the [action] to the [context], not the other way around.
PART 03 — WORKFLOW (Steps)
## Workflow

### Step 1: [Discovery / Context Acquisition]
- What to read and what to decide

### Step 2: [Draft / Execute]
- Actual work (file creation, analysis, renaming, etc.)

### Step 3: [Verification / Approval]
- Confirm with user via AskUserQuestion (MANDATORY)

### Step N: [Handoff]
- Standard format for handing off to next skill
PART 04 — HANDOFF (Final block of response)
Phase {X}: {PhaseName} — Complete

Roadmap
  [x] Phase 1: {Name1}
  [>] Phase {X+1}: {NextName}

PSE: [x] Plan [x] Spec [x] Execute [x] Complete

Next: /Qgs Phase {X+1}: {short-alias}

# Missing handoff = skill execution failure—user can't move forward
# Short alias only; no full phase description copy (feedback_handoff_brevity rule)

08

Agent Fleet & Model Tiering

21 AGENTS · 3 TIERS
21 background agents (E* prefix) + 3 model tiers—Haiku (fast, parallel), Sonnet (balanced, implementation), Opus (depth, strategy). Delegation Enforcer hook auto-injects the right model for the task.
Agent Fleet · E* Agents (21)
  • Etask-executor — execute complex checklists
  • Eqa-orchestrator — test, review, fix loop
  • Esupervision-orchestrator — domain supervisor routing
  • Ecode-reviewer — code review
  • Ecode-test-engineer — test writing
  • Ecommit-executor — AI-neutral commits
  • Erefresh-executor — project analysis, context refresh
  • Edeep-researcher — multi-source research
  • Esecurity-officer — diff security audit
  • Ecompact-executor — context window management
  • Epm-planner — PRD, roadmap, docs
  • + 10 more — archiving, profiling, handoff…
TIER 01 · FAST

Haiku

Simple, parallel tasks
Wave Teammates
Archiving / data refresh
TIER 02 · BALANCED

Sonnet

Code implementation
Etask-executor
Ecode-reviewer
TIER 03 · DEEP

Opus

Strategy, architecture
/Qplan
Edeep-researcher

# Delegation Enforcer auto-injects correct model in pre-tool-use hook
# Under token pressure: 140k → trigger Ecompact-executor, 170k → force compact

09

Hook System — Deterministic Control Layer

DETERMINISTIC CONTROL
9 event hooks (SessionStart, PreToolUse, PostToolUse, Stop, etc.) provide gates independent of LLM judgment—deterministically handle context injection, permission checks, state sync, and compression triggers.

Hooks are deterministic execution points in Claude's lifecycle—if a prompt is a "suggestion," a hook is "force."

SESSION LIFECYCLE
▶ SessionStart
QE: load _registry.json
   inject folder context
│
↺ Main Loop
(see details on right)
│
📦 PreCompact
QE: 140k → Ecompact
   170k → force compact
│
⏹ SessionEnd
QE: log task / archive
MAIN CONVERSATION LOOP
📝 HOOK
UserPromptSubmit
Receive user prompt, allow preprocessing injection
↓
Claude Decision
Generate response or decide to call tool
↓
🔁 TOOL EXECUTION LOOP · Repeats each time a tool is called
① HOOK
PreToolUse
Delegation Enforcer, ContextMemo, Security Gate
↓
② RUN
Execute Tool
Bash, Edit, Write, Read, Grep, Task
↓
③ HOOK
PostToolUse
Audit log, auto-format, lint
↺ Result returns to Claude context → if more needed, go back to ① again
↓
🛑 HOOK
Stop
Persistent Mode prevents pipeline interruption
EXIT CODE Protocol
exit 0
Success — continue.
If JSON in stdout, parse it for allow / additionalContext injection.
exit 2
Deterministic BLOCK.
Return stderr message to Claude. ContextMemo uses this to block duplicate reads.
exit N
Other error — non-blocking.
Show stderr only in verbose mode; execution continues.
# Hooks run with user permissions
# No sandbox — scripts run with full access

QE Framework Special Hooks · What happens at each point

Hook Name Event Action Result
Delegation Enforcer PreToolUse Auto-inject model (Haiku / Sonnet / Opus) based on task type. Example: /Qplan uses Opus, Wave Teammate uses Haiku. inject · exit 0
ContextMemo PreToolUse (Read) Block at hook level if trying to re-read a file already read. Prevent token waste. BLOCK · exit 2
Folder Context Loader SessionStart Match working directory against .qe/context/_registry.json; inject only root.md + matching folder context. inject ctx · exit 0
Auto-compaction Trigger PreCompact At 140k tokens, auto-call Ecompact-executor; at 170k, force compaction. spawn agent
Persistent Mode Stop If PSE Chain is in progress, block Claude from ending response early. Force execution through SIVS Loop. BLOCK · exit 2
Commit Trace Cleaner PreToolUse (Bash: git commit) Coordinate with Ecommit-executor—remove AI traces from commit messages, check convention compliance. allow / deny
Context Refresh Guard PostToolUse (Edit/Write) After file modification, check folder context staleness; trigger /Qrefresh if needed. trigger
Security Gate PreToolUse (Bash) Hard-block dangerous patterns: rm -rf /, force push to main, curl | sh, etc. BLOCK · exit 2
10

End-to-End Flow — How One Query Flows

USER QUERY → FINAL RESPONSE
Full snapshot of how a single user query passes through all 6 framework layers—see at a glance when each hook, skill, and agent kicks in from prompt receipt to final response.

When a user types one line and gets a verified response, watch how Context, Hooks, PSE Chain, and SIVS Loop actually interact in order in one flowchart. Branches (◆) split the path; on failure, it loops back to an earlier step.

MAIN step
HOOK intervention
CONTEXT state
Branch / judgment
━ solid: execute · ┄ dashed: reference/loopback
💡 The "default Opus/Sonnet/Haiku" in the diagram is just defaults—each PSE stage's engine (Claude/Codex) and model can be re-routed anytime via /Qsivs-config.
flowchart TD USER["👤 USER
Fix that bug"]:::terminal H_PROMPT["UserPromptSubmit hook"]:::hook H_SESSION["SessionStart hook"]:::hook H_PRE["PreToolUse hook
· Delegation Enforcer
· ContextMemo
· Security Gate"]:::hook H_POST["PostToolUse hook
· audit log · auto-format"]:::hook H_COMPACT["PreCompact hook"]:::hook H_STOP["Stop hook"]:::hook H_END["SessionEnd hook"]:::hook C_CTX["Folder Context
root.md + folder.md
matched context only"]:::ctx C_MEMO["File read cache"]:::ctx C_TOKEN["Token usage monitor"]:::ctx SUBMIT["Receive Prompt"]:::main CTXLOAD["Folder Context Loader
Match working dir"]:::main CLAUDE["Start Claude"]:::main PLAN["① Plan · /Qplan
default Opus"]:::main SPEC["② Spec · /Qgs
default Sonnet"]:::main EXEC["③ Execute · /Qatomic-run
default Haiku Wave"]:::main VERIFY["④ Verify · /Qcode-run-task
default Sonnet"]:::main TCALL["Tool Call Issued
Bash · Edit · Write · Read"]:::main CHECK{"Duplicate or
Security Risk?"}:::decision BLOCK["exit 2 BLOCK
Return reason to Claude"]:::block TEXEC["Execute Tool"]:::main POSTLOG["Post-process Result
audit log · format"]:::main SIVS{"SIVS Verdict"}:::decision TOKEN{"Token Threshold?"}:::decision COMPACT["Ecompact-executor
Auto-compact"]:::main STOP{"Stop Attempted
Pipeline ongoing?"}:::decision PERSIST["Persistent Mode BLOCK"]:::block ARCHIVE["Archive Session
Preserve context"]:::main RESULT["✅ Verified Response
Bug fixed + tested + reviewed"]:::terminal USER --> SUBMIT H_PROMPT -.-> SUBMIT SUBMIT --> CTXLOAD H_SESSION -.-> CTXLOAD C_CTX -.-> CTXLOAD CTXLOAD --> CLAUDE CLAUDE --> PLAN PLAN --> SPEC SPEC --> EXEC EXEC -->|Tool needed| TCALL H_PRE -.-> TCALL C_MEMO -.-> CHECK TCALL --> CHECK CHECK -->|YES block| BLOCK CHECK -->|NO pass| TEXEC TEXEC --> POSTLOG H_POST -.-> POSTLOG POSTLOG -.->|next Tool Call| TCALL POSTLOG --> VERIFY BLOCK --> VERIFY VERIFY --> SIVS SIVS -->|FAIL Remediate| SPEC SIVS -->|PASS| TOKEN C_TOKEN -.-> TOKEN TOKEN -->|≥140k auto| COMPACT TOKEN -->|≥170k force| COMPACT TOKEN -->|<140k| STOP H_COMPACT -.-> COMPACT COMPACT --> STOP H_STOP -.-> STOP STOP -->|ongoing| PERSIST PERSIST -.->|continue| EXEC STOP -->|done| ARCHIVE H_END -.-> ARCHIVE ARCHIVE --> RESULT classDef main fill:#18212d,stroke:#3a4a60,stroke-width:1px,color:#dce4ef classDef hook fill:#2a1d08,stroke:#fbbf24,stroke-width:1px,color:#fbbf24 classDef ctx fill:#0a1e2a,stroke:#7dd3fc,stroke-width:1px,color:#7dd3fc classDef decision fill:#2a0e20,stroke:#f472b6,stroke-width:1.5px,color:#f472b6 classDef terminal fill:#0a2a1d,stroke:#6ee7b7,stroke-width:2px,color:#6ee7b7 classDef block fill:#2a0e14,stroke:#fb7185,stroke-width:1px,color:#fb7185
CONTEXT
Selective load per folder
File read cache
Auto-compact tokens
HOOKS (7)
SessionStart · End
Pre·PostToolUse
PreCompact · Stop
PIPELINE
Plan → Spec
Execute → Verify
(+ Inner Tool Loop)
DECISIONS (4)
Block tool
SIVS PASS/FAIL
Token threshold · Stop