REPI Tools Guidebook — July 2026 Edition

Provided for: All SBA teams Purpose: show every SBA team the tool sets that REPI uses to build, verify, and operate useful applications — and how those tools changed between the June 2026 edition and today. Revised: 2026-07-31 Project reference: REPIv5 (supersedes the REPI Tools Guidebook Draft of 2026-06-03)

REPI is an agent-assisted real estate private equity platform in active use in a testing environment. This guidebook is not about the platform itself. It is about the toolchain — the hardware, coding agents, models, terminals, databases, and review disciplines — that any SBA team can copy to build its own applications.

The central operating principle has not changed:

Agents accelerate the work. They do not lower the standard. Every important feature must be secure, source-tied, tested, and independently verified.

1. Then vs. Now — the tool matrix

2. What changed in sixty days

Three shifts worth understanding before copying any of this:

1. Models became a commodity layer — and the price-performance leader changed. OpenRouter sits between the tools and the model providers, so swapping models for a given task is a configuration choice, not a procurement decision. The practical result: Kimi K3 and Kimi 2.7 now carry most of the daily workload — as good or better than Anthropic's models for this work, at a fraction of the price. K3 in particular is Fable-level, with outstanding UI generation and reasoning. The skill is no longer "pick the right vendor" — it is "match the model to the risk of the task and verify the output."
2. Agents multiplied; discipline did not relax. Kimi Code CLI joined Claude Code and Codex CLI. Each has a distinct strength (Section 4), and the rule that no agent certifies its own work still governs all of them.
3. The workstation got simpler — and more supervised. Ghostty plus Herdr replaced the tmux/cmux control-room setup, and Pi manages the multi-ticket agent process inside Herdr. Fewer moving parts, more parallel agent capacity, same supervision discipline.

What did not change: cross-platform Python/Postgres core, source-tied numbers, audit-before-mutation, localhost-by-default, and independent security review. Those are the parts worth copying first.

3. Tool sets for common SBA app jobs

Each set below is a complete, proven combination. Teams should start with one set, not all seven.

Set 1 — Internal web app with a database

• Python 3.12+ with uv for environment and dependency management
• Flask for routes and server-rendered UI (Jinja templates)
• PostgreSQL as the database of record; SQLAlchemy + psycopg for connectivity
• pytest / pytest-flask for unit and integration tests
• pandas + openpyxl for spreadsheet parsing and transformation

Best for: data-heavy internal tools — uploads, dashboards, reconciliation, reporting.

Set 2 — Presentation-heavy front end

• Next.js 16 + React 19 + TypeScript (the SBA Design System v2 pattern)
• Shared design tokens and skins so every team ships one familiar interface
• Static export for simple hosting

Best for: command centers, narrative/demos, design-system-driven UIs.

Set 3 — AI-assisted development

• Claude Code CLI — high-context, multi-file implementation; reads project rules first; the day-to-day workhorse
• Codex CLI — independent implementation and adversarial review of other agents' diffs; second-opinion engine
• Kimi Code CLI — orchestrated multi-step work, subagent delegation, reusable skills, goal-driven sessions
• Pi — agent management and the multi-ticket process inside Herdr; keeps parallel agent work organized and supervisable
• Cursor (Mac) — the human review cockpit for diff inspection and careful manual edits

Best for: any team writing code with AI. Use at least two agents so one can review the other.

Set 4 — Model access

• OpenRouter as the gateway for hosted models
• Daily drivers: Kimi K3 and Kimi 2.7 — Fable-level quality (K3 is especially strong at UI generation and reasoning) at a fraction of Anthropic's price
• Rest of the hosted portfolio, selected by task: GPT-5.6 (Sol), Codex 5.6, Claude Opus 4.8, GLM 5.2 (in Pi), Grok, Fable, Hermes Mixture of Agents
• Hermes orchestration runs on the Kimi API and Codex 5.6 (Sol) via OAuth (previously Codex 5.5)
• Qwen on the DGX Spark (OpenAI-compatible local endpoint) and Ollama for local serving; OpenWebUI as the browser surface for local models

Model selection rule:

• Critical code/security: frontier model + independent reviewer + tests
• Large source-data reconciliation: high-context model + spreadsheet/database proof
• Private exploratory prompts: local Qwen/OpenWebUI when quality is sufficient
• Current research: Grok-class research tooling + web research + primary-source validation
• Final executive language: strong hosted frontier model, then human review

Set 5 — Data ingestion and reconciliation

• Medallion pipeline: raw upload → bronze/staging → silver/normalized → gold/reporting facts → ops views → audit tables
• Staging-first loads; rejected rows preserved as data-quality evidence
• Source lineage on every row: file, sheet, row/cell, upload batch, parser status
• Reconciliation jobs that tie database totals back to source workbooks

Best for: any app that ingests financial templates. Details in Section 7.

Set 6 — Private AI experimentation

• NVIDIA DGX Spark as the private accelerator
• Qwen (or another local model) behind a localhost / SSH-tunneled OpenAI-compatible API
• OpenWebUI for controlled browser access by non-terminal users
• Hermes Agent installed on the DGX, coordinated with the workstation

Best for: work that must not leave the building, model comparison, long-running agent jobs.

Set 7 — Documents, reports, and decks

• WeasyPrint for HTML → PDF guidebooks and reports (this document is built that way)
• python-pptx scripted pipelines for decks — the deck is regenerated from source, never hand-patched
• Headless browser screenshots for UI verification evidence

4. Tool map — what each tool is for

Hermes Agent (NousResearch)

Role: orchestration, memory, tool calling, gateways, scheduled jobs, subagent delegation, model/provider switching. The main orchestrators in Hermes today are the Kimi API and OpenAI Codex 5.6 (Sol) connected via OAuth (previously Codex 5.5). Use Hermes for machine status checks, verified artifact delivery, scheduled monitoring, and coordinating Claude/Codex/Kimi subagents. Durable procedures are recorded as skills — the shared skill library (including the repi-v5 pack) is how one team's lessons become every team's starting point.

Claude Code CLI

Role: high-context coding agent for multi-file implementation, refactors, and tests. Use it when the task spans routes, templates, ETL, DB, and tests, and the agent should read project rules first. Keep lanes narrow; never let it self-certify security.

Codex CLI

Role: independent implementation/review agent from a second model family. Use it when Claude or Kimi already implemented something and you need an adversarial second view, or for narrow, testable, git-contained work in a parallel branch.

Kimi Code CLI

Role: orchestrated multi-step engineering agent — subagents, reusable skills, goal-driven autonomous sessions. Use it for work that needs planning, delegation across parallel lanes, and persistent task tracking. Newest addition to the stack; pairs naturally with Hermes skills.

Cursor

Role: human IDE and code-review cockpit (Mac workstation). Use it for human-in-the-loop diff review and careful manual edits after agent output. It is an instrument panel, not a substitute for tests or security review.

OpenRouter

Role: single gateway to the hosted model portfolio. Use it to pick models per task without per-provider accounts, and to keep cost tracking in one place. Confidential data still requires approval before it goes to any external endpoint — the gateway does not change the data-governance rules.

Local model stack — Qwen, Ollama, OpenWebUI (DGX Spark)

Role: private inference and experimentation. Model server binds to 127.0.0.1; access from workstations is via SSH tunnel; OpenWebUI is a controlled internal service, never a public endpoint. Do not paste secrets or confidential uploads into unreviewed endpoints, local or hosted.

Pi

Role: agent management and the multi-ticket process inside Herdr. Use it to run and supervise several agent tickets in parallel — the control layer that keeps the multi-agent terminal stack coherent. A walkthrough video of this workflow is planned.

Ghostty + Herdr

Role: the workstation terminal stack — Ghostty as the terminal emulator, Herdr as the multiplexer for long-running agent sessions. This replaces the retired tmux/cmux control-room setup. Same job — durable, supervisable sessions — with less ceremony.

Flask + PostgreSQL core

Role: the application and data backbone (Set 1). Cross-platform by design: pathlib, environment variables, no hardcoded OS paths — the May 2026 platform-flexibility assessment verified REPI migrates between macOS and Windows in 2–4 days, and that property still holds.

Next.js design system

Role: the component-driven front-end pattern (Set 2) used by the SBA Design System v2. Use it when the deliverable is a polished interface or narrative rather than a data-entry workflow.

5. Skills — reusable agent procedures

A skill is a packaged procedure an agent invokes on a trigger phrase: instead of re-explaining a workflow every time, the team records it once and every agent session can run it. The installed library combines the popular engineering-skills set (the Matt Pocock collection) with REPI's own pack (repi-v5). The most-used skills, grouped by job:

Sharpening thinking

• grill-me — a relentless interview that stress-tests a plan or design one question at a time, with a recommended answer for each. (Used to design this guidebook.)
• batch-grill-me — the same interview, but asks every frontier question at once, round by round.
• grill-with-docs — grilling that also produces the artifacts as you go: ADRs and a glossary.

Planning and breakdown

• wayfinder — for work too big for one agent session: plans it as a shared map of decision tickets on the issue tracker, resolved one at a time until the path is clear.
• to-spec — turns the current conversation into a spec (the PRD workflow) and publishes it to the tracker — synthesis, not interview.
• to-tickets — breaks a spec or plan into tracer-bullet tickets with declared blocking edges.
• to-questionnaire — turns a decision you can't answer yourself into a questionnaire for the person who can.

Building

• tdd — red-green-refactor: test first, then the minimal implementation.
• implement — executes a spec or a set of tickets.
• prototype — a throwaway build to answer a design question before committing to it.
• design-an-interface — generates several radically different interface designs in parallel subagents, then compares them.
• codebase-design — shared vocabulary for designing deep modules and choosing seams.

Quality and review

• diagnosing-bugs — a disciplined diagnosis loop for hard bugs and performance regressions.
• code-review — reviews changes against the repo's standards and the originating spec, in parallel subagents, reported side by side.
• qa — conversational bug reporting that files well-formed issues.
• request-refactor-plan — interview → refactor plan with tiny, safe commits.

Knowledge and continuity

• teach (teach-me) — teaches the user a new skill or concept, inside the actual workspace.
• research — investigates a question against primary sources and captures findings as a markdown file.
• ubiquitous-language — extracts a DDD-style glossary from the conversation, flagging ambiguous terms.
• handoff — compacts the current session into a document the next agent (or human) picks up cold.
• triage — moves issues and external PRs through a triage state machine, ending in agent-ready briefs.

The rule from the June edition still applies: durable procedures are recorded as skills, not left in chat logs.

6. Harnesses, loops, and crons

What a harness is

A harness is the program wrapped around a model that turns it from a text generator into a worker. A model on its own can only emit text; a harness gives it tools (files, shell, browser, database), feeds the results of its actions back into the conversation, enforces the project's rules, and tracks state across steps. Claude Code, Kimi Code, Codex CLI, Hermes, and Pi are all harnesses — the same underlying model produces very different results depending on the harness around it. Choosing a harness means choosing what the model is allowed to do and how its work is checked.

A simple harness example

The smallest useful harness is a shell loop: prompt the model, verify its work, stop when verification passes or attempts run out.

for i in 1 2 3; do
  kimi -p "Work on the next unchecked item in TODO.md, then run the tests."
  if uv run pytest -q; then
    echo "green — done"
    break
  fi
done

Every element of a real harness is here in miniature: a task goes in, the model acts with its tools, an independent verification gate (pytest, not the model's own claim) decides whether the work counts, and a bound (three attempts) stops the loop from running forever.

Loops

A loop is a harness running the same cycle repeatedly until a condition is met: define → build → verify → report. The development loop in Section 8 is the human-governed version; the example above is the automated version. Any loop worth trusting has three properties:

1. A clear stop condition — tests green, reconciliation parity, a reviewer verdict.
2. Verification inside the loop — never the agent grading its own homework.
3. A bound on iterations — an unbounded loop is a cost leak, not automation.

The loop-me skill exists to spec these workflows properly before they are automated.

Crons

A cron is a scheduled harness run — the agent wakes on a timer instead of waiting for a human prompt. Typical uses in this stack: a nightly status check with proof-only reporting, a weekly reconciliation summary, a morning triage digest. The rules are the same as for interactive work, tightened:

• Cron jobs report proof only; they do not mutate data, deploy, or commit without the same review gates a human-driven change would need.
• Schedules live in the harness (Hermes scheduled jobs, Kimi Code cron tasks), not in ad-hoc crontab entries nobody reviews.
• Every recurring job has an owner and a documented way to cancel it.

Harnesses, loops, and crons are how a team gets leverage from agents without giving up the standard: the automation runs the process, but verification and security review stay in the loop.

7. The data layer pattern

The June edition devoted two long chapters to PostgreSQL internals and a phased Snowflake migration. The working reality is simpler, and teams should copy the pattern, not the DDL:

1. Medallion layering. Bronze preserves raw rows with full lineage (source file, sheet, row/cell, upload batch, checksum). Silver normalizes types, dates, accounts, and entities. Gold holds reporting-ready facts. Ops views are the app's query contract. Audit tables record who did what, when, and with what result.
2. Staging-first uploads. Uploaded files land in staging — never directly into reporting tables. Validation classifies every row (accepted, warning, rejected, duplicate, superseded); rejected rows are evidence, not trash. Promotion happens only after row-count and control-total checks pass, inside a transaction, with the audit event written atomically.
3. Privileged upload paths. Authenticated, role-gated, file-type allowlist, size limits, safe parsing, no macro execution, original file stored with checksum.
4. Reconciliation as a gate. Numbers are not real until they tie back to the source workbook, file, or screenshot.

Postgres today, Snowflake when the Lab is ready. PostgreSQL remains the database of record for active development — fast iteration, direct Flask integration, auditable staging. The Snowflake transition is anticipated as part of the Rudbek lab collaboration, but it has deliberately not started. When it does, it is a warehouse lift, not a rewrite: the medallion layers, lineage fields, and audit model carry over unchanged, and the two systems dual-run until reconciliation parity is proven.

8. Operating model — the condensed loop

Tools without a loop produce fast, wrong code. This is the loop every agent-built change goes through:

1. Define the slice. Name the page, route, data source, or workflow.
2. Preflight. Git status, DB status, server status, current tests.
3. Plan. Files, DB changes, security risks, tests, acceptance evidence.
4. Assign lanes. One agent owns one lane. No file collisions.
5. Build. Agents implement within their lane.
6. Security review if sensitive. Mandatory for auth, admin, upload, DB mutation, secrets, deployments, and external data/model flows.
7. Regression verify. Tests, curl, DB queries, spreadsheet reconciliation, screenshots/PDFs.
8. Report. Files changed, commands run, results, artifacts, known gaps.
9. Commit only after proof. Green claims without evidence are rejected.

Three rules sit above the loop:

• No agent self-certification. The agent that wrote the code cannot be the agent that approves it. Independent review comes from a different model family or a human.
• Security reviewer is a role, not a checklist. It slows down exactly the decisions that should be slow: auth, uploads, roles, secrets, destructive actions, production exposure.
• Source-tied numbers. Every KPI reconciles to a source workbook, file, or screenshot.

9. Prompt library

Security-reviewer prompt

Review this change as a security reviewer. Do not edit files.
Focus areas:
- authentication and authorization;
- admin role enforcement;
- upload/file handling;
- SQL injection and parameterization;
- audit-before-mutation behavior;
- secrets in code/logs/templates/reports;
- local-dev behavior leaking into production;
- external model/tool data exposure.
Return:
- Critical issues: must fix before ship;
- Important issues: should fix before ship;
- Minor issues: can defer;
- Tests/security checks that should be added;
- Verdict: APPROVED or REQUEST_CHANGES.

Implementation prompt

Read the project rules first. Implement [feature].
Scope:
- own only [files]
- do not touch [files]
Requirements:
- secure by default;
- parameterized SQL only;
- exact source-data fidelity;
- staging-first upload flow if files are involved;
- audit-before-mutation for admin actions;
- tests required.
Verification:
- targeted pytest;
- curl affected routes;
- DB row counts / reconciliation if data changes;
- screenshot/PDF if UI/report changes;
- security reviewer required if auth/admin/upload/DB mutation is touched.

Independent review prompt

Review the current diff for security, correctness, data-fidelity, and missing
tests. Do not edit files. Return critical / important / minor issues with
file:line references and a final APPROVED or REQUEST_CHANGES verdict.

Status prompt

Check local project status: git status, DB listener, app server, health
endpoint, latest changed files, and recent test state. Report proof only.
Do not expose secrets.

10. Onboarding checklist for a new SBA team

1. Read this guide.
2. Pick one tool set from Section 3 that matches your first app. Do not adopt all seven.
3. Confirm assigned roles: developer, reviewer, data auditor, security reviewer, operator.

4. Verify the tools for your role:

   command -v hermes claude codex kimi pi uv git ghostty
   

5. Start from a generic setup — never hardcode someone else's machine paths:

   uv sync
   uv run python scripts/migrate.py
   uv run pytest -q
   

6. For any upload/admin/security-sensitive work, require a security reviewer before acceptance.

7. For any financial number, require source reconciliation before acceptance.
8. Record what you learn as a reusable skill or prompt so the next team starts further ahead.

11. Bottom line

The stack changed in sixty days — OpenRouter at the model layer, Kimi Code joining Claude Code and Codex, Ghostty and Herdr on the workstation, a scripted deck pipeline — but the operating system underneath it did not:

Secure by default. Source-tied numbers. Reviewed admin/upload paths. Verified routes. Clean evidence. No agent self-certification.

REPI remains the Real Estate team's reference implementation, and the REPIv3 platform-flexibility result still stands: the code runs on macOS, Windows, or Linux, so no team is blocked by its hardware. The Rudbek lab — Real Estate's shared AI lab initiative — is where other SBA teams can come run these tools hands-on before adopting them.

Any team can start this week: one tool set, one slice, one reviewed loop.