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.

fix: address maintainer review for goal-init PR

THRISHAL12345dc06b6aea10f
diff --git a/templates/SKILL.md.goal-scoper b/templates/SKILL.md.goal-scoper
index cd6c0e8..da95870 100644
--- a/templates/SKILL.md.goal-scoper
+++ b/templates/SKILL.md.goal-scoper
@@ -1,12 +1,17 @@
+---
name: goal-scoper
description: "Scopes an ambiguous issue or task into a concrete GOAL.md."
+user_invocable: true
+---
-instructions: |
- You are the scoping agent.
- Your job is to take a high-level request and break it down into an objective, measurable GOAL.md file.
-
- RULES:
- 1. Do not write code.
- 2. Populate `GOAL.md` using the template format.
- 3. Ensure Acceptance Criteria are objective and binary (yes/no).
- 4. Ensure explicit out-of-scope items are listed to prevent scope creep.
+# Goal Scoper Skill
+
+You are the scoping agent.
+Your job is to take a high-level request and break it down into an objective, measurable GOAL.md file.
+
+## Rules
+
+1. Do not write code.
+2. Populate `GOAL.md` using the template format.
+3. Ensure Acceptance Criteria are objective and binary (yes/no).
+4. Ensure explicit out-of-scope items are listed to prevent scope creep.
diff --git a/templates/SKILL.md.goal-verifier b/templates/SKILL.md.goal-verifier
index 27dddaa..5080f9e 100644
--- a/templates/SKILL.md.goal-verifier
+++ b/templates/SKILL.md.goal-verifier
@@ -1,12 +1,17 @@
+---
name: goal-verifier
description: "Verifies whether a goal in GOAL.md has genuinely met all of its acceptance criteria."
+user_invocable: true
+---
-instructions: |
- You are an independent verification agent.
- Your job is to read `GOAL.md`, review the acceptance criteria, and inspect the codebase to verify if those criteria have been objectively met.
-
- RULES:
- 1. Do not write or change code. You only verify.
- 2. If the goal is complete, output exactly: "VERIFIER: PASS. All criteria met."
- 3. If the goal is NOT complete, output: "VERIFIER: FAIL. Missing: [list of missing items]."
- 4. The implementation agent may not mark the goal as complete until you output PASS.
+# Goal Verifier Skill
+
+You are an independent verification agent.
+Your job is to read `GOAL.md`, review the acceptance criteria, and inspect the codebase to verify if those criteria have been objectively met.
+
+## Rules
+
+1. Do not write or change code. You only verify.
+2. If the goal is complete, output exactly: "VERIFIER: PASS. All criteria met."
+3. If the goal is NOT complete, output: "VERIFIER: FAIL. Missing: [list of missing items]."
+4. The implementation agent may not mark the goal as complete until you output PASS.
diff --git a/templates/goal-run-log.md.template b/templates/goal-run-log.md.template
new file mode 100644
index 0000000..34ab9a1
--- /dev/null
+++ b/templates/goal-run-log.md.template
@@ -0,0 +1,7 @@
+# Goal Run Log
+
+Append a short entry here whenever you start or resume work on a goal.
+
+## Log
+
+- [Date]: [Brief description of what was worked on]
diff --git a/tools/goal-init/.gitignore b/tools/goal-init/.gitignore
new file mode 100644
index 0000000..0350652
--- /dev/null
+++ b/tools/goal-init/.gitignore
@@ -0,0 +1 @@
+templates/
diff --git a/tools/goal-init/README.md b/tools/goal-init/README.md
new file mode 100644
index 0000000..6ba183d
--- /dev/null
+++ b/tools/goal-init/README.md
@@ -0,0 +1,15 @@
+# @cobusgreyling/goal-init
+
+Scaffolds goal engineering workflows. This CLI initializes a directory with `GOAL.md`, `goal-budget.md`, and relevant skills to support autonomous agents in completing objectives incrementally.
+
+## Usage
+
+```bash
+npx @cobusgreyling/goal-init . --tool grok
+```
+
+Supported tools:
+- `grok` (default)
+- `claude`
+- `codex`
+- `opencode`
diff --git a/tools/goal-init/dist/cli.js b/tools/goal-init/dist/cli.js
index 96b862e..653ee09 100644
--- a/tools/goal-init/dist/cli.js
+++ b/tools/goal-init/dist/cli.js
@@ -155,7 +155,17 @@ Examples:
}
// 3. Scaffold goal-run-log.md
if (!(await exists(path.join(targetDir, 'goal-run-log.md')))) {
- await copyFile(path.join(templatesRoot, 'loop-run-log.md.template'), path.join(targetDir, 'goal-run-log.md'), dryRun);
+ await copyFile(path.join(templatesRoot, 'goal-run-log.md.template'), path.join(targetDir, 'goal-run-log.md'), dryRun);
+ }
+ // 3.5 Scaffold docs/safety.md
+ const safetyPath = path.join(targetDir, 'docs', 'safety.md');
+ if (!(await exists(safetyPath)) && !dryRun) {
+ await mkdir(path.dirname(safetyPath), { recursive: true });
+ await writeFile(safetyPath, '# Safety Policy\n\nEnsure any autonomous tools adhere to safety guidelines.\n');
+ console.log(' created: docs/safety.md (stub)');
+ }
+ else if (dryRun) {
+ console.log(` would create: docs/safety.md (stub)`);
}
// 4. Scaffold skills
await copyTemplateSkill(templatesRoot, 'SKILL.md.goal-verifier', targetDir, tool, 'goal-verifier', dryRun);
diff --git a/tools/goal-init/package-lock.json b/tools/goal-init/package-lock.json
index ed2f774..e6fa2c4 100644
--- a/tools/goal-init/package-lock.json
+++ b/tools/goal-init/package-lock.json
@@ -8,12 +8,30 @@
"name": "@cobusgreyling/goal-init",
"version": "1.0.0",
"license": "MIT",
+ "dependencies": {
+ "@cobusgreyling/goal-audit": "^1.0.2"
+ },
"bin": {
"goal-init": "dist/cli.js"
},
"devDependencies": {
"@types/node": "^22.0.0",
"typescript": "^5.5.4"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@cobusgreyling/goal-audit": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/@cobusgreyling/goal-audit/-/goal-audit-1.0.2.tgz",
+ "integrity": "sha512-c7m25JzBPohyaJomAO6mWit6ZyuKzIc9P03qHCn3kwg8SfYPkON9aUJbQRvQoxt/H2uOa49Zdked9pA6qukx1A==",
+ "license": "MIT",
+ "bin": {
+ "goal-audit": "dist/cli.js"
+ },
+ "engines": {
+ "node": ">=18"
}
},
"node_modules/@types/node": {
diff --git a/tools/goal-init/package.json b/tools/goal-init/package.json
index e4ca4aa..6964079 100644
--- a/tools/goal-init/package.json
+++ b/tools/goal-init/package.json
@@ -3,17 +3,52 @@
"version": "1.0.0",
"description": "Scaffold goal engineering setups",
"type": "module",
- "main": "dist/cli.js",
"bin": {
- "goal-init": "dist/cli.js"
+ "goal-init": "./dist/cli.js"
},
+ "files": [
+ "dist",
+ "templates",
+ "README.md"
+ ],
"scripts": {
- "build": "tsc",
+ "bundle": "node scripts/bundle-assets.mjs",
+ "build": "npm run bundle && tsc",
"test": "npm run build && node --test test/cli.test.mjs",
- "lint": "echo 'Add lint script'"
+ "prepublishOnly": "npm test",
+ "start": "node dist/cli.js"
},
+ "engines": {
+ "node": ">=18"
+ },
+ "keywords": [
+ "goal-engineering",
+ "ai-agents",
+ "coding-agents",
+ "scaffold",
+ "starter",
+ "claude-code",
+ "grok",
+ "codex",
+ "opencode"
+ ],
"author": "Cobus Greyling",
"license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/cobusgreyling/loop-engineering.git",
+ "directory": "tools/goal-init"
+ },
+ "homepage": "https://cobusgreyling.github.io/loop-engineering/",
+ "bugs": {
+ "url": "https://github.com/cobusgreyling/loop-engineering/issues"
+ },
+ "publishConfig": {
+ "access": "public"
+ },
+ "dependencies": {
+ "@cobusgreyling/goal-audit": "^1.0.2"
+ },
"devDependencies": {
"@types/node": "^22.0.0",
"typescript": "^5.5.4"
diff --git a/tools/goal-init/scripts/bundle-assets.mjs b/tools/goal-init/scripts/bundle-assets.mjs
new file mode 100644
index 0000000..cb1ecfc
--- /dev/null
+++ b/tools/goal-init/scripts/bundle-assets.mjs
@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { cp, rm, access, rename, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const REPO_ROOT = path.resolve(PACKAGE_ROOT, '../..');
+const LOCK_DIR = path.join(PACKAGE_ROOT, '.bundle-assets.lock');
+
+async function exists(p) {
+ try {
+ await access(p);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+async function replaceDirectory(src, dest) {
+ const tempDest = `${dest}.tmp-${process.pid}-${Date.now()}`;
+ let moved = false;
+ await rm(tempDest, { recursive: true, force: true });
+ try {
+ await cp(src, tempDest, { recursive: true });
+
+ for (let attempt = 0; attempt < 3; attempt += 1) {
+ await rm(dest, { recursive: true, force: true });
+ try {
+ await rename(tempDest, dest);
+ moved = true;
+ return;
+ } catch (err) {
+ if (err?.code !== 'EEXIST' || attempt === 2) {
+ throw err;
+ }
+ }
+ }
+ } finally {
+ if (!moved) {
+ await rm(tempDest, { recursive: true, force: true });
+ }
+ }
+}
+
+async function sleep(ms) {
+ return new Promise((resolve) => {
+ setTimeout(resolve, ms);
+ });
+}
+
+async function acquireLock() {
+ for (let attempt = 0; attempt < 100; attempt += 1) {
+ try {
+ await mkdir(LOCK_DIR);
+ return async () => rm(LOCK_DIR, { recursive: true, force: true });
+ } catch (err) {
+ if (err?.code !== 'EEXIST') {
+ throw err;
+ }
+ await sleep(50);
+ }
+ }
+ throw new Error(`bundle-assets: timed out waiting for ${LOCK_DIR}`);
+}
+
+const releaseLock = await acquireLock();
+try {
+ for (const dir of ['templates']) {
+ const dest = path.join(PACKAGE_ROOT, dir);
+ const src = path.join(REPO_ROOT, dir);
+ if (!(await exists(src))) {
+ throw new Error(`bundle-assets: missing ${src}`);
+ }
+ await replaceDirectory(src, dest);
+ console.log(`bundled ${dir}/ → tools/goal-init/${dir}/`);
+ }
+} finally {
+ await releaseLock();
+}
diff --git a/tools/goal-init/src/cli.ts b/tools/goal-init/src/cli.ts
index f19ade1..0c1c6d8 100644
--- a/tools/goal-init/src/cli.ts
+++ b/tools/goal-init/src/cli.ts
@@ -175,7 +175,17 @@ Examples:
// 3. Scaffold goal-run-log.md
if (!(await exists(path.join(targetDir, 'goal-run-log.md')))) {
- await copyFile(path.join(templatesRoot, 'loop-run-log.md.template'), path.join(targetDir, 'goal-run-log.md'), dryRun);
+ await copyFile(path.join(templatesRoot, 'goal-run-log.md.template'), path.join(targetDir, 'goal-run-log.md'), dryRun);
+ }
+
+ // 3.5 Scaffold docs/safety.md
+ const safetyPath = path.join(targetDir, 'docs', 'safety.md');
+ if (!(await exists(safetyPath)) && !dryRun) {
+ await mkdir(path.dirname(safetyPath), { recursive: true });
+ await writeFile(safetyPath, '# Safety Policy\n\nEnsure any autonomous tools adhere to safety guidelines.\n');
+ console.log(' created: docs/safety.md (stub)');
+ } else if (dryRun) {
+ console.log(` would create: docs/safety.md (stub)`);
}
// 4. Scaffold skills
diff --git a/tools/goal-init/src/contributor-cta.ts b/tools/goal-init/src/contributor-cta.ts
index 241199f..15c8eaa 100644
--- a/tools/goal-init/src/contributor-cta.ts
+++ b/tools/goal-init/src/contributor-cta.ts
@@ -1,8 +1,8 @@
-export const CONTRIBUTOR_QUICKSTART_URL =
- 'https://github.com/cobusgreyling/loop-engineering/discussions/123';
-
-export function printContributorCta(): void {
- console.log('');
- console.log('Contribute (~15 min tasks):');
- console.log(` ${CONTRIBUTOR_QUICKSTART_URL}`);
-}
\ No newline at end of file
+export const CONTRIBUTOR_QUICKSTART_URL =
+ 'https://github.com/cobusgreyling/loop-engineering/discussions/123';
+
+export function printContributorCta(): void {
+ console.log('');
+ console.log('Contribute (~15 min tasks):');
+ console.log(` ${CONTRIBUTOR_QUICKSTART_URL}`);
+}
\ No newline at end of file
diff --git a/tools/goal-init/test/cli.test.mjs b/tools/goal-init/test/cli.test.mjs
index 735e7a1..3da00ed 100644
--- a/tools/goal-init/test/cli.test.mjs
+++ b/tools/goal-init/test/cli.test.mjs
@@ -57,4 +57,32 @@ describe('goal-init cli', () => {
assert.match(content, /Existing rules/);
assert.match(content, /Goal Engineering Rules/);
});
+
+ test('does not overwrite existing GOAL.md', async () => {
+ const fs = await import('node:fs/promises');
+ await fs.writeFile(path.join(testDir, 'GOAL.md'), '# Original Goal\n');
+
+ await exec('node', [CLI, testDir, '--tool', 'grok']);
+
+ const content = await fs.readFile(path.join(testDir, 'GOAL.md'), 'utf8');
+ assert.equal(content, '# Original Goal\n');
+ });
+
+ test('fails on unknown tool', async () => {
+ try {
+ await exec('node', [CLI, testDir, '--tool', 'invalid-tool']);
+ assert.fail('Should have failed');
+ } catch (err) {
+ assert.match(err.stderr, /Unknown tool: invalid-tool/);
+ }
+ });
+
+ test('dry-run does not write files', async () => {
+ const { stdout } = await exec('node', [CLI, testDir, '--tool', 'grok', '--dry-run']);
+ assert.match(stdout, /would copy:/);
+
+ // Check files DO NOT exist
+ assert.ok(!(await exists(path.join(testDir, 'GOAL.md'))));
+ assert.ok(!(await exists(path.join(testDir, 'goal-budget.md'))));
+ });
});