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
feat(constraints): add loop-constraints file + enforcement skill
neerajdad123-byte0c2abd3ec965
diff --git a/docs/safety.md b/docs/safety.mdindex a5563b7..ea1b3dc 100644--- a/docs/safety.md+++ b/docs/safety.md@@ -73,7 +73,6 @@ Always require human for:- Do not disable tests to make CI green- Do not increase timeouts blindly without root-cause note- Quarantine flakes via explicit ticket + human approval-## Incident ResponseIf a loop merges bad code:@@ -93,4 +92,12 @@ Before L3 (unattended):- [ ] Human gates documented in pattern- [ ] Kill switch documented ([operating-loops.md](./operating-loops.md))-See also [loop-design-checklist.md](./loop-design-checklist.md).\ No newline at end of file+See also [loop-design-checklist.md](./loop-design-checklist.md).++## Machine-Readable Constraints++For runtime enforcement, define constraints in `loop-constraints.md` at the project root.+The `loop-constraints` skill reads this file at the start of every loop run and enforces+every rule. Template: [templates/loop-constraints.md](../templates/loop-constraints.md).++Tool examples: [Grok](../examples/grok/constraints.md) · [Claude Code](../examples/claude-code/constraints.md) · [Codex](../examples/codex/constraints.md)\ No newline at end of filediff --git a/templates/SKILL.md.loop-constraints b/templates/SKILL.md.loop-constraintsnew file mode 100644index 0000000..2f921cb--- /dev/null+++ b/templates/SKILL.md.loop-constraints@@ -0,0 +1,48 @@+---+name: loop-constraints+description: >+ Read loop-constraints.md at the start of every run and enforce every rule.+ This skill runs BEFORE triage or any action skill. Constraints are binding.+user_invocable: true+---++# Loop Constraints Enforcer++You are the guardrail. Before any other work begins, you MUST:++1. Read `loop-constraints.md` from the project root.+2. Load every rule into your working memory.+3. Check if `loop-pause-all` is active → exit immediately.+4. Apply these rules to EVERY action that follows.++## How to enforce++- Before pushing: re-read the Push & Merge section. If ANY rule blocks it, stop and tell the human.+- Before editing a file: re-read the Paths section. If the path matches a denylist pattern, escalate.+- Before proposing a fix: re-read the Code section. Run tests. One fix per run.+- Before merging: re-read the Push & Merge section. Human must approve.++## Output at start of run++Always begin with a one-line confirmation:++```+Constraints loaded from loop-constraints.md: N rules active.+```++If no `loop-constraints.md` exists, say so and proceed with default safety rules from `docs/safety.md`.++## Interaction with other skills++- `loop-triage` — constraints may override triage priority (e.g. "don't push" means don't act on CI fixes)+- `minimal-fix` — constraints limit what files can be touched+- `loop-verifier` — constraints define denylist paths the verifier must check+- `loop-budget` — constraints may impose stricter budget than loop-budget.md++## Default constraints (when no file exists)++If `loop-constraints.md` is absent, enforce these minimums:+- Never edit `.env`, `.env.*`, `auth/`, `payments/`, `secrets/`, `credentials/`+- Never auto-merge to main+- Never disable tests+- Escalate after 3 failed fix attemptsdiff --git a/templates/loop-constraints.md b/templates/loop-constraints.mdnew file mode 100644index 0000000..b08f058--- /dev/null+++ b/templates/loop-constraints.md@@ -0,0 +1,31 @@+# Loop Constraints++> Add rules below with `/constraints <rule>` in your agent.+> The `loop-constraints` skill reads this file at the start of every run.+> Constraints here are **binding** — the agent MUST follow them.++## Push & Merge+- Don't push before telling me+- Never auto-merge to main without human approval+- Always create a draft PR first; let me review before marking ready++## Paths+- Never edit .env, .env.*, auth/, payments/, secrets/, credentials/+- Never edit infrastructure configs without human approval++## Code+- Always run tests before proposing a fix+- Never disable tests to make CI green+- Never refactor unrelated code — one fix per run+- Max 3 fix attempts per item; escalate after++## Communication+- Always tell me what you're about to do before doing it+- Never close an issue or PR without my approval++## Budget+- If token spend hits 80% of daily cap, switch to report-only+- If loop-pause-all is active, exit immediately++---+<!-- Add your own rules below. Use plain English. The loop reads this verbatim. -->diff --git a/tools/loop-audit/dist/auditor.d.ts b/tools/loop-audit/dist/auditor.d.tsindex a5ebb7d..2d81924 100644--- a/tools/loop-audit/dist/auditor.d.ts+++ b/tools/loop-audit/dist/auditor.d.ts@@ -49,6 +49,10 @@ export interface LoopSignals {loopMdBudget: boolean;budgetSkill: boolean;};+ constraints: {+ present: boolean;+ hasConstraintsSkill: boolean;+ };loopActivity: {present: boolean;evidence: string[];diff --git a/tools/loop-audit/dist/auditor.js b/tools/loop-audit/dist/auditor.jsindex 5a4ce00..7f17780 100644--- a/tools/loop-audit/dist/auditor.js+++ b/tools/loop-audit/dist/auditor.js@@ -31,6 +31,8 @@ const SCORE_WEIGHTS = {runLog: 3,loopMdBudget: 2,budgetSkill: 2,+ constraintsFile: 4,+ constraintsSkill: 2,loopActivity: 6,};const LEVEL_THRESHOLDS = {@@ -48,7 +50,7 @@ const LOOP_SKILL_NAMES = ['dependency-triage','rebase-and-clean','changelog-scan',- 'draft-release-notes',+ 'loop-constraints','issue-triage',];const SAFETY_FILES = ['safety.md', 'docs/safety.md', 'SECURITY.md'];@@ -209,6 +211,10 @@ export function computeScore(signals) {score += w.loopMdBudget;if (signals.cost.budgetSkill)score += w.budgetSkill;+ if (signals.constraints.present)+ score += w.constraintsFile;+ if (signals.constraints.hasConstraintsSkill)+ score += w.constraintsSkill;if (signals.loopActivity.present)score += w.loopActivity;score = Math.min(100, Math.max(0, score));@@ -322,6 +328,20 @@ export async function auditProject(target) {}}const loopActivity = await detectLoopActivity(root);+ const constraintsFile = await fileExists(path.join(root, 'loop-constraints.md'));+ const constraintsSkillDirs = [+ path.join(root, 'skills', 'loop-constraints'),+ path.join(root, '.grok', 'skills', 'loop-constraints'),+ path.join(root, '.claude', 'skills', 'loop-constraints'),+ path.join(root, '.codex', 'skills', 'loop-constraints'),+ ];+ let constraintsSkill = false;+ for (const dir of constraintsSkillDirs) {+ if (await fileExists(path.join(dir, 'SKILL.md'))) {+ constraintsSkill = true;+ break;+ }+ }const signals = {stateFile: { present: statePaths.length > 0, paths: statePaths },loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },@@ -334,6 +354,7 @@ export async function auditProject(target) {starters: { used: loopSkills.includes('loop-triage') },github: { present: githubDir, workflows: hasWorkflows },mcp: { present: mcpPresent },+ constraints: { present: constraintsFile, hasConstraintsSkill: constraintsSkill },worktreeEvidence: { present: worktreeEvidence },registry: { present: registryPresent },cost: { budgetDoc, runLog, loopMdBudget, budgetSkill },@@ -379,6 +400,17 @@ export async function auditProject(target) {else {findings.push({ level: 'ok', message: 'Safety documentation present.' });}+ if (!signals.constraints.present) {+ findings.push({ level: 'warn', message: 'No loop-constraints.md — structured constraints file missing.' });+ recommendations.push('Create loop-constraints.md with denylist paths, push/merge rules, and human gates (see templates/loop-constraints.md)');+ }+ else {+ findings.push({ level: 'ok', message: 'loop-constraints.md present.' });+ }+ if (signals.constraints.present && !signals.constraints.hasConstraintsSkill) {+ findings.push({ level: 'warn', message: 'loop-constraints.md exists but no loop-constraints skill — rules not enforced at runtime.' });+ recommendations.push('Add loop-constraints skill via loop-init or templates/SKILL.md.loop-constraints');+ }if (!signals.github.present) {findings.push({ level: 'warn', message: 'No .github/ directory (templates, workflows for dogfooding).' });recommendations.push('Add .github/ISSUE_TEMPLATE, PULL_REQUEST_TEMPLATE, and workflows (see this repo for examples)');diff --git a/tools/loop-audit/src/auditor.ts b/tools/loop-audit/src/auditor.tsindex e908bb0..ffc1eb0 100644--- a/tools/loop-audit/src/auditor.ts+++ b/tools/loop-audit/src/auditor.ts@@ -22,6 +22,7 @@ export interface LoopSignals {loopMdBudget: boolean;budgetSkill: boolean;};+ constraints: { present: boolean; hasConstraintsSkill: boolean };loopActivity: { present: boolean; evidence: string[] };}@@ -71,6 +72,8 @@ const SCORE_WEIGHTS = {runLog: 3,loopMdBudget: 2,budgetSkill: 2,+ constraintsFile: 4,+ constraintsSkill: 2,loopActivity: 6,} as const;@@ -90,7 +93,7 @@ const LOOP_SKILL_NAMES = ['dependency-triage','rebase-and-clean','changelog-scan',- 'draft-release-notes',+ 'loop-constraints','issue-triage',];@@ -235,6 +238,8 @@ export function computeScore(signals: LoopSignals): { score: number; level: 'L0'if (signals.cost.runLog) score += w.runLog;if (signals.cost.loopMdBudget) score += w.loopMdBudget;if (signals.cost.budgetSkill) score += w.budgetSkill;+ if (signals.constraints.present) score += w.constraintsFile;+ if (signals.constraints.hasConstraintsSkill) score += w.constraintsSkill;if (signals.loopActivity.present) score += w.loopActivity;score = Math.min(100, Math.max(0, score));@@ -281,7 +286,6 @@ export async function auditProject(target: string): Promise<AuditResult> {const loopMd = await fileExists(path.join(root, 'LOOP.md'));const agentsMd = await fileExists(path.join(root, 'AGENTS.md')) ||await fileExists(path.join(root, 'CLAUDE.md'));-const skillNames = await findSkills(root);const loopSkills = skillNames.filter((s) => LOOP_SKILL_NAMES.includes(s));@@ -357,6 +361,21 @@ export async function auditProject(target: string): Promise<AuditResult> {const loopActivity = await detectLoopActivity(root);+ const constraintsFile = await fileExists(path.join(root, 'loop-constraints.md'));+ const constraintsSkillDirs = [+ path.join(root, 'skills', 'loop-constraints'),+ path.join(root, '.grok', 'skills', 'loop-constraints'),+ path.join(root, '.claude', 'skills', 'loop-constraints'),+ path.join(root, '.codex', 'skills', 'loop-constraints'),+ ];+ let constraintsSkill = false;+ for (const dir of constraintsSkillDirs) {+ if (await fileExists(path.join(dir, 'SKILL.md'))) {+ constraintsSkill = true;+ break;+ }+ }+const signals: LoopSignals = {stateFile: { present: statePaths.length > 0, paths: statePaths },loopConfig: { present: loopMd, path: loopMd ? 'LOOP.md' : undefined },@@ -369,6 +388,7 @@ export async function auditProject(target: string): Promise<AuditResult> {starters: { used: loopSkills.includes('loop-triage') },github: { present: githubDir, workflows: hasWorkflows },mcp: { present: mcpPresent },+ constraints: { present: constraintsFile, hasConstraintsSkill: constraintsSkill },worktreeEvidence: { present: worktreeEvidence },registry: { present: registryPresent },cost: { budgetDoc, runLog, loopMdBudget, budgetSkill },@@ -418,6 +438,18 @@ export async function auditProject(target: string): Promise<AuditResult> {findings.push({ level: 'ok', message: 'Safety documentation present.' });}++ if (!signals.constraints.present) {+ findings.push({ level: 'warn', message: 'No loop-constraints.md — structured constraints file missing.' });+ recommendations.push('Create loop-constraints.md with denylist paths, push/merge rules, and human gates (see templates/loop-constraints.md)');+ } else {+ findings.push({ level: 'ok', message: 'loop-constraints.md present.' });+ }++ if (signals.constraints.present && !signals.constraints.hasConstraintsSkill) {+ findings.push({ level: 'warn', message: 'loop-constraints.md exists but no loop-constraints skill — rules not enforced at runtime.' });+ recommendations.push('Add loop-constraints skill via loop-init or templates/SKILL.md.loop-constraints');+ }if (!signals.github.present) {findings.push({ level: 'warn', message: 'No .github/ directory (templates, workflows for dogfooding).' });recommendations.push('Add .github/ISSUE_TEMPLATE, PULL_REQUEST_TEMPLATE, and workflows (see this repo for examples)');diff --git a/tools/loop-audit/test/auditor.test.mjs b/tools/loop-audit/test/auditor.test.mjsindex 023050b..bfed8e7 100644--- a/tools/loop-audit/test/auditor.test.mjs+++ b/tools/loop-audit/test/auditor.test.mjs@@ -22,6 +22,7 @@ function emptySignals() {mcp: { present: false },worktreeEvidence: { present: false },registry: { present: false },+ constraints: { present: false, hasConstraintsSkill: false },cost: { budgetDoc: false, runLog: false, loopMdBudget: false, budgetSkill: false },loopActivity: { present: false, evidence: [] },};diff --git a/tools/loop-init/dist/cli.js b/tools/loop-init/dist/cli.jsindex a20b019..08abe35 100644--- a/tools/loop-init/dist/cli.js+++ b/tools/loop-init/dist/cli.js@@ -194,6 +194,14 @@ async function scaffoldObservability(pattern, tool, targetDir, templatesRoot, dr}await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-budget', targetDir, tool, 'loop-budget', dryRun);}+async function scaffoldConstraints(targetDir, templatesRoot, tool, dryRun) {+ const constraintsPath = path.join(targetDir, 'loop-constraints.md');+ const constraintsTemplate = path.join(templatesRoot, 'loop-constraints.md');+ if (!(await exists(constraintsPath)) && (await exists(constraintsTemplate))) {+ await copyFile(constraintsTemplate, constraintsPath, dryRun);+ }+ await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-constraints', targetDir, tool, 'loop-constraints', dryRun);+}async function copyFile(src, dest, dryRun) {if (!(await exists(src)))return false;@@ -352,6 +360,7 @@ Examples:}await copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun);await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);+ await scaffoldConstraints(targetDir, templatesRoot, tool, dryRun);if (!dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {const agentsTemplate = `# AGENTS.mddiff --git a/tools/loop-init/src/cli.ts b/tools/loop-init/src/cli.tsindex 31f6ec3..301147c 100644--- a/tools/loop-init/src/cli.ts+++ b/tools/loop-init/src/cli.ts@@ -245,6 +245,22 @@ async function scaffoldObservability(await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-budget', targetDir, tool, 'loop-budget', dryRun);}+async function scaffoldConstraints(+ targetDir: string,+ templatesRoot: string,+ tool: Tool,+ dryRun: boolean,+) {+ const constraintsPath = path.join(targetDir, 'loop-constraints.md');+ const constraintsTemplate = path.join(templatesRoot, 'loop-constraints.md');++ if (!(await exists(constraintsPath)) && (await exists(constraintsTemplate))) {+ await copyFile(constraintsTemplate, constraintsPath, dryRun);+ }++ await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-constraints', targetDir, tool, 'loop-constraints', dryRun);+}+async function copyFile(src: string, dest: string, dryRun: boolean) {if (!(await exists(src))) return false;if (dryRun) {@@ -420,6 +436,7 @@ Examples:await copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun);await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);+ await scaffoldConstraints(targetDir, templatesRoot, tool, dryRun);if (!dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {const agentsTemplate = `# AGENTS.md