From 2246d25e6d190cad880c0d0497dbd58f2f26506c Mon Sep 17 00:00:00 2001 From: serkanalgur Date: Fri, 9 Oct 2026 11:31:12 +0400 Subject: [PATCH] docs: tell writing agents how backticks and heredocs fail MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A session investigating an "execute problem with backticks" turned out to be ordinary JS: a backtick nested directly inside a template literal ends it early, so `` `outer `in` `` is a syntax error rather than a nested string. Verified across Node and the code sandbox, which agree exactly. The second failure is the one with a track record of silent damage: a shell heredoc expands `\n` and backticks and corrupts the written file, with an error message that does not name the cause. Added an Escaping section to the three agents that hold `shell: allow` and author code — coder, tester, architect. Left nexus-orchestrator alone: it grants only `subagent`, and it is instructed never to write code, so the rule would describe an error it cannot commit. --- assets/agents/nexus-architect.md | 9 +++++++++ assets/agents/nexus-coder.md | 13 +++++++++++++ assets/agents/nexus-tester.md | 9 +++++++++ 3 files changed, 31 insertions(+) diff --git a/assets/agents/nexus-architect.md b/assets/agents/nexus-architect.md index 7d63ec5..1f578cf 100644 --- a/assets/agents/nexus-architect.md +++ b/assets/agents/nexus-architect.md @@ -43,6 +43,15 @@ You are a senior software architect. You design systems that are scalable, resil - Synchronous chains that create tight coupling - Over-engineering simple problems (YAGNI) +## Escaping + +- **Never write files with a shell heredoc.** Heredocs expand `\n` and backticks, + corrupting the file in ways the error message does not name. Use `write` / + `edit`, which pass content whole. + +You return a direction, not code — so the template-literal rule that applies to +the coder does not apply here. It stays if a design calls for showing a snippet. + ## Commits - NEVER add `Co-Authored-By` or any attribution trailer (e.g. `Co-Authored-By: Claude`) to a commit or PR unless the user explicitly asks for it in this conversation. Do not infer authorship from the model in use. diff --git a/assets/agents/nexus-coder.md b/assets/agents/nexus-coder.md index 06abd63..8ede08c 100644 --- a/assets/agents/nexus-coder.md +++ b/assets/agents/nexus-coder.md @@ -48,6 +48,19 @@ You are a senior software engineer who writes clean, maintainable, production-re - Tests covering happy path, edge cases, and error paths - Brief inline comments for complex logic (why, not what) +## Escaping + +- **Never write files with a shell heredoc.** Heredocs expand `\n` and backticks, + corrupting the file in ways the error message does not name. Use `write` / + `edit`, which pass content whole. +- **A backtick nested directly inside a template literal ends it early.** + `` `outer `in` `` is a syntax error, not a nested string. Escape it — + `` `outer \`in\`` `` — or inject it with `String.fromCharCode(96)`. +- Build a run of backticks from a variable; never type three in a row. + +Every one of these fails loudly rather than silently. If a build breaks on +escaping, the string is wrong at the source, not in the tool that reported it. + ## Commits - NEVER add `Co-Authored-By` or any attribution trailer (e.g. `Co-Authored-By: Claude`) to a commit or PR unless the user explicitly asks for it in this conversation. Do not infer authorship from the model in use. diff --git a/assets/agents/nexus-tester.md b/assets/agents/nexus-tester.md index c24f181..1bd800f 100644 --- a/assets/agents/nexus-tester.md +++ b/assets/agents/nexus-tester.md @@ -47,6 +47,15 @@ You are a QA engineer who writes tests that catch real bugs, not just increase c - Edge case coverage alongside happy path - Mock/stub strategy that doesn't hide real bugs +## Escaping + +- **Never write files with a shell heredoc.** Heredocs expand `\n` and backticks, + corrupting the file in ways the error message does not name. Use `write` / + `edit`, which pass content whole. +- **A backtick nested directly inside a template literal ends it early.** + `` `outer `in` `` is a syntax error, not a nested string. Escape it — + `` `outer \`in\`` `` — or inject it with `String.fromCharCode(96)`. + ## Commits - NEVER add `Co-Authored-By` or any attribution trailer (e.g. `Co-Authored-By: Claude`) to a commit or PR unless the user explicitly asks for it in this conversation. Do not infer authorship from the model in use.