BUILDME.sh and TESTME.sh: Executable Documentation That Never Goes Stale

Every developer has experienced this: you clone a repository, open the README, and find build instructions that are six months out of date. The command fails. You grep through the codebase, find a different incantation, and eventually cobble together something that works.

What if your documentation was the code?

The Problem with Traditional Documentation

README files suffer from a fundamental problem: they're static text describing dynamic systems. The moment someone changes a build step and forgets to update the README, documentation rot begins.

Common symptoms:

Commands that reference deprecated flags
Missing prerequisites
Wrong directory paths
Outdated environment variable names
Steps that worked on one developer's machine but nowhere else

Documentation reviews help, but they're fighting entropy. The system naturally drifts toward staleness.

The Solution: Executable Entry Points

We've adopted a convention that eliminates this class of problems entirely:

After README.md we have

BUILDME.sh   # How to build this project
TESTME.sh    # How to test this project  
RUNME.sh     # How to run this project

These aren't just scripts—they're executable documentation. They extend your README with living, breathing instructions that can't go stale because they ARE the process.

Key Properties

Self-Documenting: Each script starts with a clear header and usage instructions. Running ./BUILDME.sh --help tells you everything you need to know.

Self-Verifying: If the build process changes and BUILDME.sh breaks, CI fails immediately. You can't merge broken documentation.

Comprehensive Flags: Different modes for different consumers:

--quiet for AI agents that want minimal output
--verbose for humans debugging issues
--no-smoke-tests for quick iterations
--help for discoverability

Graceful Degradation: Scripts check what's available and adapt. Missing eslint? Skip linting with a warning. No Playwright? Note it and move on.

Anatomy of Good Executable Documentation

Here's what makes BUILDME.sh work:

#!/bin/bash
# BUILDME.sh - Build script for supernal-coding project

# Configuration with sensible defaults
QUIET_MODE=false
SHOW_COLORS=true
RUN_SMOKE_TESTS=true

# Dual-mode logging: minimal for AI, rich for humans
log_ai() {
    if [[ "$QUIET_MODE" == "false" ]]; then
        echo "$1"
    fi
}

log_human() {
    echo -e "${2}$1${NC}"
}

The script knows its audience. An AI agent running ./BUILDME.sh --quiet gets exactly what it needs: success/failure and nothing else. A human debugging a build issue gets colors, emojis, and context.

TESTME.sh: The Testing Contract

TESTME.sh takes this further by providing a comprehensive testing interface:

# Test Types:
#   all            Run all test suites (default)
#   unit           Run unit tests only
#   requirements   Run requirement-specific tests only
#   specific REQ-N Run tests for specific requirement

./TESTME.sh                    # Run everything
./TESTME.sh unit              # Just unit tests
./TESTME.sh specific REQ-011  # Tests for one requirement
./TESTME.sh map               # Generate test coverage map

This eliminates the "how do I run tests?" question permanently. It also provides consistent behavior across CI pipelines, local development, and AI agent execution.

Why AI Agents Love This

When an AI agent clones your repository, it faces the same problems a new developer does—but worse. It can't "figure out" what you meant. It takes instructions literally.

Executable documentation provides:

Single Entry Point: The agent doesn't need to parse your README and guess which commands apply. ./BUILDME.sh is unambiguous.
Structured Output: Quiet mode gives machine-parseable results. The agent knows definitively whether the build succeeded.
Self-Discovery: --help flags let the agent explore capabilities without reading documentation.
Consistent Interface: Every project using this convention works the same way. The agent's learned patterns transfer.

The ME.sh Convention

We use ME.sh suffixes for immediate recognition:

Script	Purpose
`BUILDME.sh`	Set up and compile the project
`TESTME.sh`	Run the test suite
`RUNME.sh`	Start development services

These names are:

SCREAMING_CASE: Visible at the top of directory listings
Self-Explanatory: No ambiguity about what they do
Memorable: Once you've seen the pattern, you'll look for it everywhere

Implementation Tips

Start Simple

Your first BUILDME.sh can be three lines:

#!/bin/bash
npm install
npm run build

That's already better than a README section that might be wrong.

Add Features Incrementally

As you discover needs, add flags:

Someone needs to skip slow steps? Add --fast
CI needs different behavior? Add --ci
Debugging a specific subsystem? Add targeted modes

Don't Duplicate

Your README should point to the scripts, not duplicate their content:

## Getting Started

1. Clone the repository
2. Run `./BUILDME.sh`
3. Run `./TESTME.sh` to verify
4. Run `./RUNME.sh` to start development

For options, run any script with `--help`.

That's it. The scripts ARE the documentation for those processes.

Include Smoke Tests

BUILDME.sh should verify its own success. We run quick smoke tests after building to catch obvious breakage:

run_smoke_tests() {
    # Test that core modules import successfully
    node -e "require('./scripts/config-loader')"
    
    # Verify configuration files parse
    node -e "JSON.parse(require('fs').readFileSync('package.json'))"
    
    log_human "✅ Smoke tests passed" "$GREEN"
}

These catch the "it built but nothing actually works" failures that plague complex projects.

The Cultural Shift

Adopting executable documentation isn't just a technical choice—it's a cultural statement:

"Our build process is important enough to be code."

When build instructions are code, they get:

Code review
Version control
CI validation
The same respect as production code

This matters. Developer experience matters. Time spent fighting broken build instructions is time not spent building features.

Conclusion

README.md describes what your project is. BUILDME.sh, TESTME.sh, and RUNME.sh describe how to use it—and unlike text documentation, they prove themselves correct every time they run.

Start with one script. Make it work. Then never answer "how do I build this?" again.

The Supernal Coding project uses this convention throughout. You can see our implementations in the repository root.