@cobusgreyling/loop-init 1.1.0 → 1.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 Scaffold loop engineering starters into your project by pattern and tool.
 
+**npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok** works immediately.
+
 ## Install & Run
 
 ```bash
@@ -12,6 +14,8 @@ npx @cobusgreyling/loop-init . -p dependency-sweeper --dry-run
 
 See [docs/RELEASE.md](../../docs/RELEASE.md) for npm publish tags. The published package bundles `starters/` and `templates/` from this monorepo.
 
+After scaffolding, always run `npx @cobusgreyling/loop-audit . --suggest` and actually execute the first report-only loop to generate activity signals.
+
 ## Patterns
 
 | Pattern | Default state file |
@@ -25,6 +29,12 @@ See [docs/RELEASE.md](../../docs/RELEASE.md) for npm publish tags. The published
 
 L2 patterns (`ci-sweeper`, `dependency-sweeper`) also copy `minimal-fix` and `loop-verifier` templates when missing from the starter.
 
+Every scaffold also creates:
+
+- `loop-budget.md` — pattern-specific daily caps and kill switch
+- `loop-run-log.md` — append-only run history
+- `loop-budget` skill — runtime budget guard at start/end of each run
+
 ## Tools
 
 - `grok` (default)
@@ -40,8 +50,9 @@ cd tools/loop-init && npm ci && npm test
 node dist/cli.js /path/to/project --pattern daily-triage --tool grok
 ```
 
-Pair with `loop-audit` after scaffolding:
+Pair with `loop-audit` and `loop-cost` after scaffolding:
 
 ```bash
+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1
 npx @cobusgreyling/loop-audit . --suggest
 ```

package/dist/cli.js

@@ -13,6 +13,7 @@ const PATTERN_STARTERS = {
     'dependency-sweeper': 'dependency-sweeper',
     'post-merge-cleanup': 'post-merge-cleanup',
     'changelog-drafter': 'changelog-drafter',
+    'issue-triage': 'minimal-loop', // reuses daily-triage starter + new skill can be added manually or via templates later
 };
 const TOOL_SUFFIX = {
     grok: '',
@@ -33,6 +34,17 @@ const STATE_FILES = {
     'dependency-sweeper': 'dependency-sweeper-state.md',
     'post-merge-cleanup': 'post-merge-state.md',
     'changelog-drafter': 'changelog-drafter-state.md',
+    'issue-triage': 'issue-triage-state.md',
+};
+/** Mirrors patterns/registry.yaml cost caps — used when scaffolding observability files. */
+const PATTERN_BUDGET = {
+    'daily-triage': { name: 'Daily Triage', maxRunsPerDay: 2, dailyCap: 100_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },
+    'pr-babysitter': { name: 'PR Babysitter', maxRunsPerDay: 288, dailyCap: 2_000_000, maxSpawnsL1: 0, maxSpawnsL2: 3 },
+    'ci-sweeper': { name: 'CI Sweeper', maxRunsPerDay: 96, dailyCap: 1_000_000, maxSpawnsL1: 0, maxSpawnsL2: 3 },
+    'dependency-sweeper': { name: 'Dependency Sweeper', maxRunsPerDay: 4, dailyCap: 500_000, maxSpawnsL1: 0, maxSpawnsL2: 3 },
+    'post-merge-cleanup': { name: 'Post-Merge Cleanup', maxRunsPerDay: 1, dailyCap: 200_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },
+    'changelog-drafter': { name: 'Changelog Drafter', maxRunsPerDay: 1, dailyCap: 100_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },
+    'issue-triage': { name: 'Issue Triage', maxRunsPerDay: 12, dailyCap: 80_000, maxSpawnsL1: 0, maxSpawnsL2: 1 },
 };
 function parseArgs(argv) {
     let pattern = 'daily-triage';
@@ -126,6 +138,62 @@ async function copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun)
         await copyTemplateVerifier(templatesRoot, targetDir, tool, dryRun);
     }
 }
+function formatTokenCap(n) {
+    if (n >= 1_000_000)
+        return `${n / 1_000_000}M`;
+    if (n >= 1_000)
+        return `${n / 1_000}k`;
+    return String(n);
+}
+function buildLoopBudgetMd(pattern) {
+    const b = PATTERN_BUDGET[pattern];
+    return `# Loop Budget — YOUR_PROJECT
+
+> Primary loop: **${b.name}** (scaffolded by loop-init)
+
+## Daily limits
+
+| Loop | Max runs/day | Max tokens/day | Max sub-agent spawns/run |
+|------|--------------|----------------|--------------------------|
+| ${b.name} | ${b.maxRunsPerDay} | ${formatTokenCap(b.dailyCap)} | ${b.maxSpawnsL1} (L1) / ${b.maxSpawnsL2} (L2) |
+
+## On budget exceed
+
+1. Pause schedulers (\`scheduler_delete\` or disable automations)
+2. Append event to \`loop-run-log.md\`
+3. Notify human (Slack / issue / STATE.md High Priority)
+
+## Kill switch
+
+- Command or issue label: \`loop-pause-all\`
+- Resume only after human clears the flag in STATE.md
+
+## Estimate spend
+
+\`\`\`bash
+npx @cobusgreyling/loop-cost --pattern ${pattern}
+\`\`\`
+`;
+}
+async function scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun) {
+    const budgetPath = path.join(targetDir, 'loop-budget.md');
+    const runLogTemplate = path.join(templatesRoot, 'loop-run-log.md.template');
+    const runLogPath = path.join(targetDir, 'loop-run-log.md');
+    if (!(await exists(budgetPath))) {
+        const content = buildLoopBudgetMd(pattern);
+        if (dryRun) {
+            console.log(`  would write: ${budgetPath}`);
+        }
+        else {
+            await writeFile(budgetPath, content);
+            console.log(`  created: loop-budget.md`);
+        }
+    }
+    if (!(await exists(runLogPath))) {
+        await copyFile(runLogTemplate, runLogPath, dryRun);
+    }
+    await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-budget', targetDir, tool, 'loop-budget', dryRun);
+}
 async function copyFile(src, dest, dryRun) {
     if (!(await exists(src)))
         return false;
@@ -170,6 +238,11 @@ function firstLoopCommand(pattern, tool) {
             claude: '/loop 1d $changelog-scan + draft-release-notes — write RELEASE_NOTES_DRAFT.md and update state. Human approves before publish.',
             codex: 'Automation daily: changelog-scan + draft-release-notes → RELEASE_NOTES_DRAFT.md. Human review.',
         },
+        'issue-triage': {
+            grok: '/loop 2h Run issue-triage. Update issue-triage-state.md. Propose labels and priority only. No auto-apply. Human reviews the needs-human slice.',
+            claude: '/loop 2h $issue-triage — update issue-triage-state.md. Suggest labels on allowlisted areas only. Report mode week one.',
+            codex: 'Automation 2h: issue-triage → issue-triage-state.md. Propose only.',
+        },
     };
     return cmds[pattern][tool];
 }
@@ -188,6 +261,7 @@ Patterns:
   dependency-sweeper
   post-merge-cleanup
   changelog-drafter (new low-risk release notes pattern)
+  issue-triage (new low-risk issue queue health companion to daily triage)
 
 Options:
   -p, --pattern   Pattern to scaffold
@@ -267,6 +341,7 @@ Examples:
         await copyFile(loopMd, path.join(targetDir, 'LOOP.md'), dryRun);
     }
     await copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun);
+    await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);
     if (!dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {
         const agentsTemplate = `# AGENTS.md
 
@@ -283,6 +358,7 @@ npm run lint
     }
     console.log('\n=== Next steps ===');
     console.log(`  npx @cobusgreyling/loop-audit ${target === '.' ? '.' : target} --suggest`);
+    console.log(`  npx @cobusgreyling/loop-cost --pattern ${pattern}`);
     console.log(`  First loop command (${tool}):\n  ${firstLoopCommand(pattern, tool)}\n`);
 }
 async function readDirNames(dir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cobusgreyling/loop-init",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Scaffold loop engineering starters into your project by pattern and tool.",
   "type": "module",
   "bin": {
@@ -35,6 +35,10 @@
     "url": "git+https://github.com/cobusgreyling/loop-engineering.git",
     "directory": "tools/loop-init"
   },
+  "homepage": "https://cobusgreyling.github.io/loop-engineering/",
+  "bugs": {
+    "url": "https://github.com/cobusgreyling/loop-engineering/issues"
+  },
   "publishConfig": {
     "access": "public"
   },

package/starters/minimal-loop/LOOP.md

@@ -13,8 +13,11 @@
 
 ## Budget
 
-- Max sub-agent spawns per run: 0 (L1)
-- Review STATE.md daily
+- Max sub-agent spawns per run: 0 (L1) / 2 (L2)
+- Max tokens/day: 100k (see `loop-budget.md`)
+- Append each run to `loop-run-log.md`; use `loop-budget` skill at start/end
+- Kill switch: `loop-pause-all` — pause schedulers and notify human
+- Estimate: `npx @cobusgreyling/loop-cost --pattern daily-triage`
 
 ## Links
 

package/templates/SKILL.md.loop-budget

@@ -0,0 +1,40 @@
+---
+name: loop-budget
+description: Check token budget and run-log spend before and after a loop run. Enforces early exit when over budget or when there is no actionable work.
+---
+
+# Loop Budget Guard
+
+Run at the **start** and **end** of every loop iteration.
+
+## Start of run
+
+1. Read `loop-budget.md` for daily caps and kill-switch flags.
+2. Read recent entries in `loop-run-log.md` (last 24h).
+3. Sum `tokens_estimate` for the active pattern today.
+4. If spend ≥ 80% of the pattern's daily cap → **report-only mode** (no sub-agents, no auto-fix).
+5. If spend ≥ 100% or `loop-pause-all` is set → **exit immediately** with a one-line note in STATE.md.
+6. If watchlist/state has no actionable items → **exit in <5k tokens** (do not spawn sub-agents).
+
+## End of run
+
+Append one JSON object to `loop-run-log.md`:
+
+```json
+{
+  "run_id": "<ISO8601>",
+  "pattern": "<pattern-id>",
+  "duration_s": <number>,
+  "items_found": <number>,
+  "actions_taken": <number>,
+  "escalations": <number>,
+  "tokens_estimate": <number>,
+  "outcome": "no-op | report-only | fix-proposed | escalated"
+}
+```
+
+## Rules
+
+- Never exceed `max sub-agent spawns/run` from `loop-budget.md`.
+- High-cadence patterns (CI Sweeper, PR Babysitter) **must** early-exit when nothing is actionable.
+- On self-throttle, append a line to `loop-budget.md` under **Alerts This Period**.