Weekend Build Log: One Ping Command, Zero Extra Flags

You sit down Saturday morning at 9:12. The coffee on your desk is already cooling. You want one command that pings one URL.

It should print ok or fail, then exit. That is the entire weekend plan on purpose.

Then the coding agent starts planning extra features. The plan adds auth, retries, and extra flags. It also adds a second subcommand for history.

You never asked for that extra surface. Cheap generation still creates extra review work later. Review work will eat your Sunday night.

This log is a scope cut with a working demo. You freeze the public CLI before helpers land. You skip every feature that grows the contract.

The inside of the binary can stay ugly. The outside of the binary stays tiny. That split is the whole method.

The Saturday failure mode

You paste a fuzzy prompt into the agent. The plan looks helpful, complete, and oversized. It invents --json, --timeout, and --retries.

It invents STATUS_PING_TOKEN without a source. It invents status-ping history as a second command. Your one-file tool becomes a platform sketch.

You will not finish a platform this weekend. You also should not merge mystery flags. Mystery flags become an accidental public API.

Accidental API becomes debt when generation is cheap. You need a gate that fails the plan. The gate is a contract card plus checker.

Both files live in the repo root. Neither file needs a paid cloud account. You run them after every agent diff.

The freeze card

Create CONTRACT.md at the repo root. Keep the file under twenty lines. Write names, not wishes or later ideas.

If a flag is missing here, it does not exist. Print the card before you prompt the agent. Paste the card into the prompt itself.

# CLI contract (frozen for this weekend)

Binary: status-ping
Commands: status-ping
Required flag: --url <absolute-http-url>
Optional flags: none
Env vars: none
Exit 0: stdout is exactly ok
Exit 2: stdout is exactly fail
Exit 1: usage error on stderr
Network: one GET, no redirects followed
Files allowed: status_ping.py, CONTRACT.md, contract_check.py, README.md
Forbidden: extra commands, extra flags, extra env, extra HTTP methods

Tell the agent the checker will fail the branch. Do not debate a flag that is absent here. Absence on this card is a hard no.

1. Scaffold the stub yourself

Do not let the agent invent the entrypoint. Write a stub that already obeys the card. You are locking the outside first.

The agent may fill request details later. It may not add flags while filling. Save the stub as status_ping.py.

#!/usr/bin/env python3
"""status-ping: one GET, two happy strings."""
from __future__ import annotations

import argparse
import sys
import urllib.error
import urllib.request


def parse_args(argv: list[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser(prog="status-ping")
    parser.add_argument("--url", required=True)
    return parser.parse_args(argv)


def ping(url: str) -> int:
    if not url.startswith(("http://", "https://")):
        print("usage: --url must be absolute http(s)", file=sys.stderr)
        return 1
    req = urllib.request.Request(url, method="GET")
    try:
        with urllib.request.urlopen(req, timeout=5, context=None) as resp:
            ok = 200 <= getattr(resp, "status", 200) < 300
    except (urllib.error.URLError, TimeoutError, ValueError):
        print("fail")
        return 2
    print("ok" if ok else "fail")
    return 0 if ok else 2


def main() -> None:
    args = parse_args(sys.argv[1:])
    raise SystemExit(ping(args.url))


if __name__ == "__main__":
    main()

Run a usage check before any agent edit. Confirm the missing-flag path without guessing.

chmod +x status_ping.py
python3 status_ping.py; echo exit:$?
python3 status_ping.py --url https://example.com; echo exit:$?

You should see exit 1 without --url. You should see ok or fail with a URL. That pair is the demo spine.

Do not add JSON output yet. Do not add a timeout flag yet. Those belong on the skip list later.

2. Add a checker that reads the freeze

The checker is the original artifact. It is deliberately dumb on purpose. Dumb gates are hard to argue with.

Label this as a local helper script. It is not a security scanner. It only freezes this weekend CLI.

#!/usr/bin/env python3
"""Fail the branch if the public CLI grew."""
from __future__ import annotations

import pathlib
import re
import sys

ROOT = pathlib.Path(__file__).resolve().parent
SOURCE = (ROOT / "status_ping.py").read_text(encoding="utf-8")
CONTRACT = (ROOT / "CONTRACT.md").read_text(encoding="utf-8")

FORBIDDEN_FLAG = re.compile(r"add_argument\(\s*[\"']--(?!url\b)[\w-]+")
FORBIDDEN_ENV = re.compile(r"os\.environ|getenv\(")
FORBIDDEN_CMD = re.compile(r"add_subparsers\(")
FORBIDDEN_METHOD = re.compile(r"method\s*=\s*[\"'](?!GET)[A-Z]+[\"']")


def main() -> int:
    errors: list[str] = []
    if "Binary: status-ping" not in CONTRACT:
        errors.append("CONTRACT.md missing frozen binary name")
    if FORBIDDEN_FLAG.search(SOURCE):
        errors.append("extra argparse flags are not in the contract")
    if FORBIDDEN_ENV.search(SOURCE):
        errors.append("env reads are forbidden this weekend")
    if FORBIDDEN_CMD.search(SOURCE):
        errors.append("subcommands are forbidden this weekend")
    if FORBIDDEN_METHOD.search(SOURCE):
        errors.append("only GET is allowed this weekend")
    if 'print("ok")' not in SOURCE and "print('ok')" not in SOURCE:
        errors.append("happy path must print ok")
    if errors:
        print("contract failed:")
        for item in errors:
            print(f"- {item}")
        return 2
    print("contract ok")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Run it on every agent diff. Keep the command in your notes.

python3 contract_check.py; echo exit:$?

If the agent adds --json, this exits 2. You reject that diff immediately. You do not negotiate the extra flag.

3. Prompt the agent against the card

Keep the prompt short and file-specific. Point at the freeze before any edit. Ban invention in plain language.

Read CONTRACT.md and contract_check.py first.
Edit only status_ping.py.
Do not add flags, env vars, or subcommands.
Keep stdout exactly ok or fail.
Keep one GET and no extra files.
Stop after python3 contract_check.py exits 0.

If you run this loop on a laptop, that is enough. If you want the agent off your machine, you can use MonkeyCode for the same freeze loop.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode offers free model access and a free server option. Treat those as weekend capacity for this loop. Do not assume named models, quotas, hardware, or duration.

Put CONTRACT.md in the project you open there. Run the same checker after the agent edits. The card still owns the public surface.

4. Prove the demo, then stop

Use a URL you control when you can. A public example host is fine for a stub. This is a demo, not a monitor.

python3 status_ping.py --url https://example.com
python3 contract_check.py

Expected shape on a healthy fetch:

ok
contract ok

Fail path, still frozen:

python3 status_ping.py --url https://127.0.0.1:1; echo exit:$?

You should see fail and exit 2. You should not see a Python stack trace. Stack traces are extra surface on stdout.

If the agent prints tracebacks, send it back. Point at the exit table in CONTRACT.md. Ask for the two strings only.

5. Write the skip list before you get clever

Scope cut only counts if you record skips. Put the list in README.md beside the demo. Do not let the agent turn it into a roadmap.

## Skipped on purpose (this weekend)

- No JSON output
- No retry loop
- No timeout flag
- No auth header
- No config file
- No history command
- No database
- No dashboard
- No Docker
- No extra HTTP methods

That list is part of the product. The ping command is only the demo. Readers can copy the list into an agent prompt.

Cheap code is not the weekend risk. Unnamed surface is the weekend risk. Name the outside, then stop.

What this does not catch

The checker is a regex net. It will miss clever parsing code. It will miss handmade sys.argv branches.

It will miss a second module the agent creates. Pair it with a four-file list if needed. Add that list to the card if your agent keeps expanding paths.

It also does not measure latency numbers. It does not prove TLS behavior. It does not replace a real API review.

It freezes a weekend CLI. That is all it claims. Keep that limit visible in the README.

Who should not use this

Do not use this approach for a real service contract. Do not use it for auth, payments, or personal data. Do not use it as production monitoring.

A five second GET with no redirects is a teaching stub. It is not an SLO and not an incident tool. Treat a green checker as a freeze, not as proof.

Skip this method if your team already has OpenAPI tests. Those tests are better than a regex card. This card exists for a solo Saturday.

It exists when the agent is faster than your review habits. It does not exist to replace design. It exists to stop Saturday from becoming a platform.

Why freeze beats another helper file

Agents like adding helpers. Helpers feel like architecture in the plan. Architecture without a freeze becomes a pile.

You already know that pile from other weekends. You have seen clients, mixins, and adapters for one GET. You cut that pile by naming the outside first.

Numbered steps keep you honest:

1. Freeze names in CONTRACT.md.
2. Scaffold the stub yourself.
3. Run contract_check.py on every diff.
4. Prompt against the card only.
5. Demo ok / fail, then stop.
6. Publish the skip list with the demo.

If a step starts spawning files, you are off the card. Return to step 1 without a debate. Delete the extra flag instead of renaming it.

Keep the loop boring

Free model access is enough for this loop. A free server is enough to keep the checker near the agent. Neither makes the contract smarter by itself.

You still have to refuse extra surface. If the run is slow, wait on the checker. If the model ignores the card, the checker still fails.

That failure is the feature you wanted. You can copy these four files into any repo. You do not need one particular host to use the freeze.

Keep the freeze, the stub, the checker, and the skip list. That set is the whole weekend method. Ship the ping, then leave the extras off the card.