@codedrifters/configulator 0.0.277 → 0.0.279

package/lib/index.mjs

@@ -2867,20 +2867,26 @@ var createPackageSkill = {
     "   places the sub-project at `packages/<scope>/<name>`.",
     "",
     "6. **Tell the user how to synthesize.** Instruct them to run, from",
-    "   the repo root:",
+    "   the repo root, the safe three-step regen sequence:",
     "",
     "   ```",
+    "   pnpm i",
     "   pnpm exec projen",
-    "   pnpm install",
+    "   pnpm i",
     "   ```",
     "",
-    "   `pnpm exec projen` regenerates the sub-project tree;",
-    "   `pnpm install` updates the workspace lockfile. Do **not** run",
-    "   these commands yourself \u2014 the user runs them.",
+    "   The leading `pnpm i` syncs `node_modules` with `pnpm-lock.yaml`",
+    "   so synth runs against the right configulator/projen/plugin",
+    "   versions \u2014 without it, `pnpm exec projen` may synth against a",
+    "   stale resolved version of any pnpm-managed component and produce",
+    "   phantom drift in generated files. `pnpm exec projen` regenerates",
+    "   the sub-project tree; the trailing `pnpm i` updates the workspace",
+    "   lockfile to pick up any dependency changes projen wrote during",
+    "   synth. Do **not** run these commands yourself \u2014 the user runs them.",
     "",
     "## Guardrails",
     "",
-    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm build`,",
+    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm i`, `pnpm build`,",
     "  `pnpm test`, or any other package-manager, build, or test command.",
     "  Emit the projen block and instructions only.",
     "- Never scaffold outside `packages/`. Deployable apps belong under",
@@ -2990,20 +2996,26 @@ var createAppSkill = {
     "   sub-project at `apps/<scope>/<name>`.",
     "",
     "6. **Tell the user how to synthesize.** Instruct them to run, from",
-    "   the repo root:",
+    "   the repo root, the safe three-step regen sequence:",
     "",
     "   ```",
+    "   pnpm i",
     "   pnpm exec projen",
-    "   pnpm install",
+    "   pnpm i",
     "   ```",
     "",
-    "   `pnpm exec projen` regenerates the sub-project tree;",
-    "   `pnpm install` updates the workspace lockfile. Do **not** run",
-    "   these commands yourself \u2014 the user runs them.",
+    "   The leading `pnpm i` syncs `node_modules` with `pnpm-lock.yaml`",
+    "   so synth runs against the right configulator/projen/plugin",
+    "   versions \u2014 without it, `pnpm exec projen` may synth against a",
+    "   stale resolved version of any pnpm-managed component and produce",
+    "   phantom drift in generated files. `pnpm exec projen` regenerates",
+    "   the sub-project tree; the trailing `pnpm i` updates the workspace",
+    "   lockfile to pick up any dependency changes projen wrote during",
+    "   synth. Do **not** run these commands yourself \u2014 the user runs them.",
     "",
     "## Guardrails",
     "",
-    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm build`,",
+    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm i`, `pnpm build`,",
     "  `pnpm test`, or any other package-manager, build, or test command.",
     "  Emit the projen block and instructions only.",
     "- Never scaffold outside `apps/`. Shared libraries belong under",
@@ -3149,20 +3161,26 @@ var createSiteSkill = {
     "   `sites/<scope>/<name>`.",
     "",
     "6. **Tell the user how to synthesize.** Instruct them to run, from",
-    "   the repo root:",
+    "   the repo root, the safe three-step regen sequence:",
     "",
     "   ```",
+    "   pnpm i",
     "   pnpm exec projen",
-    "   pnpm install",
+    "   pnpm i",
     "   ```",
     "",
-    "   `pnpm exec projen` regenerates the sub-project tree;",
-    "   `pnpm install` updates the workspace lockfile. Do **not** run",
-    "   these commands yourself \u2014 the user runs them.",
+    "   The leading `pnpm i` syncs `node_modules` with `pnpm-lock.yaml`",
+    "   so synth runs against the right configulator/projen/plugin",
+    "   versions \u2014 without it, `pnpm exec projen` may synth against a",
+    "   stale resolved version of any pnpm-managed component and produce",
+    "   phantom drift in generated files. `pnpm exec projen` regenerates",
+    "   the sub-project tree; the trailing `pnpm i` updates the workspace",
+    "   lockfile to pick up any dependency changes projen wrote during",
+    "   synth. Do **not** run these commands yourself \u2014 the user runs them.",
     "",
     "## Guardrails",
     "",
-    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm build`,",
+    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm i`, `pnpm build`,",
     "  `pnpm test`, or any other package-manager, build, or test command.",
     "  Emit the projen block and instructions only.",
     "- Never scaffold the monorepo-wide docs site under `sites/`. The",
@@ -3266,7 +3284,7 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
           "## Important Notes",
           "",
           "- **Never edit generated files** \u2014 they are marked with `// ~~ Generated by projen`",
-          "- **After modifying Projen configuration**, run `pnpm exec projen` to regenerate files, then `pnpm install` to update the lockfile.",
+          "- **After modifying Projen configuration**, run the three-step regen sequence: `pnpm i`, then `pnpm exec projen`, then `pnpm i` again. The leading `pnpm i` syncs `node_modules` with the lockfile so synth runs against the right configulator/projen/plugin versions; the trailing `pnpm i` refreshes the lockfile to match anything projen rewrote in `package.json`.",
           "- **Configure dependencies through Projen** \u2014 never use `npm install`, `pnpm add`, or `yarn add`. Add them to `deps` or `devDeps` in Projen config.",
           "- **Export from index.ts** to maintain clean public APIs",
           "",
@@ -3325,7 +3343,7 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
           "",
           "After making changes that need validation, tell the user the specific commands to run:",
           "",
-          "1. **After projen config changes** \u2014 tell the user to run `pnpm exec projen && pnpm install`",
+          "1. **After projen config changes** \u2014 tell the user to run the three-step regen sequence: `pnpm i && pnpm exec projen && pnpm i`",
           "2. **After source code changes** \u2014 tell the user to run `pnpm --filter @codedrifters/<package> test`",
           "3. **After multi-package changes** \u2014 tell the user to run `pnpm build:all`"
         ].join("\n"),
@@ -9101,7 +9119,7 @@ var githubWorkflowBundle = {
         "",
         "When the user says **open a PR** (or similar), follow these steps exactly:",
         "",
-        "1. **Regenerate project files** \u2014 run `pnpm exec projen` then `pnpm install` to ensure all generated files are up to date. Check `git diff` \u2014 if there are changes, commit them before proceeding.",
+        "1. **Regenerate project files** \u2014 run the three-step regen sequence (`pnpm i`, then `pnpm exec projen`, then `pnpm i` again) to ensure all generated files are up to date. The leading `pnpm i` is required because `pnpm exec projen` synthesises against whatever version of configulator (and projen, and any projen plugins) is currently resolved in `node_modules`; if the lockfile has moved past `node_modules` (typically right after `git pull` lands a dependency upgrade, or on a fresh checkout), synth runs against stale templates and produces phantom drift in `.claude/`, `.github/labels.yml`, `CLAUDE.md`, and other generated files. The trailing `pnpm i` picks up any dependency changes projen wrote into `package.json` during synth. Check `git diff` after the third step \u2014 if there are changes, commit them before proceeding.",
         "2. **Run the full monorepo build** \u2014 run `pnpm build:all` to compile, lint, and test all packages (mirrors the CI pipeline). This command requires the user to be authenticated to AWS on the prod account used for Turborepo remote caching (`readonlyaccess-prod-525259625215-us-east-1` profile). If the command fails due to AWS credentials, ask the user to authenticate first. If the build produces changes to turbo inputs (typically snapshot files or ESLint auto-fixes), commit those changes and run `pnpm build:all` again \u2014 the build must complete cleanly with no uncommitted changes.",
         "3. **Check for uncommitted changes** \u2014 if any exist, commit them with a conventional commit message",
         "4. **Pull and rebase from the default branch** \u2014 run `git pull origin {{repository.defaultBranch}} --rebase` to incorporate the latest changes and resolve any conflicts before pushing",
@@ -13799,7 +13817,7 @@ var issueWorkerSubAgent = {
     "",
     "Run the appropriate verification commands depending on what changed:",
     "",
-    "1. If Projen config was changed: `pnpm exec projen && pnpm install`",
+    "1. If Projen config was changed: run the three-step regen sequence `pnpm i && pnpm exec projen && pnpm i` (leading `pnpm i` syncs `node_modules` with the lockfile so synth runs against the right configulator/projen/plugin versions; trailing `pnpm i` refreshes the lockfile after synth)",
     "2. Compile the affected package: `pnpm --filter @codedrifters/<package> compile`",
     "3. Test the affected package: `pnpm --filter @codedrifters/<package> test`",
     "4. If changes span multiple packages: `pnpm build:all`",
@@ -15090,7 +15108,7 @@ var pnpmBundle = {
         "- Configure dependencies in Projen configuration files (`.projenrc.ts` or `projenrc/*.ts`)",
         "- Add dependencies to `deps`, `devDeps`, or `peerDeps` arrays in project configuration",
         '- Use catalog dependencies when available (e.g., `"aws-cdk-lib@catalog:"`)',
-        "- Ask the user to run `pnpm exec projen` and `pnpm install` after updating dependency configuration",
+        "- Ask the user to run the three-step regen sequence after updating dependency configuration: `pnpm i`, then `pnpm exec projen`, then `pnpm i` again. The leading `pnpm i` syncs `node_modules` with the lockfile so synth runs against the right configulator/projen/plugin versions; the trailing `pnpm i` picks up any dependency changes projen wrote during synth.",
         "",
         "**DO NOT:**",
         "- Run `npm install some-package`",
@@ -16527,14 +16545,19 @@ var projenBundle = {
         "",
         "## Synthesizing Projen Configuration",
         "",
-        "After modifying any file in `projenrc/` or `.projenrc.ts`, regenerate project files:",
+        "After modifying any file in `projenrc/` or `.projenrc.ts`, regenerate project files using the safe three-step sequence:",
         "",
         "```sh",
+        "pnpm i",
         "pnpm exec projen",
-        "pnpm install",
+        "pnpm i",
         "```",
         "",
-        "Both steps are required \u2014 `pnpm exec projen` regenerates files, `pnpm install` updates the lockfile to match.",
+        "All three steps are required:",
+        "",
+        "1. The leading `pnpm i` guarantees `node_modules` matches `pnpm-lock.yaml` before synth. Without this step, `pnpm exec projen` may synth against a stale version of any pnpm-resolved component (configulator itself, projen, or any plugin) that the lockfile has already moved past \u2014 most commonly right after `git pull` updates the lockfile or on a fresh checkout. The result is phantom drift in `.claude/`, `.github/labels.yml`, `CLAUDE.md`, and other configulator-generated files that looks like a real bundle change but vanishes after running `pnpm i`.",
+        "2. `pnpm exec projen` regenerates files against the now-synced templates.",
+        "3. The trailing `pnpm i` picks up any dependency changes projen wrote into `package.json` during the synth pass and refreshes the lockfile.",
         "",
         "## Building",
         "",
@@ -16615,7 +16638,7 @@ var projenBundle = {
         "After finishing implementation work, validate that changes are correct by running the appropriate commands depending on what was changed:",
         "",
         "1. **Projen config changes** (`projenrc/`, `.projenrc.ts`):",
-        "   - Run `pnpm exec projen` then `pnpm install`",
+        "   - Run the three-step regen sequence: `pnpm i`, then `pnpm exec projen`, then `pnpm i` again",
         "   - Verify no unexpected generated file changes with `git diff`",
         "",
         "2. **Source code changes** (in a sub-package):",
@@ -16632,8 +16655,8 @@ var projenBundle = {
         "",
         "| Task | Command |",
         "|------|---------|",
-        "| Synthesize projen | `pnpm exec projen` |",
-        "| Install deps | `pnpm install` |",
+        "| Regenerate projen configuration | `pnpm i && pnpm exec projen && pnpm i` |",
+        "| Install deps | `pnpm i` |",
         "| Full monorepo build | `pnpm build:all` |",
         "| Root build only | `pnpm build` |",
         "| Compile one package | `pnpm --filter @codedrifters/<pkg> compile` |",
@@ -16689,9 +16712,22 @@ var projenBundle = {
         "}",
         "```",
         "",
+        "The same pattern applies to bundled sub-agents and skills. Use `agentConfig.subAgentExtensions` to append project-specific content to a sub-agent prompt and `agentConfig.skillExtensions` to append content to a skill's `SKILL.md` body. Both options mirror `ruleExtensions` exactly \u2014 keys are sub-agent / skill names, values are markdown appended after a horizontal rule, and unknown keys are silently ignored.",
+        "",
+        "```typescript",
+        "agentConfig: {",
+        "  subAgentExtensions: {",
+        "    'requirements-writer': '## Project-Specific Gaps\\n\\n- My custom guidance',",
+        "  },",
+        "  skillExtensions: {",
+        "    'write-requirement': '## Project-Specific Templates\\n\\n- My custom template note',",
+        "  },",
+        "}",
+        "```",
+        "",
         "## After Any Change",
         "",
-        "Run `pnpm exec projen` then `pnpm install` to regenerate the output files."
+        "Run the three-step regen sequence to regenerate the output files: `pnpm i`, then `pnpm exec projen`, then `pnpm i` again. The leading `pnpm i` syncs `node_modules` with the lockfile before synth so `pnpm exec projen` runs against the right configulator/projen/plugin versions; the trailing `pnpm i` refreshes the lockfile for any dependency changes projen made during synth."
       ].join("\n"),
       tags: ["workflow"]
     },
@@ -16709,7 +16745,7 @@ var projenBundle = {
         "- Edit Projen configuration in:",
         "  - `.projenrc.ts` (root)",
         "  - `projenrc/*.ts` (package-specific)",
-        "- After making Projen changes, run `pnpm exec projen` to synthesize",
+        "- After making Projen changes, run the three-step regen sequence: `pnpm i`, `pnpm exec projen`, `pnpm i`. The leading `pnpm i` ensures `node_modules` matches the lockfile so synth runs against the right configulator/projen/plugin versions; without it, synth can produce phantom drift in generated files. The trailing `pnpm i` picks up dependency changes projen wrote during synth.",
         "",
         "## Workspace Dependencies",
         "",
@@ -27964,9 +28000,13 @@ ${hook}`
     });
   }
   /**
-   * Resolves template variables in skill instructions using project metadata.
+   * Resolves template variables in skill instructions using project metadata,
+   * then appends any matching `skillExtensions` content after a horizontal
+   * rule. Unknown keys in `skillExtensions` are silently ignored, mirroring
+   * the `ruleExtensions` contract.
    */
   resolveSkillTemplates(skills, metadata) {
+    const extensions = this.options.skillExtensions;
     return skills.map((skill) => {
       const { resolved, unresolvedKeys } = resolveTemplateVariables(
         skill.instructions,
@@ -27977,13 +28017,24 @@ ${hook}`
           `AgentConfig: ProjectMetadata not found; skill '${skill.name}' using default values`
         );
       }
-      return resolved !== skill.instructions ? { ...skill, instructions: resolved } : skill;
+      const extra = extensions?.[skill.name];
+      const baseInstructions = resolved;
+      const finalInstructions = extra !== void 0 && extra !== "" ? `${baseInstructions}
+
+---
+
+${extra}` : baseInstructions;
+      return finalInstructions !== skill.instructions ? { ...skill, instructions: finalInstructions } : skill;
     });
   }
   /**
-   * Resolves template variables in sub-agent prompts using project metadata.
+   * Resolves template variables in sub-agent prompts using project metadata,
+   * then appends any matching `subAgentExtensions` content after a horizontal
+   * rule. Unknown keys in `subAgentExtensions` are silently ignored,
+   * mirroring the `ruleExtensions` contract.
    */
   resolveSubAgentTemplates(subAgents, metadata) {
+    const extensions = this.options.subAgentExtensions;
     return subAgents.map((agent) => {
       const { resolved, unresolvedKeys } = resolveTemplateVariables(
         agent.prompt,
@@ -27994,7 +28045,14 @@ ${hook}`
           `AgentConfig: ProjectMetadata not found; sub-agent '${agent.name}' using default values`
         );
       }
-      return resolved !== agent.prompt ? { ...agent, prompt: resolved } : agent;
+      const extra = extensions?.[agent.name];
+      const basePrompt = resolved;
+      const finalPrompt = extra !== void 0 && extra !== "" ? `${basePrompt}
+
+---
+
+${extra}` : basePrompt;
+      return finalPrompt !== agent.prompt ? { ...agent, prompt: finalPrompt } : agent;
     });
   }
   /**