@codedrifters/configulator 0.0.160 → 0.0.162

package/README.md

@@ -18,6 +18,18 @@ A library of [Projen](https://projen.io/) components used by CodeDrifters to man
 - [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)
 
@@ -801,6 +813,488 @@ 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 overrides:**
+
+```typescript
+const root = new MonorepoProject({
+  name: "my-monorepo",
+  agentConfig: {
+    // Root-level config applies to all sub-projects
+    rules: [{ name: "monorepo-rule", description: "...", scope: AGENT_RULE_SCOPE.ALWAYS, content: "..." }],
+  },
+});
+
+// Sub-project inherits parent config by default
+const api = new TypeScriptProject({
+  parent: root,
+  name: "@my-org/api",
+  outdir: "packages/api",
+  // Inherits agentConfig from root
+});
+
+// Sub-project with explicit overrides
+const frontend = new TypeScriptProject({
+  parent: root,
+  name: "@my-org/frontend",
+  outdir: "packages/frontend",
+  agentConfig: {
+    // Override: only generate Claude config for this package
+    platforms: [AGENT_PLATFORM.CLAUDE],
+    excludeBundles: ["jest"], // This package uses Vitest, not Jest
+  },
+});
+
+// Sub-project with agent config disabled
+const scripts = new TypeScriptProject({
+  parent: root,
+  name: "@my-org/scripts",
+  outdir: "packages/scripts",
+  agentConfig: false, // No agent config for this package
+});
+```
+
 ## Troubleshooting
 
 **"Cannot find module" errors**

package/lib/index.js

@@ -456,6 +456,23 @@ var baseBundle = {
       ].join("\n"),
       tags: ["project"]
     },
+    {
+      name: "reference-documentation",
+      description: "Consult project rules, documentation, and existing code before answering or making changes",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# Reference Documentation",
+        "",
+        "Before answering questions or making changes, always consult available project context.",
+        "",
+        "1. **Read project rules and guidelines** \u2014 check for agent rules, contribution guides, and coding standards defined in the project.",
+        "2. **Review existing code** \u2014 understand current patterns, conventions, and architecture before proposing changes. Look at similar files and modules for reference.",
+        "3. **Check documentation** \u2014 consult README files, inline documentation, and any design documents for relevant context.",
+        "4. **Respect established patterns** \u2014 follow the conventions already in use rather than introducing new ones without discussion.",
+        "5. **Verify before assuming** \u2014 if documentation or code conflicts with your assumptions, trust the project sources and ask for clarification when needed."
+      ].join("\n"),
+      tags: ["project"]
+    },
     {
       name: "interaction-style",
       description: "Interaction style \u2014 ask questions one at a time and wait for feedback",
@@ -465,12 +482,13 @@ var baseBundle = {
         "",
         "When responding to requests, follow these interaction principles.",
         "",
-        "1. **Ask questions one at a time**: When clarification is needed, ask a single question and wait for the user's response before proceeding.",
-        "2. **Wait for feedback**: After asking a question, pause and wait for the user's answer before asking additional questions or making assumptions.",
-        "3. **Avoid question overload**: Do not ask multiple questions in a single response. If multiple clarifications are needed, prioritize the most important question first.",
-        "4. **Progressive clarification**: Once the user answers your first question, you may then ask the next most important question if needed.",
-        "5. **Confirm understanding**: After receiving feedback, acknowledge the user's response before proceeding with the next step or question.",
-        "6. **Be patient**: Do not rush ahead with assumptions. It is better to ask one clarifying question than to proceed with incorrect assumptions."
+        "1. **Ask when ambiguous**: When requirements are ambiguous or incomplete, always ask clarifying questions before proceeding. Do not make assumptions about the user's intent \u2014 it is better to ask than to guess wrong.",
+        "2. **Ask questions one at a time**: When clarification is needed, ask a single question and wait for the user's response before proceeding.",
+        "3. **Wait for feedback**: After asking a question, pause and wait for the user's answer before asking additional questions or making assumptions.",
+        "4. **Avoid question overload**: Do not ask multiple questions in a single response. If multiple clarifications are needed, prioritize the most important question first.",
+        "5. **Progressive clarification**: Once the user answers your first question, you may then ask the next most important question if needed.",
+        "6. **Confirm understanding**: After receiving feedback, acknowledge the user's response before proceeding with the next step or question.",
+        "7. **Be patient**: Do not rush ahead with assumptions. It is better to ask one clarifying question than to proceed with incorrect assumptions."
       ].join("\n"),
       tags: ["project"]
     },