@tjdals12/agent-bolt 1.4.0 → 1.5.0

package/dist/cli/views/sync.js

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import { ConsoleOutput } from '#core/output.js';
 import { Banner } from './shared/banner.js';
 import { changeSummary, countChanges, printToolReport, } from './shared/report.js';
 const STATUS_STYLES = {
@@ -7,15 +8,20 @@ const STATUS_STYLES = {
     removed: { symbol: '-', color: chalk.red, label: 'removed' },
 };
 export function renderSyncResult(result) {
-    const counts = countChanges(result);
+    const { toolSyncResults, warnings } = result;
+    const counts = countChanges(toolSyncResults);
     const changed = counts.total > 0;
     Banner.sync(changed);
-    for (const toolSyncResult of result) {
+    for (const toolSyncResult of toolSyncResults) {
         printToolReport(toolSyncResult, STATUS_STYLES);
     }
     if (changed) {
         console.log('');
         console.log(changeSummary(counts, STATUS_STYLES));
     }
+    for (const warning of warnings) {
+        console.error('');
+        ConsoleOutput.warn(warning);
+    }
 }
 //# sourceMappingURL=sync.js.map

package/dist/cli/views/sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/cli/views/sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EACL,aAAa,EACb,YAAY,EACZ,eAAe,GAEhB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,aAAa,GAAiB;IAClC,SAAS,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE;IAClE,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE;IAC/D,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE;CAC7D,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;IAEjC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAErB,KAAK,MAAM,cAAc,IAAI,MAAM,EAAE,CAAC;QACpC,eAAe,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACpD,CAAC;AACH,CAAC"}
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/cli/views/sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EACL,aAAa,EACb,YAAY,EACZ,eAAe,GAEhB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,aAAa,GAAiB;IAClC,SAAS,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE;IAClE,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE;IAC/D,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE;CAC7D,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,MAAM,EAAE,eAAe,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAC7C,MAAM,MAAM,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;IAEjC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAErB,KAAK,MAAM,cAAc,IAAI,eAAe,EAAE,CAAC;QAC7C,eAAe,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClB,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tjdals12/agent-bolt",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Manage, transform, and install team-shared AI development workflow assets across multiple AI tools",
   "type": "module",
   "license": "MIT",

package/skills/agent-bolt/SKILL.md

@@ -191,15 +191,26 @@ config is a hand edit.
                  {
                    "name": "commit-rules",
                    "description": "Commit message conventions and granularity for this project.",
+                   "usage": "Read before writing a commit message.",
                    "recommended": { "load": "always" }
                  },
                  {
                    "name": "typescript-standards",
                    "description": "Project-wide TypeScript coding standards: typing, naming, imports, function/class design, compiler options, and type performance.",
+                   "usage": "Read before editing TypeScript code.",
                    "recommended": {
                      "load": "conditional",
                      "glob": ["**/*.ts", "**/*.tsx"]
                    }
+                 },
+                 {
+                   "name": "review-guidelines",
+                   "description": "Code review conventions",
+                   "usage": "Read before reviewing code.",
+                   "recommended": {
+                     "load": "reference",
+                     "path": "docs/guidelines"
+                   }
                  }
                ]
              }
@@ -211,9 +222,9 @@ config is a hand edit.
    }
    ```
 
-   A guideline's `recommended` is the load mode `add-pack`/`add-item` will
-   write into the config: `always`, or `conditional` with the globs it applies
-   to.
+   A guideline's `recommended` contains the installation settings
+   `add-pack`/`add-item` will write into the config: `always`, `reference`
+   with an installation `path`, or `conditional` with its `glob` patterns.
 
 3. **Organize what you found and present it.** Group by pack, and give every
    item the same labeled shape, filled from its description. Present all of
@@ -437,7 +448,8 @@ and the project, settles it with the user, and hands the result to
 - Do not ask a question whose answer would not change what you recommend —
   every prompt is built from items in the working set.
 - Say what a guideline's load mode means when recommending one: `always`
-  applies it at all times, `conditional` only to files matching its globs.
+  applies it at all times, `reference` links a separate body file with its
+  `usage` text, and `conditional` applies only to files matching its globs.
 
 ## Install items
 
@@ -509,14 +521,16 @@ and the project, settles it with the user, and hands the result to
    — these commands edit `.agent-bolt/catalog-config.yml` and stop.
 
 3. **Adjust guideline load modes if the user wants them different.**
-   Selections land with the catalog's `recommended` load mode. Changing
-   `load`/`glob` afterward is done by editing the config file by hand — see
+   Selections land with the catalog's `recommended` installation settings.
+   Changing `load`/`glob`/`path` afterward is done by editing the config file
+   by hand — see
    [references/catalog-config-schema.md](references/catalog-config-schema.md).
 
-4. **Preflight the shared instructions file.** Some tools install guidelines
-   into a shared instructions file, fenced by a marker block the CLI owns
-   (e.g. Codex and OpenCode, which share `AGENTS.md`). If guidelines are being
-   installed for such a tool, check that file first:
+4. **Preflight the shared instructions file.** `always` and `reference` use
+   a marker block in `CLAUDE.md` (Claude), `AGENTS.md` (Cursor, Codex,
+   OpenCode), or `.github/copilot-instructions.md` (Copilot). Codex and
+   OpenCode also use `AGENTS.md` for conditional guidelines. Check the
+   relevant file first:
    - The file does not exist → fine; `sync` creates it, markers included.
    - The file exists and has `<!-- bolt:start -->` and `<!-- bolt:end -->` →
      fine.

package/skills/agent-bolt/references/catalog-config-schema.md

@@ -4,7 +4,7 @@
 get installed for which tools. It is normally managed through the CLI
 (`init`, `add-*`, `remove-*`). Two changes have no command and are made by
 hand: editing `sources` — adding, changing, or removing a catalog after init
-— and changing a guideline's `load`/`glob` (the CLI always writes the
+— and changing a guideline's `load`/`glob`/`path` (the CLI always writes the
 catalog's recommended value).
 
 After any hand edit, run `agent-bolt sync` (with the user's approval) to apply
@@ -48,6 +48,10 @@ packs:
         # always: applied at all times
         commit-rules:
           load: always
+        # reference: consulted when needed
+        review-guidelines:
+          load: reference
+          path: docs/guidelines
         # conditional: applied only to files matching the globs
         prisma-schema:
           load: conditional
@@ -72,14 +76,18 @@ Selection per pack:
 | `agents`     | Array of item names. Optional; defaults to `[]`          |
 | `guidelines` | Map of item name → load mode. Optional; defaults to `{}` |
 
-Guideline load modes (`load` is a discriminator — exactly one shape or the
-other):
+Guideline load modes (`load` is a discriminator — choose one of these shapes):
 
 ```yaml
 # Applied at all times
 some-guideline:
   load: always
 
+# Consulted when needed (installation directory required)
+review-guidelines:
+  load: reference
+  path: docs/guidelines
+
 # Applied only to files matching the globs (at least one glob required)
 other-guideline:
   load: conditional
@@ -93,6 +101,8 @@ other-guideline:
   hyphens (`^[a-z0-9]+(?:-[a-z0-9]+)*$`).
 - A local source `path` is resolved relative to the `.agent-bolt/` directory.
   A catalog at `<project>/.agent-bolt/catalog` is `path: ./catalog`.
+- A reference guideline's `path` is an installation directory relative to
+  the project root. Use `.` for the project root itself.
 - A pack selection whose source alias is missing from `sources` is pruned the
   next time the config is rewritten (reported as `orphanedSources` by `init`).
 - Renaming a source alias or a pack changes every installed file's name

package/skills/agent-bolt/references/json-responses.md

@@ -105,15 +105,26 @@ agent-bolt list-items --source=common --packs=common --json
               {
                 "name": "commit-rules",
                 "description": "Commit message conventions and granularity for this project.",
+                "usage": "Read before writing a commit message.",
                 "recommended": { "load": "always" }
               },
               {
                 "name": "typescript-standards",
                 "description": "Project-wide TypeScript coding standards: …",
+                "usage": "Read before editing TypeScript code.",
                 "recommended": {
                   "load": "conditional",
                   "glob": ["**/*.ts", "**/*.tsx"]
                 }
+              },
+              {
+                "name": "review-guidelines",
+                "description": "Code review conventions",
+                "usage": "Read before reviewing code.",
+                "recommended": {
+                  "load": "reference",
+                  "path": "docs/guidelines"
+                }
               }
             ]
           }
@@ -125,8 +136,11 @@ agent-bolt list-items --source=common --packs=common --json
 }
 ```
 
-- Guidelines carry `recommended` — the load mode `add-pack`/`add-item` will
-  write into the config.
+- Guidelines carry `recommended` — the installation settings
+  `add-pack`/`add-item` will write into the config — and optional `usage`,
+  the text inserted alongside the guideline link when installed as a reference.
+  Missing `usage` is omitted from JSON; reference rendering uses a fallback
+  message, and sync warns about the missing author-provided text.
 - Unlike `list-packs`, a broken source fails the whole command (top-level
   `error`, exit 1).
 
@@ -157,7 +171,9 @@ agent-bolt show-item --source=common --pack=common --item=create-commit --json
 ```
 
 - `type` is `skill`, `agent`, or `guideline`. `instructions` is the full body
-  — it can be long. `assets` lists extra files a skill ships with.
+  for skills and agents — it can be long. Guidelines return `body`,
+  `bodyPath`, optional `usage`, and `recommended` instead. `assets` lists extra files
+  a skill ships with.
 
 ## add-pack