Day 88 — Capstone build 6 (polish & demo)

Updated

July 30, 2026

Day 88 — Capstone build 6 (polish & demo)

Stage VIII · ~3h · Capstone day 6/6
Goal: Finish integration polish—Docker or release artifacts, README that runs cold, and a demo.sh (or documented script) that walks the full story without improvisation.

Important

Day 89 is evidence. Day 90 is retrospective. Today is the last “feature and packaging” day. If the demo is flaky, fix script and UX, not new scope.

Why this day exists

Six build days end here. The deliverable is not “more code”—it is a repeatable story a cold reader can run. Unscripted demos fail under nerves; demo.sh is your insurance for Day 89–90.

Daily goals by option

Option A — Agent

Deliverable Detail
Image Distroless multi-stage Dockerfile
Compose optional Single service compose for local
demo.sh build → run → snapshot → metrics → SIGTERM
README Host permissions if any (docker socket, etc.)
Safety Control API documented as dangerous/local

Option B — Microservice

Deliverable Detail
Image Distroless + health
migrate Automatic or migrate command in demo
demo.sh full user story curls
Seed data optional deterministic demo IDs
OpenAPI-lite route table in README

Option C — CLI

Deliverable Detail
scripts/build-release.sh multi GOOS/GOARCH
checksums optional sha256sum list
demo.sh init → dry-run → apply → status
Install docs go install path
Fixtures sample input files in testdata/

Theory 1 — Demo script design

Properties of a good demo.sh:

  1. Idempotent enough to re-run (or deletes temp dir first)
  2. Fails loud (set -euo pipefail)
  3. No secrets required beyond .env.example
  4. Prints what a viewer should notice
  5. Completes in <3 minutes
#!/usr/bin/env bash
set -euo pipefail
ROOT=$(cd "$(dirname "$0")/.." && pwd)
cd "$ROOT"

echo "== build =="
go build -o bin/app ./cmd/service

echo "== run =="
export DATABASE_URL="${DATABASE_URL:-sqlite:file:demo.db?cache=shared}"
export ADDR="${ADDR:-127.0.0.1:8080}"
./bin/app &
PID=$!
trap 'kill -TERM $PID 2>/dev/null || true' EXIT

wait_http "http://${ADDR#http://}/healthz"

echo "== smoke =="
curl -sf "http://$ADDR/healthz"
curl -sf -X POST "http://$ADDR/v1/items" \
  -d '{"name":"demo"}' -H 'Content-Type: application/json'
curl -sf "http://$ADDR/v1/items" | tee /tmp/demo-items.json

echo "== metrics =="
curl -sf "http://$ADDR/metrics" | head -n 5

echo "OK demo finished"

Adapt ruthlessly to your option. Put demo.sh at repo root or scripts/demo.sh and document the path.

Theory 2 — Wait-for-port helpers

Race-before-listen is the #1 flaky demo cause:

wait_http() {
  local url=$1
  for i in $(seq 1 50); do
    if curl -sf "$url" >/dev/null; then
      return 0
    fi
    sleep 0.1
  done
  echo "timeout waiting for $url" >&2
  return 1
}

For CLIs, wait is usually unnecessary—build then run commands synchronously.

Theory 3 — README cold-start test

Hand the repo path to “past you”:

1. Prerequisites (Go 1.26, Docker?)
2. go test ./...
3. how to run
4. demo.sh
5. config table
6. architecture paragraph

If any step is only in your head, write it down today.

README skeleton

# Capstone name
One sentence.

## Requirements
- Go 1.26.x
- Docker (optional)

## Quick start
```bash
go test ./...
./demo.sh

Configuration

Env Default Meaning

Architecture

(short paragraph + package list)

Safety (Option A)

What the agent will not do by default.


---

## Theory 4 — Freeze scope

Allowed today:

- Bug fixes  
- UX clarity  
- Packaging  
- Demo reliability  

Not allowed:

- New entity types  
- Extra flag systems  
- Rewrites of working architecture  

Park ideas under `CAPSTONE.md` → Future.

```markdown
## Future (not day 88)
- multi-tenant
- gRPC twin

Theory 5 — Packaging checklists

Dockerfile checklist (A/B)

# - CGO_ENABLED=0
# - nonroot USER
# - EXPOSE documented port
# - ENTRYPOINT exec form
# - multi-stage; no toolchain in final
docker build -t capstone:rc1 .
docker run --rm -p 8080:8080 capstone:rc1
docker images capstone:rc1 --format '{{.Repository}}:{{.Tag}} {{.Size}}'

Release proof (C)

#!/usr/bin/env bash
# scripts/build-release.sh
set -euo pipefail
mkdir -p dist
for pair in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64; do
  GOOS=${pair%/*} GOARCH=${pair#*/}
  out="dist/mytool_${GOOS}_${GOARCH}"
  CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o "$out" ./cmd/mytool
  file "$out"
done

Lab runbook

  1. Write/repair demo.sh until three consecutive passes.
  2. Dockerfile or release script per option.
  3. README cold-start section.
  4. Fix bugs found by demo only.
  5. Tag mental RC1; list residual risks for Day 89.
./demo.sh && ./demo.sh && ./demo.sh

Residual risks list

## RC1 residual risks
- load test only local
- no mTLS
- SQLite not Postgres

Day 89 will not fix product ambition—only quality evidence.

Worked example — Option C demo skeleton

#!/usr/bin/env bash
set -euo pipefail
TMP=$(mktemp -d)
trap 'rm -rf "$TMP"' EXIT
go build -o "$TMP/tool" ./cmd/mytool
"$TMP/tool" init --path "$TMP/work"
"$TMP/tool" apply --path "$TMP/work" --dry-run
"$TMP/tool" apply --path "$TMP/work"
"$TMP/tool" status --path "$TMP/work"
echo OK

Worked example — SIGTERM in demo (A/B)

kill -TERM "$PID"
wait "$PID" || true
echo "process exited cleanly"
trap - EXIT

Hour-by-hour suggestion

Time Focus
0:00–0:50 demo.sh reliability (3 passes)
0:50–1:40 Docker or release script
1:40–2:20 README cold start
2:20–2:50 Bugfixes only
2:50–3:00 Freeze scope; residual risks list

Common gotchas

Gotcha Fix
demo relies on preexisting DB state migrate/seed in script
Port already in use configurable ADDR; document
Race before server listens retry loop in demo.sh
Docker needs env not passed -e flags in demo
README drift run demo while editing README
Demo needs GUI browser prefer curl-only script
Scope creep “one more endpoint” Future list
demo.sh not executable chmod +x

Checkpoint

  • demo.sh passes 3×
  • Container or multi-arch binaries
  • README cold start works
  • Scope frozen
  • Residual risks listed
  • Milestone 88 done

Commit

git add .
git commit -m "day88: capstone polish demo packaging"

Write three personal gotchas before continuing.

Tomorrow

Day 89 — Harden & evidence pack: tests, govulncheck, profile/load notes, security re-check—artifacts for the final demo.