From f91ed5ab2da91fee8a5425ae332d1e4fbc8ba885 Mon Sep 17 00:00:00 2001 From: Lukas May Date: Thu, 5 Mar 2026 10:18:30 +0100 Subject: [PATCH] feat: Harden execute agent prompt with industry best practices - Add Conventional Commits format requirement to git workflow - Add pre-commit hook guidance (never --no-verify) - Add secrets/credentials guard (never stage .env, API keys) - Strengthen git add reasoning (explain why not git add .) - Add CLAUDE.md read step to session startup - Add lint/type-check gate to verification step - Add doc update step to execution protocol - Expand Definition of Done: lint, types, docs, debug cleanup - Add anti-patterns: debug artifacts, spinning on failures (3x retry cap) - Add stale reference check on file renames/moves - Improve error signal guidance (include stack traces, not summaries) --- apps/server/agent/prompts/execute.ts | 14 +++++++++++--- apps/server/agent/prompts/shared.ts | 12 ++++++++---- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/apps/server/agent/prompts/execute.ts b/apps/server/agent/prompts/execute.ts index c26cfa4..03299af 100644 --- a/apps/server/agent/prompts/execute.ts +++ b/apps/server/agent/prompts/execute.ts @@ -42,11 +42,13 @@ Follow these steps in order. Signal done only after the Definition of Done check 4. **Implement (GREEN)**: Minimum code to pass tests. Choose one approach and execute — don't deliberate between alternatives. -5. **Verify green**: Run the full relevant test suite. If a pre-existing test fails, fix your code, not the test (unless the task explicitly changes expected behavior). +5. **Verify green**: Run the full relevant test suite, linter, and type checker. If anything fails, fix your code — do not proceed with broken checks. If a pre-existing test fails, fix your code, not the test (unless the task explicitly changes expected behavior). -6. **Commit**: Stage specific files, commit with a descriptive message, update progress file. +6. **Update docs**: If your changes affect behavior documented in \`docs/\`, update the relevant doc file. When renaming or moving files, grep docs for stale references. -7. **Iterate**: For multi-part tasks, repeat 3-6 per part. Each cycle produces a commit. +7. **Commit**: Stage specific files, commit using Conventional Commits format, update progress file. + +8. **Iterate**: For multi-part tasks, repeat 3-7 per part. Each cycle produces a commit. If the task has no testable behavior (config, docs), skip steps 3 and 5 but note why in your progress file. @@ -56,12 +58,15 @@ ${TEST_INTEGRITY} - **Mega-commits**: Commit after each logical unit, not one giant commit at the end. - **Silent reinterpretation**: Task says X, do X. Don't substitute Y because you think it's better. - **Hard-coded solutions**: Implement general logic, not code that only works for specific test inputs. +- **Debug artifacts**: Remove all \`console.log\`, debug statements, and temporary instrumentation before committing. +- **Spinning on failures**: If a fix attempt fails 3 times, stop and signal "questions" or "error" with what you tried. Don't loop indefinitely. - Do exactly what the task says — no unrelated fixes, refactors, or improvements. Other agents may own those files. - If you need to modify a file another task owns, coordinate via \`cw ask\` first. - Touching 7+ files? You're probably overscoping. Re-read the task. +- When renaming or moving files, grep for stale imports and references to the old path. Fix them in the same commit. ${DEVIATION_RULES} ${GIT_WORKFLOW} @@ -72,7 +77,10 @@ ${CONTEXT_MANAGEMENT} Before writing signal.json with status "done": - [ ] All tests pass (full relevant suite) +- [ ] Linter and type checker pass (no new errors) +- [ ] Relevant docs updated (if behavior changed) - [ ] No uncommitted changes +- [ ] No debug statements or temporary instrumentation left in code - [ ] Progress file updated - [ ] Implemented exactly what the task asked — no more, no less diff --git a/apps/server/agent/prompts/shared.ts b/apps/server/agent/prompts/shared.ts index 7309e5c..af90bdf 100644 --- a/apps/server/agent/prompts/shared.ts +++ b/apps/server/agent/prompts/shared.ts @@ -9,7 +9,7 @@ export const SIGNAL_FORMAT = ` As your final action, write \`.cw/output/signal.json\`: - Done: \`{ "status": "done" }\` - Need clarification: \`{ "status": "questions", "questions": [{ "id": "q1", "question": "..." }] }\` -- Unrecoverable error: \`{ "status": "error", "error": "..." }\` +- Unrecoverable error: \`{ "status": "error", "error": "..." }\` — include the actual error output, stack trace, or repro steps, not just a summary `; export const INPUT_FILES = ` @@ -60,9 +60,12 @@ export const GIT_WORKFLOW = ` You are in an isolated git worktree. Other agents work in parallel on separate branches. -- Stage specific files with \`git add \`, not \`git add .\` +- Stage specific files with \`git add \`, never \`git add .\` or \`git add -A\` — these risk staging secrets, build artifacts, or generated files - Never force-push - Run \`git status\` before committing +- Commit messages use Conventional Commits: \`feat:\`, \`fix:\`, \`refactor:\`, \`docs:\`, \`test:\`, \`chore:\`. Describe the "why", not the "what". +- If pre-commit hooks fail, fix the underlying issue — never bypass with \`--no-verify\` +- Never stage secrets, \`.env\` files, credentials, or API keys. If you encounter them, \`git reset\` them immediately. `; export const CODEBASE_EXPLORATION = ` @@ -102,8 +105,9 @@ export const SESSION_STARTUP = ` 1. \`pwd\` — confirm working directory 2. \`git status\` — check for unexpected state -3. Run test suite — establish green baseline. If already failing, signal "error". Don't build on a broken foundation. -4. Read \`.cw/input/manifest.json\` and all **assignment** files (the \`files\` array). Do not bulk-read context files. +3. Read \`CLAUDE.md\` at the repo root (if it exists) — it contains project conventions and patterns you must follow. +4. Run test suite — establish green baseline. If already failing, signal "error". Don't build on a broken foundation. +5. Read \`.cw/input/manifest.json\` and all **assignment** files (the \`files\` array). Do not bulk-read context files. `; export const PROGRESS_TRACKING = `