toga-ai 1.0.735 → 1.0.736

package/.claude/settings.json

@@ -9,6 +9,15 @@
             "timeout": 3000
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/toga/plain-talk.js\"",
+            "timeout": 3000
+          }
+        ]
       }
     ],
     "PreToolUse": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.735",
+  "version": "1.0.736",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",

package/rules/common/communication.md

@@ -21,6 +21,12 @@ thinking, your plans, and your final answers. This is a hard team rule, not a st
 5. **Use lists.** More than two parts? Use a numbered or bulleted list, not a paragraph.
 6. **Stay technical, stay exact.** Keep the real detail — file names, error text, exact steps.
    Short does not mean vague. Be brief AND precise.
+7. **Mirror the person.** Read how each teammate writes to you — the words they use, the
+   terms they pick for things, and how long their sentences run — and answer back in that
+   same style. Reuse their own words. If they write short, you write short. This makes your
+   answers feel familiar and easy to follow.
+   - Never fake misspellings or bad grammar to "match" someone. Be natural and correct —
+     just familiar. Mirroring means their vocabulary and length, not their typos.
 
 ## When a human must do something — always use a numbered list
 
@@ -55,3 +61,14 @@ What you need to do:
 
 Wordy, jargon-heavy output is hard and slow to read — worse for non-native English readers.
 The team moves faster when you are brief and plain. Clear beats clever.
+
+## How this is enforced
+
+This rule kept drifting: it lived only here, so on long or technical sessions the model slid
+back to dense wording and teammates missed critical details. To stop that, a hook backs it up.
+
+- `scripts/hooks/plain-talk.js` runs on **every** developer turn (`UserPromptSubmit`). It
+  injects a short reminder of these rules — plus the "mirror the person" instruction — into
+  context right before each reply. So the model is reminded every turn, not just once.
+- The hook is wired in `.claude/settings.json` and ships to every repo on `npx toga-ai`.
+- It never blocks anything; it only nudges. To silence it, set `TOGA_PLAIN_TALK_DISABLED=1`.

package/scripts/hooks/plain-talk.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * plain-talk.js — EVERY-TURN enforcement of the team communication rule.
+ *
+ * Why this exists: rules/common/communication.md tells the model to write short,
+ * plain, jargon-free answers and to mirror how each teammate talks. But a rule that
+ * only lives in a file is passive — over a long or technical session the model drifts
+ * back to dense, jargon-heavy wording. Teammates (many reading English as a second
+ * language) then miss critical details and sign off on bad decisions. Prose alone did
+ * not hold; this is the mechanical backstop.
+ *
+ * How it works: registered on UserPromptSubmit. On every developer turn it prints a
+ * short <system-reminder> to stdout, which Claude Code injects into the model's context
+ * immediately before the reply is generated. So the plain-talk + mirror instruction is
+ * the last thing in context every single turn — the model cannot quietly forget it.
+ *
+ * It reads nothing and writes nothing. It never blocks (always exit 0) — a communication
+ * nudge must never stop a tool call. Fail-open on any error: a crashing nudge must never
+ * brick a session.
+ *
+ * Escape hatch: set TOGA_PLAIN_TALK_DISABLED=1 to silence the reminder.
+ */
+
+const fs = require('fs');
+
+/* Read the CC hook payload from stdin (fall back to env), so we only fire on the
+ * UserPromptSubmit event and stay quiet on anything else that reuses this script. */
+function readPayload() {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { /* no stdin */ }
+  let data = {};
+  if (raw && raw.trim()) {
+    try { data = JSON.parse(raw); } catch (e) { data = {}; }
+  }
+  if (!data.prompt && process.env.CLAUDE_USER_PROMPT) data.prompt = process.env.CLAUDE_USER_PROMPT;
+  return data;
+}
+
+function reminder() {
+  return [
+    '<system-reminder>',
+    'TEAM COMMUNICATION RULE (rules/common/communication.md) — applies to THIS reply:',
+    'Write short and plain. Many teammates read English as a second language; dense,',
+    'jargon-heavy answers make them miss critical details and accept bad decisions.',
+    '',
+    '  1. Answer first. Main point on line 1, reasons after (only if needed).',
+    '  2. Cut words. Say it, then stop. One line beats three.',
+    '  3. Common words only. No rare jargon (idempotent, cardinality, orthogonal, canonical);',
+    '     say what it means in plain words instead. Stay exact — keep file names, errors, steps.',
+    '  4. Any manual action (deploy, SQL, config, restart) goes in a numbered list under a',
+    '     "What you need to do:" heading. One action per step, in order.',
+    '',
+    'MIRROR THIS PERSON: read how the developer writes to you in this session — the words',
+    'and phrases they use, and how long their sentences run — and answer back in that same',
+    'register. Reuse their own terms for things. Match their length: if they write short,',
+    'you write short. Never fake misspellings or bad grammar; be natural, just familiar.',
+    '',
+    'Before you send: could you cut half the words and keep the meaning? Is any word too',
+    'rare for a non-native reader? Is the main point on the first line?',
+    '</system-reminder>',
+  ].join('\n');
+}
+
+function main() {
+  if (process.env.TOGA_PLAIN_TALK_DISABLED === '1') process.exit(0);
+
+  const data = readPayload();
+
+  // Only fire on a real user turn. UserPromptSubmit carries a prompt and no tool_name.
+  const isPromptEvent =
+    data.hook_event_name === 'UserPromptSubmit' ||
+    (typeof data.prompt === 'string' && !data.tool_name);
+
+  if (isPromptEvent) {
+    // stdout from a UserPromptSubmit hook is injected into the model's context.
+    console.log(reminder());
+  }
+  process.exit(0);
+}
+
+try { main(); } catch (e) { process.exit(0); } // fail-open: never brick a session