---
requirements:
  reasoning: Medium
  context: High
  speed: Low
deps:
  personas: [qa-engineer]
  skills: [qa-engineer, generic]
  templates: []
  sub_workflows: []
  kb_docs: [architecture/stack.md, MASTER_INDEX.md]
  config_fields: [paths.engineering]
---

# 🍵 Meta-Workflow: Quiz Agent

## Purpose

Verify that an agent has correctly loaded and understood the project's knowledge
base before beginning a high-stakes task (e.g. a schema change, a significant
refactor, a deployment, or a migration step).

The quiz is short — 5–7 questions drawn directly from the project's own architecture
and process docs. Vague answers fail. Pass requires specific, factual responses.

<!-- No Iron Laws section: quiz-agent is a utility workflow that makes no store writes and enforces no output contract. Knowledge-check only. It is invoked inline by other workflows, not dispatched as a task phase by the orchestrator. -->

## Algorithm

```
1. Ask the quiz questions below (in order).

2. Evaluate each answer:
   - PASS: specific and factually correct per the project KB
   - FAIL: vague ("some validation"), wrong, or "I'm not sure"

3. Verdict:
   - All pass → proceed with the original task.
   - Any fail → re-read the KB docs listed in "Fail Action", then retry the quiz.
   - Fail twice → escalate to the user before beginning the task.
```

## Questions

(Project-specific questions are generated here during init — see Generation Instructions.)

## Pass Criteria

All questions answered correctly and specifically. Vague answers fail.

## Fail Action

Re-read the project knowledge base docs listed here, then retry:

(Project-specific KB doc paths are embedded here during init.)

Then retry the quiz. If the agent fails twice, escalate to the user before
beginning the task.

---

<!-- See _fragments/generation-instructions.md for Generation Instructions template (quiz-agent: no token-reporting or event-emission — inline helper workflow) -->
## Generation Instructions

### Overview

The generated `quiz_agent.md` tests whether an agent genuinely understands
THIS project's conventions, architecture, and processes — not Forge in general.

Questions must be answerable only by reading the project's own KB docs.
Generic questions about Claude Code or Forge internals are NOT appropriate
unless this project's KB explicitly documents them as project conventions.

### Question generation

Read the following (already generated by earlier phases):
- `{KB_PATH}/architecture/` — all .md files
- `{KB_PATH}/business-domain/` — all .md files
- `{KB_PATH}/stack-checklist.md`
- `{KB_PATH}/MASTER_INDEX.md`

Generate 5–7 questions that test specific knowledge of this project. Each
question must:
1. Reference a specific fact from the project KB (not common knowledge)
2. Have an unambiguous correct answer findable in the KB
3. Cover at least three of these categories:
   - Stack conventions (language, framework rules, linting, build)
   - Architecture (key components, service boundaries, data flow)
   - Domain entities (core business objects and their relationships)
   - Process (how work is tracked, committed, reviewed, deployed)
   - Constraints (what is explicitly forbidden or required)

Avoid yes/no questions. Prefer "what", "where", "name", "describe" forms.

### Fail Action doc list

List the architecture and business-domain docs that cover the question topics.
Use the actual paths as generated (e.g. `{KB_PATH}/architecture/stack.md`).
Include `{KB_PATH}/stack-checklist.md` always.

## Template Output Format

```markdown
# 🍵 Workflow: Quiz Agent — {Project Name}

## Purpose

Verify that an agent has correctly loaded and understood the {Project Name}
knowledge base before beginning a high-stakes task.

---

## Questions

1. **[Category]:** [Question text]
2. ...

## Pass Criteria

All [N] questions answered correctly and specifically. Vague answers
("generally something", "I think it's...") fail.

## Fail Action

Re-read:
- `{KB_PATH}/architecture/[doc1].md`
- `{KB_PATH}/architecture/[doc2].md`
- `{KB_PATH}/stack-checklist.md`
- (any other docs covering the question topics)

Then retry the quiz. If the agent fails twice, escalate to the user before
beginning the task.
```

### Token Reporting

The generated `quiz_agent.md` does NOT include Token Reporting or Event Emission —
it is invoked inline by other workflows (not by the orchestrator as a task phase).