/precheck — Local CI Before Push

Run the mechanical test suite locally before creating a PR. Catches failures in 30 seconds instead of a 4-minute CI round-trip.

Run this EVERY TIME before pushing.

Execution

Step 1: Detect what changed

# What files changed on this branch vs main?
CHANGED=$(git diff main...HEAD --name-only 2>/dev/null || git diff HEAD~1 --name-only)

Step 2: Pick the right test suites

Based on what changed, run only the relevant suites:

Files Changed	Suite	Why
hooks/triage-router.sh	--suite 09	Triage output format tests
hooks/*.sh (any hook)	--suite 09	Hook execution tests
skills/*/SKILL.md	--suite 20	Skill runtime safety (frontmatter, brackets)
agents/*.md	--suite 19,20	Brownfield classification + skill safety
install.sh	--suite 01,02,03,04,19	Install flow tests
portable.manifest	--suite 01,02	Manifest consistency
tests/fixtures/**	--suite 19	Brownfield fixture tests
Multiple categories	--mechanical	Run all mechanical tests

Step 3: Run the tests

# Must be on a feature branch (test runner refuses main)
BRANCH=$(git branch --show-current)
if [ "$BRANCH" = "main" ]; then
    echo "Switch to a feature branch first: git checkout -b fix/my-change"
    exit 1
fi

# Run the selected suites
bash tests/run.sh --suite {selected_suites} --scenario a

Step 4: Report and write marker

If all pass:

# Write precheck marker (triage router checks this before allowing /pr)
mkdir -p "$CLAUDE_PROJECT_DIR/.claude"
echo "$(date +%s) $(git rev-parse --short HEAD 2>/dev/null || echo 'unknown')" > "$CLAUDE_PROJECT_DIR/.claude/.precheck-passed"

✓ Precheck passed ({N} tests, {time}s)
Ready to push.

If any fail:

# Remove stale marker on failure
rm -f "$CLAUDE_PROJECT_DIR/.claude/.precheck-passed" 2>/dev/null || true

✗ Precheck FAILED

Failed tests:
  {test name} — {failure reason}

Fix these before pushing. Do NOT push with failing tests.

Step 5: If all pass, ship it

After tests pass, run the full ship sequence. Do NOT ask — just do it.

5.1: Stage and commit (if uncommitted changes exist)

git add {relevant files — never .env or credentials}
git commit -m "{descriptive message}

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"

5.2: Push

git push -u origin {branch}

5.3: Create PR

gh pr create --title "{title}" --body "{body}"

5.4: Merge

# IMPORTANT: Never use --auto. It's not enabled on this repo.
gh pr merge --squash

5.5: Cleanup

git checkout main
git pull
git branch -d {branch}

5.6: Report

✓ Shipped: PR #{number} merged to main
  Tests: {N} passed, 0 failed
  Files: {changed files summary}

Full sequence (copy-paste safe)

The entire ship flow as a single sequence — test, commit, push, PR, merge, cleanup:

# 1. Test
bash tests/run.sh --suite {suites} --scenario a

# 2. Commit (if needed)
git add {files}
git commit -m "{message}"

# 3. Push + PR
git push -u origin {branch}
gh pr create --title "{title}" --body "{body}"

# 4. Merge (NEVER use --auto)
gh pr merge --squash

# 5. Cleanup
git checkout main && git pull && git branch -d {branch}

Common Failures

Failure	Cause	Fix
"classify_file returns IDENTICAL"	Agent fixture is stale — you changed an agent file	Update the fixture: cp agents/{name}.md tests/fixtures/claude-setups/poweruser/.claude/agents/
"regex-unsafe [brackets] in arguments"	Skill frontmatter has [brackets]	Replace [x] with <x> in SKILL.md arguments/description
"compact SPEED reminder"	Triage router compact output changed	Update test assertion in 09-triage-router-output.sh
"STALE/MODIFIED classification wrong"	Agent grew too much, ratio shifted	Check fixture agent size vs toolkit — restore original fixture if needed

Rules

• Always run before pushing. No exceptions.
• Fix failures before pushing. Don't push hoping CI will pass.
• If you changed agent files, also run --suite 19 (brownfield fixtures).
• If you changed the triage router, also run --suite 09.