nfo-cli 0.0.4-improve-prompting → 0.0.6-a89844d-dev

package/src/prompts/orchestrator-role.ts

@@ -1,84 +0,0 @@
-import { ORCHESTRATOR_TOOL_DISCIPLINE } from "./tool-discipline.js";
-
-export const ORCHESTRATOR_ROLE_PROMPT_V1 = `You are the Orchestrator of an NFO orchestra.
-
-NFO (NoFluffOrchestra) is a TUI for multi-agent work on the user's repository.
-You coordinate Musicians (other Claude Code agents) via the NFO MCP tools.
-
-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. 
-    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.
-
-  message_musician({ musician_id, message })
-    Send a message to a Musician. If the Musician is idle, NFO delivers it
-    immediately. If the Musician is still working, NFO queues it and delivers
-    it automatically on the next idle boundary.
-
-  query_musician({ musician_id, lines? })
-    Read the most recent visible output from the Musician's pane. Use this
-    sparingly — capture-pane is heuristic and may include rendering artifacts.
-
-  list_musicians()
-    Return all currently-active Musicians with their status.
-
-  dismiss_musician({ musician_id, archive_worktree? })
-    Tear down a Musician. The worktree is archived under
-    .../archive/<musician_id>/worktree (the branch is preserved). Pass
-    archive_worktree=false to drop the worktree entirely. By default drop the worktree. Ask
-    the user before archiving, as these can accumulate and consume disk space.
-
-  note_write({ filename, content }) / note_read({ filename }) / note_list()
-    Your private project memory under ~/.config/nfo/projects/<key>/notes/.
-    On every fresh Orchestrator session, the contents of notes/overview.md
-    and notes/decisions.md are loaded into your context automatically.
-    Use these to record decisions, open questions, and durable project
-    understanding the user would want you to remember next session.
-
-Coordination guidance:
-
-- ${ORCHESTRATOR_TOOL_DISCIPLINE.trim().replace(/\n/g, "\n  ")}
-- 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.
-- The orchestra's permission level applies to every Musician you spawn.
-- Prefer concise follow-up nudges. NFO persists them in JSONL and batches any
-  backlog before a Musician truly becomes idle again.
-- When a Musician calls \`report_done\` and no queued follow-up is waiting, NFO
-  pushes that completion back into your Claude session. Review the report
-  promptly and either dismiss the Musician or send the next iteration.
-- 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

@@ -1,41 +0,0 @@
-export const ORCHESTRATOR_TOOL_DISCIPLINE = `Tool discipline (mandatory):
-
-- Use the NFO MCP tools for all musician coordination and orchestra-local memory.
-- Never merely say that you will spawn, message, query, list, dismiss, or note
-  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.
-`;
-
-export const MUSICIAN_TOOL_DISCIPLINE = `Tool discipline (mandatory):
-
-- Use NFO MCP tools for orchestra coordination. Plain-text status reports are
-  not a valid handoff.
-- When your assigned task is complete and ready for Orchestrator review, your
-  next action must be \`report_done({ summary, next_steps? })\`.
-- Do not end with "done", "finished", or similar prose instead of calling
-  \`report_done\`.
-- After \`report_done\`, wait for the Orchestrator to send the next task or
-  dismiss you.
-`;
-
-export function buildMusicianInitialPrompt(task: string): string {
-  const trimmedTask = task.trim();
-  const body = trimmedTask.length > 0 ? trimmedTask : task;
-
-  return `${body}
-
-NFO operating contract (mandatory):
-- Use the NFO MCP tools for orchestra coordination.
-- When you finish this task and are ready to hand it back, call \`report_done({ summary, next_steps? })\` instead of replying with a plain-text completion message.
-- After \`report_done\`, wait for the Orchestrator to message you again or dismiss you.`;
-}

package/src/repo.ts

@@ -1,14 +0,0 @@
-import { execa } from 'execa';
-
-export async function resolveRepoRoot(cwd: string): Promise<string | null> {
-  try {
-    const { stdout } = await execa('git', ['rev-parse', '--show-toplevel'], {
-      cwd,
-      reject: false,
-    });
-    const trimmed = stdout.trim();
-    return trimmed.length > 0 ? trimmed : null;
-  } catch {
-    return null;
-  }
-}

package/src/shell-quote.ts

@@ -1,7 +0,0 @@
-export function shellQuote(value: string): string {
-  if (value.length === 0) {
-    return "''";
-  }
-
-  return `'${value.replace(/'/g, `'\"'\"'`)}'`;
-}

package/src/state-updaters.ts

@@ -1,132 +0,0 @@
-import { readState, writeState } from './state.js';
-import type {
-  ArchivedMusician,
-  Musician,
-  MusicianReport,
-  MusicianStatus,
-  OrchestraState,
-} from './state.types.js';
-
-async function update(
-  orchestraId: string,
-  mutator: (s: OrchestraState) => void,
-): Promise<void> {
-  const state = await readState(orchestraId);
-  if (!state) {
-    throw new Error(`Unknown orchestra: ${orchestraId}`);
-  }
-  mutator(state);
-  await writeState(orchestraId, state);
-}
-
-export async function addMusician(orchestraId: string, m: Musician): Promise<void> {
-  await update(orchestraId, (s) => { s.musicians.push(m); });
-}
-
-export async function setMusicianStatus(
-  orchestraId: string,
-  musicianId: string,
-  status: MusicianStatus,
-  pendingPermission?: string | null,
-): Promise<void> {
-  await update(orchestraId, (s) => {
-    const m = s.musicians.find((mu) => { return mu.id === musicianId; });
-    if (!m) {
-      throw new Error(`Unknown musician: ${musicianId}`);
-    }
-    m.status = status;
-    if (pendingPermission !== undefined) {
-      m.pending_permission = pendingPermission;
-    }
-  });
-}
-
-export async function setMusicianClaudeSessionId(
-  orchestraId: string,
-  musicianId: string,
-  sessionId: string,
-): Promise<void> {
-  await update(orchestraId, (s) => {
-    const m = s.musicians.find((mu) => { return mu.id === musicianId; });
-    if (!m) {
-      throw new Error(`Unknown musician: ${musicianId}`);
-    }
-    m.claude_session_id = sessionId;
-  });
-}
-
-export async function setMusicianTmuxWindowId(
-  orchestraId: string,
-  musicianId: string,
-  tmuxWindowId: string,
-): Promise<void> {
-  await update(orchestraId, (s) => {
-    const m = s.musicians.find((mu) => { return mu.id === musicianId; });
-    if (!m) {
-      throw new Error(`Unknown musician: ${musicianId}`);
-    }
-    m.tmux_window_id = tmuxWindowId;
-  });
-}
-
-export async function touchMusicianActivity(
-  orchestraId: string,
-  musicianId: string,
-  timestamp?: string,
-): Promise<void> {
-  const ts = timestamp ?? new Date().toISOString();
-  await update(orchestraId, (s) => {
-    const m = s.musicians.find((mu) => { return mu.id === musicianId; });
-    if (!m) {
-      throw new Error(`Unknown musician: ${musicianId}`);
-    }
-    m.last_activity = ts;
-  });
-}
-
-export async function setMusicianLatestReport(
-  orchestraId: string,
-  musicianId: string,
-  report: MusicianReport | null,
-): Promise<void> {
-  await update(orchestraId, (s) => {
-    const m = s.musicians.find((mu) => { return mu.id === musicianId; });
-    if (!m) {
-      throw new Error(`Unknown musician: ${musicianId}`);
-    }
-    m.latest_report = report;
-  });
-}
-
-export async function setOrchestratorSessionId(
-  orchestraId: string,
-  sessionId: string,
-): Promise<void> {
-  await update(orchestraId, (s) => { s.orchestrator_session_id = sessionId; });
-}
-
-export interface ArchiveArgs {
-  summary: string | null;
-  dismissedAt?: string;
-}
-
-export async function archiveMusician(
-  orchestraId: string,
-  musicianId: string,
-  args: ArchiveArgs,
-): Promise<void> {
-  await update(orchestraId, (s) => {
-    const idx = s.musicians.findIndex((mu) => { return mu.id === musicianId; });
-    if (idx === -1) {
-      throw new Error(`Unknown musician: ${musicianId}`);
-    }
-    const [m] = s.musicians.splice(idx, 1);
-    const archived: ArchivedMusician = {
-      ...m,
-      status: 'stopped',
-      dismissed_at: args.dismissedAt ?? new Date().toISOString(),
-      summary: args.summary,
-    };
-    s.archived_musicians.push(archived);
-  });
-}

package/src/state.ts

@@ -1,49 +0,0 @@
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import lockfile from 'proper-lockfile';
-import {
-  notesDir,
-  logsDir,
-  messageLogsDir,
-  worktreesDir,
-  archiveDir,
-  stateFile,
-  orchestraDir,
-} from './config.js';
-import type { OrchestraState } from './state.types.js';
-
-export async function ensureOrchestraDir(projectKey: string): Promise<void> {
-  await mkdir(orchestraDir(projectKey), { recursive: true });
-  await mkdir(notesDir(projectKey), { recursive: true });
-  await mkdir(logsDir(projectKey), { recursive: true });
-  await mkdir(messageLogsDir(projectKey), { recursive: true });
-  await mkdir(worktreesDir(projectKey), { recursive: true });
-  await mkdir(archiveDir(projectKey), { recursive: true });
-}
-
-export async function readState(projectKey: string): Promise<OrchestraState | null> {
-  const file = stateFile(projectKey);
-  if (!existsSync(file)) return null;
-  const buf = await readFile(file, 'utf8');
-  return JSON.parse(buf) as OrchestraState;
-}
-
-export async function writeState(projectKey: string, state: OrchestraState): Promise<void> {
-  const file = stateFile(projectKey);
-  await mkdir(dirname(file), { recursive: true });
-
-  // proper-lockfile needs the target file to exist before it can lock it.
-  if (!existsSync(file)) {
-    await writeFile(file, '{}', 'utf8');
-  }
-
-  const release = await lockfile.lock(file, { retries: { retries: 5, minTimeout: 50 } });
-  try {
-    const tmp = `${file}.tmp.${process.pid}.${Date.now()}`;
-    await writeFile(tmp, JSON.stringify(state, null, 2), 'utf8');
-    await rename(tmp, file);
-  } finally {
-    await release();
-  }
-}

package/src/state.types.ts

@@ -1,67 +0,0 @@
-import type { PermissionLevel } from "./permission.js";
-
-export type MusicianStatus =
-  | "working"
-  | "idle"
-  | "awaiting_permission"
-  | "stopped";
-export type SubagentModel = "sonnet" | "haiku";
-
-export interface MusicianReport {
-  summary: string;
-  next_steps: string | null;
-  reported_at: string;
-}
-
-export interface Musician {
-  id: string;
-  name: string;
-  task_summary: string;
-  status: MusicianStatus;
-  pending_permission?: string | null;
-  tmux_window_id: string;
-  claude_session_id: string | null;
-  worktree_path: string | null;
-  branch: string | null;
-  spawned_at: string;
-  last_activity: string;
-  latest_report?: MusicianReport | null;
-  model?: SubagentModel;
-}
-
-export interface ArchivedMusician extends Musician {
-  dismissed_at: string;
-  summary: string | null;
-}
-
-export interface OrchestraState {
-  version: number;
-  orchestra_id: string;
-  project_path: string;
-  created_at: string;
-  permission_level: PermissionLevel;
-  notify_on_permission?: boolean;
-  orchestrator_session_id: string | null;
-  musicians: Musician[];
-  archived_musicians: ArchivedMusician[];
-}
-
-export function makeInitialState(args: {
-  orchestraId: string;
-  projectPath: string;
-  permissionLevel: PermissionLevel;
-  notifyOnPermission?: boolean;
-}): OrchestraState {
-  const now = new Date().toISOString();
-  return {
-    version: 1,
-    orchestra_id: args.orchestraId,
-    project_path: args.projectPath,
-    created_at: now,
-    permission_level: args.permissionLevel,
-    notify_on_permission: args.notifyOnPermission ?? false,
-    orchestrator_session_id: null,
-    musicians: [],
-    archived_musicians: [],
-  };
-}

package/src/tmux.ts

@@ -1,226 +0,0 @@
-import { execa } from 'execa';
-import { DASHBOARD_WINDOW_NAME } from './dashboard.js';
-
-const NFO_SESSION_MATCH = '#{m:^nfo-,#{session_name}}';
-const EMBED_SESSION_SUFFIX = '-embed';
-const REQUIRED_TERMINAL_FEATURES = [
-  'xterm*:extkeys',
-  'screen*:extkeys',
-  'tmux*:extkeys',
-];
-
-export function sessionName(projectKey: string): string {
-  return `nfo-${projectKey}`;
-}
-
-export function embeddedSessionName(projectKey: string): string {
-  return `${sessionName(projectKey)}${EMBED_SESSION_SUFFIX}`;
-}
-
-export async function sessionExists(name: string): Promise<boolean> {
-  const result = await execa('tmux', ['has-session', '-t', name], { reject: false });
-  return result.exitCode === 0;
-}
-
-export async function createDetachedSession(
-  name: string,
-  cwd: string,
-  width = 220,
-  height = 50,
-): Promise<void> {
-  await execa('tmux', ['new-session', '-d', '-s', name, '-c', cwd, '-x', String(width), '-y', String(height)]);
-}
-
-export async function createDetachedWindow(
-  session: string,
-  windowName: string,
-  cwd: string,
-  command?: string,
-): Promise<string> {
-  const args = [
-    'new-window',
-    '-t',
-    session,
-    '-n',
-    windowName,
-    '-c',
-    cwd,
-    '-d',
-    '-P',
-    '-F',
-    '#{pane_id}',
-  ];
-  if (command) {
-    args.push(command);
-  }
-  const { stdout } = await execa('tmux', args);
-  return stdout.trim();
-}
-
-export async function killSession(name: string): Promise<void> {
-  await execa('tmux', ['kill-session', '-t', name], { reject: false });
-}
-
-export async function createLinkedSession(
-  sourceSession: string,
-  linkedSession: string,
-  cwd: string,
-): Promise<void> {
-  await execa('tmux', ['new-session', '-d', '-t', sourceSession, '-s', linkedSession, '-c', cwd]);
-}
-
-export async function ensureEmbeddedSession(
-  sourceSession: string,
-  linkedSession: string,
-  cwd: string,
-): Promise<void> {
-  if (!(await sessionExists(linkedSession))) {
-    await createLinkedSession(sourceSession, linkedSession, cwd);
-  }
-  await ensureNfoSessionUi(linkedSession);
-  await selectWindow(linkedSession, '0');
-}
-
-export async function attachSession(name: string): Promise<void> {
-  // Inherits stdio so the user's terminal becomes the tmux client.
-  await execa('tmux', ['attach-session', '-t', name], { stdio: 'inherit' });
-}
-
-export async function detachCurrentClient(): Promise<void> {
-  await execa('tmux', ['detach-client']);
-}
-
-export async function splitWindowHorizontal(
-  target: string,
-  columns: number,
-  command?: string,
-): Promise<void> {
-  // Use -l (absolute column count) rather than -p (percent) because percent
-  // requires an attached client with a known terminal size.
-  const args = ['split-window', '-h', '-l', String(columns), '-t', target];
-  if (command) args.push(command);
-  await execa('tmux', args);
-}
-
-export async function sendKeys(target: string, text: string, withEnter: boolean): Promise<void> {
-  // Use -l (literal) to avoid keystroke interpretation.
-  await execa('tmux', ['send-keys', '-l', '-t', target, '--', text]);
-  if (withEnter) {
-    await execa('tmux', ['send-keys', '-t', target, 'Enter']);
-  }
-}
-
-export async function respawnPane(target: string, command: string): Promise<void> {
-  await execa('tmux', ['respawn-pane', '-k', '-t', target, command]);
-}
-
-export async function capturePane(target: string, lines: number): Promise<string> {
-  const { stdout } = await execa('tmux', [
-    'capture-pane',
-    '-p',
-    '-t',
-    target,
-    '-S',
-    `-${lines}`,
-  ]);
-  return stdout;
-}
-
-export async function captureVisiblePane(target: string): Promise<string> {
-  const { stdout } = await execa('tmux', [
-    'capture-pane',
-    '-p',
-    '-N',
-    '-t',
-    target,
-    '-S',
-    '0',
-    '-E',
-    '-',
-  ]);
-  return stdout;
-}
-
-export async function setSessionOption(name: string, option: string, value: string): Promise<void> {
-  await execa('tmux', ['set-option', '-t', name, option, value]);
-}
-
-export async function setPaneOption(target: string, option: string, value: string): Promise<void> {
-  await execa('tmux', ['set-option', '-p', '-t', target, option, value]);
-}
-
-function parseArrayOptionValue(line: string, option: string): string {
-  return line.replace(new RegExp(`^${option}\\[\\d+\\]\\s+`, 'u'), '');
-}
-
-async function ensureSessionTerminalFeatures(
-  name: string,
-  features: string[],
-): Promise<void> {
-  const { stdout } = await execa('tmux', ['show-options', '-t', name, 'terminal-features']);
-  const configured = new Set(
-    stdout
-      .split('\n')
-      .map((line) => { return line.trim(); })
-      .filter((line) => { return line.length > 0; })
-      .map((line) => { return parseArrayOptionValue(line, 'terminal-features'); }),
-  );
-
-  for (const feature of features) {
-    if (configured.has(feature)) {
-      continue;
-    }
-    await execa('tmux', ['set-option', '-as', '-t', name, 'terminal-features', `,${feature}`]);
-  }
-}
-
-async function getRootBindingLine(key: string): Promise<string | null> {
-  const { stdout } = await execa('tmux', ['list-keys', '-T', 'root']);
-  const line = stdout
-    .split('\n')
-    .map((entry) => { return entry.trim(); })
-    .find((entry) => { return entry.startsWith(`bind-key -T root ${key} `); });
-  return line ?? null;
-}
-
-async function ensureRootKeyBinding(
-  key: string,
-  nfoCommand: string,
-): Promise<void> {
-  const existing = await getRootBindingLine(key);
-  if (existing && !existing.includes(NFO_SESSION_MATCH)) {
-    // Respect user-defined bindings that are not NFO-managed.
-    return;
-  }
-  await execa('tmux', [
-    'bind-key',
-    '-n',
-    key,
-    'if-shell',
-    '-F',
-    NFO_SESSION_MATCH,
-    nfoCommand,
-    `send-keys ${key}`,
-  ]);
-}
-
-export async function ensureNfoNavigationBindings(): Promise<void> {
-  await ensureRootKeyBinding('F6', `select-window -t :${DASHBOARD_WINDOW_NAME}`);
-  await ensureRootKeyBinding('F7', 'select-window -t :0');
-}
-
-export async function ensureNfoSessionUi(name: string): Promise<void> {
-  await setSessionOption(name, 'mouse', 'on');
-  await setSessionOption(name, 'status', 'off');
-  await setSessionOption(name, 'extended-keys', 'on');
-  await ensureSessionTerminalFeatures(name, REQUIRED_TERMINAL_FEATURES);
-  await ensureNfoNavigationBindings();
-}
-
-export async function selectWindow(name: string, windowTarget: string): Promise<void> {
-  await execa('tmux', ['select-window', '-t', `${name}:${windowTarget}`]);
-}
-
-export async function selectPane(target: string): Promise<void> {
-  await execa('tmux', ['select-pane', '-t', target]);
-}

package/src/tui/activity-line.ts

@@ -1,16 +0,0 @@
-const MAX_LEN = 60;
-
-export function extractActivityLine(paneText: string): string {
-  const lines = paneText.split('\n');
-  let last = '';
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed.length > 0) {
-      last = trimmed;
-    }
-  }
-  if (last.length > MAX_LEN) {
-    return last.slice(0, MAX_LEN - 1) + '…';
-  }
-  return last;
-}