Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
chore: clean up manual artifacts and drive-by rebuilds
THRISHAL12345d49ed788c4f9
diff --git a/.test-manual/AGENTS.md b/.test-manual/AGENTS.mddeleted file mode 100644index 229e4f7..0000000--- a/.test-manual/AGENTS.md+++ /dev/null@@ -1,5 +0,0 @@-# AGENTS.md--## Goal Engineering Rules-- Use /goal and update_goal.-- `goal-verifier` MUST PASS before setting completed: true in GOAL.md.diff --git a/.test-manual/GOAL.md b/.test-manual/GOAL.mddeleted file mode 100644index 6188e1a..0000000--- a/.test-manual/GOAL.md+++ /dev/null@@ -1,24 +0,0 @@-# Goal: [Insert Goal Title Here]--**Status:** IN_PROGRESS-**Owner:** [Assigned Agent or Human]-**Target Date:** YYYY-MM-DD--## Objective-Describe the main objective of this goal. What are we trying to achieve?--## Acceptance Criteria-- [ ] Criterion 1 (e.g. Unit tests cover X)-- [ ] Criterion 2 (e.g. Integration with Y works)-- [ ] Verified by `goal-verifier` skill--## Scope & Constraints-- What is explicitly OUT of scope?-- Are there budget limits (see `goal-budget.md`)?-- Are there technical constraints?--## Context-Include links to issues, design docs, or relevant slack threads.------*Generated by loop-init / goal-init*diff --git a/.test-manual/goal-budget.md b/.test-manual/goal-budget.mddeleted file mode 100644index 9ef066f..0000000--- a/.test-manual/goal-budget.md+++ /dev/null@@ -1,16 +0,0 @@-# Goal Budget--> Bound the execution of a goal to prevent runaway agents.--## Limits--- **Maximum total tokens:** 1,000,000-- **Maximum API calls:** 200-- **Maximum duration:** 24 hours--## Exceedance Policy-If the budget is exceeded, the agent MUST:-1. Halt execution.-2. Update `GOAL.md` status to BLOCKED.-3. Append a failure note to `goal-run-log.md`.-4. Await human intervention.diff --git a/.test-manual/goal-run-log.md b/.test-manual/goal-run-log.mddeleted file mode 100644index b35f8d5..0000000--- a/.test-manual/goal-run-log.md+++ /dev/null@@ -1,22 +0,0 @@-# Loop Run Log — YOUR_PROJECT--Append one entry per run. Prune entries older than 30 days.--## Format--```json-{- "run_id": "2026-06-09T08:15:00Z",- "pattern": "daily-triage",- "duration_s": 45,- "items_found": 4,- "actions_taken": 1,- "escalations": 0,- "tokens_estimate": 52000,- "outcome": "report-only | fix-proposed | escalated | no-op"-}-```--## Recent Runs--<!-- Loop appends below this line -->\ No newline at end of filediff --git a/PR_DESCRIPTION.md b/PR_DESCRIPTION.mddeleted file mode 100644index 95916de..0000000--- a/PR_DESCRIPTION.md+++ /dev/null@@ -1,31 +0,0 @@-## Summary-Replaces exact string matching for error signatures with a highly robust **Character Trigram Jaccard Similarity** algorithm in `loop-context`, ensuring the circuit breaker trips on semantically-similar failures even if the phrasing or wording morphs slightly across iterations.--## Changes-- [ ] New pattern or starter (followed `templates/pattern-template.md` + updated `registry.yaml`)-- [ ] Doc / example improvement-- [x] Tool change (`loop-context`)-- [ ] Story (includes real failure or surprise + lesson)--## Checklist (from CONTRIBUTING)-- [ ] All required sections present for patterns-- [ ] Links work from README, patterns/README, starters/README, docs/index-- [x] No secrets, tokens, internal company URLs-- [ ] `STATE.md*` examples use `.example` suffix-- [ ] Safety-related content references `docs/safety.md`-- [x] Ran `node tools/loop-audit/dist/cli.js .` (or on the starter) and addressed findings--## Testing / Dogfood-- [x] `loop-audit` passes on affected starters or this repo (Scored 100/100 L3)-- [x] Manual review of generated state / skill output (Fully tested with `npm run test` inside `tools/loop-context` - all 49 edge-case and algorithm tests pass cleanly).--## Screenshots / Examples (if UI or command output)-**Running loop-context on slightly morphed failures:**-```bash-$ loop-context --check --stagnation 3 --similarity-threshold 0.85 < run.json-ESCALATE [stagnation] — Same error repeated 3× in a row (threshold 3): "Error: connection timeout on port #". Escalating instead of retrying.-```-------*This template enforces the high bar this reference is known for.*diff --git a/scratch.js b/scratch.jsdeleted file mode 100644index 53210bd..0000000--- a/scratch.js+++ /dev/null@@ -1,35 +0,0 @@-import { errorSignature } from './tools/loop-context/dist/context-manager.js';--function getTrigrams(str) {- const trigrams = new Set();- const padded = ` ${str.toLowerCase()} `;- for (let i = 0; i < padded.length - 2; i++) {- trigrams.add(padded.substring(i, i + 3));- }- return trigrams;-}--function calculateSimilarity(a, b) {- if (a === b) return 1.0;- const setA = getTrigrams(a);- const setB = getTrigrams(b);- if (setA.size === 0 && setB.size === 0) return 1.0;- if (setA.size === 0 || setB.size === 0) return 0.0;-- let intersection = 0;- for (const item of setA) {- if (setB.has(item)) intersection++;- }- const union = setA.size + setB.size - intersection;- return intersection / union;-}--const e1 = errorSignature('Error: timeout on port 8080');-const e2 = errorSignature('Error: timed out waiting for 8080');-const e3 = errorSignature('Error: connection timeout on port 8080');-console.log('e1:', e1);-console.log('e2:', e2);-console.log('e3:', e3);-console.log('e1 vs e2:', calculateSimilarity(e1, e2));-console.log('e1 vs e3:', calculateSimilarity(e1, e3));-console.log('e2 vs e3:', calculateSimilarity(e2, e3));diff --git a/tools/loop-context/dist/cli.js b/tools/loop-context/dist/cli.jsindex 6eada01..03b0c54 100755--- a/tools/loop-context/dist/cli.js+++ b/tools/loop-context/dist/cli.js@@ -15,16 +15,6 @@ function parsePositiveIntFlag(raw, flag) {}return n;}-function parsePositiveFloatFlag(raw, flag) {- if (raw === undefined || raw === '') {- throw new Error(`${flag} requires a positive number value.`);- }- const n = Number(raw);- if (Number.isNaN(n) || n <= 0) {- throw new Error(`${flag} must be a positive number; got "${raw}".`);- }- return n;-}function parseArgs(argv) {const breaker = { ...DEFAULT_BREAKER };const prune = { ...DEFAULT_PRUNE };@@ -90,11 +80,6 @@ function parseArgs(argv) {prune.window = parsePositiveIntFlag(argv[++i], '--window');else if (a === '--max-trace-lines')prune.maxTraceLines = parsePositiveIntFlag(argv[++i], '--max-trace-lines');- else if (a === '--similarity-threshold') {- const val = parsePositiveFloatFlag(argv[++i], '--similarity-threshold');- breaker.similarityThreshold = val;- prune.similarityThreshold = val;- }}return { help: false, ledger, ...base() };}@@ -165,7 +150,6 @@ Options:--on-exceed <script> On escalate, pipe the decision as JSON to thisscript's stdin (fire-and-forget; its exit codeis not checked and does not change --check's own).- --similarity-threshold <f> Float 0.0-1.0 to cluster similar errors (default: ${DEFAULT_BREAKER.similarityThreshold})--window <n> Attempts kept when pruning (default: ${DEFAULT_PRUNE.window})--max-trace-lines <n> Stack-trace lines kept (default: ${DEFAULT_PRUNE.maxTraceLines})-h, --help This helpdiff --git a/tools/loop-context/dist/context-manager.d.ts b/tools/loop-context/dist/context-manager.d.tsindex 7bed4e9..39c69e3 100644--- a/tools/loop-context/dist/context-manager.d.ts+++ b/tools/loop-context/dist/context-manager.d.ts@@ -49,16 +49,12 @@ export interface CircuitBreakerConfig {noProgressThreshold: number;/** Optional hard cap on cumulative tokens across the run. */tokenBudget?: number;- /** Float 0.0-1.0. If consecutive errors are this similar, they count as stagnant. */- similarityThreshold: number;}export interface PruneConfig {/** Max lines to keep from any single stack trace. */maxTraceLines: number;/** Number of most-recent attempts to retain in the pruned ledger. */window: number;- /** Float 0.0-1.0. If consecutive errors are this similar, they are collapsed. */- similarityThreshold: number;}export declare const DEFAULT_BREAKER: CircuitBreakerConfig;export declare const DEFAULT_PRUNE: PruneConfig;@@ -68,7 +64,6 @@ export declare const DEFAULT_PRUNE: PruneConfig;* (line numbers, addresses, timestamps, ports, temp paths) differ.*/export declare function errorSignature(error: string): string;-export declare function calculateSimilarity(a: string, b: string): number;export type BreakerTrigger = 'ok' | 'stagnation' | 'no-progress' | 'token-budget' | 'daily-budget' | 'max-iterations';export interface BreakerDecision {/** Whether the loop is cleared to run another iteration. */@@ -115,7 +110,7 @@ export interface AttemptSummary {actionsTried: string[];}/** Deterministic factual rollup of the whole run — no LLM required. */-export declare function summarizeAttempts(ledger: Ledger, similarityThreshold?: number): AttemptSummary;+export declare function summarizeAttempts(ledger: Ledger): AttemptSummary;/*** Build the compact context block to prepend to the next prompt. Contains only* what the agent needs to make progress: the goal, what has already been trieddiff --git a/tools/loop-context/dist/context-manager.js b/tools/loop-context/dist/context-manager.jsindex a927884..a229f70 100644--- a/tools/loop-context/dist/context-manager.js+++ b/tools/loop-context/dist/context-manager.js@@ -19,12 +19,10 @@ export const DEFAULT_BREAKER = {maxIterations: 10,stagnationThreshold: 3,noProgressThreshold: 5,- similarityThreshold: 0.85,};export const DEFAULT_PRUNE = {maxTraceLines: 8,window: 5,- similarityThreshold: 0.85,};// ── Error normalization ────────────────────────────────────────────/**@@ -47,35 +45,6 @@ export function errorSignature(error) {.replace(/\s+/g, ' ').trim();}-/**- * Calculate Jaccard similarity (0.0 to 1.0) using character trigrams.- * Highly robust to minor phrasing variations.- */-function getTrigrams(str) {- const trigrams = new Set();- const padded = ` ${str.toLowerCase()} `;- for (let i = 0; i < padded.length - 2; i++) {- trigrams.add(padded.substring(i, i + 3));- }- return trigrams;-}-export function calculateSimilarity(a, b) {- if (a === b)- return 1.0;- const setA = getTrigrams(a);- const setB = getTrigrams(b);- if (setA.size === 0 && setB.size === 0)- return 1.0;- if (setA.size === 0 || setB.size === 0)- return 0.0;- let intersection = 0;- for (const item of setA) {- if (setB.has(item))- intersection++;- }- const union = setA.size + setB.size - intersection;- return intersection / union;-}function totalTokens(ledger) {return ledger.attempts.reduce((sum, a) => sum + (a.tokensUsed ?? 0), 0);}@@ -105,8 +74,7 @@ export function checkCircuitBreaker(ledger, config = DEFAULT_BREAKER) {const lastSig = errorSignature(failRun[failRun.length - 1].error ?? '');let same = 0;for (let i = failRun.length - 1; i >= 0; i--) {- const curSig = errorSignature(failRun[i].error ?? '');- if (calculateSimilarity(curSig, lastSig) >= config.similarityThreshold)+ if (errorSignature(failRun[i].error ?? '') === lastSig)same++;elsebreak;@@ -189,7 +157,7 @@ export function pruneLedger(ledger, config = DEFAULT_PRUNE) {const sameFailure = prev !== undefined &&prev.outcome === 'failure' &&pruned.outcome === 'failure' &&- calculateSimilarity(errorSignature(prev.error ?? ''), errorSignature(pruned.error ?? '')) >= config.similarityThreshold;+ errorSignature(prev.error ?? '') === errorSignature(pruned.error ?? '');if (sameFailure) {prev.repeated = (prev.repeated ?? 1) + 1;prev.iteration = pruned.iteration; // advance to the latest iteration@@ -201,7 +169,7 @@ export function pruneLedger(ledger, config = DEFAULT_PRUNE) {return { goal: ledger.goal, startedAt: ledger.startedAt, attempts: collapsed };}/** Deterministic factual rollup of the whole run — no LLM required. */-export function summarizeAttempts(ledger, similarityThreshold = 0.85) {+export function summarizeAttempts(ledger) {const groups = new Map();const actions = new Set();let successes = 0;@@ -217,17 +185,11 @@ export function summarizeAttempts(ledger, similarityThreshold = 0.85) {failures++;if (a.error) {const sig = errorSignature(a.error);- let found = false;- for (const existing of groups.values()) {- if (calculateSimilarity(existing.signature, sig) >= similarityThreshold) {- existing.count++;- found = true;- break;- }- }- if (!found) {+ const existing = groups.get(sig);+ if (existing)+ existing.count++;+ elsegroups.set(sig, { signature: sig, count: 1, sample: a.error.split('\n')[0].trim() });- }}}}@@ -248,7 +210,7 @@ export function summarizeAttempts(ledger, similarityThreshold = 0.85) {* (so it does not repeat itself), the last pruned error, and the breaker status.*/export function buildContextInjection(ledger, breaker = DEFAULT_BREAKER, prune = DEFAULT_PRUNE) {- const summary = summarizeAttempts(ledger, breaker.similarityThreshold);+ const summary = summarizeAttempts(ledger);const decision = checkCircuitBreaker(ledger, breaker);const pruned = pruneLedger(ledger, prune);const lines = [];diff --git a/tools/mcp-server/dist/index.js b/tools/mcp-server/dist/index.jsindex 4fcaf1b..e79e04c 100755--- a/tools/mcp-server/dist/index.js+++ b/tools/mcp-server/dist/index.js@@ -294,9 +294,9 @@ server.tool('loop_estimate_cost', 'Estimate daily token cost for a pattern at a}const { cost } = pattern;const mix = level === 'L1'- ? { noop: 0.6, report: 0.4, action: 0 }+ ? { noop: 0.7, report: 0.3, action: 0 }: level === 'L2'- ? { noop: 0.5, report: 0.3, action: 0.2 }+ ? { noop: 0.6, report: 0.25, action: 0.15 }: { noop: 0.4, report: 0.35, action: 0.25 };const realisticPerRun = cost.tokens_noop * mix.noop+ cost.tokens_report * mix.report