ma-agents 3.13.0 → 3.13.2-skillname.0

package/lib/installer.js

@@ -166,7 +166,12 @@ function composeInstructionBlock({ profile, projectRoot } = {}) {
     composed += '\n\n' + onprem.replace(/\s+$/, '');
   }
 
-  return composed + '\n';
+  // Bug 27.10 — the source templates are authored with CRLF line endings, but the
+  // segment seams and terminator above are hand-written LF. That mix yields a block
+  // whose body lines are CRLF while the joins are LF. Normalize to pure LF once here
+  // so the composed block is EOL-consistent regardless of how templates were checked
+  // out on Windows, and so downstream marker-merge (which assumes LF) stays stable.
+  return composed.replace(/\r\n/g, '\n') + '\n';
 }
 
 /**
@@ -245,6 +250,17 @@ function resolveBmadOutputDirs(projectRoot) {
 const CLAUDE_CODE_HOOK_ID = 'ma-agents-verify-manifest';
 const CLAUDE_CODE_SETTINGS_FILE = '.claude/settings.json';
 
+// Bug 27.8 — the SessionStart hook must point at a path that exists in a real
+// (npx/node_modules) install, not at the package's own `lib/` which is never
+// copied into the target. The dependency-free hook script is copied into the
+// target's `.claude/hooks/` and the command resolves it via $CLAUDE_PROJECT_DIR
+// (the target project root). The legacy `lib/hooks/...` command string is kept
+// here only so existing installs get it removed/migrated on the next run.
+const CLAUDE_CODE_HOOK_SOURCE = path.join(__dirname, 'hooks', 'claude-code', 'verify-manifest.js');
+const CLAUDE_CODE_HOOK_TARGET_REL = '.claude/hooks/verify-manifest.js';
+const CLAUDE_CODE_HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR/${CLAUDE_CODE_HOOK_TARGET_REL}"`;
+const CLAUDE_CODE_HOOK_LEGACY_COMMAND = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+
 function getPackageVersion() {
   const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
   return pkg.version;
@@ -397,13 +413,91 @@ function ensurePluginStageIgnored(projectRoot) {
   );
 }
 
+// Bug 27.11 — the installer writes the `_bmad/` module tree which is
+// "Installer-managed. Regenerated on every install — treat as read-only."
+// Leaving it tracked guarantees churn and merge conflicts on every reinstall.
+// This sister-policy to PLUGIN_STAGE_PATTERNS ensures `_bmad/` is gitignored.
+//
+// IMPORTANT: this targets ONLY the regenerated `_bmad/` tree. The
+// `_bmad-output/` directory holds tracked project knowledge and is
+// deliberately kept OUT of .gitignore (see ensureBmadOutputTracked) — the
+// patterns below never match it because git treats `_bmad/` (trailing-slash
+// anchored) and `_bmad-output` as distinct entries.
+const BMAD_DIR_NAME = '_bmad';
+const BMAD_DIR_PATTERNS = [
+  BMAD_DIR_NAME,            // _bmad
+  `${BMAD_DIR_NAME}/`,      // _bmad/
+  `/${BMAD_DIR_NAME}`,      // /_bmad
+  `/${BMAD_DIR_NAME}/`,     // /_bmad/
+];
+const BMAD_DIR_CANONICAL_ENTRY = `${BMAD_DIR_NAME}/`;
+
+/**
+ * Ensure `_bmad/` is present in the target project's `.gitignore`. Mirrors the
+ * append-only, idempotent, EOL-preserving contract of `ensurePluginStageIgnored`.
+ *
+ *  - If `.gitignore` is absent, create it with the single canonical entry.
+ *  - If any active (non-comment) line already matches any BMAD_DIR_PATTERNS
+ *    variant, do nothing.
+ *  - Otherwise, append `BMAD_DIR_CANONICAL_ENTRY` preserving existing EOL style.
+ *
+ * Defensive: no-op on falsy/non-string projectRoot, matching the sister helper.
+ *
+ * @param {string} projectRoot - Absolute path to the target project root.
+ */
+function ensureBmadDirIgnored(projectRoot) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return;
+  }
+
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  let content = '';
+  let fileExists = true;
+  try {
+    content = fs.readFileSync(gitignorePath, 'utf-8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    fileExists = false;
+  }
+
+  if (fileExists) {
+    const alreadyPresent = content.split(/\r?\n/).some(rawLine => {
+      const line = rawLine.trim();
+      if (!line || line.startsWith('#')) return false; // skip blanks & comments
+      return BMAD_DIR_PATTERNS.includes(line);
+    });
+    if (alreadyPresent) return; // idempotent no-op
+  }
+
+  const usesCrlf = fileExists && /\r\n/.test(content);
+  const eol = usesCrlf ? '\r\n' : '\n';
+
+  let next = content;
+  if (next && !next.endsWith('\n') && !next.endsWith('\r\n')) {
+    next += eol; // ensure the append lands on its own line
+  }
+  next += BMAD_DIR_CANONICAL_ENTRY + eol;
+
+  fs.writeFileSync(gitignorePath, next, 'utf-8');
+  console.log(
+    chalk.green(
+      `${BMAD_DIR_CANONICAL_ENTRY} added to .gitignore (installer-managed BMAD tree — regenerated on every install)`
+    )
+  );
+}
+
 function ensureManifest(installPath, agentId, scope) {
   let manifest = readManifest(installPath);
   if (!manifest) {
+    // Bug 27.9 — when bootstrapped before any agent is known (e.g. profile
+    // bootstrap via setProfile → ensureManifest(root, null, 'project')), agentId
+    // is null. Mirror the migrate-branch guard so we never write the malformed
+    // `agent: null` / `agents: [null]` shape; an empty agents array is valid.
     manifest = {
       manifestVersion: MANIFEST_VERSION,
-      agent: agentId,
-      agents: [agentId],
+      agent: agentId || null,
+      agents: agentId ? [agentId] : [],
       scope: scope,
       skills: {}
     };
@@ -1228,10 +1322,14 @@ async function performInstall(skillId, skill, agent, installPath) {
   const frontmatterRegex = /^---\s*\n[\s\S]*?\n---\s*\n/;
   content = content.replace(frontmatterRegex, '');
 
-  // Inject YAML frontmatter from skill.json (single source of truth)
+  // Inject YAML frontmatter. The Agent Skills spec (and strict validators such
+  // as cline) require the frontmatter `name` to be the kebab-case skill id that
+  // matches the SKILL.md's containing directory — NOT the human-readable display
+  // name. We therefore inject `skillId` (the directory basename) here and keep
+  // `skill.name` from skill.json as the display name used by listings/wizard UI.
   const frontmatter = [
     '---',
-    `name: ${skill.name}`,
+    `name: ${skillId}`,
     `description: ${skill.description}`,
     '---',
     ''
@@ -1265,6 +1363,116 @@ async function performInstall(skillId, skill, agent, installPath) {
   return true;
 }
 
+// --- Bug 27.16 — .agents/skills pipeline-consistency reconciliation ----------
+//
+// Two pipelines write skills: ma-agents' own standalone loop (installSkill →
+// performInstall + generateSkillsManifest — the ONLY writer of MANIFEST.yaml),
+// and bmad-method's PluginResolver (via --custom-source) which routes
+// copilot/roo/kilo to the shared `.agents/skills/` dir. The standalone loop only
+// targets `.agents/skills` when a copilot/kilocode/roo-code agent is selected.
+//
+// When the user selects only claude-code/cline/opencode, BMAD still writes the
+// BMAD-family skills into `.agents/skills` (175 of them in the Workshop repro)
+// but the standalone catalog and MANIFEST.yaml are never written there — leaving
+// a dir that looks installed but is silently partial AND missing the
+// MANIFEST.yaml the stamped instruction block points agents at.
+//
+// This pass makes `.agents/skills` pipeline-consistent: if BMAD populated it but
+// no `.agents`-targeting agent was selected (so the standalone loop skipped it),
+// install the full standalone catalog there and generate MANIFEST.yaml. The set
+// of `.agents`-targeting agent ids is derived from agents whose project skills
+// dir resolves to `.agents/skills`.
+
+const AGENTS_SHARED_SKILLS_DIRNAME = '.agents';
+
+/**
+ * Return the list of agent ids whose project-level skills dir is the shared
+ * `.agents/skills/` directory (copilot, kilocode, roo-code). Derived from the
+ * agent registry's `skillsDir` so a future registry change surfaces here.
+ */
+function getAgentsSharedSkillAgentIds() {
+  return listAgents()
+    .filter(a => a.skillsDir === path.join(AGENTS_SHARED_SKILLS_DIRNAME, 'skills') ||
+                 a.skillsDir === `${AGENTS_SHARED_SKILLS_DIRNAME}/skills`)
+    .map(a => a.id);
+}
+
+/**
+ * Bug 27.16 — reconcile a BMAD-populated `.agents/skills` directory that the
+ * standalone loop never targeted. No-op unless ALL of:
+ *   - scope === 'project'
+ *   - `<projectRoot>/.agents/skills` exists on disk (BMAD created it)
+ *   - no `.agents`-targeting agent was among the selected agents
+ *   - the dir has no MANIFEST.yaml (the standalone-loop signature)
+ *
+ * When triggered, installs the full standalone catalog into `.agents/skills`
+ * (using a representative `.agents`-targeting agent for template resolution),
+ * records the skills into that dir's `.ma-agents.json`, and generates
+ * MANIFEST.yaml — so the dir is never BMAD-only without a manifest.
+ *
+ * Idempotent: once MANIFEST.yaml exists the early-return fires.
+ *
+ * @param {string} projectRoot
+ * @param {string[]} selectedAgentIds - agent ids the user selected this run
+ * @param {string} scope - 'project' | 'global'
+ * @returns {Promise<{reconciled: boolean, installed: number}>}
+ */
+async function reconcileAgentsSharedSkills(projectRoot, selectedAgentIds = [], scope = 'project') {
+  const result = { reconciled: false, installed: 0 };
+  if (scope !== 'project') return result;
+  if (typeof projectRoot !== 'string' || !projectRoot) return result;
+
+  const sharedDir = path.join(projectRoot, AGENTS_SHARED_SKILLS_DIRNAME, 'skills');
+  if (!fs.existsSync(sharedDir)) return result; // BMAD never populated it
+
+  const sharedAgentIds = getAgentsSharedSkillAgentIds();
+  const selectedSet = new Set(selectedAgentIds || []);
+  const anySharedSelected = sharedAgentIds.some(id => selectedSet.has(id));
+  if (anySharedSelected) return result; // standalone loop already targeted it
+
+  // If a MANIFEST.yaml already exists, the dir is not standalone-orphaned.
+  if (fs.existsSync(path.join(sharedDir, 'MANIFEST.yaml'))) return result;
+
+  // Pick a representative `.agents`-targeting agent for template resolution.
+  const repAgent = sharedAgentIds.map(id => getAgent(id)).find(Boolean);
+  if (!repAgent) return result; // registry has no such agent — nothing to do
+
+  console.log(chalk.yellow(
+    `  Note: ${sharedDir} was populated by BMAD but carries no MANIFEST.yaml ` +
+    `(no .agents-targeting agent selected) — backfilling the standalone catalog (bug 27.16).`
+  ));
+
+  const skills = listSkills();
+  const manifest = ensureManifest(sharedDir, repAgent.id, scope);
+  const now = new Date().toISOString();
+
+  for (const skill of skills) {
+    try {
+      const ok = await performInstall(skill.id, skill, repAgent, sharedDir);
+      if (!ok) continue;
+      const existing = manifest.skills[skill.id];
+      manifest.skills[skill.id] = {
+        version: skill.version,
+        installedAt: existing ? existing.installedAt : now,
+        updatedAt: now,
+        installerVersion: getPackageVersion(),
+        agentVersion: repAgent.version
+      };
+      result.installed++;
+    } catch (err) {
+      console.log(chalk.yellow(`    x ${skill.id} skipped in .agents/skills backfill: ${err.message}`));
+    }
+  }
+
+  writeManifest(sharedDir, manifest);
+  await generateSkillsManifest(sharedDir);
+  result.reconciled = true;
+  console.log(chalk.green(
+    `  Backfilled ${result.installed} standalone skill(s) + MANIFEST.yaml into ${sharedDir}`
+  ));
+  return result;
+}
+
 // --- Install with upgrade detection ---
 
 async function installSkill(skillId, agentIds, customPath = '', scope = 'project', options = {}) {
@@ -1882,7 +2090,12 @@ function getStatus(agentIds, customPath = '', scope = 'project') {
 
     for (const { path: checkPath, scope: checkScope } of pathsToCheck) {
       const manifest = readManifest(checkPath);
-      if (!manifest || !manifest.skills || Object.keys(manifest.skills).length === 0) {
+      // Bug 27.12 — never treat the PROFILE-ONLY project-root manifest as a
+      // skill inventory. The per-agent skills manifests are authoritative; a
+      // manifest carrying the `project-root` scope discriminator is a
+      // profile/settings store and must be skipped here.
+      if (!manifest || manifest.scope === 'project-root' ||
+          !manifest.skills || Object.keys(manifest.skills).length === 0) {
         continue;
       }
 
@@ -1924,27 +2137,49 @@ async function deployClaudeCodeHook(projectRoot) {
     settings.hooks.SessionStart = [];
   }
 
-  // Check if our hook is already present
-  const hookCommand = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+  // Bug 27.8 — copy the self-contained hook into the target so the command
+  // resolves in any install (npx/node_modules/dev-repo). The legacy command
+  // string (which pointed at the never-copied package `lib/`) is migrated to
+  // the new command on every run.
+  const hookTargetPath = path.join(projectRoot, CLAUDE_CODE_HOOK_TARGET_REL);
+  await fs.ensureDir(path.dirname(hookTargetPath));
+  await fs.copy(CLAUDE_CODE_HOOK_SOURCE, hookTargetPath, { overwrite: true });
+
+  const hookCommand = CLAUDE_CODE_HOOK_COMMAND;
+  let migrated = false;
+  for (const group of settings.hooks.SessionStart) {
+    if (!group.hooks) continue;
+    for (const h of group.hooks) {
+      if (h.command === CLAUDE_CODE_HOOK_LEGACY_COMMAND || h._id === CLAUDE_CODE_HOOK_ID) {
+        h.command = hookCommand;
+        h._id = CLAUDE_CODE_HOOK_ID;
+        migrated = true;
+      }
+    }
+  }
+
   const alreadyInstalled = settings.hooks.SessionStart.some(group =>
     group.hooks && group.hooks.some(h => h.command === hookCommand)
   );
 
-  if (alreadyInstalled) {
-    return; // Already deployed
+  if (!alreadyInstalled) {
+    settings.hooks.SessionStart.push({
+      matcher: 'startup',
+      hooks: [
+        {
+          type: 'command',
+          command: hookCommand,
+          _id: CLAUDE_CODE_HOOK_ID
+        }
+      ]
+    });
+  } else if (!migrated) {
+    // Hook entry already current and file copied — still ensure settings exist.
+    await fs.ensureDir(path.dirname(settingsPath));
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    return;
   }
 
-  settings.hooks.SessionStart.push({
-    matcher: 'startup',
-    hooks: [
-      {
-        type: 'command',
-        command: hookCommand,
-        _id: CLAUDE_CODE_HOOK_ID
-      }
-    ]
-  });
-
   await fs.ensureDir(path.dirname(settingsPath));
   await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
   console.log(chalk.cyan('    + Deployed Claude Code verify-manifest hook'));
@@ -1956,6 +2191,15 @@ async function deployClaudeCodeHook(projectRoot) {
 async function removeClaudeCodeHook(projectRoot) {
   const settingsPath = path.join(projectRoot, CLAUDE_CODE_SETTINGS_FILE);
 
+  // Bug 27.8 — remove the copied hook file first, before any settings.json
+  // early-return, so a missing/corrupt settings.json never orphans the file.
+  const hookTargetPath = path.join(projectRoot, CLAUDE_CODE_HOOK_TARGET_REL);
+  try {
+    await fs.remove(hookTargetPath);
+  } catch {
+    // best-effort cleanup — never fail uninstall over a missing file
+  }
+
   if (!fs.existsSync(settingsPath)) return;
 
   let settings;
@@ -1967,10 +2211,15 @@ async function removeClaudeCodeHook(projectRoot) {
 
   if (!settings.hooks || !settings.hooks.SessionStart) return;
 
-  const hookCommand = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+  // Match both the current command and the legacy package-relative command so
+  // older installs get cleaned up too.
   settings.hooks.SessionStart = settings.hooks.SessionStart.filter(group => {
     if (!group.hooks) return true;
-    group.hooks = group.hooks.filter(h => h.command !== hookCommand && h._id !== CLAUDE_CODE_HOOK_ID);
+    group.hooks = group.hooks.filter(h =>
+      h.command !== CLAUDE_CODE_HOOK_COMMAND &&
+      h.command !== CLAUDE_CODE_HOOK_LEGACY_COMMAND &&
+      h._id !== CLAUDE_CODE_HOOK_ID
+    );
     return group.hooks.length > 0;
   });
 
@@ -1997,6 +2246,7 @@ module.exports = {
   listSkills,
   listAgents,
   installSkill,
+  performInstall,
   uninstallSkill,
   getStatus,
   readManifest,
@@ -2009,6 +2259,9 @@ module.exports = {
   removeClaudeCodeHook,
   ensureBmadOutputTracked,
   ensurePluginStageIgnored,
+  ensureBmadDirIgnored,
+  reconcileAgentsSharedSkills,
+  getAgentsSharedSkillAgentIds,
   generateSkillsManifest,
   generateProjectContext,
   generateRepoLayoutSection,

package/lib/profile.js

@@ -23,6 +23,29 @@ const path = require('path');
 const MANIFEST_FILE = '.ma-agents.json';
 const VALID_PROFILES = ['on-prem', 'standard'];
 
+// Bug 27.12 — the project-root .ma-agents.json is a PROFILE/settings store, not
+// a skill inventory. Per-agent skills dirs (e.g. .claude/skills/.ma-agents.json)
+// own the installed-skill inventory and remain the authoritative source read by
+// getStatus/uninstall/reconcile. The root bootstrap therefore emits ONLY the
+// fields it owns (manifestVersion + a scope discriminator) and NOT a `skills`/
+// `agents` shape it would never back-fill — so the root file can no longer
+// masquerade as an empty skill inventory (`skills: {}`).
+const ROOT_MANIFEST_VERSION = '1.2.0';
+const ROOT_SCOPE = 'project-root';
+
+/**
+ * Bootstrap a fresh PROFILE-ONLY root manifest object (not persisted here).
+ * Intentionally omits `skills` and `agents`: those belong to per-agent skills
+ * manifests. The `scope: 'project-root'` discriminator makes the file's role
+ * explicit for any reader.
+ */
+function bootstrapRootManifest() {
+  return {
+    manifestVersion: ROOT_MANIFEST_VERSION,
+    scope: ROOT_SCOPE,
+  };
+}
+
 /**
  * Reads the persisted profile from .ma-agents.json at the given project root.
  * Returns undefined if the file does not exist, is malformed, or the "profile"
@@ -73,10 +96,12 @@ function setProfile(projectRoot, value) {
   }
 
   if (!manifest || typeof manifest !== 'object') {
-    // Bootstrap via the standard schema (mirrors lib/installer.js ensureManifest shape).
-    // Require lazily to avoid potential circular-import pitfalls at module load.
-    const { ensureManifest } = require('./installer');
-    manifest = ensureManifest(projectRoot, null, 'project');
+    // Bug 27.12 — bootstrap a PROFILE-ONLY root manifest. Previously this used
+    // ensureManifest(root, null, 'project'), which stamped an empty `skills: {}`
+    // / `agents: []` shape the root file never owns or back-fills, making it
+    // look like an (empty) skill inventory. The per-agent skills manifests are
+    // the authoritative inventory; the root file stores profile/settings only.
+    manifest = bootstrapRootManifest();
   }
 
   // Migrate 1.1.0 (or missing version) → 1.2.0, since the "profile" field is 1.2.0-only.
@@ -127,4 +152,70 @@ function clearProfile(projectRoot) {
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
 }
 
-module.exports = { getProfile, setProfile, resolveProfile, clearProfile };
+/**
+ * Bug 27.13 — durable BMAD-module selection.
+ *
+ * Reads the persisted BMAD module set from .ma-agents.json (the `bmadModules`
+ * field). Returns undefined when the file is absent/malformed or the field is
+ * missing, so callers can distinguish "never persisted" (→ install default set)
+ * from an explicit empty selection. A persisted value is always returned as an
+ * array of strings.
+ */
+function getBmadModules(projectRoot) {
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) return undefined;
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return undefined;
+  }
+  if (!manifest || typeof manifest !== 'object') return undefined;
+  if (!Object.prototype.hasOwnProperty.call(manifest, 'bmadModules')) return undefined;
+  const value = manifest.bmadModules;
+  if (!Array.isArray(value)) return undefined;
+  // Normalize to a clean, de-duplicated array of non-empty strings.
+  return [...new Set(value.filter(m => typeof m === 'string' && m.length > 0))];
+}
+
+/**
+ * Bug 27.13 — persists the selected BMAD module set into .ma-agents.json,
+ * preserving all other fields. Creates the file via the standard ensureManifest
+ * bootstrap path if absent (mirroring setProfile). The choice then survives
+ * subsequent installs/reconfigures that do not re-pass --bmad-modules.
+ *
+ * @param {string} projectRoot
+ * @param {string[]} modules - module ids to persist (e.g. ['bmm','tea','bmb'])
+ */
+function setBmadModules(projectRoot, modules) {
+  if (!Array.isArray(modules)) {
+    throw new Error(`setBmadModules expects an array of module ids (got ${JSON.stringify(modules)})`);
+  }
+  const cleaned = [...new Set(modules.filter(m => typeof m === 'string' && m.length > 0))];
+
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  let manifest;
+  if (fs.existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      manifest = null;
+    }
+  }
+  if (!manifest || typeof manifest !== 'object') {
+    // Bug 27.12 — profile-only root bootstrap (see setProfile / bootstrapRootManifest).
+    manifest = bootstrapRootManifest();
+  }
+
+  manifest.bmadModules = cleaned;
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+module.exports = {
+  getProfile,
+  setProfile,
+  resolveProfile,
+  clearProfile,
+  getBmadModules,
+  setBmadModules,
+};

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

@@ -1,25 +1,25 @@
-## Git Workflow (ALL file-changing tasks)
-
-These rules apply to EVERY task that modifies a tracked file. There is no
-"small fix exemption" — a one-line edit follows the same workflow as a feature.
-
-- **Worktree first.** Before changing any file, create a fresh isolated worktree
-  on a new feature branch: `git worktree add ../<project>-<branch> -b <branch>`.
-  The scripted form is `skills/git-workflow-skill/scripts/start-feature.sh`. All
-  file-writing happens inside that worktree — never in the main working tree.
-- **Never commit directly to the trunk.** Do NOT commit to `main`, `dev`,
-  `master`, or whatever the trunk branch is. Commits land only on your feature
-  branch inside the worktree.
-- **Conventional Commits.** Every commit message uses a Conventional Commits
-  prefix. The allowed prefixes are: `feat`, `fix`, `chore`, `docs`, `refactor`,
-  `test`, `ci`.
-- **PR is the only path into the trunk.** Integrate exclusively by opening a pull
-  request with `gh pr create`. Never merge directly and never auto-merge a PR
-  without explicit human approval.
-- **Self-review before opening the PR.** Run the `code-review` skill on your own
-  changes and address its findings before you open the PR.
-- **Clean up after merge.** Once the PR is merged, remove the worktree with
-  `git worktree remove` and delete the feature branch.
-
-Full procedure: see `skills/git-workflow-skill/SKILL.md`, and the helper scripts
-`scripts/start-feature.sh` / `scripts/finish-feature.sh`.
+## Git Workflow (ALL file-changing tasks)
+
+These rules apply to EVERY task that modifies a tracked file. There is no
+"small fix exemption" — a one-line edit follows the same workflow as a feature.
+
+- **Worktree first.** Before changing any file, create a fresh isolated worktree
+  on a new feature branch: `git worktree add ../<project>-<branch> -b <branch>`.
+  The scripted form is `skills/git-workflow-skill/scripts/start-feature.sh`. All
+  file-writing happens inside that worktree — never in the main working tree.
+- **Never commit directly to the trunk.** Do NOT commit to `main`, `dev`,
+  `master`, or whatever the trunk branch is. Commits land only on your feature
+  branch inside the worktree.
+- **Conventional Commits.** Every commit message uses a Conventional Commits
+  prefix. The allowed prefixes are: `feat`, `fix`, `chore`, `docs`, `refactor`,
+  `test`, `ci`.
+- **PR is the only path into the trunk.** Integrate exclusively by opening a pull
+  request with `gh pr create`. Never merge directly and never auto-merge a PR
+  without explicit human approval.
+- **Self-review before opening the PR.** Run the `code-review` skill on your own
+  changes and address its findings before you open the PR.
+- **Clean up after merge.** Once the PR is merged, remove the worktree with
+  `git worktree remove` and delete the feature branch.
+
+Full procedure: see `skills/git-workflow-skill/SKILL.md`, and the helper scripts
+`scripts/start-feature.sh` / `scripts/finish-feature.sh`.