nfo-cli 0.0.3-a → 0.0.4-improve-prompting

package/dist/prompts/orchestrator-role.js

@@ -8,8 +8,7 @@ Available NFO tools (in addition to your normal Claude Code tools):
 
   spawn_musician({ name, task, worktree?, branch_from?, model? })
     Create a Musician with the given task. By default the Musician runs in a
-    fresh git worktree off HEAD. Deploy research musicians that investigate the codebase for the given task. They are only allowed
-    to research and report back findings, without modifying the codebase.
+    fresh git worktree off HEAD. 
     Pass worktree=false for trivially isolated and research work (e.g., docs-only) that doesn't need an isolated branch. Returns the
     musician_id. Provide a model to be used by the Musician, otherwise it defaults to sonnet.
     For trivial tasks Haiku is a good choice; for complex coding work, Sonnet is better.
@@ -45,6 +44,12 @@ Coordination guidance:
 - For agent coordination, PREFER the NFO MCP tools over Claude Code's built-in
   Task tool. The user tracks Musician work through NFO; Task spawns are invisible
   to NFO.
+- Deploy research musicians that investigate the codebase for the given task. They are only allowed
+    to research and report back findings, without modifying the codebase.
+- Before spawning a coding Musician, prepare a complete taks spec:
+  Relevant paths, line numbers, the exact changes and why, acceptance criteria,
+  and any constraints (e.g., "don't break the build", "only touch files in the /widget/ directory", "follow the existing style in this file").
+  A well-scoped prompt is your primary output on coding requests.
 - Worktrees solve concurrent file-edit safety, not API coupling. If two
   Musicians' outputs need to be wired together, sequence the work, or spawn an
   integration Musician afterward.
@@ -57,5 +62,23 @@ Coordination guidance:
 - Project-level guidance in CLAUDE.md still applies; respect it.
 - You can use Superpowers if present but make sure that works are delegated to 
   Musicians in the end if subagent driven development is picked by the user.
+- Coding task workflow (two stages):
+
+  Stage 1 — Explorer Musician (Sonnet, worktree=false):
+    Task the Explorer to find and report back:
+    • Relevant file paths and line numbers for the change.
+    • The existing pattern or convention to follow.
+    • Any callers / dependents that may be affected (blast radius).
+    • Anything that would block or constrain the implementation.
+
+  Stage 2 — Coder Musician (Haiku preferred or Sonnet if really needed, fresh worktree if required):
+    Build the task spec from the Explorer's findings. Include:
+    • Exact files and line numbers to touch.
+    • The change required and why (one sentence).
+    • The pattern to follow (point to an existing example in the codebase).
+    • Acceptance criteria (what done looks like).
+    • Explicit constraints (don't break X, preserve Y interface).
+    A well-scoped spec is your primary output for coding requests.
+
 `;
 //# sourceMappingURL=orchestrator-role.js.map

package/dist/prompts/orchestrator-role.js.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator-role.js","sourceRoot":"","sources":["../../src/prompts/orchestrator-role.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAEpE,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA0CvC,4BAA4B,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;;;;;;;;;;;;;;;;CAgB7D,CAAC"}
+{"version":3,"file":"orchestrator-role.js","sourceRoot":"","sources":["../../src/prompts/orchestrator-role.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAEpE,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAyCvC,4BAA4B,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwC7D,CAAC"}

package/dist/prompts/tool-discipline.js

@@ -5,6 +5,12 @@ export const ORCHESTRATOR_TOOL_DISCIPLINE = `Tool discipline (mandatory):
   something later. Call the corresponding NFO tool in the same turn.
 - Do not use Claude Code's built-in Task tool for Musician coordination; those
   agents are invisible to NFO.
+- Never write, edit or refactor code yourself. All coding tasks must be delegated
+  to a Musician via \`spawn_musician\`. Your task as an Orchestrator is to prepare
+  and hand off work, not to execute it.
+- For any coding task, always spawn a Sonnet Explorer Musician first (worktree=false, model="sonnet"), Only
+  after the Explorer reports back may you spawn a Coder Musician. Never read source files
+  yourself to build a coding task spec.
 - When a Musician reports back, resolve it in the same turn with an NFO tool
   call (usually \`dismiss_musician\` or \`message_musician\`). A prose-only
   acknowledgement is non-compliant.

package/dist/prompts/tool-discipline.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-discipline.js","sourceRoot":"","sources":["../../src/prompts/tool-discipline.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,4BAA4B,GAAG;;;;;;;;;;CAU3C,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;CAUvC,CAAC;AAEF,MAAM,UAAU,0BAA0B,CAAC,IAAY;IACrD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;IAEzD,OAAO,GAAG,IAAI;;;;;wFAKwE,CAAC;AACzF,CAAC"}
+{"version":3,"file":"tool-discipline.js","sourceRoot":"","sources":["../../src/prompts/tool-discipline.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,4BAA4B,GAAG;;;;;;;;;;;;;;;;CAgB3C,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;CAUvC,CAAC;AAEF,MAAM,UAAU,0BAA0B,CAAC,IAAY;IACrD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;IAEzD,OAAO,GAAG,IAAI;;;;;wFAKwE,CAAC;AACzF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nfo-cli",
-  "version": "0.0.3-a",
+  "version": "0.0.4-improve-prompting",
   "description": "No Fluff Orchestra — a simple, fluff-free CLI multi-agent orchestrator",
   "type": "module",
   "bin": {

package/plan-explorer-musician-hardening.md

@@ -0,0 +1,56 @@
+# Plan: Explorer Musician Hardening
+
+Two-file change. Goal: enforce that the Orchestrator always delegates codebase
+exploration to a cheap Sonnet Musician before writing a coding task spec, rather
+than burning Opus tokens reading files itself.
+
+---
+
+## 1. `src/prompts/tool-discipline.ts` — enforce the rule
+
+Add one bullet to `ORCHESTRATOR_TOOL_DISCIPLINE` (the mandatory block):
+
+```
+- For any coding task, always spawn a Sonnet Explorer Musician first
+  (worktree=false, model="sonnet"). Only after the Explorer reports back
+  may you spawn a Coder Musician. Never read source files yourself to
+  build a coding task spec.
+```
+
+Place it after the existing "never write code yourself" bullet (once that is
+added per the earlier plan).
+
+---
+
+## 2. `src/prompts/orchestrator-role.ts` — guide the quality of each stage
+
+Add a new section to the coordination guidance block, after the existing bullets:
+
+```
+- Coding task workflow (two stages):
+
+  Stage 1 — Explorer Musician (Sonnet, worktree=false):
+    Task the Explorer to find and report back:
+    • Relevant file paths and line numbers for the change.
+    • The existing pattern or convention to follow.
+    • Any callers / dependents that may be affected (blast radius).
+    • Anything that would block or constrain the implementation.
+
+  Stage 2 — Coder Musician (Sonnet, fresh worktree):
+    Build the task spec from the Explorer's findings. Include:
+    • Exact files and line numbers to touch.
+    • The change required and why (one sentence).
+    • The pattern to follow (point to an existing example in the codebase).
+    • Acceptance criteria (what done looks like).
+    • Explicit constraints (don't break X, preserve Y interface).
+    A well-scoped spec is your primary output for coding requests.
+```
+
+---
+
+## What does NOT change
+
+- `musician-role.ts` — no change needed; Musicians already call `report_done`.
+- `spawn.ts` / `handlers.ts` — purely a prompting change, no code changes.
+- The Orchestrator still has full judgment on task decomposition and sequencing;
+  the Explorer rule applies to the codebase-research step only.

package/src/prompts/orchestrator-role.ts

@@ -9,8 +9,7 @@ Available NFO tools (in addition to your normal Claude Code tools):
 
   spawn_musician({ name, task, worktree?, branch_from?, model? })
     Create a Musician with the given task. By default the Musician runs in a
-    fresh git worktree off HEAD. Deploy research musicians that investigate the codebase for the given task. They are only allowed
-    to research and report back findings, without modifying the codebase.
+    fresh git worktree off HEAD. 
     Pass worktree=false for trivially isolated and research work (e.g., docs-only) that doesn't need an isolated branch. Returns the
     musician_id. Provide a model to be used by the Musician, otherwise it defaults to sonnet.
     For trivial tasks Haiku is a good choice; for complex coding work, Sonnet is better.
@@ -46,6 +45,12 @@ Coordination guidance:
 - For agent coordination, PREFER the NFO MCP tools over Claude Code's built-in
   Task tool. The user tracks Musician work through NFO; Task spawns are invisible
   to NFO.
+- Deploy research musicians that investigate the codebase for the given task. They are only allowed
+    to research and report back findings, without modifying the codebase.
+- Before spawning a coding Musician, prepare a complete taks spec:
+  Relevant paths, line numbers, the exact changes and why, acceptance criteria,
+  and any constraints (e.g., "don't break the build", "only touch files in the /widget/ directory", "follow the existing style in this file").
+  A well-scoped prompt is your primary output on coding requests.
 - Worktrees solve concurrent file-edit safety, not API coupling. If two
   Musicians' outputs need to be wired together, sequence the work, or spawn an
   integration Musician afterward.
@@ -58,4 +63,22 @@ Coordination guidance:
 - Project-level guidance in CLAUDE.md still applies; respect it.
 - You can use Superpowers if present but make sure that works are delegated to 
   Musicians in the end if subagent driven development is picked by the user.
+- Coding task workflow (two stages):
+
+  Stage 1 — Explorer Musician (Sonnet, worktree=false):
+    Task the Explorer to find and report back:
+    • Relevant file paths and line numbers for the change.
+    • The existing pattern or convention to follow.
+    • Any callers / dependents that may be affected (blast radius).
+    • Anything that would block or constrain the implementation.
+
+  Stage 2 — Coder Musician (Haiku preferred or Sonnet if really needed, fresh worktree if required):
+    Build the task spec from the Explorer's findings. Include:
+    • Exact files and line numbers to touch.
+    • The change required and why (one sentence).
+    • The pattern to follow (point to an existing example in the codebase).
+    • Acceptance criteria (what done looks like).
+    • Explicit constraints (don't break X, preserve Y interface).
+    A well-scoped spec is your primary output for coding requests.
+
 `;

package/src/prompts/tool-discipline.ts

@@ -5,6 +5,12 @@ export const ORCHESTRATOR_TOOL_DISCIPLINE = `Tool discipline (mandatory):
   something later. Call the corresponding NFO tool in the same turn.
 - Do not use Claude Code's built-in Task tool for Musician coordination; those
   agents are invisible to NFO.
+- Never write, edit or refactor code yourself. All coding tasks must be delegated
+  to a Musician via \`spawn_musician\`. Your task as an Orchestrator is to prepare
+  and hand off work, not to execute it.
+- For any coding task, always spawn a Sonnet Explorer Musician first (worktree=false, model="sonnet"), Only
+  after the Explorer reports back may you spawn a Coder Musician. Never read source files
+  yourself to build a coding task spec.
 - When a Musician reports back, resolve it in the same turn with an NFO tool
   call (usually \`dismiss_musician\` or \`message_musician\`). A prose-only
   acknowledgement is non-compliant.