From 84648bf0fa1c25f5c73fe0d762789b1e08d8766d Mon Sep 17 00:00:00 2001
From: Paul Huliganga <paje0101@gmail.com>
Date: Mon, 23 Mar 2026 23:39:02 -0400
Subject: [PATCH] fix(harness): improve task clarity and error signaling per
 agent-harness methodology

- TODO.md: Split vague tasks into explicit, atomic steps with verification criteria
- AGENT_INSTRUCTIONS.md: Add STUCK/ERROR/ALL_TASKS_COMPLETE signals per harness docs
- AGENT_INSTRUCTIONS.md: Add OpenClaw environment notes (absolute paths, exit signals)

Fixes stuck agent issue by following canonical agent-harness pattern from docs/agent-harness/.
---
 AGENT_INSTRUCTIONS.md | 67 +++++++++++++++++++++++++++++++++++++++++++
 TODO.md               |  6 ++--
 2 files changed, 70 insertions(+), 3 deletions(-)

diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md
index d077177..6ccf424 100644
--- a/AGENT_INSTRUCTIONS.md
+++ b/AGENT_INSTRUCTIONS.md
@@ -223,6 +223,49 @@ If PROJECT.md or ARCHITECTURE.md doesn't specify:
 
 ---
 
+## Error Signals (CRITICAL)
+
+If you encounter a blocker or error, **DO NOT fail silently**. Include one of these signals in your response:
+
+### STUCK Signal
+```markdown
+⚠️ **STUCK:** Cannot complete task "[task name]"
+
+**Attempted:**
+- [what you tried]
+- [what you tried]
+
+**Error/Blocker:**
+[exact error message or description of the problem]
+
+**Need from Paul:**
+[specific question or decision needed]
+```
+
+### ERROR Signal
+```markdown
+❌ **ERROR:** Build/test failure
+
+**Command:** `[exact command that failed]`
+
+**Error output:**
+```
+[paste last 20 lines of error]
+```
+
+**Context:** [what you were trying to do]
+```
+
+### ALL_TASKS_COMPLETE Signal
+```markdown
+🎉 **ALL_TASKS_COMPLETE**
+
+[summary of what was built]
+[deployment instructions]
+```
+
+---
+
 ## Communication Protocol
 
 ### Progress Updates (After Each Commit)
@@ -330,4 +373,28 @@ You're doing it right if:
 
 ---
 
+## OpenClaw Environment Notes
+
+### File Access
+- Working directory: `/home/paulh/.openclaw/workspace/projects/recipe-manager`
+- **CRITICAL:** Use absolute paths in all exec commands
+- The `~` shorthand does NOT work in exec — use `/home/paulh/` instead
+
+### Build Commands
+- Use `cd /absolute/path && command` pattern
+- Example: `cd /home/paulh/.openclaw/workspace/projects/recipe-manager && npm test`
+- Never rely on implicit working directory
+
+### Git
+- Commit after each completed task
+- Use conventional commit format: `feat(scope): description`
+- Don't push — Paul will review and push
+
+### Exit Signals
+- Include **ALL_TASKS_COMPLETE** when all TODO.md tasks are checked
+- Include **STUCK:** or **ERROR:** if blocked (see Error Signals above)
+- Always exit after ONE commit (don't chain multiple tasks)
+
+---
+
 _Remember: You're not just writing code—you're building a product Paul's family will use. Quality matters._
diff --git a/TODO.md b/TODO.md
index e5cf70c..e22f5fb 100644
--- a/TODO.md
+++ b/TODO.md
@@ -8,9 +8,9 @@
 ## 🎯 Active Tasks
 
 ### Backend Setup
-- [ ] Initialize Node.js project structure
-- [ ] Set up TypeScript configuration
-- [ ] Create SQLite schema with migrations
+- [ ] Initialize Node.js backend: Create src/backend/, package.json with express, better-sqlite3, zod, vitest. Create src/backend/index.ts with "Hello World" server on port 3000. Verify: npm install && npm run dev (server starts). Commit as "feat(backend): initialize Node.js project with Express"
+- [ ] Set up TypeScript: Create tsconfig.json (strict mode, ES2022, Node16 module resolution). Add build script to package.json. Verify: npm run build succeeds. Commit.
+- [ ] Create SQLite schema: Create src/backend/db/schema.sql with recipes, tags, recipe_tags tables per ARCHITECTURE.md. Create src/backend/db/migrate.ts to apply schema. Verify: npm run migrate creates data/recipes.db. Commit.
 - [ ] Implement recipe CRUD API endpoints
 - [ ] Add Zod validation schemas
 - [ ] Write API integration tests