@ethlete/agent-rules 0.1.0-next.2 → 0.1.0-next.21

package/migrations/search-query-field.md

@@ -0,0 +1,52 @@
+# Replace a hand-debounced search with `searchQueryField`
+
+The earlier query guidance said there was no built-in debounce and to debounce at the input. So a
+search box that feeds a query was debounced by hand: `debounceTime` on a stream, a `setTimeout`, or a
+debounced copy of the input signal. `searchQueryField()` debounces by itself (300ms), and applies a
+cleared input at once.
+
+## Before you start
+
+`et update` regenerates the skills when it moves `@ethlete/agent-rules`. If
+`.agents/skills/ethlete-query/SKILL.md` does not mention `searchQueryField`, run
+`ethlete-agents sync` with this repo's package manager (`yarn`, `pnpm exec` or `npx`) first.
+
+## Find the call sites
+
+```bash
+grep -rnE 'debounceTime\(|debounce\(' apps libs --include='*.ts'
+grep -rnE 'setTimeout\(' apps libs --include='*.ts'
+```
+
+A call site is in scope when the debounced value ends up in the args of a query.
+
+## What to change
+
+1. Add a `search: searchQueryField()` field to the list's `defineQueryForm`, or declare a form with
+   that one field.
+2. Call `.observe()` on it. Keep the URL behaviour the old search had. If it did not write the
+   URL, as a search inside a dialog, pass `{ writeToQueryParams: false, syncOnNavigation: false }`.
+   `writeToQueryParams: false` alone stops the writes only: the form still reads the page's own
+   params, such as `page`.
+3. Read `this.qf.value().search` in `withArgs`, and bind the input with `[formField]="qf.fields.search"`.
+4. Delete the debounce, the subject or timer, and the intermediate signal.
+5. Pass `debounce` to the field when the old delay was deliberately different from 300ms.
+
+If the search text is part of list state the component syncs to the URL by hand, skip the call
+site: it moves with the rest of the list to `defineQueryForm` when that list is next edited.
+
+## Leave these alone
+
+- A debounce whose value never reaches a query: resize and scroll handlers, autosave, analytics.
+- An SDK control that takes a search input of its own.
+
+## Done when
+
+- No hit of the greps above feeds a query any more, apart from the hand-synced lists you skipped.
+  Your final message names each skipped one.
+- The type check, lint and tests pass for every project you changed.
+
+Then delete this task file.
+
+The guide the `Docs` line at the top of this file links (`/query/query-forms` on the SDK docs site)
+has the field creators and their options.

package/migrations.json

@@ -0,0 +1,48 @@
+{
+  "migrations": [
+    {
+      "name": "app-styling-utilities",
+      "version": "0.1.0-next.17",
+      "kind": "assisted",
+      "level": "required",
+      "description": "App rules in @layer components move out of that layer, so SDK styles stop overriding them.",
+      "instructions": "./migrations/app-styling-utilities.md",
+      "docs": "/components/setup"
+    },
+    {
+      "name": "list-state-query-form",
+      "version": "0.1.0-next.17",
+      "kind": "manual",
+      "level": "optional",
+      "description": "Lists that sync their params to the URL by hand move to defineQueryForm when they are next edited.",
+      "instructions": "./migrations/list-state-query-form.md",
+      "docs": "/query/query-forms"
+    },
+    {
+      "name": "search-query-field",
+      "version": "0.1.0-next.17",
+      "kind": "assisted",
+      "level": "optional",
+      "description": "A hand-debounced search that feeds a query moves to searchQueryField.",
+      "instructions": "./migrations/search-query-field.md",
+      "docs": "/query/query-forms"
+    },
+    {
+      "name": "sdk-components-over-hand-built-ui",
+      "version": "0.1.0-next.17",
+      "kind": "manual",
+      "level": "optional",
+      "description": "Hand-built bar charts, avatars and progress bars move to the SDK components when their view is next edited.",
+      "instructions": "./migrations/sdk-components-over-hand-built-ui.md",
+      "docs": "/components/"
+    },
+    {
+      "name": "nx-layout",
+      "version": "0.1.0-next.17",
+      "kind": "manual",
+      "level": "optional",
+      "description": "Compare the workspace with the Nx layout rule, and decide whether any project moves.",
+      "instructions": "./migrations/nx-layout.md"
+    }
+  ]
+}

package/package.json

@@ -1,15 +1,29 @@
 {
   "name": "@ethlete/agent-rules",
-  "version": "0.1.0-next.2",
+  "version": "0.1.0-next.21",
   "license": "MIT",
   "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./git-flow": {
+      "types": "./src/lib/git-flow/index.d.ts",
+      "default": "./src/lib/git-flow/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",
   "bin": {
     "ethlete-agents": "./src/index.js"
   },
   "peerDependencies": {
-    "tslib": "2.8.1"
+    "tslib": "^2.3.0"
+  },
+  "ethlete": {
+    "migrations": "./migrations.json"
   },
   "types": "./src/index.d.ts"
 }

package/src/index.js

@@ -4,14 +4,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const fs_1 = require("fs");
 const path_1 = require("path");
+const cli_args_1 = require("./lib/cli-args");
 const config_1 = require("./lib/config");
+const git_flow_command_1 = require("./lib/git-flow-command");
+const load_content_1 = require("./lib/load-content");
 const migrate_1 = require("./lib/migrate");
+const output_style_command_1 = require("./lib/output-style-command");
+const package_runner_1 = require("./lib/package-runner");
+const plain_text_1 = require("./lib/plain-text");
 const sync_1 = require("./lib/sync");
+const timetrack_command_1 = require("./lib/timetrack-command");
 const USAGE = `ethlete-agents — compile @ethlete agent rules and skills into your repo
 
   ethlete-agents sync      Write the generated rules/skills for every detected agent
   ethlete-agents check     Exit non-zero when the generated files are out of date (for CI)
   ethlete-agents init      Write a starter ${config_1.CONFIG_FILE_NAME}
+  ethlete-agents git-flow  Name, check and repair branches against the repo's git flow
+                           (start, check, repair, explain)
+  ethlete-agents output-style
+                           Install an Ethlete output style into this machine's Claude Code
+                           config and switch to it (Claude Code only)
+  ethlete-agents timetrack Ask the running Timetrack app about Jira - it holds this
+                           machine's credentials, so no repo needs a token
+                           (status, instance, issue, search, project, create, log)
   ethlete-agents migrate   Convert the repo to the AGENTS.md + .agents/skills layout:
                            CLAUDE.md content moves into AGENTS.md (CLAUDE.md becomes an
                            @AGENTS.md import), hand-written .claude/skills move to
@@ -19,7 +34,8 @@ const USAGE = `ethlete-agents — compile @ethlete agent rules and skills into y
 
 Options
   --targets <list>   Comma-separated subset of: ${config_1.AGENT_TARGETS.join(', ')}
-  --root <path>      Repo root to write into (default: current directory)
+  --root <path>      Repo root to write into (default: the nearest directory holding
+                     ${config_1.CONFIG_FILE_NAME}, else the current directory)
   --dry-run          Print what would change without writing (sync and migrate)
 `;
 const readFlag = (args, flag) => {
@@ -28,46 +44,65 @@ const readFlag = (args, flag) => {
         return undefined;
     return args[index + 1];
 };
-const parseTargets = (args) => {
-    const raw = readFlag(args, '--targets');
-    if (!raw)
-        return undefined;
-    return raw.split(',').map((entry) => entry.trim());
-};
-const readVersion = () => {
-    const manifest = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', 'package.json'), 'utf8'));
-    return manifest.version;
-};
+const INIT_VARS = ['lintCommand', 'lintFixCommand', 'formatCommand', 'storybookStartCommand', 'storybookUrl'];
 const init = (root) => {
     const path = (0, path_1.join)(root, config_1.CONFIG_FILE_NAME);
     if ((0, fs_1.existsSync)(path)) {
         console.error(`${config_1.CONFIG_FILE_NAME} already exists.`);
         return 1;
     }
+    const defaults = (0, load_content_1.loadDefaultVars)();
+    const detected = (0, package_runner_1.detectCommandVars)(root);
+    const vars = Object.fromEntries(INIT_VARS.map((name) => { var _a; return [name, (_a = detected[name]) !== null && _a !== void 0 ? _a : defaults[name]]; }).filter(([, value]) => value));
     const template = {
         targets: (0, config_1.detectTargets)(root),
-        vars: {},
+        vars,
         exclude: [],
         hooks: [],
     };
     (0, fs_1.writeFileSync)(path, `${JSON.stringify(template, null, 2)}\n`, 'utf8');
-    console.log(`Wrote ${config_1.CONFIG_FILE_NAME}. Fill in "vars" for your repo, then run \`ethlete-agents sync\`.`);
+    console.log(`Wrote ${config_1.CONFIG_FILE_NAME}. Check the commands in "vars" (${Object.keys(vars).join(', ')}) against your repo, then run \`ethlete-agents sync\`.`);
     return 0;
 };
-const run = (argv) => {
-    var _a;
-    const command = argv[0];
-    const root = (_a = readFlag(argv, '--root')) !== null && _a !== void 0 ? _a : process.cwd();
-    const options = { root, version: readVersion(), targets: parseTargets(argv) };
+const STRICT_COMMANDS = ['sync', 'check', 'init', 'migrate'];
+const runStrict = (command, args) => {
+    var _a, _b;
+    const root = (_a = args.root) !== null && _a !== void 0 ? _a : (0, config_1.resolveRepoRoot)(process.cwd());
+    const options = { root, targets: args.targets };
     switch (command) {
         case 'sync':
-            return (0, sync_1.sync)(Object.assign(Object.assign({}, options), { dryRun: argv.includes('--dry-run') }));
+            return (0, sync_1.sync)(Object.assign(Object.assign({}, options), { dryRun: args.dryRun }));
         case 'check':
             return (0, sync_1.check)(options);
         case 'init':
-            return init(root);
-        case 'migrate':
-            return (0, migrate_1.migrate)(Object.assign(Object.assign({}, options), { dryRun: argv.includes('--dry-run') }));
+            return init((_b = args.root) !== null && _b !== void 0 ? _b : process.cwd());
+        default:
+            return (0, migrate_1.migrate)(Object.assign(Object.assign({}, options), { dryRun: args.dryRun }));
+    }
+};
+const run = (argv) => {
+    var _a;
+    const command = argv[0];
+    if (command !== undefined && STRICT_COMMANDS.includes(command)) {
+        const args = (0, cli_args_1.parseCommandArgs)(command, argv.slice(1));
+        if (args.problems.length) {
+            console.error(`${args.problems.join('\n')}\n\n${USAGE}`);
+            return 1;
+        }
+        if (args.help) {
+            console.log(USAGE);
+            return 0;
+        }
+        return runStrict(command, args);
+    }
+    const root = (_a = readFlag(argv, '--root')) !== null && _a !== void 0 ? _a : (0, config_1.resolveRepoRoot)(process.cwd());
+    switch (command) {
+        case 'git-flow':
+            return (0, git_flow_command_1.gitFlowCommand)({ root, argv: argv.slice(1) });
+        case 'output-style':
+            return (0, output_style_command_1.outputStyleCommand)({ argv: argv.slice(1) });
+        case 'timetrack':
+            return (0, timetrack_command_1.timetrackCommand)({ root, argv: argv.slice(1) });
         default:
             console.log(USAGE);
             return command === undefined || command === '--help' || command === '-h' ? 0 : 1;
@@ -76,12 +111,12 @@ const run = (argv) => {
 tslib_1.__exportStar(require("./lib"), exports);
 // Guarded so the package can also be imported as a library without running the CLI.
 if (require.main === module) {
-    try {
-        process.exit(run(process.argv.slice(2)));
-    }
-    catch (error) {
-        console.error(error instanceof Error ? error.message : error);
+    Promise.resolve()
+        .then(() => run(process.argv.slice(2)))
+        .then((code) => process.exit(code))
+        .catch((error) => {
+        console.error((0, plain_text_1.plain)(error instanceof Error ? error.message : String(error)));
         process.exit(1);
-    }
+    });
 }
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/agent-rules/src/index.ts"],"names":[],"mappings":";;;;AACA,2BAA6D;AAC7D,+BAA4B;AAC5B,yCAA2F;AAC3F,2CAAwC;AACxC,qCAAyC;AAEzC,MAAM,KAAK,GAAG;;;;6CAI+B,yBAAgB;;;;;;;kDAOX,sBAAa,CAAC,IAAI,CAAC,IAAI,CAAC;;;CAGzE,CAAC;AAEF,MAAM,QAAQ,GAAG,CAAC,IAAc,EAAE,IAAY,EAAE,EAAE;IAChD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjC,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAEnC,OAAO,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AACzB,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,IAAc,EAAE,EAAE;IACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAExC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAE3B,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAkB,CAAC;AACtE,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,GAAG,EAAE;IACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,iBAAY,EAAC,IAAA,WAAI,EAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAwB,CAAC;IAEhH,OAAO,QAAQ,CAAC,OAAO,CAAC;AAC1B,CAAC,CAAC;AAEF,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE;IAC5B,MAAM,IAAI,GAAG,IAAA,WAAI,EAAC,IAAI,EAAE,yBAAgB,CAAC,CAAC;IAE1C,IAAI,IAAA,eAAU,EAAC,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,CAAC,KAAK,CAAC,GAAG,yBAAgB,kBAAkB,CAAC,CAAC;QAErD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,QAAQ,GAAG;QACf,OAAO,EAAE,IAAA,sBAAa,EAAC,IAAI,CAAC;QAC5B,IAAI,EAAE,EAAE;QACR,OAAO,EAAE,EAAE;QACX,KAAK,EAAE,EAAE;KACV,CAAC;IAEF,IAAA,kBAAa,EAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtE,OAAO,CAAC,GAAG,CAAC,SAAS,yBAAgB,mEAAmE,CAAC,CAAC;IAE1G,OAAO,CAAC,CAAC;AACX,CAAC,CAAC;AAEF,MAAM,GAAG,GAAG,CAAC,IAAc,EAAE,EAAE;;IAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,MAAA,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,mCAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACvD,MAAM,OAAO,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;IAE9E,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,IAAA,WAAI,kCAAM,OAAO,KAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAG,CAAC;QAClE,KAAK,OAAO;YACV,OAAO,IAAA,YAAK,EAAC,OAAO,CAAC,CAAC;QACxB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,IAAA,iBAAO,kCAAM,OAAO,KAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAG,CAAC;QACrE;YACE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAEnB,OAAO,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,CAAC;AACH,CAAC,CAAC;AAEF,gDAAsB;AAEtB,oFAAoF;AACpF,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/agent-rules/src/index.ts"],"names":[],"mappings":"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"}

package/src/lib/cli-args.d.ts

@@ -0,0 +1,9 @@
+import { AgentTarget } from './config';
+export type CommandArgs = {
+    targets?: AgentTarget[];
+    root?: string;
+    dryRun: boolean;
+    help: boolean;
+    problems: string[];
+};
+export declare const parseCommandArgs: (command: string, argv: readonly string[]) => CommandArgs;

package/src/lib/cli-args.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCommandArgs = void 0;
+const VALUE_FLAGS = ['--targets', '--root'];
+const FLAGS_BY_COMMAND = {
+    sync: ['--targets', '--root', '--dry-run'],
+    check: ['--targets', '--root'],
+    init: ['--root'],
+    migrate: ['--targets', '--root', '--dry-run'],
+};
+const parseCommandArgs = (command, argv) => {
+    var _a, _b;
+    const allowed = [...((_a = FLAGS_BY_COMMAND[command]) !== null && _a !== void 0 ? _a : []), '--help', '-h'];
+    const args = { dryRun: false, help: false, problems: [] };
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = (_b = argv[index]) !== null && _b !== void 0 ? _b : '';
+        const separator = argument.indexOf('=');
+        const flag = separator === -1 ? argument : argument.slice(0, separator);
+        if (!allowed.includes(flag)) {
+            args.problems.push(flag.startsWith('-') ? `Unknown flag "${flag}" for ${command}.` : `Unexpected argument "${argument}".`);
+            continue;
+        }
+        if (VALUE_FLAGS.includes(flag)) {
+            const value = separator === -1 ? argv[++index] : argument.slice(separator + 1);
+            const targets = value === null || value === void 0 ? void 0 : value.split(',').map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+            if (!value || value.startsWith('-') || (flag === '--targets' && !(targets === null || targets === void 0 ? void 0 : targets.length))) {
+                args.problems.push(`${flag} needs a value.`);
+                continue;
+            }
+            if (flag === '--root')
+                args.root = value;
+            else
+                args.targets = targets;
+            continue;
+        }
+        if (separator !== -1) {
+            args.problems.push(`${flag} takes no value.`);
+            continue;
+        }
+        if (flag === '--dry-run')
+            args.dryRun = true;
+        else
+            args.help = true;
+    }
+    return args;
+};
+exports.parseCommandArgs = parseCommandArgs;
+//# sourceMappingURL=cli-args.js.map

package/src/lib/cli-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../../../../../libs/agent-rules/src/lib/cli-args.ts"],"names":[],"mappings":"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"}

package/src/lib/commitlint.d.ts

@@ -0,0 +1,10 @@
+/** The file that validates commit messages, as the skill should name it, or `null` when none does. */
+export type CommitlintSource = string | null;
+export declare const findCommitlintConfig: (root: string) => CommitlintSource;
+/**
+ * The git-commit skill states where its format comes from, and whether a message can be verified,
+ * from what the repo actually has. Promising a `commitlint` run to a repo without one makes the
+ * agent narrate the contradiction it finds instead of just writing the commit — so a repo with no
+ * commitlint gets a guide that never mentions it.
+ */
+export declare const commitMessageVars: (source: CommitlintSource) => Record<string, string>;

package/src/lib/commitlint.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commitMessageVars = exports.findCommitlintConfig = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const COMMITLINT_CONFIG_FILES = [
+    'commitlint.config.js',
+    'commitlint.config.cjs',
+    'commitlint.config.mjs',
+    'commitlint.config.ts',
+    'commitlint.config.mts',
+    'commitlint.config.json',
+    'commitlint.config.yaml',
+    'commitlint.config.yml',
+    '.commitlintrc',
+    '.commitlintrc.js',
+    '.commitlintrc.cjs',
+    '.commitlintrc.mjs',
+    '.commitlintrc.ts',
+    '.commitlintrc.json',
+    '.commitlintrc.yaml',
+    '.commitlintrc.yml',
+];
+const findCommitlintConfig = (root) => {
+    const configFile = COMMITLINT_CONFIG_FILES.find((name) => (0, fs_1.existsSync)((0, path_1.join)(root, name)));
+    if (configFile)
+        return configFile;
+    const manifestPath = (0, path_1.join)(root, 'package.json');
+    if (!(0, fs_1.existsSync)(manifestPath))
+        return null;
+    const manifest = JSON.parse((0, fs_1.readFileSync)(manifestPath, 'utf8'));
+    return manifest.commitlint ? 'package.json' : null;
+};
+exports.findCommitlintConfig = findCommitlintConfig;
+/**
+ * The git-commit skill states where its format comes from, and whether a message can be verified,
+ * from what the repo actually has. Promising a `commitlint` run to a repo without one makes the
+ * agent narrate the contradiction it finds instead of just writing the commit — so a repo with no
+ * commitlint gets a guide that never mentions it.
+ */
+const commitMessageVars = (source) => source
+    ? {
+        commitRuleSource: `the **commitlint rules** in \`${source}\` - conventional commits with a required scope`,
+        commitValidation: 'When unsure a message passes, check it: `echo "<msg>" | npx commitlint`.',
+    }
+    : {
+        commitRuleSource: "this repo's **conventional-commit** convention",
+        commitValidation: 'Nothing checks the message once it is written, so get the type, scope and subject case right the first time.',
+    };
+exports.commitMessageVars = commitMessageVars;
+//# sourceMappingURL=commitlint.js.map

package/src/lib/commitlint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commitlint.js","sourceRoot":"","sources":["../../../../../libs/agent-rules/src/lib/commitlint.ts"],"names":[],"mappings":";;;AAAA,2BAA8C;AAC9C,+BAA4B;AAK5B,MAAM,uBAAuB,GAAG;IAC9B,sBAAsB;IACtB,uBAAuB;IACvB,uBAAuB;IACvB,sBAAsB;IACtB,uBAAuB;IACvB,wBAAwB;IACxB,wBAAwB;IACxB,uBAAuB;IACvB,eAAe;IACf,kBAAkB;IAClB,mBAAmB;IACnB,mBAAmB;IACnB,kBAAkB;IAClB,oBAAoB;IACpB,oBAAoB;IACpB,mBAAmB;CACpB,CAAC;AAEK,MAAM,oBAAoB,GAAG,CAAC,IAAY,EAAoB,EAAE;IACrE,MAAM,UAAU,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAA,eAAU,EAAC,IAAA,WAAI,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAExF,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAElC,MAAM,YAAY,GAAG,IAAA,WAAI,EAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAEhD,IAAI,CAAC,IAAA,eAAU,EAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,iBAAY,EAAC,YAAY,EAAE,MAAM,CAAC,CAA6B,CAAC;IAE5F,OAAO,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC,CAAC;AAZW,QAAA,oBAAoB,wBAY/B;AAEF;;;;;GAKG;AACI,MAAM,iBAAiB,GAAG,CAAC,MAAwB,EAA0B,EAAE,CACpF,MAAM;IACJ,CAAC,CAAC;QACE,gBAAgB,EAAE,iCAAiC,MAAM,iDAAiD;QAC1G,gBAAgB,EAAE,0EAA0E;KAC7F;IACH,CAAC,CAAC;QACE,gBAAgB,EAAE,gDAAgD;QAClE,gBAAgB,EACd,8GAA8G;KACjH,CAAC;AAVK,QAAA,iBAAiB,qBAUtB"}

package/src/lib/config.d.ts

@@ -1,8 +1,17 @@
 import { ContentScope } from './frontmatter';
+import { GitFlowConfig } from './git-flow';
 export declare const AGENT_TARGETS: readonly ["claude", "codex", "cursor", "copilot"];
 export type AgentTarget = (typeof AGENT_TARGETS)[number];
 export declare const CONFIG_FILE_NAME = "ethlete-agents.config.json";
 export declare const LOCAL_CONFIG_FILE_NAME = "ethlete-agents.config.local.json";
+/**
+ * How this repo reads a Jira issue into a branch name. The instance, the credentials and the subject
+ * field are not here and cannot be: the Timetrack app holds them, and `git-flow start` asks it.
+ */
+export type JiraSettings = {
+    /** Branch type per Jira issue type, e.g. `{ "Bug": "fix" }`. Anything unlisted becomes `feat`. */
+    typeByIssueType?: Record<string, string>;
+};
 export type SyncConfig = {
     root: string;
     targets: AgentTarget[];
@@ -16,9 +25,17 @@ export type SyncConfig = {
      * `AGENTS.md` marker block, and a second copy would load twice.
      */
     claudeMdImportsAgentsMd: boolean;
-    /** Opt-in Claude Code hooks (they run commands on the developer's machine, so never default). */
+    /** Opt-in agent hooks (they run commands on the developer's machine, so never default). */
     hooks: string[];
+    /** Opt-in git hooks, appended to the repo's own husky hooks. Same reason they never default. */
+    gitHooks: string[];
+    /** The branch grammar, resolved against its defaults — see `@ethlete/agent-rules/git-flow`. */
+    gitFlow: GitFlowConfig;
+    jira: JiraSettings;
+    configWarnings?: string[];
 };
+/** The nearest directory at or above `start` holding an `ethlete-agents.config.json`, else `start`. */
+export declare const resolveRepoRoot: (start: string) => string;
 /**
  * The gitignored local config holds per-machine values, read at runtime — by the generated hook
  * scripts, and by the agent while following a skill — never by `sync`. Sync output must be
@@ -26,12 +43,19 @@ export type SyncConfig = {
  * so nothing here may change what gets emitted:
  *
  * - `disableHooks: true` silences every generated hook, `["context-warning"]` just the named ones.
- * - `sdkSourcePath` points at a local `ethlete-sdk` checkout, which the SDK source and local-build
- *   skills read when they need the SDK's own sources instead of the published package.
+ * - `disableAutoHandoffSave: true` keeps the context-warning hook's normal tiered messages (including
+ *   in auto mode), but at the critical tier in auto mode it falls back to just recommending
+ *   a handoff instead of writing the handoff file automatically.
+ *
+ * Where the sibling checkouts live (`sdkSourcePath`, `apiRepoPaths`, `apiRepoBranches`) is not here:
+ * it moved to `@ethlete/cli`'s `ethlete.config.local.json`, because `et` reads the same values.
+ *
+ * No secret belongs here any more. Jira is reached through the Timetrack app, which holds the token
+ * in the machine's keychain — one secret per machine rather than one per checkout.
  */
 export type LocalConfig = {
     disableHooks?: boolean | string[];
-    sdkSourcePath?: string;
+    disableAutoHandoffSave?: boolean;
 };
 export type LocalConfigState = {
     exists: false;
@@ -43,7 +67,17 @@ export type LocalConfigState = {
     valid: true;
     config: LocalConfig;
     unknownKeys: string[];
+    movedKeys: string[];
 };
+export declare const LOCAL_CONFIG_KEYS: (keyof LocalConfig)[];
+/**
+ * Repo topology moved to `@ethlete/cli`'s `ethlete.config.local.json`, because `et` needs it too.
+ * Still recognised here so a checkout that has not moved them yet gets told where they went
+ * instead of an "unsupported key" warning.
+ */
+export declare const MOVED_LOCAL_CONFIG_KEYS: string[];
+/** Named only to point a migration at it. `@ethlete/cli` owns the file and validates its values. */
+export declare const TOPOLOGY_CONFIG_FILE_NAME = "ethlete.config.local.json";
 export declare const readLocalConfig: (root: string) => LocalConfigState;
 /**
  * Emit for the agents a repo already uses. `codex` is always included: `AGENTS.md` is the