Testing the Estate
Relevant source files
The following files were used as context for generating this wiki page:
Testing the Estate ensures the integrity, reliability, and performance of the governed agent skills and hooks within the claude-skills project. The testing infrastructure verifies that the agent estate—consisting of version-controlled skills, global rules, and session hooks—operates correctly across different repository contexts and workflow phases. It encompasses unit tests for workflow hooks, architectural benchmarks, and global verification rules to prevent regressions in the production environment.
Sources: README.md:1-10, CLAUDE.md:10-15, skills/repo-production-workflow/SKILL.md:1-5
Verification Infrastructure
The project utilizes a multi-layered verification approach to maintain the quality of the agent estate. This includes local shell scripts for environment verification, Python-based unit tests for hook logic, and benchmarking tools for architectural assessment.
Global Verification Rules
All testing and verification must adhere to the Mock Ban and Root-Cause-First invariants defined in the global rules. Verification must cross the real production Interface or Seam; substituted collaborators (stubs/fakes) are prohibited for production proof. Any failure must be reproduced and its source trigger traced before a fix is implemented.
Sources: CLAUDE.md:20-45
Hook Testing
Workflow hooks are verified using a dedicated test runner and Python unit tests. The hooks ensure that transitions between workflow phases (e.g., preflight to TDD) are valid and that metadata is correctly recorded in the repository-scoped SQLite ledger.
The diagram shows the execution flow from the shell entry point to the final workflow validation against the SQLite ledger.
Sources: hooks/tests/run.sh:1-5, hooks/tests/test_workflow_hooks.py:10-25
Benchmarking the Estate
Benchmarks evaluate the performance and structural health of the estate, specifically focusing on "A/B" comparisons between different architectural states or repository configurations.
Architectural Benchmarks
The ab_estate_benchmark.py tool measures the efficiency of the estate's tools and skills. It processes performance metrics such as timing for context forging, diagnosis loops, and advisor consultations. These benchmarks identify bottlenecks in the agent's reasoning or execution speed.
Sources: benchmarks/ab_estate_benchmark.py:1-50, benchmarks/test_ab_estate_benchmark.py:5-20
Key Benchmarking Components
| Component | Function | Derived From |
|---|---|---|
BenchmarkRunner | Orchestrates the execution of estate tasks for performance measurement. | ab_estate_benchmark.py |
MetricCollector | Records timing, token usage, and tool invocation counts. | ab_estate_benchmark.py |
test_benchmark_flow | Verifies that the benchmarking suite itself produces valid reports. | test_ab_estate_benchmark.py |
Sources: benchmarks/ab_estate_benchmark.py:10-40, benchmarks/test_ab_estate_benchmark.py:15-30
Workflow Phase Verification
Testing validates the mandatory order of the repo-production-workflow. Each phase must satisfy specific verification criteria before the next phase begins.
Phase Readiness Criteria
- Context Forge: Must produce a valid
REPO_CONTEXT_FORGE_REQUIRED_INTAKEpacket. - TDD: Requires a failing test (RED) through a real Seam that produces the declared
redFailure. - Verification: Records completion only through a unified CLI runner that reruns lint, typecheck, and build.
- Final Review: Re-derives the attack surface to check for unattacked load-bearing promises.
The sequence diagram illustrates how agent skills invoke the verification suite through the unified workflow CLI to record evidence.
Sources: skills/repo-production-workflow/SKILL.md:130-145, README.md:15-20
Estate Integrity Checks
Integrity checks prevent "drift" between the tracked source and the installed estate in ~/.claude/.
Installation Verification
After an update, developers must verify the installed estate using specific diff commands to ensure machine-managed files and orphans are correctly classified. The hooks/tests/run.sh script provides a baseline check for the environment.
# Verify installed hooks are executable and content matches source
bash ~/.claude/hooks/tests/run.sh
diff -qr --exclude '__pycache__' skills/ ~/.claude/skills/
find ~/.claude/hooks -maxdepth 1 -name '*.py' ! -perm -u+x
Sources: README.md:65-90, hooks/tests/run.sh:1-10
Testing the Estate is a continuous requirement for every PR slice. A pass is not complete until every contract item is GREEN and every preservation item is validly dispositioned against the reviewable working tree.