Agentic engineering workflow assessment

Agentic engineering workflow assessment

First self-assessment of the agentic coding loop (2026-08-26). The repo had accumulated
substantial agent infrastructure — 19.6K tokens of AGENTS.md surface, a 640K-token
.agents/ knowledge corpus, 12 check-*.ts gates, 64 skills, 9 MCP servers, four
harnesses in active use (Claude Code, Codex, Maki, Crush) — without ever being designed
as a system. Source plan: .agents/plans/2026-08-26-agentic-workflow-assessment.md.

F1 — Gate flakiness (fixed)

Root cause: turbo.json had no concurrency cap (default 10), and none of the 27
workspace test scripts capped vitest’s worker pool (defaults to ncpu). On an
8-core/8GB box already 2.7GB into swap, that’s enough concurrent processes to starve
memory and fail suites under contention that pass in isolation.

Fix: turbo.json "concurrency": "50%"; packages/vitest.shared.mts (maxWorkers: 2)
imported by all 27 package configs; mise run validate:quick fast tier;
timeout-minutes on ci.yml and test-slow.yml.

F2 — Retrieval was recency-only (fixed)

Only retrieval instruction in the repo was “skim the most recent 2-3 notes” — recency
over a corpus 100x the context window. Added scripts/build-agent-index.ts →
.agents/INDEX.md (mise run agents:index): one grep-friendly line per file across
plans/, notes/, docs/ (date, path, one-sentence summary). AGENTS.md’s Session
memory section now points here first, recency-skim second.

Open question, not resolved here: whether real hybrid search (BM25 + embeddings + RRF)
is worth building on top. The index is the cheap experiment — revisit if grep-the-index
demonstrably misses things a hybrid search would have caught.

F3 — Plan knowledge was scattered (fixed for this repo’s store)

173 plan files existed, only 9 tracked (.gitignore:83 ignored .agents/plans/, plus
a personal ~/.gitignore-global rule doing the same independent of the repo). Triaged
all 164 untracked files for secrets/scratch content (zero hits — see the commit that
un-ignored and added them) and committed them. AGENTS.md now says explicitly that
.agents/plans/ is the one store, not any harness-local default
(~/.claude/plans/, ~/.codex/, ~/.local/state/maki/plans/).

Not migrated: the 52+36+13 plans still sitting in those harness-local stores. Optional
per the source plan — revisit if they keep getting referenced by absolute path from
notes (as .agents/notes/2026-08-25.md already did once).

F4 — Durable investment was Claude-locked (partially fixed)

• .mcp.json added at repo root, declaring the two MCP servers that are genuinely
  project-owned portable infrastructure (brioso-sqlite at db.usebrioso.com,
  brioso-logs at logs.usebrioso.com — both Tailscale-gated HTTP with per-teammate
  bearer tokens, no secrets committed). The other 7 servers agents used daily
  (Stripe, browserOS, posthog, calendar, mindwtr, mobbin, email_ai) run through a
  personal Bifrost aggregator on localhost:8317 — not portable, left out by design.
• .claude/settings.json added: wires block-dangerous-git.sh (previously
  git-tracked but registered nowhere — a dead guardrail reading as a live one) as a
  PreToolUse hook, plus a small read-only Bash allowlist.
• 12 of 64 global skills promoted into .agents/skills/ (symlinked into
  .claude/skills/, following the existing dogfood/qa-studio pattern): see the
  promotion commit for the full list and the audit’s “leave alone” list (~52 skills
  judged Claude-Code-generic, personal, or for unrelated projects).
• .agents/skills/skills-lock.json added, recording each skill’s source — the source
  plan referenced this as an existing precedent; it didn’t actually exist yet, so this
  pass created it.

F5 — Rot in the always-loaded surface (fixed)

• AGENTS.md’s duplicated ## Testing conventions block (lines 233 and 263,
  byte-identical, verified before deleting) is gone — ~700 tokens saved on every
  agent turn, every harness.
• .claude/hooks/block-dangerous-git.sh is now wired (see F4).

F6 — Retrieval tooling, now documented

AGENTS.md’s Session memory section now names ugrep (and its no-PCRE2-JIT caveat —
-P patterns are slow), ast-grep, rtk, opensrc, ghx as available beyond plain
grep/find.

Recurring review (weekly agenda)

• Re-run the gate benchmarks (warm, cold, peak RSS via /usr/bin/time -l); flag any
  regression against this doc’s baseline (55-58s cold, 79/79 green, zero flakes over 3
  runs).
• rtk gain / rtk discover deltas.
• New notes in .agents/notes/ worth promoting into AGENTS.md or a .agents/docs/
  runbook (the “dreaming”/compaction step), then letting the note age out.
• Harness friction encountered that week, per harness (Claude Code, Codex, Maki, Crush).
• Instruction-surface token count (AGENTS.md + global CLAUDE.md + RTK.md,
  currently ~7,030 tokens before this pass) — does it still earn its place?
• Whether .agents/INDEX.md retrieval is actually closing the gap it was built for, or
  whether hybrid search is now justified by evidence instead of intuition.

Ticket

No BRI-* issue was filed before this work started (per AGENTS.md, that’s not a
blocker). File “Agentic workflow hardening” as an umbrella issue and link this doc,
retroactively, in Linear.