Initial commit: minimal agent framework

2026-05-30 23:27:09 -04:00
commit 72ae07c310
17 changed files with 808 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Stop-Hook Pattern (How to Enforce Task Completion)
+
+This pattern prevents the agent from ending a session until the contract is satisfied, matching the article's recommendation.
+
+## Core Idea
+Instead of relying on the agent to voluntarily output "CONTRACT_MET", the orchestration layer (you or a thin wrapper) only allows the session to terminate when the stop condition is met.
+
+## Implementation Options
+
+### Option 1: Explicit Stop Condition in Every Prompt (Recommended)
+Add this block to the end of `implement.md`, `research.md`, and any other phase that produces a deliverable:
+
+```
+## Stop Condition (MANDATORY)
+You are not allowed to end this session until one of the following is true:
+- You have produced the required output file(s) AND output the exact phrase "CONTRACT_MET"
+- You have explicitly stated that the contract cannot be met and explained why
+
+Until then, continue working or ask clarifying questions.
+```
+
+### Option 2: Contract File as Gate
+Every task folder must contain a `{task-name}_CONTRACT.md`.
+
+The agent is instructed:
+- Read the contract at the start of the session
+- Only output "CONTRACT_MET" after every item in the contract has been verified (tests pass, files exist, acceptance criteria checked)
+
+### Option 3: External Orchestrator Hook (Strongest)
+If using a thin wrapper script around the agent CLI:
+
+```bash
+# Example pseudo-wrapper
+while true; do
+  agent run --prompt "$(render_prompt implement.md)"
+  if grep -q "CONTRACT_MET" last_output.txt; then
+    break
+  fi
+  # Otherwise feed the failure back into the same session or new one
+done
+```
+
+## Recommended Addition to referee.md and implement.md
+After the verdict or implementation, add:
+
+```
+## Final Gate
+Before finishing, re-read the CONTRACT.md (if present) and confirm every line item is satisfied.
+Only then output "CONTRACT_MET".
+```
+
+## Files to Update
+- Add the stop condition block to:
+  - prompts/implement.md
+  - prompts/research.md
+  - prompts/bug_finder.md (optional)
+- Update ONBOARDING.md to document this pattern under "Define Clear End States"
+
+This turns the voluntary "CONTRACT_MET" into a hard mechanical requirement.