Skip to content

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.

feat: trust fixes and adoption tooling (priority 1 + 2) (#65)

Cobus Greyling61a85e22d8bf
diff --git a/.github/ISSUE_TEMPLATE/add-adopter.yml b/.github/ISSUE_TEMPLATE/add-adopter.yml
new file mode 100644
index 0000000..9377178
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/add-adopter.yml
@@ -0,0 +1,72 @@
+name: Add my project to Adopters
+description: List your loop setup on the showcase and docs/adopters.md
+title: "Adopter: "
+labels:
+ - docs
+body:
+ - type: markdown
+ value: |
+ Share how you run loops from this repo (or an adaptation). We'll add your project to [docs/adopters.md](https://github.com/cobusgreyling/loop-engineering/blob/main/docs/adopters.md) and the [showcase adopters wall](https://cobusgreyling.github.io/loop-engineering/#adopters).
+
+ **Optional:** paste your Loop Ready badge from `npx @cobusgreyling/loop-audit . --badge`.
+
+ - type: input
+ id: project
+ attributes:
+ label: Project
+ description: Repo URL or product name
+ placeholder: https://github.com/you/your-repo
+ validations:
+ required: true
+
+ - type: input
+ id: patterns
+ attributes:
+ label: Pattern(s)
+ description: e.g. Daily Triage + Issue Triage
+ placeholder: daily-triage, issue-triage
+ validations:
+ required: true
+
+ - type: dropdown
+ id: tool
+ attributes:
+ label: Primary tool
+ options:
+ - Grok
+ - Claude Code
+ - Codex
+ - Cursor
+ - Windsurf
+ - GitHub Actions
+ - Mixed
+ validations:
+ required: true
+
+ - type: dropdown
+ id: level
+ attributes:
+ label: Readiness level (honest)
+ options:
+ - L1
+ - L2
+ - L3
+ validations:
+ required: true
+
+ - type: textarea
+ id: notes
+ attributes:
+ label: One-line notes
+ description: What worked or what broke — failures welcome
+ placeholder: L1 daily triage for 2 weeks; killed CI sweeper after token spike
+ validations:
+ required: true
+
+ - type: textarea
+ id: badge
+ attributes:
+ label: Loop Ready badge (optional)
+ description: Output of `npx @cobusgreyling/loop-audit . --badge`
+ render: text
+ placeholder: "[![Loop Ready L2 (58/100)](...)](...)"
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 90fd442..6d22ef8 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -6,6 +6,9 @@ contact_links:
- name: "\ud83d\udc1b Report an issue with the docs site or showcase"
url: https://github.com/cobusgreyling/loop-engineering/issues/new?labels=docs
about: "Use the bug report template for the reference itself."
+ - name: "\ud83c\udf10 Add my project to Adopters"
+ url: https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml
+ about: "List your loop on the showcase adopters wall and docs/adopters.md."
labels:
- name: "pattern-request"
diff --git a/.github/workflows/audit.yml b/.github/workflows/audit.yml
index 3813b8e..1ea74f0 100644
--- a/.github/workflows/audit.yml
+++ b/.github/workflows/audit.yml
@@ -16,7 +16,7 @@ jobs:
audit:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- uses: actions/setup-node@v6
with:
diff --git a/.github/workflows/changelog-drafter.yml b/.github/workflows/changelog-drafter.yml
index c9350c4..c16b98d 100644
--- a/.github/workflows/changelog-drafter.yml
+++ b/.github/workflows/changelog-drafter.yml
@@ -13,7 +13,7 @@ jobs:
draft:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
with:
fetch-depth: 0
diff --git a/.github/workflows/daily-triage.yml b/.github/workflows/daily-triage.yml
index d0430f7..f553b7a 100644
--- a/.github/workflows/daily-triage.yml
+++ b/.github/workflows/daily-triage.yml
@@ -15,7 +15,7 @@ jobs:
triage:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- name: Record run start
id: timing
@@ -121,14 +121,27 @@ jobs:
node scripts/append-run-log.mjs "$ENTRY"
echo "outcome=${OUTCOME}" >> "$GITHUB_OUTPUT"
+ # These run the SAME gates a PR-triggered workflow would. Their outcomes
+ # (not a hardcoded value) drive the commit statuses posted below, so the
+ # loop cannot mark its own change green unless the real gates passed.
- name: Run validate gates (for PR status)
id: validate_gates
+ continue-on-error: true
run: bash scripts/ci-validate-gates.sh
- name: Run audit gates (for PR status)
id: audit_gates
+ continue-on-error: true
run: bash scripts/ci-audit-gates.sh
+ - name: Fail the run if either gate failed
+ if: steps.validate_gates.outcome == 'failure' || steps.audit_gates.outcome == 'failure'
+ run: |
+ echo "validate gates: ${{ steps.validate_gates.outcome }}"
+ echo "audit gates: ${{ steps.audit_gates.outcome }}"
+ echo "One or more dogfood gates failed — not opening/merging an automated PR."
+ exit 1
+
- name: Open PR for STATE.md + loop-run-log if changed
id: pr
env:
@@ -186,16 +199,25 @@ jobs:
core.setFailed('Missing head_sha for commit statuses');
return;
}
+ const toState = (outcome) => (outcome === 'success' ? 'success' : 'failure');
const checks = [
- { context: 'validate', description: 'Pattern/registry gates (daily-triage inline)' },
- { context: 'audit', description: 'Loop readiness gates (daily-triage inline)' },
+ {
+ context: 'validate',
+ description: 'Pattern/registry gates (daily-triage inline)',
+ state: toState('${{ steps.validate_gates.outcome }}'),
+ },
+ {
+ context: 'audit',
+ description: 'Loop readiness gates (daily-triage inline)',
+ state: toState('${{ steps.audit_gates.outcome }}'),
+ },
];
for (const check of checks) {
await github.rest.repos.createCommitStatus({
owner: context.repo.owner,
repo: context.repo.repo,
sha,
- state: 'success',
+ state: check.state,
context: check.context,
description: check.description,
target_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
diff --git a/.github/workflows/publish-goal-audit-bootstrap.yml b/.github/workflows/publish-goal-audit-bootstrap.yml
index e393884..4b044fc 100644
--- a/.github/workflows/publish-goal-audit-bootstrap.yml
+++ b/.github/workflows/publish-goal-audit-bootstrap.yml
@@ -15,7 +15,7 @@ jobs:
publish:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
with:
repository: cobusgreyling/goal-engineering
ref: main
diff --git a/.github/workflows/release-goal-audit.yml b/.github/workflows/release-goal-audit.yml
index 9585b44..9bd1dc2 100644
--- a/.github/workflows/release-goal-audit.yml
+++ b/.github/workflows/release-goal-audit.yml
@@ -13,7 +13,7 @@ jobs:
test-and-publish:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- uses: actions/setup-node@v6
with:
diff --git a/.github/workflows/release-loop-audit.yml b/.github/workflows/release-loop-audit.yml
index da7f27c..efb2c8d 100644
--- a/.github/workflows/release-loop-audit.yml
+++ b/.github/workflows/release-loop-audit.yml
@@ -13,7 +13,7 @@ jobs:
test-and-publish:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- uses: actions/setup-node@v6
with:
diff --git a/.github/workflows/release-loop-cost.yml b/.github/workflows/release-loop-cost.yml
index 5e5c66d..d0a11c5 100644
--- a/.github/workflows/release-loop-cost.yml
+++ b/.github/workflows/release-loop-cost.yml
@@ -13,7 +13,7 @@ jobs:
test-and-publish:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- uses: actions/setup-node@v6
with:
diff --git a/.github/workflows/release-loop-init.yml b/.github/workflows/release-loop-init.yml
index 606065b..5cf5fe6 100644
--- a/.github/workflows/release-loop-init.yml
+++ b/.github/workflows/release-loop-init.yml
@@ -13,7 +13,7 @@ jobs:
publish:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- uses: actions/setup-node@v6
with:
diff --git a/.github/workflows/validate-patterns.yml b/.github/workflows/validate-patterns.yml
index ca0c68e..4e66670 100644
--- a/.github/workflows/validate-patterns.yml
+++ b/.github/workflows/validate-patterns.yml
@@ -10,7 +10,7 @@ jobs:
validate:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- uses: actions/setup-node@v6
with:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b5d1199..0c6ab30 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -53,7 +53,8 @@ Also add an entry to `patterns/registry.yaml`.
## Community
- **Questions**: [GitHub Discussions](https://github.com/cobusgreyling/loop-engineering/discussions) (preferred) or issue with label `question`
-- **Show your loop**: post in Discussions or add a row to [docs/adopters.md](./docs/adopters.md)
+- **Show your loop**: [Add Adopter issue](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml), Discussions, or a row in [docs/adopters.md](./docs/adopters.md)
+- **Loop Ready badge**: `npx @cobusgreyling/loop-audit . --badge` — paste into your README
- **Good first issues**: look for label [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
- **Security**: see [SECURITY.md](./SECURITY.md) — do not file public issues for exploitable vulnerabilities
diff --git a/README.md b/README.md
index 7889208..7adca20 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,7 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with
| [Loop Design Checklist](docs/loop-design-checklist.md) | Ship readiness rubric |
| [Patterns](patterns/README.md) | 7 production patterns + [interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) |
| [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex) |
-| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.4 + activity detection) — `npx @cobusgreyling/loop-audit . --suggest` |
+| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.4 + activity detection) — `npx @cobusgreyling/loop-audit . --suggest` · `--badge` for README |
| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log (v1.2) — `npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok` |
| [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |
| [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | Companion: Grok Build `/goal` — run-until-done objectives (`npx @cobusgreyling/goal-audit`) |
@@ -148,6 +148,9 @@ npx @cobusgreyling/loop-cost --pattern daily-triage --level L1
# 3. Audit readiness (budget + run-log now scored)
npx @cobusgreyling/loop-audit . --suggest
+# Optional: paste Loop Ready badge into your README
+npx @cobusgreyling/loop-audit . --badge
+
# 4. See scores climb: empty → L1 → L2
bash scripts/before-after-demo.sh
diff --git a/docs/adopters.md b/docs/adopters.md
index a293c3f..380aa0a 100644
--- a/docs/adopters.md
+++ b/docs/adopters.md
@@ -2,9 +2,21 @@
Forks and stars mean people are trying this in their own stacks. If you run a loop from this repo (or adapted from it), add yourself here via PR.
+## Loop Ready badge
+
+Show your readiness level in your README:
+
+```bash
+npx @cobusgreyling/loop-audit . --badge
+```
+
+Paste the markdown output into your README. Re-run after you graduate L1 → L2 → L3.
+
## How to list your project
-Open a PR that adds a row to the table below:
+**Fast path:** [open the Add Adopter issue](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) — we'll add your row.
+
+Or open a PR that adds a row to the table below:
| Field | What to include |
|-------|-----------------|
diff --git a/docs/assets/css/showcase.css b/docs/assets/css/showcase.css
index 5ba09a6..d122118 100644
--- a/docs/assets/css/showcase.css
+++ b/docs/assets/css/showcase.css
@@ -712,4 +712,81 @@ section {
margin-left: 8px;
}
-.copy-btn:hover { background: rgba(62,232,197,0.2); }
\ No newline at end of file
+.copy-btn:hover { background: rgba(62,232,197,0.2); }
+
+/* Adopters */
+.adopters-cta {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 24px;
+ flex-wrap: wrap;
+ padding: 24px 28px;
+ background: var(--bg-elevated);
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ margin-bottom: 28px;
+}
+
+.adopters-cta h3 {
+ font-size: 1.1rem;
+ margin-bottom: 8px;
+}
+
+.adopters-cta p {
+ color: var(--text-muted);
+ font-size: 0.9rem;
+ margin-bottom: 10px;
+}
+
+.inline-cmd {
+ display: inline-block;
+ font-family: var(--font-mono);
+ font-size: 0.8rem;
+ background: var(--bg-card);
+ padding: 6px 10px;
+ border-radius: 6px;
+ border: 1px solid var(--border);
+}
+
+.adopters-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+ gap: 16px;
+}
+
+.adopter-card {
+ padding: 20px;
+ background: var(--bg-elevated);
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+}
+
+.adopter-card h4 {
+ font-size: 1rem;
+ margin-bottom: 8px;
+}
+
+.adopter-meta {
+ font-size: 0.8rem;
+ color: var(--accent-2);
+ margin-bottom: 10px;
+}
+
+.adopter-note {
+ font-size: 0.85rem;
+ color: var(--text-muted);
+ line-height: 1.5;
+}
+
+.adopter-placeholder {
+ border-style: dashed;
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+}
+
+.adopter-placeholder .btn {
+ align-self: flex-start;
+ margin-top: 4px;
+}
\ No newline at end of file
diff --git a/docs/index.html b/docs/index.html
index da437e6..52eb1af 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -37,6 +37,7 @@ title: Loop Engineering — Showcase
<li><a href="#primitives">Primitives</a></li>
<li><a href="#interactive">Picker</a></li>
<li><a href="#start">Get Started</a></li>
+ <li><a href="#adopters">Adopters</a></li>
<li><a href="https://cobusgreyling.substack.com/p/loop-engineering">Essay</a></li>
<li><a href="https://github.com/cobusgreyling/loop-engineering">GitHub</a></li>
</ul>
@@ -430,6 +431,49 @@ npx @cobusgreyling/loop-audit . --suggest
</div>
</div>
+<section id="adopters" class="wrap">
+ <p class="section-label">Community</p>
+ <h2 class="section-title">Adopters</h2>
+ <p class="section-desc">
+ Forks mean people are trying this. Listed projects run (or adapted) loops from this reference.
+ Add yours via the <a href="https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml">Add Adopter issue</a>
+ or a PR to <code>docs/adopters.md</code>.
+ </p>
+
+ <div class="adopters-cta card">
+ <div>
+ <h3>Show your Loop Ready score</h3>
+ <p>Paste a badge in your README after <code>loop-audit</code> — social proof for your team and contributors.</p>
+ <code class="inline-cmd">npx @cobusgreyling/loop-audit . --badge</code>
+ </div>
+ <a href="https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml" class="btn btn-primary">Add my project →</a>
+ </div>
+
+ <div class="adopters-grid">
+ <article class="adopter-card card">
+ <h4><a href="https://github.com/cobusgreyling/loop-engineering">loop-engineering</a></h4>
+ <p class="adopter-meta">Daily Triage · Changelog Drafter · audit dogfood · <strong>L3</strong></p>
+ <p class="adopter-note">Reference implementation — loop-audit on every PR; readiness score 100.</p>
+ </article>
+ <article class="adopter-card card">
+ <h4><a href="https://github.com/cobusgreyling/loop-engineering">loop-engineering (maintainer)</a></h4>
+ <p class="adopter-meta">Post-Merge Cleanup · Grok + Actions · <strong>L1→L2</strong></p>
+ <p class="adopter-note">Off-peak scan; verifier caught doc/API drift.</p>
+ </article>
+ <article class="adopter-card card">
+ <h4><a href="https://github.com/cobusgreyling/loop-engineering">loop-engineering (maintainer)</a></h4>
+ <p class="adopter-meta">Issue Triage + Daily Triage · Grok · <strong>L1</strong></p>
+ <p class="adopter-note">Propose labels only week one; pairs with morning STATE.md triage.</p>
+ </article>
+ <article class="adopter-card card adopter-placeholder">
+ <h4>Your project here</h4>
+ <p class="adopter-meta">Pattern · Tool · Level</p>
+ <p class="adopter-note">One line on what worked or broke — failures are first-class.</p>
+ <a href="https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml" class="btn btn-ghost">List yours →</a>
+ </article>
+ </div>
+</section>
+
<footer class="footer">
<p>
<a href="https://github.com/cobusgreyling/loop-engineering">GitHub</a>
@@ -521,7 +565,7 @@ const PATTERNS = {
npx: 'npx @cobusgreyling/loop-init . --pattern issue-triage --tool grok',
loop: '/loop 1d Run issue-triage. Update issue-triage-state.md. Propose labels and priorities only — no auto-close.',
patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/issue-triage.md',
- starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/minimal-loop'
+ starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/issue-triage'
}
};
diff --git a/examples/github-actions/changelog-drafter.yml b/examples/github-actions/changelog-drafter.yml
index 04ac5bd..eb220e3 100644
--- a/examples/github-actions/changelog-drafter.yml
+++ b/examples/github-actions/changelog-drafter.yml
@@ -11,7 +11,7 @@ jobs:
draft:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
with:
fetch-depth: 0
diff --git a/examples/github-actions/ci-sweeper.yml b/examples/github-actions/ci-sweeper.yml
index d06b2dd..8744422 100644
--- a/examples/github-actions/ci-sweeper.yml
+++ b/examples/github-actions/ci-sweeper.yml
@@ -18,7 +18,7 @@ jobs:
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- name: Record failure context
run: |
diff --git a/examples/github-actions/daily-triage.yml b/examples/github-actions/daily-triage.yml
index 1300b03..c42e141 100644
--- a/examples/github-actions/daily-triage.yml
+++ b/examples/github-actions/daily-triage.yml
@@ -19,7 +19,7 @@ jobs:
triage:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- name: Gather CI context
id: ci
diff --git a/examples/github-actions/dependency-sweeper.yml b/examples/github-actions/dependency-sweeper.yml
index 316e1da..95a42c9 100644
--- a/examples/github-actions/dependency-sweeper.yml
+++ b/examples/github-actions/dependency-sweeper.yml
@@ -12,7 +12,7 @@ jobs:
sweep:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- uses: actions/setup-node@v6
with:
diff --git a/examples/github-actions/issue-triage.yml b/examples/github-actions/issue-triage.yml
index 613f8e7..7f7194d 100644
--- a/examples/github-actions/issue-triage.yml
+++ b/examples/github-actions/issue-triage.yml
@@ -20,7 +20,7 @@ jobs:
triage:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- name: Gather issue context
id: issues
diff --git a/examples/github-actions/post-merge-cleanup.yml b/examples/github-actions/post-merge-cleanup.yml
index 72a6653..1aee06a 100644
--- a/examples/github-actions/post-merge-cleanup.yml
+++ b/examples/github-actions/post-merge-cleanup.yml
@@ -16,7 +16,7 @@ jobs:
cleanup-scan:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
with:
fetch-depth: 50
diff --git a/examples/github-actions/pr-babysitter.yml b/examples/github-actions/pr-babysitter.yml
index d765022..f158850 100644
--- a/examples/github-actions/pr-babysitter.yml
+++ b/examples/github-actions/pr-babysitter.yml
@@ -14,7 +14,7 @@ jobs:
babysit:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v6
+ - uses: actions/checkout@v7
- name: Placeholder — wire to your agent runtime
run: |
diff --git a/patterns/registry.yaml b/patterns/registry.yaml
index 072c202..89f7aa4 100644
--- a/patterns/registry.yaml
+++ b/patterns/registry.yaml
@@ -139,7 +139,7 @@ patterns:
state: issue-triage-state.md
phases: [discover, dedupe, score, propose-labels, human-review]
human_gates: [security, p0-p1, ambiguous-duplicates, stale-closures]
- starter: starters/minimal-loop
+ starter: starters/issue-triage
week_one_mode: L1
token_cost: low
cost:
diff --git a/tools/loop-audit/README.md b/tools/loop-audit/README.md
index ff13e11..a198c9a 100644
--- a/tools/loop-audit/README.md
+++ b/tools/loop-audit/README.md
@@ -37,6 +37,7 @@ loop-audit . # human-readable (default)
loop-audit . --json # machine-readable
loop-audit . --md # markdown report
loop-audit . --suggest # copy-from-template commands + activity tips (all tools)
+loop-audit . --badge # markdown README badge (Loop Ready level + score)
```
Exit code `2` if score < 40 (useful for CI gates once your project is loop-ready).
diff --git a/tools/loop-audit/dist/auditor.js b/tools/loop-audit/dist/auditor.js
index 3cb57b6..5a4ce00 100644
--- a/tools/loop-audit/dist/auditor.js
+++ b/tools/loop-audit/dist/auditor.js
@@ -10,6 +10,34 @@ const STATE_FILES = [
'changelog-drafter-state.md',
'issue-triage-state.md',
];
+/** Score contribution for each readiness signal (see computeScore). */
+const SCORE_WEIGHTS = {
+ base: 10,
+ stateFile: 18,
+ triage: 14,
+ loopConfig: 9,
+ agentsMd: 9,
+ skillsTwoPlus: 14,
+ skillsOne: 7,
+ verifier: 14,
+ safetyLoopMd: 4,
+ safetyDoc: 4,
+ github: 6,
+ githubWorkflows: 4,
+ mcp: 3,
+ worktree: 3,
+ registry: 2,
+ budgetDoc: 3,
+ runLog: 3,
+ loopMdBudget: 2,
+ budgetSkill: 2,
+ loopActivity: 6,
+};
+const LEVEL_THRESHOLDS = {
+ L1: 38,
+ L2: 58,
+ L3: 78,
+};
const LOOP_SKILL_NAMES = [
'loop-triage',
'minimal-fix',
@@ -122,7 +150,7 @@ async function detectLoopActivity(root) {
timeout: 1500,
});
const lower = log.toLowerCase();
- if (/state\.md|loop| t riage |changelog-drafter|post-merge|daily triage|audit/i.test(lower)) {
+ if (/state\.md|loop|triage|changelog-drafter|post-merge|daily triage|audit/i.test(lower)) {
const firstMatch = log.trim().split('\n')[0] || '';
evidence.push(`git:${firstMatch.slice(0, 60)}`);
}
@@ -143,45 +171,46 @@ async function detectLoopActivity(root) {
return { present: evidence.length > 0, evidence: Array.from(new Set(evidence)).slice(0, 4) };
}
export function computeScore(signals) {
- let score = 10;
+ const w = SCORE_WEIGHTS;
+ let score = w.base;
if (signals.stateFile.present)
- score += 18;
+ score += w.stateFile;
if (signals.triage.present)
- score += 14;
+ score += w.triage;
if (signals.loopConfig.present)
- score += 9;
+ score += w.loopConfig;
if (signals.agentsMd.present)
- score += 9;
+ score += w.agentsMd;
if (signals.skills.count >= 2)
- score += 14;
+ score += w.skillsTwoPlus;
else if (signals.skills.count === 1)
- score += 7;
+ score += w.skillsOne;
if (signals.verifier.present)
- score += 14;
+ score += w.verifier;
if (signals.safety.loopMdMentionsSafety)
- score += 4;
+ score += w.safetyLoopMd;
if (signals.safety.safetyDocPresent)
- score += 4;
+ score += w.safetyDoc;
if (signals.github.present)
- score += 6;
+ score += w.github;
if (signals.github.workflows)
- score += 4;
+ score += w.githubWorkflows;
if (signals.mcp.present)
- score += 3;
+ score += w.mcp;
if (signals.worktreeEvidence.present)
- score += 3;
+ score += w.worktree;
if (signals.registry.present)
- score += 2;
+ score += w.registry;
if (signals.cost.budgetDoc)
- score += 3;
+ score += w.budgetDoc;
if (signals.cost.runLog)
- score += 3;
+ score += w.runLog;
if (signals.cost.loopMdBudget)
- score += 2;
+ score += w.loopMdBudget;
if (signals.cost.budgetSkill)
- score += 2;
+ score += w.budgetSkill;
if (signals.loopActivity.present)
- score += 6;
+ score += w.loopActivity;
score = Math.min(100, Math.max(0, score));
const costReady = signals.cost.budgetDoc &&
signals.cost.runLog &&
@@ -189,11 +218,11 @@ export function computeScore(signals) {
const hasRealActivity = signals.loopActivity.present;
const l3Ready = costReady && hasRealActivity;
let level = 'L0';
- if (score >= 78 && signals.verifier.present && signals.stateFile.present && l3Ready)
+ if (score >= LEVEL_THRESHOLDS.L3 && signals.verifier.present && signals.stateFile.present && l3Ready)
level = 'L3';
- else if (score >= 58 && signals.triage.present)
+ else if (score >= LEVEL_THRESHOLDS.L2 && signals.triage.present)
level = 'L2';
- else if (score >= 38 && signals.stateFile.present)
+ else if (score >= LEVEL_THRESHOLDS.L1 && signals.stateFile.present)
level = 'L1';
else
level = 'L0';
diff --git a/tools/loop-audit/dist/cli.js b/tools/loop-audit/dist/cli.js
index 6134c0b..58c54dd 100644
--- a/tools/loop-audit/dist/cli.js
+++ b/tools/loop-audit/dist/cli.js
@@ -1,11 +1,12 @@
#!/usr/bin/env node
import { auditProject } from './auditor.js';
-import { formatHuman, formatJson, formatMarkdown } from './reporter.js';
+import { formatBadge, formatHuman, formatJson, formatMarkdown } from './reporter.js';
const args = process.argv.slice(2);
const target = args.find((a) => !a.startsWith('-')) || '.';
const json = args.includes('--json');
const md = args.includes('--md');
const suggest = args.includes('--suggest') || args.includes('--fix');
+const badge = args.includes('--badge');
const help = args.includes('--help') || args.includes('-h');
if (help) {
console.log(`loop-audit — Loop Readiness Score CLI (v1.4+)
@@ -17,6 +18,7 @@ Options:
--json JSON output (for CI / scripting)
--md Markdown report
--suggest Show copy-from-template commands for missing pieces (recommended on first runs)
+ --badge Markdown README badge (Loop Ready level + score)
--help, -h This help
New in v1.4:
@@ -31,6 +33,7 @@ Exit codes:
Examples:
loop-audit .
loop-audit . --suggest
+ loop-audit . --badge >> README.md
npx @cobusgreyling/loop-audit . --json
npx @cobusgreyling/loop-audit starters/minimal-loop --suggest
bash scripts/before-after-demo.sh
@@ -39,7 +42,9 @@ Examples:
}
try {
const result = await auditProject(target);
- if (json)
+ if (badge)
+ console.log(formatBadge(result));
+ else if (json)
console.log(formatJson(result));
else if (md)
console.log(formatMarkdown(result));
diff --git a/tools/loop-audit/dist/reporter.d.ts b/tools/loop-audit/dist/reporter.d.ts
index 8bac4bb..9381720 100644
--- a/tools/loop-audit/dist/reporter.d.ts
+++ b/tools/loop-audit/dist/reporter.d.ts
@@ -1,4 +1,6 @@
import type { AuditResult } from './auditor.js';
+/** Markdown badge for README — paste output from `loop-audit . --badge`. */
+export declare function formatBadge(r: AuditResult): string;
export declare function formatHuman(r: AuditResult): string;
export declare function formatJson(r: AuditResult): string;
export declare function formatMarkdown(r: AuditResult): string;
diff --git a/tools/loop-audit/dist/reporter.js b/tools/loop-audit/dist/reporter.js
index b4eebef..5b5290f 100644
--- a/tools/loop-audit/dist/reporter.js
+++ b/tools/loop-audit/dist/reporter.js
@@ -1,3 +1,17 @@
+const LEVEL_BADGE_COLORS = {
+ L0: '6e7681',
+ L1: 'd29922',
+ L2: '58a6ff',
+ L3: '3ee8c5',
+};
+const SHOWCASE_URL = 'https://cobusgreyling.github.io/loop-engineering/';
+/** Markdown badge for README — paste output from `loop-audit . --badge`. */
+export function formatBadge(r) {
+ const color = LEVEL_BADGE_COLORS[r.level];
+ const label = encodeURIComponent(`${r.level} (${r.score}/100)`).replace(/%20/g, '_');
+ const badgeUrl = `https://img.shields.io/badge/Loop_Ready-${label}-${color}?style=flat-square`;
+ return `[![Loop Ready ${r.level} (${r.score}/100)](${badgeUrl})](${SHOWCASE_URL})`;
+}
export function formatHuman(r) {
const lines = [];
lines.push('');
diff --git a/tools/loop-audit/package-lock.json b/tools/loop-audit/package-lock.json
index 95ce089..fc87d57 100644
--- a/tools/loop-audit/package-lock.json
+++ b/tools/loop-audit/package-lock.json
@@ -1,38 +1,38 @@
{
- "name": "loop-audit",
- "version": "1.4.1",
+ "name": "@cobusgreyling/loop-audit",
+ "version": "1.4.2",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
- "name": "loop-audit",
- "version": "1.4.1",
+ "name": "@cobusgreyling/loop-audit",
+ "version": "1.4.2",
"license": "MIT",
"bin": {
"loop-audit": "dist/cli.js"
},
"devDependencies": {
- "@types/node": "^25.9.3",
- "typescript": "^5.0.0"
+ "@types/node": "^26.0.0",
+ "typescript": "^6.0.3"
},
"engines": {
"node": ">=18"
}
},
"node_modules/@types/node": {
- "version": "25.9.3",
- "resolved": "https://registry.npmjs.org/@types/node/-/node-25.9.3.tgz",
- "integrity": "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg==",
+ "version": "26.0.1",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-26.0.1.tgz",
+ "integrity": "sha512-fc3KiUoBt6kie0N9bIW3E47vZsuaMf0PM2AaUpLCLT0s/LvX1nxAim6Fc049cNxODPpGm6qRAuUOB86SkRuPQw==",
"dev": true,
"license": "MIT",
"dependencies": {
- "undici-types": ">=7.24.0 <7.24.7"
+ "undici-types": "~8.3.0"
}
},
"node_modules/typescript": {
- "version": "5.9.3",
- "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
- "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+ "version": "6.0.3",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
+ "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
"dev": true,
"license": "Apache-2.0",
"bin": {
@@ -44,9 +44,9 @@
}
},
"node_modules/undici-types": {
- "version": "7.24.6",
- "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
- "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
+ "version": "8.3.0",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz",
+ "integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==",
"dev": true,
"license": "MIT"
}
diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.json
index daf52f6..616b513 100644
--- a/tools/loop-audit/package.json
+++ b/tools/loop-audit/package.json
@@ -1,6 +1,6 @@
{
"name": "@cobusgreyling/loop-audit",
- "version": "1.4.1",
+ "version": "1.4.2",
"description": "Loop engineering readiness auditor. Compute Loop Readiness Score (L0-L3), detect activity, and get actionable suggestions. npx @cobusgreyling/loop-audit . --suggest",
"type": "module",
"bin": {
@@ -47,7 +47,7 @@
"access": "public"
},
"devDependencies": {
- "@types/node": "^25.9.3",
- "typescript": "^5.0.0"
+ "@types/node": "^26.0.0",
+ "typescript": "^6.0.3"
}
}
\ No newline at end of file
diff --git a/tools/loop-audit/src/auditor.ts b/tools/loop-audit/src/auditor.ts
index 52f178d..e908bb0 100644
--- a/tools/loop-audit/src/auditor.ts
+++ b/tools/loop-audit/src/auditor.ts
@@ -50,6 +50,36 @@ const STATE_FILES = [
'issue-triage-state.md',
];
+/** Score contribution for each readiness signal (see computeScore). */
+const SCORE_WEIGHTS = {
+ base: 10,
+ stateFile: 18,
+ triage: 14,
+ loopConfig: 9,
+ agentsMd: 9,
+ skillsTwoPlus: 14,
+ skillsOne: 7,
+ verifier: 14,
+ safetyLoopMd: 4,
+ safetyDoc: 4,
+ github: 6,
+ githubWorkflows: 4,
+ mcp: 3,
+ worktree: 3,
+ registry: 2,
+ budgetDoc: 3,
+ runLog: 3,
+ loopMdBudget: 2,
+ budgetSkill: 2,
+ loopActivity: 6,
+} as const;
+
+const LEVEL_THRESHOLDS = {
+ L1: 38,
+ L2: 58,
+ L3: 78,
+} as const;
+
const LOOP_SKILL_NAMES = [
'loop-triage',
'minimal-fix',
@@ -163,7 +193,7 @@ async function detectLoopActivity(root: string): Promise<{ present: boolean; evi
timeout: 1500,
});
const lower = log.toLowerCase();
- if (/state\.md|loop| t riage |changelog-drafter|post-merge|daily triage|audit/i.test(lower)) {
+ if (/state\.md|loop|triage|changelog-drafter|post-merge|daily triage|audit/i.test(lower)) {
const firstMatch = log.trim().split('\n')[0] || '';
evidence.push(`git:${firstMatch.slice(0, 60)}`);
}
@@ -184,27 +214,28 @@ async function detectLoopActivity(root: string): Promise<{ present: boolean; evi
}
export function computeScore(signals: LoopSignals): { score: number; level: 'L0' | 'L1' | 'L2' | 'L3'; assessment: string } {
- let score = 10;
-
- if (signals.stateFile.present) score += 18;
- if (signals.triage.present) score += 14;
- if (signals.loopConfig.present) score += 9;
- if (signals.agentsMd.present) score += 9;
- if (signals.skills.count >= 2) score += 14;
- else if (signals.skills.count === 1) score += 7;
- if (signals.verifier.present) score += 14;
- if (signals.safety.loopMdMentionsSafety) score += 4;
- if (signals.safety.safetyDocPresent) score += 4;
- if (signals.github.present) score += 6;
- if (signals.github.workflows) score += 4;
- if (signals.mcp.present) score += 3;
- if (signals.worktreeEvidence.present) score += 3;
- if (signals.registry.present) score += 2;
- if (signals.cost.budgetDoc) score += 3;
- if (signals.cost.runLog) score += 3;
- if (signals.cost.loopMdBudget) score += 2;
- if (signals.cost.budgetSkill) score += 2;
- if (signals.loopActivity.present) score += 6;
+ const w = SCORE_WEIGHTS;
+ let score: number = w.base;
+
+ if (signals.stateFile.present) score += w.stateFile;
+ if (signals.triage.present) score += w.triage;
+ if (signals.loopConfig.present) score += w.loopConfig;
+ if (signals.agentsMd.present) score += w.agentsMd;
+ if (signals.skills.count >= 2) score += w.skillsTwoPlus;
+ else if (signals.skills.count === 1) score += w.skillsOne;
+ if (signals.verifier.present) score += w.verifier;
+ if (signals.safety.loopMdMentionsSafety) score += w.safetyLoopMd;
+ if (signals.safety.safetyDocPresent) score += w.safetyDoc;
+ if (signals.github.present) score += w.github;
+ if (signals.github.workflows) score += w.githubWorkflows;
+ if (signals.mcp.present) score += w.mcp;
+ if (signals.worktreeEvidence.present) score += w.worktree;
+ if (signals.registry.present) score += w.registry;
+ if (signals.cost.budgetDoc) score += w.budgetDoc;
+ if (signals.cost.runLog) score += w.runLog;
+ if (signals.cost.loopMdBudget) score += w.loopMdBudget;
+ if (signals.cost.budgetSkill) score += w.budgetSkill;
+ if (signals.loopActivity.present) score += w.loopActivity;
score = Math.min(100, Math.max(0, score));
@@ -216,9 +247,9 @@ export function computeScore(signals: LoopSignals): { score: number; level: 'L0'
const l3Ready = costReady && hasRealActivity;
let level: 'L0' | 'L1' | 'L2' | 'L3' = 'L0';
- if (score >= 78 && signals.verifier.present && signals.stateFile.present && l3Ready) level = 'L3';
- else if (score >= 58 && signals.triage.present) level = 'L2';
- else if (score >= 38 && signals.stateFile.present) level = 'L1';
+ if (score >= LEVEL_THRESHOLDS.L3 && signals.verifier.present && signals.stateFile.present && l3Ready) level = 'L3';
+ else if (score >= LEVEL_THRESHOLDS.L2 && signals.triage.present) level = 'L2';
+ else if (score >= LEVEL_THRESHOLDS.L1 && signals.stateFile.present) level = 'L1';
else level = 'L0';
const assessment =
diff --git a/tools/loop-audit/src/cli.ts b/tools/loop-audit/src/cli.ts
index 0370df2..b99e5e5 100644
--- a/tools/loop-audit/src/cli.ts
+++ b/tools/loop-audit/src/cli.ts
@@ -1,12 +1,13 @@
#!/usr/bin/env node
import { auditProject } from './auditor.js';
-import { formatHuman, formatJson, formatMarkdown } from './reporter.js';
+import { formatBadge, formatHuman, formatJson, formatMarkdown } from './reporter.js';
const args = process.argv.slice(2);
const target = args.find((a) => !a.startsWith('-')) || '.';
const json = args.includes('--json');
const md = args.includes('--md');
const suggest = args.includes('--suggest') || args.includes('--fix');
+const badge = args.includes('--badge');
const help = args.includes('--help') || args.includes('-h');
if (help) {
@@ -19,6 +20,7 @@ Options:
--json JSON output (for CI / scripting)
--md Markdown report
--suggest Show copy-from-template commands for missing pieces (recommended on first runs)
+ --badge Markdown README badge (Loop Ready level + score)
--help, -h This help
New in v1.4:
@@ -33,6 +35,7 @@ Exit codes:
Examples:
loop-audit .
loop-audit . --suggest
+ loop-audit . --badge >> README.md
npx @cobusgreyling/loop-audit . --json
npx @cobusgreyling/loop-audit starters/minimal-loop --suggest
bash scripts/before-after-demo.sh
@@ -42,7 +45,8 @@ Examples:
try {
const result = await auditProject(target);
- if (json) console.log(formatJson(result));
+ if (badge) console.log(formatBadge(result));
+ else if (json) console.log(formatJson(result));
else if (md) console.log(formatMarkdown(result));
else console.log(formatHuman(result));
diff --git a/tools/loop-audit/src/reporter.ts b/tools/loop-audit/src/reporter.ts
index 6a9f6a0..314c260 100644
--- a/tools/loop-audit/src/reporter.ts
+++ b/tools/loop-audit/src/reporter.ts
@@ -1,5 +1,22 @@
import type { AuditResult } from './auditor.js';
+const LEVEL_BADGE_COLORS: Record<AuditResult['level'], string> = {
+ L0: '6e7681',
+ L1: 'd29922',
+ L2: '58a6ff',
+ L3: '3ee8c5',
+};
+
+const SHOWCASE_URL = 'https://cobusgreyling.github.io/loop-engineering/';
+
+/** Markdown badge for README — paste output from `loop-audit . --badge`. */
+export function formatBadge(r: AuditResult): string {
+ const color = LEVEL_BADGE_COLORS[r.level];
+ const label = encodeURIComponent(`${r.level} (${r.score}/100)`).replace(/%20/g, '_');
+ const badgeUrl = `https://img.shields.io/badge/Loop_Ready-${label}-${color}?style=flat-square`;
+ return `[![Loop Ready ${r.level} (${r.score}/100)](${badgeUrl})](${SHOWCASE_URL})`;
+}
+
export function formatHuman(r: AuditResult): string {
const lines: string[] = [];
lines.push('');
diff --git a/tools/loop-audit/test/auditor.test.mjs b/tools/loop-audit/test/auditor.test.mjs
index c20e5f7..023050b 100644
--- a/tools/loop-audit/test/auditor.test.mjs
+++ b/tools/loop-audit/test/auditor.test.mjs
@@ -3,7 +3,9 @@ import assert from 'node:assert/strict';
import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import path from 'node:path';
+import { execSync } from 'node:child_process';
import { auditProject, computeScore } from '../dist/auditor.js';
+import { formatBadge } from '../dist/reporter.js';
function emptySignals() {
return {
@@ -135,6 +137,38 @@ test('auditProject: minimal L1 layout', async () => {
}
});
+test('formatBadge: includes level and score', () => {
+ const badge = formatBadge({
+ target: '/tmp',
+ score: 72,
+ level: 'L2',
+ assessment: 'test',
+ signals: emptySignals(),
+ findings: [],
+ recommendations: [],
+ });
+ assert.match(badge, /Loop Ready L2 \(72\/100\)/);
+ assert.match(badge, /img\.shields\.io/);
+ assert.match(badge, /loop-engineering/);
+});
+
+test('auditProject: git commit with triage counts as loop activity', async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-git-'));
+ try {
+ execSync('git init', { cwd: dir, stdio: 'ignore' });
+ execSync('git config user.email "[email protected]"', { cwd: dir, stdio: 'ignore' });
+ execSync('git config user.name "Test"', { cwd: dir, stdio: 'ignore' });
+ await writeFile(path.join(dir, 'README.md'), '# test\n');
+ execSync('git add README.md', { cwd: dir, stdio: 'ignore' });
+ execSync('git commit -m "chore: daily triage update"', { cwd: dir, stdio: 'ignore' });
+ const result = await auditProject(dir);
+ assert.ok(result.signals.loopActivity.present);
+ assert.ok(result.signals.loopActivity.evidence.some((e) => e.startsWith('git:')));
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
test('auditProject: L2 with verifier skill', async () => {
const dir = await mkdtemp(path.join(tmpdir(), 'loop-audit-l2-'));
try {
diff --git a/tools/loop-audit/tsconfig.json b/tools/loop-audit/tsconfig.json
index 3aaa0bd..6ce60bc 100644
--- a/tools/loop-audit/tsconfig.json
+++ b/tools/loop-audit/tsconfig.json
@@ -7,7 +7,8 @@
"rootDir": "src",
"strict": true,
"skipLibCheck": true,
- "declaration": true
+ "declaration": true,
+ "types": ["node"]
},
"include": ["src/**/*"]
}
\ No newline at end of file
diff --git a/tools/loop-cost/dist/cli.js b/tools/loop-cost/dist/cli.js
old mode 100644
new mode 100755
index a999ff9..6d324d6
--- a/tools/loop-cost/dist/cli.js
+++ b/tools/loop-cost/dist/cli.js
@@ -3,7 +3,7 @@ import { readFile, access } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import yaml from 'yaml';
-import { estimateCost, formatEstimateHuman, } from './estimator.js';
+import { assertValidLevel, estimateCost, formatEstimateHuman, } from './estimator.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const PACKAGE_ROOT = path.resolve(__dirname, '..');
function parseArgs(argv) {
@@ -87,6 +87,14 @@ Examples:
console.error(`Unknown pattern: ${args.pattern}. Use --list for ids.`);
process.exit(1);
}
+ try {
+ assertValidLevel(args.level);
+ }
+ catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.error(msg);
+ process.exit(1);
+ }
if (!pattern.cost) {
console.error(`Pattern ${args.pattern} has no cost block in registry.`);
process.exit(1);
diff --git a/tools/loop-cost/dist/estimator.d.ts b/tools/loop-cost/dist/estimator.d.ts
index 5ce001e..b5da5e7 100644
--- a/tools/loop-cost/dist/estimator.d.ts
+++ b/tools/loop-cost/dist/estimator.d.ts
@@ -1,4 +1,6 @@
export type ReadinessLevel = 'L1' | 'L2' | 'L3';
+export declare const VALID_READINESS_LEVELS: ReadinessLevel[];
+export declare function assertValidLevel(level: string): asserts level is ReadinessLevel;
export interface PatternCost {
tokens_noop: number;
tokens_report: number;
diff --git a/tools/loop-cost/dist/estimator.js b/tools/loop-cost/dist/estimator.js
index 0437465..18988c4 100644
--- a/tools/loop-cost/dist/estimator.js
+++ b/tools/loop-cost/dist/estimator.js
@@ -1,3 +1,9 @@
+export const VALID_READINESS_LEVELS = ['L1', 'L2', 'L3'];
+export function assertValidLevel(level) {
+ if (!VALID_READINESS_LEVELS.includes(level)) {
+ throw new Error(`Invalid level: ${level}. Valid: ${VALID_READINESS_LEVELS.join(', ')}`);
+ }
+}
const INTERVAL_MS = {
m: 60_000,
h: 3_600_000,
@@ -62,6 +68,7 @@ function formatTokens(n) {
return String(n);
}
export function estimateCost(input) {
+ assertValidLevel(input.level);
const cadence = input.cadence ?? input.pattern.cadence;
const runsPerDay = cadenceToRunsPerDay(cadence, input.conservative);
const { cost, token_cost: tokenCostTier } = input.pattern;
diff --git a/tools/loop-cost/package.json b/tools/loop-cost/package.json
index 1d804df..a56e4a7 100644
--- a/tools/loop-cost/package.json
+++ b/tools/loop-cost/package.json
@@ -1,6 +1,6 @@
{
"name": "@cobusgreyling/loop-cost",
- "version": "1.0.2",
+ "version": "1.0.3",
"description": "Estimate token budgets and daily costs for loop engineering patterns. By cadence, readiness level (L1/L2/L3), and coding agent tool.",
"type": "module",
"bin": {
diff --git a/tools/loop-cost/registry.json b/tools/loop-cost/registry.json
index 3ed5aa3..b5c76f8 100644
--- a/tools/loop-cost/registry.json
+++ b/tools/loop-cost/registry.json
@@ -279,7 +279,7 @@
"ambiguous-duplicates",
"stale-closures"
],
- "starter": "starters/minimal-loop",
+ "starter": "starters/issue-triage",
"week_one_mode": "L1",
"token_cost": "low",
"cost": {
diff --git a/tools/loop-cost/src/cli.ts b/tools/loop-cost/src/cli.ts
index 9a61c60..d7e6fe7 100644
--- a/tools/loop-cost/src/cli.ts
+++ b/tools/loop-cost/src/cli.ts
@@ -4,6 +4,7 @@ import path from 'node:path';
import { fileURLToPath } from 'node:url';
import yaml from 'yaml';
import {
+ assertValidLevel,
estimateCost,
formatEstimateHuman,
type ReadinessLevel,
@@ -95,6 +96,14 @@ Examples:
process.exit(1);
}
+ try {
+ assertValidLevel(args.level);
+ } catch (err: unknown) {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.error(msg);
+ process.exit(1);
+ }
+
if (!pattern.cost) {
console.error(`Pattern ${args.pattern} has no cost block in registry.`);
process.exit(1);
diff --git a/tools/loop-cost/src/estimator.ts b/tools/loop-cost/src/estimator.ts
index d0b30cd..7814f03 100644
--- a/tools/loop-cost/src/estimator.ts
+++ b/tools/loop-cost/src/estimator.ts
@@ -1,5 +1,13 @@
export type ReadinessLevel = 'L1' | 'L2' | 'L3';
+export const VALID_READINESS_LEVELS: ReadinessLevel[] = ['L1', 'L2', 'L3'];
+
+export function assertValidLevel(level: string): asserts level is ReadinessLevel {
+ if (!VALID_READINESS_LEVELS.includes(level as ReadinessLevel)) {
+ throw new Error(`Invalid level: ${level}. Valid: ${VALID_READINESS_LEVELS.join(', ')}`);
+ }
+}
+
export interface PatternCost {
tokens_noop: number;
tokens_report: number;
@@ -117,6 +125,7 @@ function formatTokens(n: number): string {
}
export function estimateCost(input: EstimateInput): EstimateResult {
+ assertValidLevel(input.level);
const cadence = input.cadence ?? input.pattern.cadence;
const runsPerDay = cadenceToRunsPerDay(cadence, input.conservative);
const { cost, token_cost: tokenCostTier } = input.pattern;
diff --git a/tools/loop-cost/test/estimator.test.mjs b/tools/loop-cost/test/estimator.test.mjs
index c481b57..d1fce3a 100644
--- a/tools/loop-cost/test/estimator.test.mjs
+++ b/tools/loop-cost/test/estimator.test.mjs
@@ -1,6 +1,7 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
+ assertValidLevel,
cadenceToRunsPerDay,
runsPerDayForInterval,
estimateCost,
@@ -48,6 +49,10 @@ test('estimateCost: ci-sweeper 15m L2 warns on high spend', () => {
assert.ok(r.scenarios.realistic.tokensPerDay < r.scenarios.action.tokensPerDay);
});
+test('assertValidLevel: rejects unknown level', () => {
+ assert.throws(() => assertValidLevel('garbage'), /Invalid level/);
+});
+
test('estimateCost: daily-triage 1d L1 is cheap', () => {
const r = estimateCost({
pattern: {
diff --git a/tools/loop-init/dist/cli.js b/tools/loop-init/dist/cli.js
index e42d1f5..a20b019 100644
--- a/tools/loop-init/dist/cli.js
+++ b/tools/loop-init/dist/cli.js
@@ -276,6 +276,16 @@ Examples:
process.exit(0);
}
const { pattern, tool, target, dryRun } = args;
+ const validPatterns = Object.keys(PATTERN_STARTERS);
+ const validTools = Object.keys(TOOL_SUFFIX);
+ if (!validPatterns.includes(pattern)) {
+ console.error(`Unknown pattern: ${pattern}. Valid: ${validPatterns.join(', ')}`);
+ process.exit(1);
+ }
+ if (!validTools.includes(tool)) {
+ console.error(`Unknown tool: ${tool}. Valid: ${validTools.join(', ')}`);
+ process.exit(1);
+ }
const targetDir = path.resolve(target);
const baseStarter = PATTERN_STARTERS[pattern];
const suffix = TOOL_SUFFIX[tool];
diff --git a/tools/loop-init/package-lock.json b/tools/loop-init/package-lock.json
index 8288c27..2976dbb 100644
--- a/tools/loop-init/package-lock.json
+++ b/tools/loop-init/package-lock.json
@@ -1,38 +1,38 @@
{
"name": "@cobusgreyling/loop-init",
- "version": "1.2.1",
+ "version": "1.2.2",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@cobusgreyling/loop-init",
- "version": "1.2.1",
+ "version": "1.2.2",
"license": "MIT",
"bin": {
"loop-init": "dist/cli.js"
},
"devDependencies": {
- "@types/node": "^25.9.3",
- "typescript": "^5.0.0"
+ "@types/node": "^26.0.0",
+ "typescript": "^6.0.3"
},
"engines": {
"node": ">=18"
}
},
"node_modules/@types/node": {
- "version": "25.9.3",
- "resolved": "https://registry.npmjs.org/@types/node/-/node-25.9.3.tgz",
- "integrity": "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg==",
+ "version": "26.0.1",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-26.0.1.tgz",
+ "integrity": "sha512-fc3KiUoBt6kie0N9bIW3E47vZsuaMf0PM2AaUpLCLT0s/LvX1nxAim6Fc049cNxODPpGm6qRAuUOB86SkRuPQw==",
"dev": true,
"license": "MIT",
"dependencies": {
- "undici-types": ">=7.24.0 <7.24.7"
+ "undici-types": "~8.3.0"
}
},
"node_modules/typescript": {
- "version": "5.9.3",
- "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
- "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+ "version": "6.0.3",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
+ "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
"dev": true,
"license": "Apache-2.0",
"bin": {
@@ -44,9 +44,9 @@
}
},
"node_modules/undici-types": {
- "version": "7.24.6",
- "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
- "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
+ "version": "8.3.0",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz",
+ "integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==",
"dev": true,
"license": "MIT"
}
diff --git a/tools/loop-init/package.json b/tools/loop-init/package.json
index ca34edd..3b510fc 100644
--- a/tools/loop-init/package.json
+++ b/tools/loop-init/package.json
@@ -1,6 +1,6 @@
{
"name": "@cobusgreyling/loop-init",
- "version": "1.2.1",
+ "version": "1.2.2",
"description": "Scaffold loop engineering patterns and starters into any project. Supports Grok, Claude Code, Codex and more. npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok",
"type": "module",
"bin": {
@@ -49,7 +49,7 @@
"access": "public"
},
"devDependencies": {
- "@types/node": "^25.9.3",
- "typescript": "^5.0.0"
+ "@types/node": "^26.0.0",
+ "typescript": "^6.0.3"
}
}
\ No newline at end of file
diff --git a/tools/loop-init/registry.yaml b/tools/loop-init/registry.yaml
index 072c202..89f7aa4 100644
--- a/tools/loop-init/registry.yaml
+++ b/tools/loop-init/registry.yaml
@@ -139,7 +139,7 @@ patterns:
state: issue-triage-state.md
phases: [discover, dedupe, score, propose-labels, human-review]
human_gates: [security, p0-p1, ambiguous-duplicates, stale-closures]
- starter: starters/minimal-loop
+ starter: starters/issue-triage
week_one_mode: L1
token_cost: low
cost:
diff --git a/tools/loop-init/src/cli.ts b/tools/loop-init/src/cli.ts
index 9bd614c..31f6ec3 100644
--- a/tools/loop-init/src/cli.ts
+++ b/tools/loop-init/src/cli.ts
@@ -330,6 +330,18 @@ Examples:
}
const { pattern, tool, target, dryRun } = args;
+
+ const validPatterns = Object.keys(PATTERN_STARTERS) as Pattern[];
+ const validTools = Object.keys(TOOL_SUFFIX) as Tool[];
+ if (!validPatterns.includes(pattern)) {
+ console.error(`Unknown pattern: ${pattern}. Valid: ${validPatterns.join(', ')}`);
+ process.exit(1);
+ }
+ if (!validTools.includes(tool)) {
+ console.error(`Unknown tool: ${tool}. Valid: ${validTools.join(', ')}`);
+ process.exit(1);
+ }
+
const targetDir = path.resolve(target);
const baseStarter = PATTERN_STARTERS[pattern];
const suffix = TOOL_SUFFIX[tool];
diff --git a/tools/loop-init/test/cli.test.mjs b/tools/loop-init/test/cli.test.mjs
index 31defe4..96951d9 100644
--- a/tools/loop-init/test/cli.test.mjs
+++ b/tools/loop-init/test/cli.test.mjs
@@ -47,6 +47,20 @@ test('loop-init scaffolds issue-triage with bundled assets', async () => {
}
});
+test('loop-init rejects unknown pattern', async () => {
+ await assert.rejects(
+ () => exec('node', [CLI, '.', '--pattern', 'not-a-pattern', '--tool', 'grok', '--dry-run']),
+ (err) => err.stderr?.includes('Unknown pattern') || err.message?.includes('Unknown pattern'),
+ );
+});
+
+test('loop-init rejects unknown tool', async () => {
+ await assert.rejects(
+ () => exec('node', [CLI, '.', '--pattern', 'daily-triage', '--tool', 'emacs', '--dry-run']),
+ (err) => err.stderr?.includes('Unknown tool') || err.message?.includes('Unknown tool'),
+ );
+});
+
test('loop-init scaffolds ci-sweeper with bundled assets', async () => {
const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-'));
try {
diff --git a/tools/loop-init/tsconfig.json b/tools/loop-init/tsconfig.json
index 1e66d55..2edfb06 100644
--- a/tools/loop-init/tsconfig.json
+++ b/tools/loop-init/tsconfig.json
@@ -7,7 +7,8 @@
"rootDir": "src",
"strict": true,
"declaration": true,
- "skipLibCheck": true
+ "skipLibCheck": true,
+ "types": ["node"]
},
"include": ["src/**/*"]
}
\ No newline at end of file