Self-Improve

Analyze the Nomos codebase, implement improvements, and open a pull request for review.

Workflow

Step 1 — Clone

Always work in a fresh clone. Never modify the running instance.

WORK_DIR=$(mktemp -d)/nomos
git clone git@github.com:meidad/nomos.git "$WORK_DIR"
cd "$WORK_DIR"

Step 2 — Analyze

1. Read CLAUDE.md in the cloned repo for project conventions
2. Install dependencies:

   PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 pnpm install
   

3. Run pnpm check to confirm a clean baseline — if the baseline is broken, stop and report to the user
4. Analyze the codebase based on the user's request, or identify improvements self-directed

Step 3 — Branch

Create a branch from main:

git checkout -b improve/<descriptive-slug>

Use descriptive slugs: improve/add-chunker-edge-case-tests, improve/fix-session-cleanup, etc.

Step 4 — Implement

• Make focused, single-purpose changes
• Follow project conventions from CLAUDE.md: strict TypeScript, ESM imports with .ts extensions, files under 500 LOC, colocated tests
• One PR = one concern — do not bundle unrelated changes
• Include test coverage for any new code

Step 5 — Verify

All three must pass before proceeding. If any fail, fix before continuing.

pnpm check       # format + typecheck + lint
pnpm test         # all tests pass
pnpm build        # build succeeds

Step 6 — Commit & Push

git add <specific-files>
git commit -m "<conventional commit message>"
git push -u origin improve/<slug>

Step 7 — Open PR

gh pr create \
  --repo meidad/nomos \
  --title "<short title>" \
  --body "## Summary
<what was changed and why>

## Changes
<bulleted list of changes>"

Step 8 — Report

Return the PR URL to the user and summarize what was changed and why.

Guardrails

• Always work in a fresh clone — never modify the running instance
• Never force push or delete branches
• Never commit secrets, .env files, or credentials
• Run all checks before opening the PR
• Keep PRs small and focused — prefer multiple small PRs over one large one
• The PR description should explain the "why" not just the "what"