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
fix: address maintainer review for goal-init PR
THRISHAL12345dc06b6aea10f
diff --git a/templates/SKILL.md.goal-scoper b/templates/SKILL.md.goal-scoperindex cd6c0e8..da95870 100644--- a/templates/SKILL.md.goal-scoper+++ b/templates/SKILL.md.goal-scoper@@ -1,12 +1,17 @@+---name: goal-scoperdescription: "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-verifierindex 27dddaa..5080f9e 100644--- a/templates/SKILL.md.goal-verifier+++ b/templates/SKILL.md.goal-verifier@@ -1,12 +1,17 @@+---name: goal-verifierdescription: "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.templatenew file mode 100644index 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/.gitignorenew file mode 100644index 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.mdnew file mode 100644index 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.jsindex 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.mdif (!(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 skillsawait 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.jsonindex 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.jsonindex 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.mjsnew file mode 100644index 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.tsindex 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.mdif (!(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 skillsdiff --git a/tools/goal-init/src/contributor-cta.ts b/tools/goal-init/src/contributor-cta.tsindex 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 filediff --git a/tools/goal-init/test/cli.test.mjs b/tools/goal-init/test/cli.test.mjsindex 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'))));+ });});