ma-agents 3.5.6 → 3.6.0

package/lib/merge/roomodes.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * Story 21.3 — .roomodes YAML merger (pure splicer).
+ *
+ * Contract (per AC #5, decision A):
+ *   - Input: two strings — existingYaml (may be empty/undefined when the
+ *     target file does not exist) and templateYaml (the already-composed
+ *     template content; the caller — lib/installer.js — substituted
+ *     {{UNIVERSAL_BLOCK}} via composeInstructionBlock BEFORE calling us).
+ *   - This function MUST NOT call composeInstructionBlock. It treats
+ *     templateYaml as opaque pre-composed input.
+ *   - Parse both as YAML via js-yaml.
+ *   - Output: serialized YAML string whose customModes array is
+ *       [ ...user entries whose slug ∉ MA_AGENTS_OWNED_SLUGS,
+ *         ...all entries from templateYaml.customModes ]
+ *     (preserved-user-first ordering — NFR46 idempotency).
+ *   - Any other top-level YAML keys from existingYaml are preserved (FR176).
+ *   - For each user entry whose slug collides with an ma-agents-owned slug,
+ *     emit exactly one console.warn line naming the slug verbatim (AC #6).
+ *   - Pure function — no file I/O.
+ *
+ * Deterministic serialization (NFR46 — AC #10):
+ *   js-yaml dump options are pinned so consecutive runs with identical
+ *   inputs produce byte-identical output.
+ */
+
+const yaml = require('js-yaml');
+
+/**
+ * Canonical set of slugs owned by ma-agents. Exported for downstream
+ * consumers (Stories 21.10 profile-reconfigure, 21.11 profile-uninstall).
+ * Order is canonical — do not sort or reshuffle.
+ */
+const MA_AGENTS_OWNED_SLUGS = Object.freeze([
+  'bmad-pm',
+  'bmad-architect',
+  'bmad-techlead',
+  'bmad-dev'
+]);
+
+const DUMP_OPTIONS = Object.freeze({
+  indent: 2,
+  lineWidth: -1,
+  noRefs: true,
+  quotingType: '"',
+  sortKeys: false
+});
+
+/**
+ * Parse a YAML string into an object, returning {} for empty/undefined input.
+ * Throws with a descriptive message when the YAML is malformed.
+ *
+ * @param {string|undefined|null} text
+ * @param {string} label - 'existing' or 'template' (for error context)
+ * @returns {object}
+ */
+function parseYaml(text, label) {
+  if (text == null || String(text).trim() === '') return {};
+  let parsed;
+  try {
+    parsed = yaml.load(text);
+  } catch (err) {
+    throw new Error(`mergeRoomodes: failed to parse ${label} YAML — ${err.message}`);
+  }
+  if (parsed == null) return {};
+  if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`mergeRoomodes: ${label} YAML must be a mapping, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`);
+  }
+  return parsed;
+}
+
+/**
+ * Merge the ma-agents roomodes template into an existing .roomodes YAML string.
+ * See file header for the full contract.
+ *
+ * @param {string|undefined} existingYaml - existing file content (or empty string / undefined)
+ * @param {string} templateYaml - already-composed template content (NO placeholders remain)
+ * @param {{warn?: (msg: string) => void}} [options] - injection point for warn emitter (tests)
+ * @returns {string} serialized merged YAML
+ */
+function mergeRoomodes(existingYaml, templateYaml, options = {}) {
+  const warn = typeof options.warn === 'function' ? options.warn : (msg) => console.warn(msg);
+
+  const existing = parseYaml(existingYaml, 'existing');
+  const template = parseYaml(templateYaml, 'template');
+
+  const templateModes = Array.isArray(template.customModes) ? template.customModes : [];
+  if (templateModes.length === 0) {
+    throw new Error('mergeRoomodes: template YAML has no customModes entries — refusing to produce an empty file');
+  }
+
+  const ownedSet = new Set(MA_AGENTS_OWNED_SLUGS);
+  const existingModes = Array.isArray(existing.customModes) ? existing.customModes : [];
+
+  const preservedUserModes = [];
+  for (const entry of existingModes) {
+    // Defensive: tolerate malformed entries (null / non-object / missing slug).
+    // Non-object entries are preserved as-is; entries without a valid slug
+    // cannot collide by definition and are kept in place.
+    const slug = entry && typeof entry === 'object' ? entry.slug : undefined;
+    if (typeof slug === 'string' && ownedSet.has(slug)) {
+      // AC #6 — one warning per colliding slug, slug cited verbatim.
+      warn(`WARNING: .roomodes slug "${slug}" overwritten by ma-agents template`);
+      continue;
+    }
+    preservedUserModes.push(entry);
+  }
+
+  // Build the merged document: non-customModes keys from existing + merged modes.
+  const merged = {};
+  for (const key of Object.keys(existing)) {
+    if (key === 'customModes') continue;
+    merged[key] = existing[key];
+  }
+  merged.customModes = [...preservedUserModes, ...templateModes];
+
+  return yaml.dump(merged, DUMP_OPTIONS);
+}
+
+module.exports = {
+  mergeRoomodes,
+  MA_AGENTS_OWNED_SLUGS,
+  _DUMP_OPTIONS: DUMP_OPTIONS
+};

package/lib/profile.js

@@ -3,12 +3,14 @@
 /**
  * Story 21.1 — Install-time profile persistence and resolution.
  *
- * Public API (exactly three functions):
+ * Public API (four functions):
  *   getProfile(projectRoot)                  -> "on-prem" | "standard" | undefined
  *   setProfile(projectRoot, value)           -> void (persists to .ma-agents.json)
  *   resolveProfile({ persisted, yesMode })   -> resolved value | null (pure, no I/O)
+ *   clearProfile(projectRoot)               -> void (deletes the 'profile' key from .ma-agents.json)
  *
  * NFR44: setProfile is the ONLY mutator of the "profile" field.
+ * Story 21.11: clearProfile is the ONLY remover of the "profile" field.
  * Back-compat: manifests at 1.1.0 without "profile" are read without error;
  *              getProfile returns undefined for missing field.
  *              setProfile migrates 1.1.0 → 1.2.0 on write (profile field is
@@ -104,4 +106,25 @@ function resolveProfile({ persisted, yesMode } = {}) {
   return null;
 }
 
-module.exports = { getProfile, setProfile, resolveProfile };
+/**
+ * Story 21.11 — Removes the 'profile' key from .ma-agents.json entirely.
+ * Does NOT set to null or empty string — the key is deleted so getProfile
+ * returns undefined after this call.
+ * If .ma-agents.json does not exist, this is a no-op.
+ * Preserves all other fields (profileHistory, roomodesOverwriteLog, etc.).
+ */
+function clearProfile(projectRoot) {
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) return;
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return;
+  }
+  if (!manifest || typeof manifest !== 'object') return;
+  delete manifest.profile;
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+module.exports = { getProfile, setProfile, resolveProfile, clearProfile };

package/lib/reconfigure.js

@@ -0,0 +1,334 @@
+'use strict';
+
+/**
+ * Story 21.10 — Profile Reconfigure orchestrator.
+ *
+ * Public API:
+ *   async reconfigure({ projectRoot, argv, promptsLib }) -> { status, from, to }
+ *
+ * Orchestrates:
+ *   1. Pre-flight: refuse --yes, require .ma-agents.json.
+ *   2. Re-run the profile-selection prompt (same shape as Story 21.1 wizard)
+ *      with the currently-persisted value as the default.
+ *   3. Same-value shortcut.
+ *   4. Per-file drift guards:
+ *        - Story 21.3 slug-stomp protection (RoomodesSlugDivergenceError)
+ *          unless --force-roomodes-overwrite.
+ *        - Story 21.5 .clinerules dual-file drift (ClinerulesDualFileDriftError,
+ *          no override).
+ *   5. Two-step confirmation listing files to be modified (AC #7).
+ *   6. Persist new profile via setProfile (source="wizard" log line).
+ *   7. Re-stamp all profile-dependent artifacts by calling the canonical
+ *      updateAgentInstructions helper from lib/installer.js for every agent in
+ *      the manifest. Backups are written by the installer's drift handler via
+ *      the canonical buildBackupFilename helper (Story 21.2 AC #8).
+ *   8. Append a { date, from, to, source: "reconfigure" } entry to
+ *      .ma-agents.json::profileHistory, capped at PROFILE_HISTORY_CAP entries
+ *      with oldest-first eviction.
+ *
+ * Does NOT modify lib/profile.js's public contract — it is a new consumer.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const defaultPrompts = require('prompts');
+
+const { getProfile, setProfile } = require('./profile');
+const installer = require('./installer');
+const { getAgent } = require('./agents');
+
+const MANIFEST_FILE = '.ma-agents.json';
+const PROFILE_HISTORY_CAP = 20;
+const YES_REJECT_MESSAGE =
+  '--yes is not valid for reconfigure — this command is interactive by design to prevent accidental CI-triggered profile changes.';
+
+/**
+ * Story 21.10 AC #9 — thrown when the user has edited content of an
+ * ma-agents-owned `.roomodes` slug in place. Reconfigure would otherwise
+ * silently overwrite those edits. Bypass with --force-roomodes-overwrite.
+ */
+class RoomodesSlugDivergenceError extends Error {
+  constructor({ divergentSlugs, path: roomodesPath }) {
+    const slugs = divergentSlugs.map(s => `"${s}"`).join(', ');
+    const header = `ma-agents-owned .roomodes slug(s) ${slugs} diverge from the shipped template in ${roomodesPath}.`;
+    const guidance = 'Either rename the slug(s) so they are user-owned, or pass --force-roomodes-overwrite to accept the overwrite.';
+    super(`${header}\n${guidance}`);
+    this.name = 'RoomodesSlugDivergenceError';
+    this.divergentSlugs = divergentSlugs;
+    this.path = roomodesPath;
+  }
+}
+
+/**
+ * Story 21.10 AC #1 — named error when .ma-agents.json is absent.
+ * Distinct name so CLI + tests can dispatch on it without message-matching.
+ */
+class ManifestNotFoundError extends Error {
+  constructor(projectRoot) {
+    super(`.ma-agents.json not found at ${projectRoot} — run \`ma-agents install\` first. reconfigure presumes a prior install.`);
+    this.name = 'ManifestNotFoundError';
+    this.projectRoot = projectRoot;
+  }
+}
+
+/**
+ * Story 21.10 AC #6 — thrown when --yes is supplied.
+ * Exposed so callers can dispatch on .name rather than matching the message.
+ */
+class ReconfigureYesRejectedError extends Error {
+  constructor() {
+    super(YES_REJECT_MESSAGE);
+    this.name = 'ReconfigureYesRejectedError';
+  }
+}
+
+/**
+ * Returns the list of project-relative files reconfigure would touch for the
+ * given installed-agent list. Used for the AC #7 confirmation preview and by
+ * tests. Order is stable.
+ */
+function listTouchedFiles(projectRoot, agentEntries) {
+  const files = new Set();
+  for (const agent of agentEntries) {
+    if (!agent) continue;
+    // Primary instruction files.
+    if (Array.isArray(agent.instructionFiles)) {
+      for (const rel of agent.instructionFiles) files.add(rel);
+    }
+    // Extra templates (AGENTS.md, .roomodes, etc.).
+    if (Array.isArray(agent.extraInstructionTemplates)) {
+      for (const entry of agent.extraInstructionTemplates) {
+        if (entry && typeof entry.target === 'string') files.add(entry.target);
+      }
+    }
+  }
+  return Array.from(files).sort();
+}
+
+/**
+ * Story 21.10 AC #9 — slug-stomp protection.
+ *
+ * Parses the project-root `.roomodes` (YAML). For each ma-agents-owned slug
+ * present in the existing file whose customInstructions (or any non-slug field)
+ * differs from the shipped template, record the slug as divergent. Throws
+ * RoomodesSlugDivergenceError when any are divergent and `force` is false.
+ *
+ * If `.roomodes` or the roomodes template is absent, the check is a no-op —
+ * nothing to diverge from.
+ */
+function checkRoomodesSlugDivergence(projectRoot, { force } = {}) {
+  const roomodesPath = path.join(projectRoot, '.roomodes');
+  if (!fs.existsSync(roomodesPath)) return;
+  const templatePath = path.join(installer.EXTRA_TEMPLATE_DIR, 'roomodes.template.yaml');
+  if (!fs.existsSync(templatePath)) return;
+
+  const yaml = require('js-yaml');
+  const { MA_AGENTS_OWNED_SLUGS } = require('./merge/roomodes');
+
+  let existing;
+  let template;
+  try {
+    existing = yaml.load(fs.readFileSync(roomodesPath, 'utf-8')) || {};
+    template = yaml.load(fs.readFileSync(templatePath, 'utf-8')) || {};
+  } catch {
+    // Malformed YAML — not our problem at this layer; let the merger surface it.
+    return;
+  }
+
+  const existingModes = Array.isArray(existing.customModes) ? existing.customModes : [];
+  const templateModes = Array.isArray(template.customModes) ? template.customModes : [];
+  const templateBySlug = new Map();
+  for (const m of templateModes) {
+    if (m && typeof m === 'object' && typeof m.slug === 'string') {
+      templateBySlug.set(m.slug, m);
+    }
+  }
+
+  const divergent = [];
+  for (const entry of existingModes) {
+    if (!entry || typeof entry !== 'object') continue;
+    const slug = entry.slug;
+    if (typeof slug !== 'string') continue;
+    if (!MA_AGENTS_OWNED_SLUGS.includes(slug)) continue;
+    const tpl = templateBySlug.get(slug);
+    if (!tpl) {
+      // Owned slug present but not in template — treat as user-modified.
+      divergent.push(slug);
+      continue;
+    }
+    // Compare YAML dumps of the two entries minus placeholder expansion. The
+    // template still contains `{{UNIVERSAL_BLOCK}}` sentinels inside
+    // customInstructions; compare all other fields strictly. For
+    // customInstructions, ignore the {{UNIVERSAL_BLOCK}}-bearing line and
+    // compare the surrounding static text.
+    const normalize = (mode) => {
+      const copy = { ...mode };
+      // Strip customInstructions — it contains per-profile composed text after
+      // installer stamping; its content legitimately changes per profile.
+      delete copy.customInstructions;
+      return yaml.dump(copy, { sortKeys: true });
+    };
+    if (normalize(entry) !== normalize(tpl)) {
+      divergent.push(slug);
+    }
+  }
+
+  if (divergent.length > 0 && !force) {
+    throw new RoomodesSlugDivergenceError({
+      divergentSlugs: divergent,
+      path: path.relative(projectRoot, roomodesPath).replace(/\\/g, '/') || '.roomodes'
+    });
+  }
+}
+
+/**
+ * Story 21.10 AC #11 — append { date, from, to, source } to
+ * .ma-agents.json::profileHistory, capped at PROFILE_HISTORY_CAP entries
+ * (oldest-first eviction when the cap is exceeded).
+ *
+ * Performed as a read-modify-write through the same JSON-IO path used by
+ * setProfile so we avoid parallel I/O semantics (AC spec: "Ensure the write
+ * goes through setProfile or an equivalent atomic write path").
+ */
+function appendProfileHistory(projectRoot, entry) {
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  // Read current manifest (setProfile has just written to it).
+  const raw = fs.readFileSync(manifestPath, 'utf-8');
+  const manifest = JSON.parse(raw);
+  const history = Array.isArray(manifest.profileHistory) ? manifest.profileHistory.slice() : [];
+  history.push(entry);
+  while (history.length > PROFILE_HISTORY_CAP) {
+    history.shift(); // oldest-first eviction
+  }
+  manifest.profileHistory = history;
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Main orchestrator.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.projectRoot
+ * @param {string[]} [opts.argv]           raw argv (excluding the 'reconfigure' verb)
+ * @param {object}   [opts.promptsLib]     prompts implementation (for tests)
+ * @param {Date}     [opts.now]            date injection (for tests)
+ * @returns {Promise<{status: 'unchanged'|'aborted'|'reconfigured', from: string|undefined, to: string|undefined}>}
+ */
+async function reconfigure({ projectRoot, argv = [], promptsLib, now } = {}) {
+  const prompts = promptsLib || defaultPrompts;
+  const nowDate = now || new Date();
+
+  // --- AC #6: --yes rejection ---
+  if (argv.includes('--yes')) {
+    throw new ReconfigureYesRejectedError();
+  }
+
+  const forceRoomodes = argv.includes('--force-roomodes-overwrite');
+
+  // --- AC #1: require .ma-agents.json ---
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) {
+    throw new ManifestNotFoundError(projectRoot);
+  }
+
+  const previousProfile = getProfile(projectRoot);
+
+  // --- AC #2: re-prompt with persisted value as default ---
+  const choices = [
+    { title: 'Yes — apply local-LLM guardrails (recommended for non-Claude models)', value: 'on-prem' },
+    { title: 'No  — standard install (Claude on web, Anthropic API, etc.)', value: 'standard' }
+  ];
+  const initialIdx = previousProfile === 'on-prem' ? 0 : 1;
+  const promptResponse = await prompts({
+    type: 'select',
+    name: 'chosenProfile',
+    message: `Current profile: ${previousProfile || '(unset)'}. Change to?`,
+    choices,
+    initial: initialIdx
+  });
+  const chosenProfile = promptResponse && promptResponse.chosenProfile;
+  if (!chosenProfile) {
+    // User hit Ctrl-C at the prompt — abort silently, nothing modified.
+    return { status: 'aborted', from: previousProfile, to: undefined };
+  }
+
+  // --- AC #4: same-value short-circuit ---
+  if (chosenProfile === previousProfile) {
+    console.log(`Profile unchanged: ${chosenProfile}. No re-stamp needed.`);
+    return { status: 'unchanged', from: previousProfile, to: chosenProfile };
+  }
+
+  // --- Enumerate installed agents from manifest BEFORE any mutation ---
+  const rawManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  const agentIds = installer.getManifestAgents(rawManifest);
+  const agentEntries = agentIds.map(id => getAgent(id)).filter(Boolean);
+
+  // --- AC #9: slug-stomp pre-check (before any write) ---
+  checkRoomodesSlugDivergence(projectRoot, { force: forceRoomodes });
+
+  // --- AC #10: .clinerules dual-file drift pre-check (no override) ---
+  //            Only check when Cline is installed.
+  const clineInstalled = agentEntries.some(a => a && a.id === 'cline');
+  if (clineInstalled) {
+    installer.checkClinerulesDualFileDrift(projectRoot);
+  }
+
+  // --- AC #7: two-step confirmation — list files and ask to continue ---
+  const touched = listTouchedFiles(projectRoot, agentEntries);
+  const list = touched.length ? touched.map(f => `  - ${f}`).join('\n') : '  (no files)';
+  console.log(`The following files will be updated to match profile=${chosenProfile}:\n${list}`);
+  const continueResp = await prompts({
+    type: 'confirm',
+    name: 'proceed',
+    message: 'Continue?',
+    initial: false
+  });
+  if (!continueResp || continueResp.proceed !== true) {
+    console.log(chalk.gray('Aborted — no files modified.'));
+    return { status: 'aborted', from: previousProfile, to: chosenProfile };
+  }
+
+  // --- AC #3: persist new profile, log canonical format ---
+  setProfile(projectRoot, chosenProfile);
+  console.log(chalk.cyan(`Using profile: ${chosenProfile} (from wizard)`));
+
+  // --- AC #5 + #8: re-stamp all profile-dependent artifacts.
+  //                 updateAgentInstructions handles drift detection + backup
+  //                 via the canonical buildBackupFilename helper; yesMode=true
+  //                 suppresses per-file interactive prompts since we've already
+  //                 obtained a single global confirmation in the step above.
+  for (const agent of agentEntries) {
+    try {
+      await installer._testUpdateAgentInstructions(agent, projectRoot, { yesMode: true });
+    } catch (err) {
+      // Surface the error to the caller but make sure the history is NOT
+      // appended — incomplete re-stamp should not record a success event.
+      throw err;
+    }
+  }
+
+  // --- AC #11: append profileHistory entry (capped) ---
+  appendProfileHistory(projectRoot, {
+    date: nowDate.toISOString(),
+    from: previousProfile,
+    to: chosenProfile,
+    source: 'reconfigure'
+  });
+
+  console.log(chalk.green(`Reconfigure complete: ${previousProfile} → ${chosenProfile}`));
+  return { status: 'reconfigured', from: previousProfile, to: chosenProfile };
+}
+
+module.exports = {
+  reconfigure,
+  RoomodesSlugDivergenceError,
+  ManifestNotFoundError,
+  ReconfigureYesRejectedError,
+  PROFILE_HISTORY_CAP,
+  YES_REJECT_MESSAGE,
+  // exposed for tests
+  listTouchedFiles,
+  checkRoomodesSlugDivergence,
+  appendProfileHistory
+};

package/lib/templates/agents-md.template.md

@@ -0,0 +1,67 @@
+# Project Agent Instructions
+
+This file is auto-discovered by OpenCode and any agent that respects `AGENTS.md`.
+It establishes universal safety rules, text-vs-file discipline, and BMAD phase
+discipline for every agent operating in this project.
+
+## Universal Rules
+
+The universal rules block below is stamped and maintained by ma-agents. Edit
+outside the HTML-comment `MA-AGENTS` start and end markers to preserve your
+own additions — content inside the markers is regenerated on every install.
+
+<!-- MA-AGENTS-START -->
+<!-- MA-AGENTS-END -->
+
+## Critical Behavior Rules
+
+These rules are non-negotiable across every profile and every agent.
+
+- **Never create files in `~/.claude/` or any user home directory.** All
+  project artifacts must land inside the current working directory. Home-
+  directory writes cross-contaminate between projects and are a common source
+  of secret/config leakage.
+- **Never write outside the project root without an explicit user request
+  naming the absolute path.** "Write to disk" means the project, not the
+  operator's machine.
+- **Do not modify files you did not read first.** Read the current content
+  before proposing or performing an edit — blind writes silently destroy user
+  work.
+
+## BMAD Phase Declaration
+
+BMAD-METHOD organizes work into four phases. Respect the currently declared
+phase; do not skip ahead to the next phase without a phase transition signal
+from the user, the active skill, or the story status.
+
+- **Discovery / PM (analysis, planning).** Deliverables: product briefs,
+  PRDs, market and domain research, epics and stories lists. Do NOT produce
+  code, architecture diagrams, or implementation artifacts in this phase.
+  When asked "what do you think", respond in text.
+- **Architecture.** Deliverables: solution design, component boundaries,
+  data-flow, interface contracts. Do NOT write application code or skill
+  implementations. Narrate decisions and capture them as documents.
+- **Tech Lead / Stories.** Deliverables: individual story files with full
+  acceptance criteria, task breakdowns, and dev notes. Do NOT begin
+  implementation — stories are contracts the implementer consumes later.
+- **Implementation.** Deliverables: code, tests, and the Dev Agent Record on
+  the story file. At this phase, write files. Do NOT retroactively fabricate
+  planning documents for code that already exists — flag the gap instead.
+
+When no phase is declared (no active skill, no story in progress, no explicit
+user statement), ask before assuming.
+
+## Project BMAD Output Structure
+
+BMAD artifacts live under `_bmad-output/` (or the paths configured in
+`_bmad/bmm/config.yaml` when present). The install-time resolver logs the
+resolved paths on each run; consult that log output if in doubt.
+
+- **Planning artifacts** — PRDs, product briefs, market and domain research.
+- **Architecture artifacts** — solution design, component boundaries. May be
+  co-located with planning artifacts when no separate directory is configured.
+- **Implementation artifacts (stories)** — individual story files and their
+  Dev Agent Records.
+
+Always consult the `MANIFEST.yaml` referenced inside the universal block above
+for the full list of installed skills and their locations.

package/lib/templates/clinerules.template.md

@@ -0,0 +1,13 @@
+# Cline Project Rules
+
+These rules apply to every Cline session in this project. Cline auto-loads
+`.clinerules` (and `.cline/clinerules.md`) on session start. The universal rule
+body below is stamped and maintained by ma-agents — edit outside the HTML
+comment `MA-AGENTS` start and end markers to preserve your own additions;
+content inside the markers is regenerated on every install.
+
+Use Cline's Architect mode for BMAD planning phases (PM, Architect, Tech Lead).
+Switch to Code mode only for the implementation phase.
+
+<!-- MA-AGENTS-START -->
+<!-- MA-AGENTS-END -->

package/lib/templates/instruction-block-onprem.template.md

@@ -0,0 +1,86 @@
+## On-Prem / Local-LLM Guardrails
+
+These rules apply ONLY when this project is installed with `profile: on-prem`.
+They are appended to the universal block by the composer in `lib/installer.js`.
+Local LLMs (Nemotron, Qwen, DeepSeek, Llama-3, etc. served via vLLM, Ollama, or
+TGI) fail in patterns cloud LLMs rarely exhibit — the rules below pin those
+failure modes down explicitly. Keep these rules verbatim in every response
+context where tool use is possible.
+
+### Reasoning mode: `/no_think` on planning-phase prompts
+
+Local reasoning-capable models (Nemotron-variants and similar) default to
+chain-of-thought reasoning that bloats planning-phase prompts with internal
+deliberation the operator does not need to read. Prepend the literal token
+`/no_think` as the first line of any planning-phase system prompt or user turn
+you compose. The token is consumed by the serving layer and suppresses the
+model's reasoning trace on that turn.
+
+- Planning-phase turns (PM, Architect, Tech Lead): begin the turn with
+  `/no_think` on its own line. Reasoning-mode OFF.
+- Implementation-phase turns (Dev): omit `/no_think`. Reasoning-mode ON is
+  desirable for stepwise code synthesis and debugging.
+- Review / QA turns: omit `/no_think` when the review benefits from explicit
+  reasoning (root-cause analysis). Include `/no_think` for mechanical checks
+  (lint, style, formatting).
+
+If the downstream serving layer does not recognize `/no_think`, it is a no-op
+text token — safe to include unconditionally on planning turns.
+
+### No writes to `~/.claude/` or any user home directory
+
+Local LLMs frequently hallucinate paths under `~/.claude/`, `~/.cache/`,
+`~/Library/`, or `%APPDATA%` — imitating patterns learned from Claude Code and
+Cursor training data. These paths are OUTSIDE the project and cross-contaminate
+other projects on the same machine.
+
+- NEVER create, write, or modify files under `~/.claude/`, `~/.cache/`,
+  `~/Library/`, `~/AppData/`, `%APPDATA%`, or any path that resolves outside
+  the current project directory.
+- All project artifacts — code, configuration, logs, scratch notes, and agent
+  state — MUST land under the current working directory (the project root) or
+  an explicitly-named subdirectory thereof.
+- When a tool call appears to target a home-directory path, refuse the write
+  and respond in text explaining the violation. Ask the user for an explicit
+  in-project path before proceeding.
+
+### No `str_replace_editor` or Claude Code-specific tools
+
+Local LLMs hallucinate Anthropic-proprietary tools — most commonly
+`str_replace_editor`, `text_editor_20241022`, and `computer_use_preview` — that
+do NOT exist outside the Anthropic API. Calling them against a local-LLM
+serving layer produces a tool-not-found error or, worse, a silent no-op.
+
+- Do NOT emit tool calls named `str_replace_editor`, `text_editor_*`,
+  `computer_use_*`, or any other tool whose name includes `str_replace_editor`
+  or matches Anthropic-specific tool schemas.
+- Use only tools enumerated in the active tool manifest (`MANIFEST.yaml`) or
+  the IDE's native tool surface (Roo Code, Cline, OpenCode native tools).
+- When you want to edit a file, use the native file-write tool of the active
+  agent — not `str_replace_editor`. If unsure what tool is available, list
+  available tools or ask the user before emitting a tool call.
+
+### Per-phase reasoning and sampling guidance
+
+Local LLMs require tighter sampling control than cloud LLMs. Use these defaults
+unless the serving layer overrides them.
+
+- **Planning phase (PM, Architect, Tech Lead):**
+  - Reasoning: OFF (`/no_think` prepended).
+  - Temperature: low (0.0 – 0.3). Planning artifacts should be deterministic
+    and reproducible.
+  - Top-p: 0.9 or unset. Top-k: unset.
+  - Max tokens: generous (8k+) — planning documents are long.
+- **Implementation phase (Dev):**
+  - Reasoning: ON (omit `/no_think`).
+  - Temperature: moderate (0.3 – 0.6). Code synthesis benefits from controlled
+    exploration but not creative rewriting.
+  - Top-p: 0.95 or unset. Top-k: unset.
+  - Max tokens: generous (8k+) — full-file rewrites are common.
+- **Review / QA phase:**
+  - Reasoning: ON for root-cause analysis; OFF for mechanical checks.
+  - Temperature: low (0.0 – 0.2). Reviews should be deterministic.
+
+If the serving layer applies its own sampler defaults, the per-phase guidance
+above is advisory — but the phase boundary and `/no_think` placement are
+load-bearing and MUST be honored on every turn.