@codedrifters/configulator 0.0.250 → 0.0.251

package/README.md

@@ -1,1330 +1,7 @@
-# Configulator
+# @codedrifters/configulator
 
-A library of [Projen](https://projen.io/) components used by CodeDrifters to manage repository configuration across various projects. Configulator extends standard Projen configurations with our preferred defaults and provides company-specific components and workflows.
+A library of [Projen](https://projen.io/) components used by CodeDrifters to manage repository configuration across projects. Configulator extends standard Projen configurations with preferred defaults and provides shared project types (`MonorepoProject`, `TypeScriptProject`), a PNPM/Turborepo integration, and an `AgentConfig` API for single-source AI assistant configuration.
 
-## Table of Contents
+**Documentation:** See the [@codedrifters/configulator docs](../../../docs/src/content/docs/packages/@codedrifters/configulator/index.md) in the monorepo's Starlight site.
 
-- [Overview](#overview)
-- [What is Projen?](#what-is-projen)
-- [What is Configulator?](#what-is-configulator)
-- [Project Types](#project-types)
-  - [MonorepoProject](#monorepoproject)
-  - [TypeScriptProject](#typescriptproject)
-- [Usage Patterns](#usage-patterns)
-- [Configuration Options](#configuration-options)
-- [Turbo Repo](#turbo-repo)
-- [PNPM Workspace](#pnpm-workspace)
-- [Updating VERSION constants](#updating-version-constants)
-- [File Management Rules](#file-management-rules)
-- [Workflow Tips](#workflow-tips)
-- [API Reference](#api-reference)
-- [Agent Configuration](#agent-configuration)
-  - [Why Single-Source?](#why-single-source)
-  - [Quick Start](#quick-start)
-  - [Configuration Options](#configuration-options-1)
-  - [Built-in Rule Bundles](#built-in-rule-bundles)
-  - [Custom Rules](#custom-rules)
-  - [Skills](#skills)
-  - [Sub-Agents](#sub-agents)
-  - [MCP Server Configuration](#mcp-server-configuration)
-  - [Platform-Specific Settings](#platform-specific-settings)
-  - [Template Variables](#template-variables)
-  - [Examples](#examples)
-- [Troubleshooting](#troubleshooting)
-- [Additional Resources](#additional-resources)
-
-## Overview
-
-This guide explains the core infrastructure tools used in our projects: Projen and Configulator. These tools help us maintain consistency across multiple projects and reduce repetitive setup work.
-
-## What is Projen?
-
-Projen is a project generator and configuration management tool that:
-
-- Creates standardized project structures
-- Manages configuration files programmatically
-- Handles dependency updates automatically
-- Provides consistent build workflows
-
-### Key Concepts
-
-**Components:** Individual pieces of configuration (e.g., Jest, Vitest, Prettier, TypeScript). Each component configures specific files and settings. When you add or remove a component, all its associated files and configurations are automatically managed.
-
-**Project Types:** Base-level configurations for different kinds of projects (e.g., TypeScript app, monorepo, React project).
-
-**Synthesis:** The process of generating actual files from your configuration. Run `npx projen` to synthesize your project.
-
-## What is Configulator?
-
-Configulator is CodeDrifters' custom extension of Projen. It:
-
-- Extends standard Projen configurations with our preferred defaults
-- Provides company-specific components and workflows
-- Available as an npm package: `@codedrifters/configulator`
-
-### Why We Built It
-
-Instead of setting up each new project from scratch (90% identical setup repeated), Configulator lets us:
-
-- Generate consistent project structures
-- Pick and choose components we need
-- Maintain standardized tooling across all projects
-- Receive updates to common configurations automatically
-
-## Project Types
-
-Configulator provides two main project types designed for monorepo workflows:
-
-### MonorepoProject
-
-**MonorepoProject** extends Projen's `TypeScriptAppProject` and is designed specifically for monorepo root projects. It provides all the infrastructure needed to manage a monorepo with multiple sub-projects.
-
-#### When to Use It
-
-Use `MonorepoProject` for:
-- Root-level monorepo configuration
-- Managing workspace-wide settings (PNPM, Turborepo, VS Code)
-- Defining shared dependency catalogs
-- Configuring build workflows for the entire monorepo
-
-#### Key Features
-
-- **PNPM Workspace Management**: Automatically generates and manages `pnpm-workspace.yaml`
-- **Turborepo Integration**: Built-in support for Turborepo with remote caching capabilities
-- **VS Code Configuration**: Automatic VS Code settings for consistent development experience
-- **Default Catalog**: Pre-configured catalog of common dependency versions (AWS CDK, Projen, Constructs, Turbo)
-- **Build Workflow Configuration**: GitHub Actions workflows with Turborepo support
-- **TypeScript Configuration**: Pre-configured TypeScript with sensible defaults
-
-#### Basic Example
-
-```typescript
-import { MonorepoProject } from '@codedrifters/configulator';
-
-const project = new MonorepoProject({
-  name: 'my-monorepo'
-});
-
-project.synth();
-```
-
-#### Advanced Example with Remote Cache
-
-```typescript
-import { MonorepoProject } from '@codedrifters/configulator';
-
-const project = new MonorepoProject({
-  name: 'my-monorepo',
-  
-  turboOptions: {
-    remoteCacheOptions: {
-      profileName: 'profile-prod-000000000000-us-east-1',
-      oidcRole: 'arn:aws:iam::000000000000:role/TurborepoRemoteCachingRole',
-      endpointParamName: '/TURBOREPO/ENDPOINT/PARAMETER',
-      tokenParamName: '/TURBOREPO/TOKEN/PARAMETER',
-      teamName: 'prod',
-    },
-  },
-  
-  pnpmOptions: {
-    pnpmWorkspaceOptions: {
-      onlyBuiltDependencies: ['@swc/core', 'esbuild', 'unrs-resolver'],
-    },
-  },
-});
-
-project.synth();
-```
-
-#### Configuration Options
-
-The `MonorepoProject` accepts all options from `TypeScriptProjectOptions` plus:
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `name` | `string` | **Required** | Project name |
-| `turbo` | `boolean` | `true` | Enable Turborepo support |
-| `turboOptions` | `TurboRepoOptions` | `undefined` | Turborepo configuration including remote cache options |
-| `pnpmOptions.version` | `string` | `VERSION.PNPM_VERSION` | PNPM version to use |
-| `pnpmOptions.pnpmWorkspaceOptions` | `PnpmWorkspaceOptions` | See below | PNPM workspace configuration |
-
-**Default Behavior:**
-- `projenrcTs: true` - Uses TypeScript for projen configuration
-- `prettier: true` - Enables Prettier formatting
-- `licensed: false` - No license by default
-- `sampleCode: false` - No sample code generated
-- `jest: false` - Jest disabled at root level
-- `release: false` - Root project is not released
-- `depsUpgrade: false` - No automatic dependency upgrades at root
-- `disableTsconfigDev: true` - No tsconfig.dev.json at root
-- `packageManager: NodePackageManager.PNPM` - PNPM is mandatory
-- `defaultReleaseBranch: "main"` - Standard branch name
-
-**Pull Request Linting:**
-- By default, pull request titles are validated to follow [Conventional Commits](https://www.conventionalcommits.org/)
-- All conventional commit types are allowed by default: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
-- This provides flexibility for different types of changes while maintaining consistency
-
-**Overriding Pull Request Lint Options:**
-
-To customize which commit types are allowed, override the `githubOptions.pullRequestLintOptions`:
-
-```typescript
-const project = new MonorepoProject({
-  name: 'my-monorepo',
-  githubOptions: {
-    pullRequestLintOptions: {
-      semanticTitleOptions: {
-        types: ['feat', 'fix', 'docs', 'chore'], // Only allow these types
-      },
-    },
-  },
-});
-```
-
-You can also configure other pull request linting options:
-
-```typescript
-const project = new MonorepoProject({
-  name: 'my-monorepo',
-  githubOptions: {
-    pullRequestLintOptions: {
-      semanticTitleOptions: {
-        types: ['feat', 'fix', 'docs'],
-        requireScope: true, // Require scope in commit type (e.g., feat(ui):)
-        scopes: ['ui', 'api', 'core'], // Only allow these scopes
-      },
-    },
-  },
-});
-```
-
-The root project automatically includes `@codedrifters/configulator` and `constructs` as dev dependencies.
-
-### TypeScriptProject
-
-**TypeScriptProject** extends Projen's `TypeScriptProject` with CodeDrifters defaults. It's designed for sub-projects within a monorepo or standalone TypeScript projects.
-
-#### When to Use It
-
-Use `TypeScriptProject` for:
-- Sub-projects within a monorepo (most common use case)
-- Standalone TypeScript libraries or applications
-- Packages that will be published to NPM
-- Projects that need consistent testing, linting, and build configuration
-
-#### Key Features
-
-- **Automatic PNPM Version Inheritance**: Inherits PNPM version from parent `MonorepoProject` when used as a sub-project
-- **Configurable Test Runner**: Choose Jest (default) or Vitest via the `testRunner` option. Jest uses `@swc/jest` for fast execution; Vitest uses a generated `vitest.config.ts` with coverage and watch tasks.
-- **Prettier Integration**: Automatic Prettier configuration
-- **Automatic Turborepo Integration**: Automatically configures Turborepo tasks when parent has TurboRepo enabled
-- **Catalog Dependency Support**: Can use catalog dependencies defined in parent workspace
-- **Release Support**: Built-in support for NPM releases with continuous deployment triggers
-
-#### Basic Example
-
-```typescript
-import { MonorepoProject, TypeScriptProject } from '@codedrifters/configulator';
-
-// Root project
-const root = new MonorepoProject({
-  name: 'my-monorepo'
-});
-
-// Sub-project
-const myPackage = new TypeScriptProject({
-  name: 'my-package',
-  packageName: '@myorg/my-package',
-  outdir: 'packages/my-package',
-  parent: root,
-  description: 'My awesome package',
-  deps: ['some-dependency'],
-  devDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
-});
-
-root.synth();
-```
-
-#### Example with Release Configuration
-
-```typescript
-import { MonorepoProject, TypeScriptProject } from '@codedrifters/configulator';
-
-const root = new MonorepoProject({
-  name: 'my-monorepo'
-});
-
-const constructs = new TypeScriptProject({
-  name: '@codedrifters/constructs',
-  packageName: '@codedrifters/constructs',
-  outdir: 'packages/@codedrifters/constructs',
-  description: 'Constructs frequently used in CodeDrifter projects.',
-  repository: 'https://github.com/codedrifters/packages',
-  authorName: 'CodeDrifters',
-  authorOrganization: true,
-  licensed: false,
-  parent: root,
-  
-  deps: [
-    '@aws-sdk/client-dynamodb',
-    '@types/aws-lambda',
-    'change-case@^4.0',
-    'type-fest@^4',
-  ],
-  devDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
-  peerDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
-  
-  release: true,
-  releaseToNpm: true,
-});
-
-root.synth();
-```
-
-#### Parent-Child Relationship
-
-When `TypeScriptProject` is created with a `parent` that is a `MonorepoProject`:
-
-1. **PNPM Version**: Automatically inherits the PNPM version from the parent
-2. **Workspace Integration**: Automatically added to the parent's PNPM workspace
-3. **Turborepo Integration**: If parent has Turborepo enabled, the sub-project automatically gets Turborepo task configuration
-4. **Catalog Dependencies**: Can reference catalog dependencies defined in the parent's workspace
-5. **Dependency Upgrade Exclusions**: Automatically excludes catalog-managed dependencies from upgrade workflows
-
-#### Configuration Options
-
-The `TypeScriptProject` accepts all options from Projen's `TypeScriptProjectOptions` with these defaults:
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `name` | `string` | **Required** | Project name |
-| `packageName` | `string` | Same as `name` | NPM package name |
-| `outdir` | `string` | `"."` | Output directory (required for sub-projects) |
-| `parent` | `MonorepoProject` | `undefined` | Parent monorepo project (recommended) |
-| `defaultReleaseBranch` | `string` | `"main"` | Default release branch |
-| `packageManager` | `NodePackageManager` | `PNPM` | Package manager (always PNPM) |
-| `prettier` | `boolean` | `true` | Enable Prettier |
-| `sampleCode` | `boolean` | `false` | Generate sample code |
-| `release` | `boolean` | `false` | Enable NPM releases |
-| `licensed` | `boolean` | `false` | Include license (unless `license` option provided) |
-| `testRunner` | `TestRunner` | `TestRunner.JEST` | Test runner: `TestRunner.JEST` or `TestRunner.VITEST` |
-| `vitestOptions` | `VitestOptions` | `undefined` | Options for Vitest (only used when `testRunner` is `TestRunner.VITEST`) |
-
-**Test runner (Jest or Vitest):**
-- **Jest (default):** External `jest.config.json`, `@swc/jest` for fast compilation, test files in `src/`. Use when you want to keep existing Jest-based workflows.
-- **Vitest:** Set `testRunner: TestRunner.VITEST` to use Vitest. The project gets a generated `vitest.config.ts`, `vitest` (and optionally `@vitest/coverage-v8`) as devDeps, and tasks: `test` (runs `vitest run`), `test:watch`. Snapshots are updated automatically on each test run to match the project's previous Jest behavior (no separate snapshot-update step). Coverage directory is added to `.gitignore` and `.npmignore`. Jest is disabled (`jest: false`) when Vitest is selected; the two cannot be used together.
-
-**NPM Ignore:**
-- Automatically ignores `*.spec.*`, `*.test.*`, and `__fixtures__` patterns
-
-**Release Configuration:**
-- Uses continuous release trigger
-- Only releases when package directory content changes
-- Release path based on `outdir`
-
-## Usage Patterns
-
-### Monorepo Setup Pattern
-
-The most common pattern is to create a monorepo with a root project and multiple sub-projects:
-
-1. **Create the root project** using `MonorepoProject`:
-
-```typescript
-// projenrc/root-project.ts
-import { MonorepoProject } from '@codedrifters/configulator';
-
-export const configureRootProject = () => {
-  const project = new MonorepoProject({
-    name: 'my-monorepo',
-    turboOptions: {
-      remoteCacheOptions: {
-        profileName: 'my-profile',
-        oidcRole: 'arn:aws:iam::123456789012:role/TurborepoRole',
-        endpointParamName: '/TURBOREPO/ENDPOINT',
-        tokenParamName: '/TURBOREPO/TOKEN',
-        teamName: 'my-team',
-      },
-    },
-  });
-  
-  return project;
-};
-```
-
-2. **Add sub-projects** using `TypeScriptProject`:
-
-```typescript
-// projenrc/my-package.ts
-import { MonorepoProject } from '@codedrifters/configulator';
-import { TypeScriptProject } from '@codedrifters/configulator';
-
-export const configureMyPackage = (parent: MonorepoProject) => {
-  const myPackage = new TypeScriptProject({
-    name: 'my-package',
-    packageName: '@myorg/my-package',
-    outdir: 'packages/my-package',
-    description: 'My package description',
-    parent,
-    deps: ['dependency-1', 'dependency-2'],
-    devDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
-  });
-  
-  return { myPackage };
-};
-```
-
-3. **Wire everything together** in your main projenrc file:
-
-```typescript
-// .projenrc.ts or projenrc/index.ts
-import { configureRootProject } from './projenrc/root-project';
-import { configureMyPackage } from './projenrc/my-package';
-
-const root = configureRootProject();
-const { myPackage } = configureMyPackage(root);
-
-root.synth();
-```
-
-### Standalone Project Pattern
-
-You can also use `TypeScriptProject` without a parent for standalone projects:
-
-```typescript
-import { TypeScriptProject } from '@codedrifters/configulator';
-
-const project = new TypeScriptProject({
-  name: 'standalone-project',
-  packageName: '@myorg/standalone-project',
-  description: 'A standalone TypeScript project',
-  deps: ['some-dependency'],
-});
-
-project.synth();
-```
-
-Note: Without a parent, the project will use the default PNPM version from Configulator's version constants.
-
-### Dependency Management
-
-> **⚠️ Important:** All dependencies must be configured through Projen configuration files (`.projenrc.ts` or `projenrc/*.ts`), never by manually running package manager commands like `npm install`, `pnpm add`, or `yarn add`. Manual installation will create conflicts with Projen-managed files and may be overwritten when you run `npx projen`.
-
-#### Using Catalog Dependencies
-
-The `MonorepoProject` automatically sets up a default catalog with common dependencies:
-
-```typescript
-// Defined in MonorepoProject defaults
-defaultCatalog: {
-  'aws-cdk': VERSION.AWS_CDK_CLI_VERSION,
-  'aws-cdk-lib': VERSION.AWS_CDK_LIB_VERSION,
-  'projen': VERSION.PROJEN_VERSION,
-  'constructs': VERSION.AWS_CONSTRUCTS_VERSION,
-  'turbo': VERSION.TURBO_VERSION,
-}
-```
-
-Sub-projects can reference these using the `catalog:` protocol:
-
-```typescript
-const myPackage = new TypeScriptProject({
-  // ... other options
-  devDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
-  peerDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
-});
-```
-
-#### Workspace Dependencies
-
-Sub-projects can depend on other packages in the same monorepo:
-
-```typescript
-const packageB = new TypeScriptProject({
-  // ... other options
-  deps: ['@myorg/package-a@workspace:*'],
-});
-```
-
-#### Custom Catalog
-
-You can also define custom catalogs in the `MonorepoProject`:
-
-```typescript
-const root = new MonorepoProject({
-  name: 'my-monorepo',
-  pnpmOptions: {
-    pnpmWorkspaceOptions: {
-      defaultCatalog: {
-        'react': '^18.0.0',
-        'typescript': '^5.0.0',
-      },
-      namedCatalogs: {
-        frontend: {
-          'react': '^18.0.0',
-          'react-dom': '^18.0.0',
-        },
-        backend: {
-          'express': '^4.18.0',
-        },
-      },
-    },
-  },
-});
-```
-
-Then reference them in sub-projects:
-
-```typescript
-// Default catalog
-deps: ['react@catalog:react']
-
-// Named catalog
-deps: ['react@catalog:frontend/react']
-```
-
-### Updating VERSION constants
-
-The catalog versions (e.g. `VERSION.PROJEN_VERSION`, `VERSION.TURBO_VERSION`) in `src/versions.ts` can be updated automatically so they stay in sync with npm releases while respecting the PNPM workspace `minimumReleaseAge` (so only versions published long enough ago are considered).
-
-**What it does**
-
-- A script (`scripts/update-versions.ts` at monorepo root) fetches the latest eligible version for each npm-backed constant from the npm registry using the `time` field.
-- Only versions that have been published for at least `minimumReleaseAge` minutes (from the PNPM workspace) are considered.
-- The script runs as part of the **upgrade** task, so when the upgrade workflow runs (e.g. nightly or `workflow_dispatch`), version updates are included in the same PR as dependency upgrades.
-
-**How to run**
-
-From the monorepo root:
-
-- **Propose only** (print suggested changes, do not edit files):
-  ```bash
-  pnpm run update-versions
-  ```
-- **Apply locally** (update `versions.ts` and run `npx projen`):
-  ```bash
-  pnpm run update-versions -- --apply
-  ```
-- **In CI**: When run from the upgrade workflow, the script auto-applies when there are updates so changes are included in the upgrade PR.
-
-**Adding a new npm-backed constant**
-
-1. Add the constant to `src/versions.ts` (e.g. `MY_PACKAGE_VERSION: "1.0.0"`).
-2. Add an entry to `VERSION_NPM_PACKAGES` in `src/version-package-map.ts`:
-   ```typescript
-   { key: "MY_PACKAGE_VERSION", npmPackage: "my-package" },
-   ```
-   Constants not listed in `VERSION_NPM_PACKAGES` (e.g. `NODE_WORKFLOWS`) are skipped by the update script.
-
-### Turborepo Integration
-
-When you create a `MonorepoProject` with `turbo: true` (the default), Turborepo is automatically configured. Sub-projects created with `TypeScriptProject` automatically get Turborepo task configuration if their parent has Turborepo enabled.
-
-The integration includes:
-- Automatic task definitions (compile, test, package)
-- Output directory configuration (`dist/**`, `lib/**`)
-- Remote cache support (when configured)
-- Build workflow integration
-
-See the [Turbo Repo](#turbo-repo) section for more details.
-
-## Configuration Options
-
-### MonorepoProjectOptions
-
-Extends `TypeScriptProjectOptions` with:
-
-```typescript
-interface MonorepoProjectOptions {
-  name: string; // Required
-  turbo?: boolean; // Default: true
-  turboOptions?: TurboRepoOptions;
-  pnpmOptions?: {
-    version?: string;
-    pnpmWorkspaceOptions?: PnpmWorkspaceOptions;
-  };
-  // ... all TypeScriptProjectOptions
-}
-```
-
-### TypeScriptProjectOptions
-
-Extends Projen's `TypeScriptProjectOptions` with CodeDrifters defaults. See the [TypeScriptProject](#typescriptproject) section for details.
-
-### TurboRepoOptions
-
-```typescript
-interface TurboRepoOptions {
-  turboVersion?: string;
-  remoteCacheOptions?: RemoteCacheOptions;
-  extends?: Array<string>;
-  globalDependencies?: Array<string>;
-  globalEnv?: Array<string>;
-  globalPassThroughEnv?: Array<string>;
-  ui?: 'tui' | 'stream';
-  envMode?: string;
-  // ... and more
-}
-
-interface RemoteCacheOptions {
-  profileName: string;
-  oidcRole: string;
-  endpointParamName: string;
-  tokenParamName: string;
-  teamName: string;
-}
-```
-
-### PnpmWorkspaceOptions
-
-```typescript
-interface PnpmWorkspaceOptions {
-  fileName?: string; // Default: 'pnpm-workspace.yaml'
-  minimumReleaseAge?: number; // Minutes, default: ONE_DAY (1440)
-  minimumReleaseAgeExclude?: Array<string>; // Default: ['@codedrifters/*']
-  onlyBuiltDependencies?: Array<string>;
-  ignoredBuiltDependencies?: Array<string>;
-  subprojects?: Array<string>;
-  defaultCatalog?: { [key: string]: string };
-  namedCatalogs?: { [catalogName: string]: { [dependencyName: string]: string } };
-}
-```
-
-## Turbo Repo
-
-### What It Does
-
-Turbo Repo is a build system for monorepos that:
-
-- Caches build outputs intelligently
-- Only rebuilds what changed
-- Speeds up CI/CD significantly
-- Works with remote caching
-
-### How It Works
-
-**Hashing:** All input files (source code, configs) are hashed
-
-**Cache Check:** If inputs haven't changed, cached outputs are reused
-
-**Smart Rebuilds:** Only affected packages rebuild when dependencies change
-
-**Remote Cache:** Build outputs stored in S3 (not Vercel) for team sharing
-
-### Configuration
-
-Turborepo is automatically enabled in `MonorepoProject` (can be disabled with `turbo: false`). Configure it using the `turboOptions`:
-
-```typescript
-const project = new MonorepoProject({
-  name: 'my-monorepo',
-  turboOptions: {
-    remoteCacheOptions: {
-      profileName: 'my-profile',
-      oidcRole: 'arn:aws:iam::123456789012:role/TurborepoRole',
-      endpointParamName: '/TURBOREPO/ENDPOINT',
-      tokenParamName: '/TURBOREPO/TOKEN',
-      teamName: 'my-team',
-    },
-  },
-});
-```
-
-### Running Locally
-
-Before using Turbo Repo locally, you need AWS credentials:
-
-```bash
-# Run the login script (credentials last ~8 hours)
-./scripts/aws-profile-turbo-repo.sh
-```
-
-**Common Error:** If you get a "gRPC error" when running Turbo first thing in the morning, the Lambda function is cold. Just run the command again - it will work the second time.
-
-### Benefits
-
-- **Fast CI:** Builds can complete in under a minute when using cached outputs
-- **Selective Rebuilds:** Only changed code rebuilds, not the entire monorepo
-- **Local + CI Sharing:** Cache between your machine and GitHub Actions
-
-## PNPM Workspace
-
-The `MonorepoProject` automatically generates and manages `pnpm-workspace.yaml`. This file:
-
-- Lists all sub-projects in the `packages` array
-- Configures PNPM settings like `minimumReleaseAge` and `onlyBuiltDependencies`
-- Defines dependency catalogs for version management
-
-### Workspace Structure
-
-The workspace file is auto-generated and lists all sub-projects:
-
-```yaml
-packages:
-  - 'packages/package-a'
-  - 'packages/package-b'
-  - 'apps/frontend'
-```
-
-Sub-projects are automatically discovered from `project.subprojects` and any additional paths specified in `pnpmWorkspaceOptions.subprojects`.
-
-### Configuration
-
-Configure the workspace through `pnpmOptions.pnpmWorkspaceOptions`:
-
-```typescript
-const project = new MonorepoProject({
-  name: 'my-monorepo',
-  pnpmOptions: {
-    pnpmWorkspaceOptions: {
-      minimumReleaseAge: MINIMUM_RELEASE_AGE.ONE_DAY,
-      minimumReleaseAgeExclude: ['@codedrifters/*'],
-      onlyBuiltDependencies: ['@swc/core', 'esbuild'],
-      defaultCatalog: {
-        'react': '^18.0.0',
-      },
-    },
-  },
-});
-```
-
-## File Management Rules
-
-### DO NOT Edit These Files Directly
-
-Projen manages many files automatically. Never edit these files by hand:
-
-- Configuration files (`.prettierrc`, `tsconfig.json`, etc.)
-- GitHub workflows (`.github/workflows/*`)
-- Build scripts
-- Most files listed in `.projen/files.json`
-
-### Exception: package.json
-
-`package.json` is special - Projen reads, modifies, and writes it back, preserving some manual changes. However, you should still manage dependencies through Projen config, not by editing `package.json` directly.
-
-### Adding Dependencies
-
-**WRONG:**
-```bash
-npm install some-package
-```
-
-**CORRECT:** Add dependencies in your `.projenrc.ts` configuration and run `npx projen`.
-
-```typescript
-const project = new TypeScriptProject({
-  // ... other options
-  deps: ['some-package'],
-});
-```
-
-## Workflow Tips
-
-### Before Committing
-
-Run Turbo build locally (from monorepo root) to cache everything:
-
-```bash
-# This caches outputs that GitHub Actions can reuse
-pnpm build:all
-```
-
-Then commit and push. Your GitHub build will be much faster.
-
-### Adding New Packages
-
-1. Create a new configuration file in `projenrc/` (e.g., `projenrc/new-package.ts`)
-2. Export a function that creates a `TypeScriptProject` with the parent as a parameter
-3. Import and call it in your main projenrc file
-4. Run `npx projen` to regenerate configs
-5. Commit the changes
-
-Example:
-
-```typescript
-// projenrc/new-package.ts
-import { MonorepoProject, TypeScriptProject } from '@codedrifters/configulator';
-
-export const configureNewPackage = (parent: MonorepoProject) => {
-  return new TypeScriptProject({
-    name: 'new-package',
-    packageName: '@myorg/new-package',
-    outdir: 'packages/new-package',
-    parent,
-    deps: ['dependency'],
-  });
-};
-```
-
-### Updating Configulator
-
-To receive updates from Configulator in your project:
-
-1. Update the version in your projenrc definition file
-2. Run `npx projen`
-3. Review and test changes
-4. Commit
-
-## API Reference
-
-### MonorepoProject
-
-**Constructor:**
-```typescript
-new MonorepoProject(options: MonorepoProjectOptions)
-```
-
-**Key Properties:**
-- `pnpmVersion: string` - The PNPM version used by the monorepo
-
-**Key Methods:**
-- Inherits all methods from `TypeScriptAppProject`
-
-### TypeScriptProject
-
-**Constructor:**
-```typescript
-new TypeScriptProject(options: TypeScriptProjectOptions)
-```
-
-**Key Methods:**
-- `addDeps(...deps: string[])` - Add runtime dependencies
-- `addDevDeps(...deps: string[])` - Add dev dependencies
-- `addPeerDeps(...deps: string[])` - Add peer dependencies
-- Inherits all methods from Projen's `TypeScriptProject`
-
-### PnpmWorkspace
-
-**Static Method:**
-```typescript
-PnpmWorkspace.of(project: Project): PnpmWorkspace | undefined
-```
-
-Returns the PnpmWorkspace component from a project if it exists.
-
-### TurboRepo
-
-**Static Method:**
-```typescript
-TurboRepo.of(project: Project): TurboRepo | undefined
-```
-
-Returns the TurboRepo component from a project if it exists.
-
-### AgentConfig
-
-**Static Method:**
-```typescript
-AgentConfig.of(project: Project): AgentConfig | undefined
-```
-
-Returns the AgentConfig component from a project if it exists.
-
-## Agent Configuration
-
-AgentConfig provides a **single-source, multi-platform** approach to AI coding assistant configuration. Define rules, skills, sub-agents, and MCP servers once in your `.projenrc.ts`, and configulator renders the correct files for each target platform during synthesis.
-
-### Why Single-Source?
-
-Every AI coding assistant has its own configuration format — Cursor uses `.mdc` files with YAML frontmatter, Claude Code uses `.md` files and `settings.json`, Codex uses `AGENTS.md`, and Copilot uses `.github/instructions/`. Without a unified approach, teams end up maintaining duplicate rule sets that inevitably drift out of sync.
-
-AgentConfig solves this by defining rules in a platform-agnostic format and rendering them into each platform's native format:
-
-```
-.projenrc.ts (AgentConfig)
-    │
-    ├── Cursor:  .cursor/rules/*.mdc, .cursor/agents/*.md, .cursor/mcp.json
-    ├── Claude:  CLAUDE.md, .claude/rules/*.md, .claude/settings.json, .claude/skills/*, .claude/agents/*
-    ├── Codex:   AGENTS.md (planned)
-    └── Copilot: .github/instructions/*.md (planned)
-```
-
-### Quick Start
-
-Enable agent configuration with defaults — auto-detects rule bundles based on your project's tooling:
-
-```typescript
-// In .projenrc.ts — MonorepoProject
-const project = new MonorepoProject({
-  name: "my-project",
-  agentConfig: true, // or {} for defaults
-});
-
-// Sub-projects inherit from parent automatically
-const api = new TypeScriptProject({
-  parent: project,
-  name: "@my-org/api",
-  outdir: "packages/api",
-  // agentConfig inherited from parent — no explicit config needed
-});
-```
-
-After running `npx projen`, the following files are generated (varies by detected tooling):
-
-| Platform | Files |
-|----------|-------|
-| Cursor | `.cursor/rules/*.mdc`, `.cursor/agents/*.md`, `.cursor/mcp.json`, `.cursor/hooks.json`, `.cursorignore`, `.cursorindexingignore` |
-| Claude | `CLAUDE.md`, `.claude/rules/*.md`, `.claude/settings.json`, `.claude/skills/*/SKILL.md`, `.claude/agents/*.md` |
-| Codex | `AGENTS.md` (planned) |
-| Copilot | `.github/instructions/*.md` (planned) |
-
-### Configuration Options
-
-The `AgentConfigOptions` interface controls all aspects of agent configuration:
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `platforms` | `AgentPlatform[]` | `[CURSOR, CLAUDE]` | Target platforms to generate config for |
-| `autoDetectBundles` | `boolean` | `true` | Auto-detect rule bundles based on project tooling |
-| `includeBundles` | `string[]` | — | Force-include specific bundles by name |
-| `excludeBundles` | `string[]` | — | Exclude bundles even if auto-detected |
-| `includeBaseRules` | `boolean` | `true` | Include base rules (project-overview, conventions) |
-| `excludeRules` | `string[]` | — | Exclude individual rules by name |
-| `ruleExtensions` | `Record<string, string>` | — | Append content to existing rules |
-| `rules` | `AgentRule[]` | — | Custom rules (override bundled rules of same name) |
-| `skills` | `AgentSkill[]` | — | Custom skill definitions |
-| `subAgents` | `AgentSubAgent[]` | — | Custom sub-agent definitions |
-| `mcpServers` | `Record<string, McpServerConfig>` | — | MCP server configs (cross-platform) |
-| `claudeSettings` | `ClaudeSettingsConfig` | — | Claude Code settings.json config |
-| `cursorSettings` | `CursorSettingsConfig` | — | Cursor hooks and ignore patterns |
-
-### Built-in Rule Bundles
-
-Configulator ships with context-aware rule bundles that are automatically included when their tooling is detected in the project:
-
-| Bundle | Auto-detection | Rules | Description |
-|--------|---------------|-------|-------------|
-| `base` | Always (unless `includeBaseRules: false`) | `project-overview`, `interaction-style`, `general-conventions`, `pull-request-conventions`, `branch-naming-conventions`, `issue-conventions` | Core project context, interaction style, and coding conventions. Also includes `create-rule` and `review-pr` skills. |
-| `typescript` | `tsconfig.json` exists | `typescript-conventions` | Type safety, naming, JSDoc, member ordering |
-| `vitest` | Vitest component present | `vitest-testing` | Vitest testing patterns and file scoping |
-| `jest` | `jest` in dependencies | `jest-testing` | Jest testing patterns, SWC compilation, mocking |
-| `turborepo` | TurboRepo component present | `turborepo-conventions` | Build system, task pipeline, caching |
-| `pnpm` | PnpmWorkspace component present | `pnpm-workspace` | Workspace dependencies, package management |
-| `aws-cdk` | `aws-cdk-lib` in dependencies | `aws-cdk-conventions` | Construct patterns, L2/L3, IAM best practices |
-| `projen` | `projen` in dependencies | `projen-conventions` | Config patterns, synthesis workflow, components |
-
-**Controlling bundles:**
-
-```typescript
-new AgentConfig(project, {
-  // Disable auto-detection entirely
-  autoDetectBundles: false,
-
-  // Force-include bundles that aren't auto-detected
-  includeBundles: ["aws-cdk"],
-
-  // Exclude auto-detected bundles
-  excludeBundles: ["jest"],
-
-  // Disable the base rule set
-  includeBaseRules: false,
-
-  // Exclude individual rules from any source
-  excludeRules: ["branch-naming-conventions"],
-
-  // Append content to an existing rule without replacing it
-  ruleExtensions: {
-    "typescript-conventions": "## Additional Conventions\n\n- Use branded types for IDs",
-  },
-});
-```
-
-### Custom Rules
-
-Define custom rules using the `AgentRule` interface:
-
-```typescript
-import { AGENT_RULE_SCOPE, CLAUDE_RULE_TARGET } from "@codedrifters/configulator";
-
-new AgentConfig(project, {
-  rules: [
-    {
-      name: "api-conventions",
-      description: "REST API design conventions for this project",
-      scope: AGENT_RULE_SCOPE.FILE_PATTERN,
-      filePatterns: ["src/api/**/*.ts", "src/routes/**/*.ts"],
-      content: `# API Conventions
-
-- Use RESTful resource naming
-- Always validate request bodies with Zod
-- Return consistent error response shapes`,
-      tags: ["api"],
-    },
-  ],
-});
-```
-
-**Rule fields:**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | `string` | Yes | Unique kebab-case identifier, used as filename |
-| `description` | `string` | Yes | AI-readable purpose (Cursor uses this for rule selection) |
-| `scope` | `AgentRuleScope` | Yes | `ALWAYS` (always active) or `FILE_PATTERN` (active on matching files) |
-| `filePatterns` | `string[]` | When `FILE_PATTERN` | Glob patterns for conditional activation |
-| `content` | `string` | Yes | Markdown rule body |
-| `platforms` | `AgentPlatformOverrides` | No | Per-platform overrides |
-| `tags` | `string[]` | No | For categorizing and ordering rules |
-
-**Platform overrides** let you customize or exclude rules per platform:
-
-```typescript
-{
-  name: "claude-specific-rule",
-  description: "A rule only for Claude Code",
-  scope: AGENT_RULE_SCOPE.ALWAYS,
-  content: "# Claude-Only\n\nThis rule is excluded from Cursor.",
-  platforms: {
-    cursor: { exclude: true },
-    claude: { target: CLAUDE_RULE_TARGET.CLAUDE_MD }, // Render to CLAUDE.md instead of .claude/rules/
-  },
-}
-```
-
-Claude supports three render targets:
-- `SCOPED_FILE` (default) — `.claude/rules/{name}.md` with optional paths frontmatter
-- `AGENTS_MD` — `AGENTS.md` (always-active, shared with Codex)
-- `CLAUDE_MD` — `CLAUDE.md` (always-active, Claude-only)
-
-### Skills
-
-Skills define slash commands and automated workflows. They are rendered to `.claude/skills/*/SKILL.md` (Claude Code) and `.cursor/skills/` (Cursor).
-
-```typescript
-new AgentConfig(project, {
-  skills: [
-    {
-      name: "deploy-check",
-      description: "Verify deployment readiness before merging",
-      instructions: `# Deploy Check
-
-1. Run the full test suite
-2. Check for any TODO/FIXME comments in changed files
-3. Verify no console.log statements in production code
-4. Report findings`,
-      allowedTools: ["Read", "Glob", "Grep", "Bash(pnpm run test *)"],
-      disableModelInvocation: true, // Only triggered by /deploy-check
-    },
-  ],
-});
-```
-
-**Skill fields:**
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `name` | `string` | — | Slash-command name (e.g., `/commit`) |
-| `description` | `string` | — | Used by AI for auto-invocation decisions |
-| `instructions` | `string` | — | Markdown body (becomes SKILL.md) |
-| `allowedTools` | `string[]` | All | Tool allowlist |
-| `disableModelInvocation` | `boolean` | `false` | Prevent auto-invocation |
-| `userInvocable` | `boolean` | `true` | Allow `/skill-name` command |
-| `model` | `string` | — | Model override |
-| `effort` | `string` | — | Reasoning effort level |
-| `paths` | `string[]` | — | Auto-load on matching files |
-| `context` | `string` | — | Set to `'fork'` for isolated subagent |
-| `agent` | `string` | — | Subagent name when context is `'fork'` |
-
-**Built-in skills** (from the base bundle):
-- `create-rule` — Guide for creating new agent rules
-- `review-pr` — PR review workflow
-
-### Sub-Agents
-
-Sub-agents define specialized AI agents that the parent agent can delegate to:
-
-```typescript
-import { AGENT_MODEL } from "@codedrifters/configulator";
-
-new AgentConfig(project, {
-  subAgents: [
-    {
-      name: "test-writer",
-      description: "Write and update unit tests for changed code",
-      prompt: `# Test Writer
-
-You are a specialized testing agent. Given source files, write comprehensive
-unit tests following the project's testing conventions.
-
-- Use the project's test runner (Vitest or Jest)
-- Follow existing test patterns in the codebase
-- Ensure full branch coverage`,
-      model: AGENT_MODEL.BALANCED,
-      tools: ["Read", "Glob", "Grep", "Edit", "Write", "Bash(pnpm run test *)"],
-      maxTurns: 20,
-    },
-  ],
-});
-```
-
-**Sub-agent fields:**
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `name` | `string` | — | Lowercase kebab-case identifier |
-| `description` | `string` | — | When to delegate to this agent |
-| `prompt` | `string` | — | System prompt (markdown) |
-| `model` | `AgentModel` | `INHERIT` | `INHERIT`, `FAST`, `BALANCED`, or `POWERFUL` |
-| `tools` | `string[]` | All | Tool allowlist |
-| `disallowedTools` | `string[]` | — | Tool denylist |
-| `maxTurns` | `number` | — | Agentic turn limit |
-| `skills` | `string[]` | — | Pre-loaded skills |
-| `mcpServers` | `Record<string, McpServerConfig>` | — | MCP servers for this agent |
-| `canDelegateToAgents` | `string[]` | — | Agents this agent can invoke |
-| `platforms` | `AgentSubAgentPlatformOverrides` | — | Per-platform overrides |
-
-**Platform-specific sub-agent overrides:**
-
-```typescript
-{
-  name: "code-reviewer",
-  description: "Review code for quality and conventions",
-  prompt: "...",
-  platforms: {
-    claude: {
-      permissionMode: "plan",       // default, acceptEdits, dontAsk, bypassPermissions, plan
-      isolation: "worktree",        // Run in isolated git worktree
-      background: true,             // Run as background task
-      effort: "high",               // Reasoning effort: low, medium, high, max
-    },
-    cursor: {
-      readonly: true,               // Read-only operations only
-      isBackground: true,           // Async background task
-    },
-  },
-}
-```
-
-### MCP Server Configuration
-
-MCP servers are defined once and rendered to the appropriate config for each platform (`.claude/settings.json` for Claude, `.cursor/mcp.json` for Cursor):
-
-```typescript
-import { MCP_TRANSPORT } from "@codedrifters/configulator";
-
-new AgentConfig(project, {
-  mcpServers: {
-    "my-server": {
-      command: "npx",
-      args: ["-y", "@my-org/mcp-server"],
-      env: { API_KEY: "${API_KEY}" },
-      enabledTools: ["search", "read_file"],
-    },
-    "remote-api": {
-      transport: MCP_TRANSPORT.HTTP,
-      url: "https://api.example.com/mcp",
-      headers: { Authorization: "Bearer ${TOKEN}" },
-      disabledTools: ["dangerous_action"],
-    },
-  },
-});
-```
-
-**McpServerConfig fields:**
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `transport` | `McpTransport` | `STDIO` | `STDIO`, `HTTP`, or `SSE` |
-| `command` | `string` | — | Command for stdio servers |
-| `args` | `string[]` | — | Command arguments |
-| `url` | `string` | — | URL for HTTP/SSE servers |
-| `headers` | `Record<string, string>` | — | HTTP headers |
-| `env` | `Record<string, string>` | — | Environment variables |
-| `enabledTools` | `string[]` | All | Tool allowlist |
-| `disabledTools` | `string[]` | — | Tool denylist |
-
-### Platform-Specific Settings
-
-#### Claude Code Settings
-
-Configure Claude Code's `settings.json` with permissions, hooks, sandbox, and more:
-
-```typescript
-new AgentConfig(project, {
-  claudeSettings: {
-    defaultMode: "default", // default, acceptEdits, plan, auto
-    permissions: {
-      allow: ["Bash(pnpm run *)", "Edit(/src/**/*.ts)"],
-      deny: ["Bash(rm -rf *)"],
-      ask: ["Bash"],
-      additionalDirectories: ["/shared/libs"],
-    },
-    hooks: {
-      PreToolUse: [
-        {
-          matcher: "Bash",
-          hooks: [{ type: "command", command: "echo 'Running Bash'" }],
-        },
-      ],
-    },
-    sandbox: { enabled: true },
-    model: "claude-opus-4-6",
-    effortLevel: "high",
-    excludeSensitivePatterns: ["**/.env", "**/*.key"],
-  },
-});
-```
-
-#### Cursor Settings
-
-Configure Cursor hooks and ignore patterns:
-
-```typescript
-new AgentConfig(project, {
-  cursorSettings: {
-    hooks: {
-      beforeShellExecution: [{ command: "echo 'pre-exec check'" }],
-      afterFileEdit: [{ command: "pnpm run lint --fix" }],
-    },
-    ignorePatterns: ["**/.env", "**/secrets/**"],
-    indexingIgnorePatterns: ["**/generated/**", "*.min.js"],
-  },
-});
-```
-
-### Template Variables
-
-Rule content, skill instructions, and sub-agent prompts support `{{variable}}` template placeholders that are resolved from `ProjectMetadata` during synthesis:
-
-| Variable | Fallback | Description |
-|----------|----------|-------------|
-| `{{repository.owner}}` | `<owner>` | GitHub repository owner |
-| `{{repository.name}}` | `<repo>` | Repository name |
-| `{{repository.defaultBranch}}` | `main` | Default branch |
-| `{{organization.name}}` | `<organization>` | Organization name |
-| `{{organization.githubOrg}}` | `<org>` | GitHub organization |
-| `{{githubProject.name}}` | `<project-name>` | GitHub project name |
-| `{{githubProject.number}}` | `<project-number>` | GitHub project number |
-| `{{githubProject.nodeId}}` | `<project-node-id>` | GitHub project node ID |
-| `{{docsPath}}` | `<docs-path>` | Documentation path |
-
-If `ProjectMetadata` is not configured, fallback placeholders are used and a synthesis warning is emitted.
-
-### Examples
-
-**Minimal setup — all defaults:**
-
-```typescript
-const project = new MonorepoProject({
-  name: "my-project",
-  agentConfig: true,
-});
-```
-
-**Custom platform selection:**
-
-```typescript
-import { AGENT_PLATFORM } from "@codedrifters/configulator";
-
-const project = new MonorepoProject({
-  name: "my-project",
-  agentConfig: {
-    platforms: [AGENT_PLATFORM.CLAUDE], // Claude only, no Cursor
-  },
-});
-```
-
-**Custom rules and skills:**
-
-```typescript
-import { AGENT_RULE_SCOPE } from "@codedrifters/configulator";
-
-const project = new MonorepoProject({
-  name: "my-project",
-  agentConfig: {
-    rules: [
-      {
-        name: "database-conventions",
-        description: "Database migration and query conventions",
-        scope: AGENT_RULE_SCOPE.FILE_PATTERN,
-        filePatterns: ["src/db/**/*.ts", "migrations/**/*.ts"],
-        content: "# Database Conventions\n\n- Use parameterized queries\n- Never use raw SQL",
-      },
-    ],
-    skills: [
-      {
-        name: "migrate",
-        description: "Run database migrations",
-        instructions: "# Migrate\n\nRun `pnpm run db:migrate` and verify the schema.",
-        allowedTools: ["Bash(pnpm run db:*)"],
-      },
-    ],
-  },
-});
-```
-
-**Monorepo with per-package opt-in:**
-
-`AgentConfig` is **not** auto-inherited by sub-projects. Agent rule files are
-rendered only on projects that explicitly opt in, so the monorepo root's
-`AgentConfig` does not duplicate `.cursor/`, `.claude/`, or `CLAUDE.md` into
-each sub-project's `outdir`. Sub-projects that opt in do still resolve
-`ProjectMetadata` from the root, so template tokens like
-`{{repository.owner}}` work without redeclaring metadata.
-
-```typescript
-const root = new MonorepoProject({
-  name: "my-monorepo",
-  agentConfig: {
-    // Root-level config — renders into the monorepo root only
-    rules: [{ name: "monorepo-rule", description: "...", scope: AGENT_RULE_SCOPE.ALWAYS, content: "..." }],
-  },
-});
-
-// Sub-project with no agent config — nothing rendered into packages/api/
-const api = new TypeScriptProject({
-  parent: root,
-  name: "@my-org/api",
-  outdir: "packages/api",
-});
-
-// Sub-project that explicitly opts into its own agent config
-const frontend = new TypeScriptProject({
-  parent: root,
-  name: "@my-org/frontend",
-  outdir: "packages/frontend",
-  agentConfig: {
-    // Only generate Claude config for this package
-    platforms: [AGENT_PLATFORM.CLAUDE],
-    excludeBundles: ["jest"], // This package uses Vitest, not Jest
-  },
-});
-```
-
-## Troubleshooting
-
-**"Cannot find module" errors**
-
-Run `npx projen` to regenerate configuration files.
-
-**Turbo Repo cache errors**
-
-- Ensure you've run the AWS login script
-- If it's your first run of the day, try running the command twice
-
-**Build workflow failures**
-
-Check that you haven't manually edited generated files. If you have, run `npx projen` to restore them.
-
-**Dependency conflicts**
-
-Don't mix `npm install` with Projen. Always add dependencies through configuration.
-
-**Sub-project not appearing in workspace**
-
-- Ensure the sub-project has `parent` set to the MonorepoProject
-- Ensure `outdir` is set correctly
-- Run `npx projen` to regenerate the workspace file
-
-## Additional Resources
-
-- **Projen Documentation:** https://projen.io
-- **Turbo Repo Docs:** https://turbo.build/repo/docs
-- **PNPM Workspaces:** https://pnpm.io/workspaces
-- **Code Drifters Configulator:** https://www.npmjs.com/package/@codedrifters/packages
-
----
-
-**Remember:** The goal is consistency and automation. Let the tools manage the boilerplate so you can focus on building features.
+**NPM:** [@codedrifters/configulator](https://www.npmjs.com/package/@codedrifters/configulator)