@mootup/moot-templates 0.2.1 → 0.3.1

package/templates/skills/stack-reset/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: stack-reset
+description: Full teardown, rebuild, provision, and verify cycle for the docker compose stack. QA-owned operation.
+---
+
+# Stack Reset
+
+## Purpose
+
+Rebuild the docker compose stack from a clean state. Used when (a) database schema changes require a fresh volume, (b) container images drift from the shipped code, (c) the stack is in an unknown state after a failed deploy or interrupted migration, (d) explicit operator request to start over. Prevents the failure class where "it worked yesterday" turns into untracked divergence between running containers and current source.
+
+**Why it exists as a named skill:** the reset sequence has a required order (teardown → rebuild → health-check → dep-install → provision → smoke) and multiple easy-to-miss details (the worktree-directory cwd, the `--group test` sync flag, conditional re-provisioning). Ad-hoc resets tend to skip the health-check gate or run compose from the wrong cwd. Capturing the recipe once makes the sequence reproducible.
+
+## Preconditions
+
+Before invoking this skill, the caller MUST verify:
+
+- **Role:** caller is the QA agent. Other roles MUST request a reset via `message_type="stack_request"` rather than invoking this skill directly.
+- **Working directory:** commands will run from `/workspaces/convo/.worktrees/qa` (the QA Worktree). Running from any other cwd is a silent failure — the compose file there carries `BACKEND_SRC` volume mounts that bind worktree source into containers; without them, containers build with stale or wrong source.
+- **Docker daemon:** `docker info` exits 0. If the daemon isn't running, every subsequent step fails with opaque errors.
+- **Pending requester context:** if the reset was requested via a channel `stack_request` message, the `event_id` is known so the post-reset status-update can reply-to the request rather than creating an orphan thread.
+
+## Invariants
+
+These MUST hold throughout the reset:
+
+- **Ordering is absolute.** Steps in Procedure MUST execute in order. Parallelizing or reordering (e.g., installing test deps before services are healthy) produces misleading failures.
+- **No cross-stack contamination.** The reset operates on the `convo-qa` compose project only. Commands MUST NOT affect `convo` (host) or `convo-impl` (Implementation) stacks running on the same docker daemon.
+- **Truthful status reporting.** QA MUST NOT post "stack reset complete" until smoke tests have passed in step 8. Reporting complete with a red smoke is a protocol violation.
+
+## Postconditions
+
+On successful completion:
+
+- All five `convo-qa-*` containers (postgres, redis, backend, frontend, caddy) are in `running` state.
+- Test dependencies (`--group test`) are installed inside `convo-qa-backend-1`.
+- Actors exist in the QA database (either preserved across the volume or re-provisioned in step 6).
+- `pytest -x -q` exits 0 against the current worktree code.
+- A `status_update` has been posted to the channel confirming operational state, including the test pass count.
+
+On failure at any step, the skill stops rather than proceeding. The postconditions above do not hold, and the caller is notified via a channel message describing the failure point — not a "stack reset complete" status.
+
+## Procedure
+
+1. **Change to the QA Worktree.**
+   ```bash
+   cd /workspaces/convo/.worktrees/qa
+   ```
+
+2. **Tear down the existing stack.** MUST be `down`, not `stop` — clean state requires container removal:
+   ```bash
+   docker compose -p convo-qa --env-file .env.qa down
+   ```
+
+3. **Rebuild and start all services:**
+   ```bash
+   docker compose -p convo-qa --env-file .env.qa up --build -d
+   ```
+
+4. **Wait for all services healthy.** MUST verify every service shows `running` before proceeding:
+   ```bash
+   docker compose -p convo-qa --env-file .env.qa ps
+   ```
+   Proceeding early produces test failures that look like application bugs.
+
+5. **Install test dependencies.** The `--group test` flag is required; without it, `pytest` and test-only deps are absent:
+   ```bash
+   docker exec convo-qa-backend-1 uv sync --group test
+   ```
+
+6. **Re-provision only if the database volume was removed.** Actors persist across rebuilds; skip otherwise:
+   ```bash
+   docker exec convo-qa-backend-1 python scripts/provision_actors.py
+   ```
+
+7. **Verify identity:** run `whoami` in the QA agent session; identity MUST resolve.
+
+8. **Run smoke tests:**
+   ```bash
+   docker exec convo-qa-backend-1 uv run pytest -x -q
+   ```
+   `-x` exits on first failure; `-q` suppresses noise. Smoke MUST pass before step 9.
+
+9. **Post the completion status_update to the channel:**
+   ```
+   Stack reset complete. All services running. [N] tests passed. Ready for work.
+   ```
+   SHOULD be a `status_update`, not a top-level message, to avoid operational noise.
+
+## Practice
+
+**When to use `down -v` (volume removal) vs. plain `down`.** Plain `down` preserves the PostgreSQL volume; volumes persist actors, tenant schemas, accumulated test data. `down -v` wipes volumes and forces full re-provisioning. Default to plain `down` unless the schema itself has changed and a clean database is required. Flag any `down -v` invocation to the requester so they're aware data was wiped.
+
+**Smoke test failure handling.** If step 8 fails, invariant 3 ("truthful status reporting") forbids proceeding to step 9. Re-run with `pytest -x -q --tb=short` for a readable traceback, then decide: (a) real regression, re-escalate; (b) flaky test, retry once; (c) infrastructure issue (Redis unreachable, Postgres slow), investigate before proceeding.
+
+**Posting discipline for step 9.** The status_update is the signal other agents use to know QA is operational. Post promptly after smoke passes; don't wait for additional verification unless the requester asked for it.
+
+**Playwright system deps in the frontend container.** The QA frontend image does NOT carry `libglib-2.0.so.0` (and friends) needed by headless Chromium. First Playwright run after a rebuild fails with `error while loading shared libraries`. Once per container lifetime, after step 4 succeeds:
+
+```bash
+docker exec -u root convo-qa-frontend-1 npx playwright install-deps chromium
+```
+
+The deps persist until the container is recreated (which `down` does), so re-install after every full `stack-reset`. Until the frontend Dockerfile adds this to the image build (F-STACKRESET-PLAYWRIGHT-DEPS), the runtime install is the canonical path.
+
+## Defined terms
+
+- **QA Worktree** — `/workspaces/convo/.worktrees/qa/`, the filesystem location where QA's compose commands MUST run.
+- **QA stack** — the `convo-qa` docker compose project, built from the QA Worktree's compose file with `.env.qa`.
+- **BACKEND_SRC** — environment variable in `.env.qa` pointing to the QA Worktree's `backend/` directory, enabling live-source bind-mount.
+

package/templates/skills/verify/SKILL.md

@@ -4,61 +4,139 @@ description: QA verification workflow. Rebuild the test stack, run tests, diff a
 argument-hint: [commit hash or feature name]
 ---
 
-Run the QA verification workflow for a feature handoff.
+# Verify
 
-## Steps
+## Purpose
 
-1. **Identify what to verify.** Check the recent Moot channel context for the handoff message. Note the commit hash, spec file, and files changed ($ARGUMENTS may contain the commit hash).
+Run QA's end-of-pipeline verification gate on a feature handed off by Implementation. Confirms the shipped code matches the spec, tests pass, and no regressions were introduced. The failure class this skill prevents is **silent non-conformance** — Implementation's green self-report covering for a spec-deviation, a latent bug, or an incomplete test suite that only shows up when someone independently rebuilds and runs.
 
-2. **Rebuild the test stack** (QA owns the stack). Use the project's rebuild command. For example, on a docker compose project:
+**Why it exists as a named skill:** verification has several easy-to-miss steps (uvicorn-doesn't-hot-reload-from-volume-mounts; residual DB connections from prior runs can cause phantom ~900-ERROR failures; the spec compliance check requires reading files against the spec, not just running tests). Each of those has bitten verification runs historically; capturing them in one place prevents rediscovery.
+
+## Preconditions
+
+- **Role:** caller is QA.
+- **Handoff received:** a channel message from Implementation (or the feature-thread's most recent git-request ack from Leader) names the commit hash and spec file. Don't start verification without a known target.
+- **Stack ready:** the QA stack is either already running with current source, or QA is about to rebuild. If unsure, run `stack-reset` first.
+- **Spec file reachable:** `docs/specs/<slug>.md` (or equivalent) exists and is readable — this is the source of truth for "what was supposed to ship."
+
+## Invariants
+
+- **Independent verification.** QA MUST rebuild the stack or confirm the running stack reflects the handoff commit. Running tests against a stale-source container validates nothing.
+- **Full pipeline run.** MUST run backend pytest + frontend build + spec compliance pass. Skipping any leg produces a false-positive verdict.
+- **Truthful verdict.** Verdict is Approved OR Blocked, not "looks good" or "mostly passed." Verdicts that soften real failures break the pipeline's ship gate.
+- **Report mentions Leader.** QA's verification-complete handoff MUST mention Leader (via the `mentions` parameter, not just display name in text). Leader is the ship-squash owner; without the mention, the ring stalls.
+- **Small-repair scope is narrow.** QA MAY commit unambiguous bug fixes directly (wrong status code a test asserts, obvious typo, missing validation a test already covers). MUST NOT commit judgment-call or design changes — flag those in the report instead.
+
+## Postconditions
+
+- Backend pytest results captured (pass/fail count, new failures if any).
+- Frontend build status captured (clean / errors).
+- Spec compliance reviewed against the changed files (matches / deviations documented).
+- A verification report exists in the feature thread, mentions Leader, states Approved or Blocked, includes test counts and review findings.
+- If Approved: Leader is the next agent. If Blocked: Implementation is mentioned with what needs to change.
+- Any small repairs committed to QA's branch with notes in the report.
+
+## Procedure
+
+1. **Identify what to verify.** Pull the handoff message (commit hash, spec file, files changed). `$ARGUMENTS` may contain the commit hash.
+
+2. **Rebuild (or confirm current) test stack.** If in doubt about current state, invoke the `stack-reset` skill. Otherwise:
    ```bash
    docker compose up --build -d
    ```
-   Wait for services to be healthy.
+   Wait for all services healthy.
+
+3. **Install test dependencies:**
+   ```bash
+   docker exec convo-backend-1 uv sync --group test
+   ```
+
+4. **Run backend tests:**
+   ```bash
+   docker exec convo-backend-1 uv run pytest
+   ```
+   Note pass/fail counts. See Practice for handling the two most common failure patterns (residual-connection storms; uvicorn-not-reloaded runtime smokes).
 
-3. **Install test dependencies** for your language/toolchain. For example:
+5. **Check frontend build:**
    ```bash
-   <project-test-install-command>
+   docker exec convo-frontend-1 npm run build
    ```
 
-4. **Run the test suite:**
+   For Playwright runs, `PLAYWRIGHT_BASE_URL` MUST be set explicitly on the `docker exec`. Without it, Playwright's config tries to spin its own `webServer` command (`cd ../backend && …`), which fails inside the frontend container. Port table (internal / external):
+
+   | Stack | Project | Internal | External |
+   |---|---|---|---|
+   | Impl | `convo-impl` | 5173 | 5180 |
+   | QA | `convo-qa` | 5173 | 5190 |
+   | Host | `convo` | 5173 | 5173 |
+
    ```bash
-   <project-test-run-command>
+   docker exec -e PLAYWRIGHT_BASE_URL=http://localhost:5173 convo-qa-frontend-1 npx playwright test frontend/tests/<spec>
    ```
-   Note pass/fail count and any new failures.
 
-   **If you see a flood of errors at suite start** (contention from residual state left over from a prior run, stale DB connections, etc.): restart the relevant services to clear residual state before investigating further. This is the first diagnostic step, not a last resort.
+   **First-time Playwright runs in the QA frontend container require system deps.** `libglib-2.0.so.0` is not pre-installed; once-per-container-lifetime run:
 
-5. **Check the frontend build** (if applicable):
    ```bash
-   <project-frontend-build-command>
+   docker exec -u root convo-qa-frontend-1 npx playwright install-deps chromium
    ```
 
-6. **Code review.** Read the changed files and diff against the spec:
-   - Does the implementation match the spec?
-   - Are there deviations? Are they justified?
+   After this the tests can run under the default non-root user. See `stack-reset` practice note for persisting this across rebuilds.
+
+6. **Spec compliance review.** Read the changed files against the spec:
+   - Does the implementation match spec § 4 / § 5 / § 6?
+   - Are there deviations? Are they documented + justified?
    - Were all spec test cases included?
-   - Any security concerns (XSS, injection, etc.)?
+   - Any security concerns (XSS, injection, auth bypass, tenant leakage)?
 
-7. **Post verification report** to the Moot channel in the feature thread:
+7. **Post verification report** as a reply in the feature thread, mentioning Leader:
 
-```
-Verification complete for [feature] (commit [hash]).
+   ```
+   Verification complete for [feature] (commit [hash]).
+
+   **Code review:** [Approved / Changes requested]
+   - [finding 1]
+   - [finding 2]
 
-**Code review:** [Approved/Changes requested]
-- [finding 1]
-- [finding 2]
+   **Tests:**
+   - Backend: [X passed, Y failed]
+   - Frontend build: [clean / errors]
+   - New test coverage: [included / missing]
 
-**Tests:**
-- Backend: [X passed, Y failed]
-- Frontend build: [clean/errors]
-- New test coverage: [included/missing]
+   **Spec compliance:** [matches / deviations noted]
+
+   Verdict: **[Approved / Blocked]**
+   ```
 
-**Spec compliance:** [matches/deviations noted]
+8. **If Approved:** mention Leader (ship). **If Blocked:** mention Implementation with specifics of what needs to change.
 
-Verdict: **[Approved/Blocked]**
+## Practice
+
+**Runtime curl smokes require a backend restart even when the stack doesn't need a rebuild.** `docker exec ... uv run pytest` uses an ASGI test client that loads volume-mounted source directly — tests always run current code. But the live uvicorn process in `convo-qa-backend-1` does NOT hot-reload from the volume mount; it serves whatever source was loaded at container start. When a run has no dep changes / no image rebuild, curl smokes (Q-gates for `/oauth/<route>`, `/api/...`, etc.) MUST be preceded by `docker restart convo-qa-backend-1` (or `docker compose -p convo-qa restart backend`) so uvicorn re-loads updated source. Pytest-green but curl-404 is the telltale symptom — new code is present, uvicorn hasn't read it yet.
+
+**~900+ ERRORs at suite start is almost always residual-connection contention.** Live DB connections left from a prior run cause phantom failures. First diagnostic step — not last resort — is a restart:
+```bash
+docker restart convo-qa-backend-1 convo-qa-postgres-1 convo-qa-redis-1
+```
+Wait for health; re-run pytest. If errors persist, investigate fixture setup / session-scoped state. If they vanish, it was residual contention and the suite is clean.
+
+**Docs source-only greps must exclude `_build/` binary artifacts.** When running an invariant grep under `docs/site/` (e.g., `grep -rn 'pip install mootup' docs/site/`), add `--include=*.md --include=*.rst --include=*.html` to keep the check source-only. The `_build/` subtree is gitignored but the files exist on disk post-build and contain binary `.doctree`, `.pickle`, `searchindex.js` artifacts that match many plain greps. CLI-1's INV 14 first run flagged 5 `.doctree` binary matches before the filter clarified the source was clean. Pattern:
+```bash
+grep -rn --include='*.md' --include='*.rst' '<pattern>' docs/site/
 ```
 
-8. Mention Leader in the report so the pipeline advances. If blocked, mention Implementation with what needs to change.
+**Small-repair judgment.** Commit directly when the intended behavior is unambiguous:
+- A test asserts status 400 and the impl returns 500 — fix the impl to 400.
+- A missing null-check that a test covers — add it.
+- An obvious typo in a string literal.
+
+Flag and don't fix when judgment is required:
+- "Is this the right error code?" — that's spec territory.
+- "Should this endpoint exist at all?" — Product.
+- "Is the overall approach correct?" — Spec.
+
+## Defined terms
+
+- **QA stack** — the `convo-qa` docker compose project (see `stack-reset` skill for full definition).
+- **Runtime curl smoke** — tests that hit the live uvicorn endpoint, distinct from pytest's ASGI test client. Requires backend restart to pick up source changes.
+- **Residual-connection contention** — DB / Redis connections left open from a prior run's process, producing ~900+ ERROR cascade at the start of a new test session.
 
-9. **Small repairs.** If you find an unambiguous bug during verification (wrong status code, missing validation a test covers, obvious typo), fix it directly — commit to your branch and include the fix in your report. No git-request needed for these. If the fix involves judgment calls or design decisions, flag it instead of fixing.

package/templates/teams/loop-6/CLAUDE.md

@@ -2,42 +2,58 @@
 
 TODO: Describe your project. What does it do? What problem does it solve?
 
-## Status
+## Direction
 
-TODO: What works, what doesn't. Update as the project evolves.
-
-## Tech stack
+### Mission
 
-TODO: Language, frameworks, databases, build tools.
+TODO: Why this project exists. What humans + agents accomplish together here.
 
-## Running
+### Values
 
-TODO: How to run the project, run tests, build, deploy.
+TODO: Operational values that guide code, docs, and decisions.
 
-## Code conventions
+## Operating
 
-TODO: Formatting, linting, type checking, naming conventions.
-
-## Agent Workflow
+### Roles
 
 {role_count} agents collaborate on this project: {role_list}. They communicate via the Convo shared context server. Pipeline agents use Claude Code. Product coordinates strategy; Leader orchestrates the operational pipeline; Librarian observes asynchronously for docs.
 
-### Roles
-
 {role_descriptions}
 
-### Strategic vs Operational Layers
+### Topology
 
 Product handles strategic direction and is operator-facing. Leader handles operational orchestration -- day-to-day git operations, pipeline monitoring, ship coordination. Product makes design decisions; Leader executes.
 
-### Observer Role
-
 The Librarian is an async observer -- it monitors the pipeline for shipped features and updates documentation, but does not block the main work pipeline. Librarian communicates with Product via a dedicated side thread.
 
-### Resource Ownership
+### Resource ownership
 
 {resource_ownership}
 
-### Git Workflow
+## Project reference
+
+### Status
+
+TODO: What works, what doesn't. Update as the project evolves.
+
+### Tech stack
+
+TODO: Language, frameworks, databases, build tools.
+
+### Running
+
+TODO: How to run the project, run tests, build, deploy.
+
+### Code conventions
+
+TODO: Formatting, linting, type checking, naming conventions.
+
+## Operational practice
+
+### Git workflow
 
 {git_description}
+
+### Handoff discipline
+
+TODO: How agents coordinate work -- channel mentions, branch names, merge protocol.

package/templates/teams/loop-6/team.toml

@@ -36,7 +36,7 @@ Post a status_update confirming you are online."""
 name = "leader"
 display_name = "Leader"
 harness = "claude-code"
-model = "opus"
+model = "sonnet"
 theme = "purple"
 responsibilities = """
 Pipeline orchestration. Replies to Product's kickoff with the operational
@@ -84,7 +84,7 @@ the channel. Post a status_update confirming you are online. Wait for work."""
 name = "qa"
 display_name = "QA"
 harness = "claude-code"
-model = "opus"
+model = "sonnet"
 theme = "red"
 responsibilities = """
 Test strategy, test implementation, feature verification. Owns the docker
@@ -100,7 +100,7 @@ Post a status_update confirming you are online. Wait for work."""
 name = "librarian"
 display_name = "Librarian"
 harness = "claude-code"
-model = "opus"
+model = "sonnet"
 theme = "cyan"
 responsibilities = """
 Observer role. Owns docs/design/, docs/arch/, docs/site/, READMEs,