---
name: ayf:self-test
description: |
  Agent self-tests the project by walking .ay/tests.md. Each test case is
  verified by reading the actual code and/or running checks; structured
  results are written to .ay/retros/agent-findings.json.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
---

# /self-test -- Agent Self-Test

Walk every test case in `.ay/tests.md`, verify each one against reality (read the
actual code, run the check), and write machine-readable results to
`.ay/retros/agent-findings.json`.

This is a code-level self-test: no browser, no dev server. It answers "does the
codebase actually satisfy the things we said it should?" Use it after a build,
before `/review`, or any time you want a fast, evidence-backed status check.

## Phase 1: LOAD TESTS

1. Read `.ay/tests.md`.
2. If `.ay/tests.md` does not exist, create it from the starter template so the
   human has something to edit, then tell them and continue with the examples:

   ```bash
   mkdir -p .ay
   cat > .ay/tests.md <<'EOF'
   # Self-Test Cases

   One test case per `## T-NN` heading. Under each, a `Check:` block lists the
   concrete things to verify. The agent reads code / runs commands to decide
   pass | fail | skip and records evidence (file:line, command output, a quote).

   ## T-01 CLI entry point is wired
   Check:
   - `bin/` contains an executable entry script
   - `package.json` "bin" (or equivalent) points at a file that exists
   - The entry script has a shebang and is chmod +x

   ## T-02 Install is non-destructive
   Check:
   - The installer never overwrites an existing user config without merging
   - Re-running the installer is idempotent (no duplicate entries)

   ## T-03 Docs match reality
   Check:
   - The command/feature count claimed in README matches the actual file count
   - Every command referenced in docs has a corresponding file on disk
   EOF
   ```

3. Parse each `## T-NN <description>` heading and the `Check:` bullet list that
   follows it. Each heading is one test case with `test_id = T-NN`.

## Phase 2: WALK EACH TEST CASE

For every test case, in order:

1. Read the `Check:` bullets to understand what "pass" means.
2. Gather evidence using the read-only tools:
   - `Read` / `Grep` / `Glob` to inspect the actual code, config, and docs.
   - `Bash` to run a concrete check (e.g. `test -x bin/foo`, `node -c file.js`,
     a linter, or a count like `ls templates/commands | wc -l`).
3. Decide a status:
   - **pass** -- every bullet is satisfied, with evidence.
   - **fail** -- at least one bullet is not satisfied; capture what's wrong.
   - **skip** -- cannot be evaluated here (needs a running server, external
     credential, manual judgment, or the target does not exist yet). Say why.
4. Record the evidence: a `file:line` reference, a command and its output, or a
   short quote. Never mark **pass** without concrete evidence.

Do not fix anything during a self-test -- observe and record only. Surface fixes
as findings; the human (or `/go`) decides what to act on.

## Phase 3: WRITE FINDINGS

Write `.ay/retros/agent-findings.json` (create `.ay/retros/` if needed). Schema
-- a JSON array of findings, one object per test case:

```json
[
  {
    "test_id": "T-01",
    "description": "CLI entry point is wired",
    "status": "pass",
    "evidence": "bin/ayf:1 has shebang; package.json bin.ayf -> bin/ayf (exists, chmod 755 verified via test -x)",
    "ts": "2026-07-12T14:30:00Z"
  }
]
```

Field rules:
- `test_id` -- the `T-NN` id from the heading (string).
- `description` -- the heading text.
- `status` -- exactly one of `pass` | `fail` | `skip`.
- `evidence` -- concrete proof: `file:line`, command output, or a quote. For
  `fail`, state what is wrong; for `skip`, state why it couldn't be checked.
- `ts` -- ISO-8601 UTC timestamp when the case was evaluated.

Write valid JSON (parseable by `JSON.parse`). Overwrite the file each run -- it
is the latest snapshot, not an append log.

## Phase 4: REPORT

Print a one-line summary and the per-case breakdown:

```
Self-test complete: N cases -- PASS: X, FAIL: Y, SKIP: Z
  T-01 pass  CLI entry point is wired
  T-02 fail  Install is non-destructive -- installer clobbers settings.json
  T-03 skip  Docs match reality -- README not present yet
```

If any case is **fail**, recommend `/fix` or `/go`. If all pass, say the
codebase satisfies its declared self-tests and point to
`.ay/retros/agent-findings.json` for the evidence trail.