tutorial-check

Tutorial-Check Protocol

Homework validator for the QUICKSTART walkthrough. Runs 5 checks against the user's workspace to confirm they set up their first real project correctly. Reports ✅/❌ per step with a one-line remediation hint.

Read-only — never modifies files or DB.

---

When to invoke

After the user completes the 5-step homework in docs/QUICKSTART.md § 5:

1. Create a project named my-tutorial
2. Start a task in that project (/go-start + /go-fast)
3. Approve the full chain (ok, ok, 1)
4. Verify 5 artifact files exist in tasks/log/{slug}/
5. Confirm the task appears in Flow UI

Then the user runs /tutorial-check and gets pass/fail per step.

---

Step 0 — Detect workspace root

Find the workspace root by walking up from CWD until we find framework.yml or manifest.yml at the same level. If none found within 5 levels — abort:

⚠️ Not inside a framework workspace. Run this from anywhere inside your
   framework directory (where framework.yml lives).

Set {workspace_root} for all subsequent checks.

---

Step 1 — Run the 5 checks

Each check is independent — a failure in one doesn't skip the others.

Check 1: Project my-tutorial created

test -d "{workspace_root}/projects/my-tutorial" && D1=✅ || D1=❌
grep -q "id: my-tutorial" "{workspace_root}/aihub/projects.yml" && D2=✅ || D2=❌
test -L "{workspace_root}/projects/my-tutorial/.claude/skills" && D3=✅ || D3=❌

Pass = D1 AND D2 AND D3. Remediation: bash bin/new-project my-tutorial

Check 2: Task started in that project

COUNT=$(sqlite3 "{workspace_root}/tasks/routing.db" \
  "SELECT COUNT(*) FROM artifacts WHERE project = 'my-tutorial'")
test "$COUNT" -gt 0 && CHECK2=✅ || CHECK2=❌

Pass = at least one artifact row exists. Remediation: cd projects/my-tutorial && claude, then /go-start and /go-fast "...".

Check 3: Chain approved (plan-first artifact exists)

COUNT=$(sqlite3 "{workspace_root}/tasks/routing.db" \
  "SELECT COUNT(*) FROM task_artifacts ta
   JOIN artifacts a ON ta.task_id = a.id
   WHERE a.project = 'my-tutorial' AND ta.artifact_type = 'plan-first'")
test "$COUNT" -gt 0 && CHECK3=✅ || CHECK3=❌