@codedrifters/configulator 0.0.153 → 0.0.155

package/lib/index.d.mts

@@ -1,14 +1,742 @@
-import { Component, Project, typescript } from 'projen';
+import { Component, Project as Project$1, typescript } from 'projen';
+import { Project, Component as Component$1, Task } from 'projen/lib';
 import { AwsCdkTypeScriptApp } from 'projen/lib/awscdk';
 import { AwsStageType, DeploymentTargetRoleType, AwsEnvironmentType, AWS_STAGE_TYPE } from '@codedrifters/utils';
 import * as spec from '@jsii/spec';
 import { TypeScriptProject as TypeScriptProject$1, TypeScriptAppProject, TypeScriptProjectOptions as TypeScriptProjectOptions$1 } from 'projen/lib/typescript';
 import { ValueOf } from 'type-fest';
-import { Component as Component$1, Project as Project$1, Task } from 'projen/lib';
 import { BuildWorkflowOptions, BuildWorkflow } from 'projen/lib/build';
 import { NodeProject } from 'projen/lib/javascript';
 import { JobStep } from 'projen/lib/github/workflows-model';
 
+/**
+ * Defines the scope/activation model for an agent rule.
+ * - ALWAYS: Rule is always active regardless of context
+ * - FILE_PATTERN: Rule activates when the AI is working on files matching the patterns
+ */
+declare const AGENT_RULE_SCOPE: {
+    readonly ALWAYS: "always";
+    readonly FILE_PATTERN: "file-pattern";
+};
+type AgentRuleScope = (typeof AGENT_RULE_SCOPE)[keyof typeof AGENT_RULE_SCOPE];
+/**
+ * Supported AI coding assistant platforms.
+ */
+declare const AGENT_PLATFORM: {
+    readonly CURSOR: "cursor";
+    readonly CLAUDE: "claude";
+    readonly CODEX: "codex";
+    readonly COPILOT: "copilot";
+};
+type AgentPlatform = (typeof AGENT_PLATFORM)[keyof typeof AGENT_PLATFORM];
+/**
+ * Render target for Claude Code rules.
+ * - SCOPED_FILE: .claude/rules/{name}.md (default — supports paths frontmatter for conditional activation)
+ * - AGENTS_MD: AGENTS.md (always-active, shared with Codex)
+ * - CLAUDE_MD: CLAUDE.md (always-active, Claude-only content not consumed by other agents)
+ */
+declare const CLAUDE_RULE_TARGET: {
+    readonly SCOPED_FILE: "scoped-file";
+    readonly AGENTS_MD: "agents-md";
+    readonly CLAUDE_MD: "claude-md";
+};
+type ClaudeRuleTarget = (typeof CLAUDE_RULE_TARGET)[keyof typeof CLAUDE_RULE_TARGET];
+/**
+ * Model selection for sub-agents. Platforms map these to their own model identifiers.
+ */
+declare const AGENT_MODEL: {
+    readonly INHERIT: "inherit";
+    readonly FAST: "fast";
+    readonly BALANCED: "balanced";
+    readonly POWERFUL: "powerful";
+};
+type AgentModel = (typeof AGENT_MODEL)[keyof typeof AGENT_MODEL];
+/**
+ * MCP server transport type.
+ */
+declare const MCP_TRANSPORT: {
+    readonly STDIO: "stdio";
+    readonly HTTP: "http";
+    readonly SSE: "sse";
+};
+type McpTransport = (typeof MCP_TRANSPORT)[keyof typeof MCP_TRANSPORT];
+/**
+ * Platform-specific overrides for a rule.
+ */
+interface AgentPlatformOverrides {
+    /** Cursor-specific overrides */
+    readonly cursor?: {
+        /** Override the description used in Cursor's YAML frontmatter */
+        readonly description?: string;
+        /** Exclude this rule from Cursor output entirely */
+        readonly exclude?: boolean;
+    };
+    /** Claude Code-specific overrides */
+    readonly claude?: {
+        /**
+         * Where to render this rule for Claude Code.
+         * - SCOPED_FILE: .claude/rules/{name}.md (default — supports paths frontmatter)
+         * - AGENTS_MD: AGENTS.md (always-active, shared with Codex)
+         * - CLAUDE_MD: CLAUDE.md (always-active, Claude-only)
+         */
+        readonly target?: ClaudeRuleTarget;
+        /** Exclude this rule from Claude Code output entirely */
+        readonly exclude?: boolean;
+    };
+    /** Codex-specific overrides (future) */
+    readonly codex?: {
+        /** Place this rule in a sub-directory AGENTS.md instead of root */
+        readonly directory?: string;
+        /** Exclude this rule from Codex output entirely */
+        readonly exclude?: boolean;
+    };
+    /** Copilot-specific overrides (future) */
+    readonly copilot?: {
+        /** Exclude this rule from Copilot output entirely */
+        readonly exclude?: boolean;
+    };
+}
+/**
+ * A single agent rule definition, platform-agnostic.
+ */
+interface AgentRule {
+    /**
+     * Unique identifier for the rule. Used as the filename stem in platforms
+     * that use per-rule files (Cursor, Claude Code, Copilot).
+     * @example 'typescript-conventions'
+     */
+    readonly name: string;
+    /**
+     * Human-readable description of the rule's purpose.
+     * Used by Cursor for AI-assisted rule selection.
+     * @example 'TypeScript project patterns and conventions'
+     */
+    readonly description: string;
+    /**
+     * Activation scope for this rule.
+     * - AGENT_RULE_SCOPE.ALWAYS: Active in all contexts
+     * - AGENT_RULE_SCOPE.FILE_PATTERN: Active only when working on matching files
+     */
+    readonly scope: AgentRuleScope;
+    /**
+     * Glob patterns for conditional activation.
+     * Required when scope is AGENT_RULE_SCOPE.FILE_PATTERN.
+     * @example ['src/**\/*.ts', 'tests/**\/*.ts']
+     */
+    readonly filePatterns?: ReadonlyArray<string>;
+    /**
+     * The rule content as markdown. This is the platform-agnostic body
+     * that applies equally to all AI assistants.
+     */
+    readonly content: string;
+    /**
+     * Optional per-platform overrides. Use sparingly — prefer platform-agnostic content.
+     */
+    readonly platforms?: AgentPlatformOverrides;
+    /**
+     * Optional tags for categorizing and ordering rules.
+     * Rules are ordered by tag (alphabetical), then by name within each tag.
+     * @example ['typescript', 'testing', 'workflow']
+     */
+    readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * A skill definition following the cross-platform Agent Skills specification.
+ * Rendered to .claude/skills/ (Claude Code) and .cursor/skills/ (Cursor).
+ */
+interface AgentSkill {
+    /**
+     * Unique identifier for the skill. Becomes the /slash-command name.
+     * @example 'commit'
+     */
+    readonly name: string;
+    /**
+     * Human-readable description. Claude uses this to decide when to auto-invoke.
+     */
+    readonly description: string;
+    /**
+     * Multi-line instruction content (markdown). Becomes the SKILL.md body.
+     */
+    readonly instructions: string;
+    /**
+     * Optional tool allowlist for this skill.
+     * @example ['Read', 'Bash(npm run *)']
+     */
+    readonly allowedTools?: ReadonlyArray<string>;
+    /**
+     * Whether to prevent auto-invocation of this skill.
+     * When true, only triggered by the user typing /skill-name.
+     * @default false
+     */
+    readonly disableModelInvocation?: boolean;
+    /**
+     * Whether the user can invoke this skill directly via /skill-name.
+     * Set to false for background skills that should not appear in the / menu.
+     * @default true
+     */
+    readonly userInvocable?: boolean;
+    /**
+     * Model override when this skill is active.
+     * @example 'claude-opus-4-6'
+     */
+    readonly model?: string;
+    /**
+     * Reasoning effort level when this skill is active.
+     * @example 'high'
+     */
+    readonly effort?: string;
+    /**
+     * Glob patterns that limit when the skill is auto-loaded.
+     * @example ['src/api/**\/*.ts']
+     */
+    readonly paths?: ReadonlyArray<string>;
+}
+/**
+ * Platform-specific overrides for a sub-agent definition.
+ */
+interface AgentSubAgentPlatformOverrides {
+    /** Claude Code-specific overrides */
+    readonly claude?: {
+        /** Permission mode: default, acceptEdits, dontAsk, bypassPermissions, plan */
+        readonly permissionMode?: string;
+        /** Run in isolated git worktree */
+        readonly isolation?: string;
+        /** Reasoning effort level */
+        readonly effort?: string;
+        /** Exclude this sub-agent from Claude Code output entirely */
+        readonly exclude?: boolean;
+    };
+    /** Cursor-specific overrides */
+    readonly cursor?: {
+        /** Restrict the sub-agent to read-only operations */
+        readonly readonly?: boolean;
+        /** Run the sub-agent asynchronously as a background task */
+        readonly isBackground?: boolean;
+        /** Exclude this sub-agent from Cursor output entirely */
+        readonly exclude?: boolean;
+    };
+    /** Codex-specific overrides (future) */
+    readonly codex?: {
+        /** Exclude this sub-agent from Codex output entirely */
+        readonly exclude?: boolean;
+    };
+    /** Copilot-specific overrides (future) */
+    readonly copilot?: {
+        /** Exclude this sub-agent from Copilot output entirely */
+        readonly exclude?: boolean;
+    };
+}
+/**
+ * A custom sub-agent definition, platform-agnostic.
+ * Rendered to .cursor/agents/ (Cursor), .claude/agents/ (Claude Code).
+ */
+interface AgentSubAgent {
+    /**
+     * Unique identifier for the sub-agent. Used as the filename stem.
+     * Must be lowercase letters and hyphens only.
+     * @example 'code-reviewer'
+     */
+    readonly name: string;
+    /** Human-readable description. Used by the parent agent to decide when to delegate. */
+    readonly description: string;
+    /**
+     * System prompt / instructions for the sub-agent (markdown).
+     * This becomes the body of the generated agent file.
+     */
+    readonly prompt: string;
+    /**
+     * Model selection for this sub-agent.
+     * @default AGENT_MODEL.INHERIT
+     */
+    readonly model?: AgentModel;
+    /**
+     * Tool allowlist. When omitted, inherits all tools from parent.
+     * @example ['Read', 'Glob', 'Grep']
+     */
+    readonly tools?: ReadonlyArray<string>;
+    /** Maximum agentic turns before the sub-agent stops. */
+    readonly maxTurns?: number;
+    /** Optional per-platform overrides for this sub-agent. */
+    readonly platforms?: AgentSubAgentPlatformOverrides;
+}
+/**
+ * MCP server configuration. Cross-platform — rendered to .claude/settings.json
+ * (Claude Code) and .cursor/mcp.json (Cursor).
+ */
+interface McpServerConfig {
+    /**
+     * Transport type for the server connection.
+     * @default MCP_TRANSPORT.STDIO
+     */
+    readonly transport?: McpTransport;
+    /** Command to launch a stdio server. */
+    readonly command?: string;
+    /** Command arguments for stdio server. */
+    readonly args?: ReadonlyArray<string>;
+    /** URL for HTTP/SSE remote servers. */
+    readonly url?: string;
+    /** Environment variables for the server process. */
+    readonly env?: Readonly<Record<string, string>>;
+}
+
+/*******************************************************************************
+ *
+ * Agent Rule Bundle
+ *
+ ******************************************************************************/
+/**
+ * A context-aware bundle of rules and/or skills that ships with configulator.
+ * Bundles are automatically selected based on project introspection (e.g.,
+ * which components are present, which libraries are in use).
+ */
+interface AgentRuleBundle {
+    /**
+     * Unique identifier for the bundle.
+     * @example 'vitest', 'turborepo', 'pnpm-monorepo', 'aws-cdk'
+     */
+    readonly name: string;
+    /**
+     * Human-readable description of when this bundle applies.
+     * @example 'Rules for projects using Vitest as their test runner'
+     */
+    readonly description: string;
+    /**
+     * Function that inspects the Projen project and returns true if this
+     * bundle should be automatically included. Receives the root project
+     * as input and can check for sibling components, dependencies, etc.
+     * @example (project) => Vitest.of(project) !== undefined
+     */
+    readonly appliesWhen: (project: Project) => boolean;
+    /** Rules included in this bundle. */
+    readonly rules: ReadonlyArray<AgentRule>;
+    /** Skills included in this bundle (cross-platform where supported). */
+    readonly skills?: ReadonlyArray<AgentSkill>;
+    /** Sub-agents included in this bundle. */
+    readonly subAgents?: ReadonlyArray<AgentSubAgent>;
+}
+/*******************************************************************************
+ *
+ * Claude Code Settings
+ *
+ ******************************************************************************/
+/**
+ * A single Cursor hook action.
+ */
+interface CursorHookAction {
+    /** Shell command to execute. */
+    readonly command: string;
+}
+/**
+ * Cursor hook lifecycle events. Each event takes an array of hook actions.
+ *
+ * Cursor hooks use a different model than Claude Code hooks:
+ * - Blocking hooks can return permission decisions to block actions
+ * - Non-blocking hooks are informational only
+ */
+interface CursorHooksConfig {
+    /**
+     * Fires before a user prompt is submitted. Non-blocking (informational).
+     */
+    readonly beforeSubmitPrompt?: ReadonlyArray<CursorHookAction>;
+    /**
+     * Fires before a shell command executes. Blocking — can deny execution.
+     */
+    readonly beforeShellExecution?: ReadonlyArray<CursorHookAction>;
+    /**
+     * Fires before an MCP tool is invoked. Blocking — can deny execution.
+     */
+    readonly beforeMCPExecution?: ReadonlyArray<CursorHookAction>;
+    /**
+     * Fires before a file is read by the AI. Blocking — can rewrite content.
+     */
+    readonly beforeReadFile?: ReadonlyArray<CursorHookAction>;
+    /**
+     * Fires after a file is edited. Non-blocking (informational).
+     */
+    readonly afterFileEdit?: ReadonlyArray<CursorHookAction>;
+    /**
+     * Fires when the agent stops. Non-blocking (informational).
+     */
+    readonly stop?: ReadonlyArray<CursorHookAction>;
+}
+/**
+ * Cursor-specific configuration options.
+ * Cursor does not support a project-level settings.json — its AI settings
+ * are stored in an internal SQLite database. However, it does support
+ * project-level hooks (.cursor/hooks.json) and ignore files.
+ */
+interface CursorSettingsConfig {
+    /**
+     * Lifecycle hooks for Cursor's agent. Generated to .cursor/hooks.json.
+     */
+    readonly hooks?: CursorHooksConfig;
+    /**
+     * Patterns for .cursorignore — files completely invisible to Cursor.
+     * This is a hard security boundary: matched files are not indexed,
+     * not readable by AI, and not included in any context.
+     * Uses .gitignore syntax.
+     * @example ['**\/.env', '**\/secrets/**', 'dist/']
+     */
+    readonly ignorePatterns?: ReadonlyArray<string>;
+    /**
+     * Patterns for .cursorindexingignore — files excluded from codebase
+     * indexing but still accessible to AI if referenced directly.
+     * Uses .gitignore syntax.
+     * @example ['**\/generated/**', '**\/vendor/**', '*.min.js']
+     */
+    readonly indexingIgnorePatterns?: ReadonlyArray<string>;
+}
+/**
+ * Permission rule syntax supports fine-grained patterns:
+ * - Tool name: "Bash", "Read", "Edit", "WebFetch"
+ * - With args: "Bash(npm run *)", "Bash(git * main)"
+ * - File paths: "Edit(/src/**\/*.ts)"
+ * - MCP tools: "mcp__puppeteer__puppeteer_navigate"
+ */
+interface ClaudePermissionsConfig {
+    /** Tools auto-approved without prompts. */
+    readonly allow?: ReadonlyArray<string>;
+    /** Tools completely blocked. */
+    readonly deny?: ReadonlyArray<string>;
+    /** Tools that always prompt (overrides allow). */
+    readonly ask?: ReadonlyArray<string>;
+    /** Additional directories Claude can access beyond the project root. */
+    readonly additionalDirectories?: ReadonlyArray<string>;
+}
+/**
+ * A single hook action. Supports four types: command, http, prompt, agent.
+ */
+interface ClaudeHookAction {
+    /** Hook type. */
+    readonly type: "command" | "http" | "prompt" | "agent";
+    /** Shell command to execute (type: 'command'). */
+    readonly command?: string;
+    /** URL to POST to (type: 'http'). */
+    readonly url?: string;
+    /** HTTP headers (type: 'http'). */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** LLM/agent prompt text (type: 'prompt' | 'agent'). */
+    readonly prompt?: string;
+    /** Model override for prompt hooks (type: 'prompt'). */
+    readonly model?: string;
+    /** Permission rule filter — only fire when this pattern matches. */
+    readonly if?: string;
+    /** Timeout in seconds. */
+    readonly timeout?: number;
+    /** Custom spinner text shown while the hook runs. */
+    readonly statusMessage?: string;
+    /** Run in background without blocking (type: 'command'). */
+    readonly async?: boolean;
+    /** Only execute this hook once per session. */
+    readonly once?: boolean;
+    /** Shell to use (type: 'command'). */
+    readonly shell?: string;
+}
+/**
+ * Hook definition for Claude Code lifecycle events.
+ */
+interface ClaudeHookEntry {
+    /**
+     * Tool name or regex pattern to match.
+     * @example 'Bash', 'Edit|Write', '.*'
+     */
+    readonly matcher: string;
+    /** Array of hook actions to execute when the matcher triggers. */
+    readonly hooks: ReadonlyArray<ClaudeHookAction>;
+}
+/**
+ * All supported Claude Code hook lifecycle events.
+ */
+interface ClaudeHooksConfig {
+    readonly PreToolUse?: ReadonlyArray<ClaudeHookEntry>;
+    readonly PostToolUse?: ReadonlyArray<ClaudeHookEntry>;
+    readonly PostToolUseFailure?: ReadonlyArray<ClaudeHookEntry>;
+    readonly PermissionRequest?: ReadonlyArray<ClaudeHookEntry>;
+    readonly PermissionDenied?: ReadonlyArray<ClaudeHookEntry>;
+    readonly Notification?: ReadonlyArray<ClaudeHookEntry>;
+    readonly UserPromptSubmit?: ReadonlyArray<ClaudeHookEntry>;
+    readonly Stop?: ReadonlyArray<ClaudeHookEntry>;
+    readonly StopFailure?: ReadonlyArray<ClaudeHookEntry>;
+    readonly SubagentStart?: ReadonlyArray<ClaudeHookEntry>;
+    readonly SubagentStop?: ReadonlyArray<ClaudeHookEntry>;
+    readonly TaskCreated?: ReadonlyArray<ClaudeHookEntry>;
+    readonly TaskCompleted?: ReadonlyArray<ClaudeHookEntry>;
+    readonly TeammateIdle?: ReadonlyArray<ClaudeHookEntry>;
+    readonly PreCompact?: ReadonlyArray<ClaudeHookEntry>;
+    readonly PostCompact?: ReadonlyArray<ClaudeHookEntry>;
+    readonly ConfigChange?: ReadonlyArray<ClaudeHookEntry>;
+    readonly WorktreeCreate?: ReadonlyArray<ClaudeHookEntry>;
+    readonly WorktreeRemove?: ReadonlyArray<ClaudeHookEntry>;
+    readonly SessionStart?: ReadonlyArray<ClaudeHookEntry>;
+    readonly SessionEnd?: ReadonlyArray<ClaudeHookEntry>;
+    readonly Elicitation?: ReadonlyArray<ClaudeHookEntry>;
+    readonly ElicitationResult?: ReadonlyArray<ClaudeHookEntry>;
+    readonly InstructionsLoaded?: ReadonlyArray<ClaudeHookEntry>;
+    readonly FileChanged?: ReadonlyArray<ClaudeHookEntry>;
+    readonly CwdChanged?: ReadonlyArray<ClaudeHookEntry>;
+}
+/**
+ * Sandbox configuration for Claude Code. Controls filesystem, network,
+ * and execution restrictions.
+ */
+interface ClaudeSandboxConfig {
+    /** Enable sandboxing. */
+    readonly enabled?: boolean;
+    /**
+     * Sandbox mode.
+     * - 'auto-allow': Auto-approve Bash commands when sandboxed
+     * - 'regular-permissions': Use normal permission prompts even when sandboxed
+     */
+    readonly mode?: string;
+    /** Fail if sandbox cannot be initialized. */
+    readonly failIfUnavailable?: boolean;
+    /** Auto-allow Bash commands when sandboxed. */
+    readonly autoAllowBashIfSandboxed?: boolean;
+    /** Commands excluded from sandbox. */
+    readonly excludedCommands?: ReadonlyArray<string>;
+    /** Filesystem access restrictions. */
+    readonly filesystem?: {
+        readonly allowRead?: ReadonlyArray<string>;
+        readonly denyRead?: ReadonlyArray<string>;
+        readonly allowWrite?: ReadonlyArray<string>;
+        readonly denyWrite?: ReadonlyArray<string>;
+    };
+    /** Network access restrictions. */
+    readonly network?: {
+        readonly allowedDomains?: ReadonlyArray<string>;
+        readonly denyDomains?: ReadonlyArray<string>;
+    };
+}
+/**
+ * Auto mode configuration. Provides context to Claude's permission
+ * classifier for more intelligent auto-approval decisions.
+ */
+interface ClaudeAutoModeConfig {
+    /** Environmental context strings about the organization/project. */
+    readonly environment?: ReadonlyArray<string>;
+    /** Actions explicitly allowed with reasoning. */
+    readonly allow?: ReadonlyArray<string>;
+    /** Actions soft-denied with reasoning. */
+    readonly soft_deny?: ReadonlyArray<string>;
+}
+/**
+ * Full Claude Code settings.json configuration.
+ * Maps to the project-level .claude/settings.json file.
+ */
+interface ClaudeSettingsConfig {
+    /**
+     * Default permission mode for the project.
+     * @example 'default', 'acceptEdits', 'plan', 'auto'
+     */
+    readonly defaultMode?: string;
+    /** Permission rules (allow, deny, ask, additionalDirectories). */
+    readonly permissions?: ClaudePermissionsConfig;
+    /** Lifecycle hooks. */
+    readonly hooks?: ClaudeHooksConfig;
+    /** MCP server configurations for .claude/settings.json. */
+    readonly mcpServers?: Readonly<Record<string, McpServerConfig>>;
+    /** MCP servers to explicitly allow. */
+    readonly allowedMcpServers?: ReadonlyArray<string>;
+    /** Environment variables passed to Claude's shell. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Sandbox configuration. */
+    readonly sandbox?: ClaudeSandboxConfig;
+    /** Auto mode configuration. */
+    readonly autoMode?: ClaudeAutoModeConfig;
+    /** Set to "disable" to prevent use of bypassPermissions mode. */
+    readonly disableBypassPermissionsMode?: string;
+    /** Set to "disable" to prevent use of auto mode. */
+    readonly disableAutoMode?: string;
+    /** Disable all hooks (project and user-level). */
+    readonly disableAllHooks?: boolean;
+    /**
+     * Glob patterns for sensitive files to exclude from suggestions.
+     * @example ['**\/.env', '**\/*.key', '**\/secrets/**']
+     */
+    readonly excludeSensitivePatterns?: ReadonlyArray<string>;
+    /** Attribution configuration for commits and PRs created by Claude. */
+    readonly attribution?: {
+        /** Attribution mode: 'inherit', 'always', 'never'. */
+        readonly mode?: string;
+        /** Commit author details. */
+        readonly commits?: {
+            readonly author?: string;
+            readonly email?: string;
+        };
+    };
+}
+/*******************************************************************************
+ *
+ * AgentConfig Options
+ *
+ ******************************************************************************/
+/**
+ * Options for the AgentConfig component.
+ */
+interface AgentConfigOptions {
+    /**
+     * Target platforms to generate configuration for.
+     * @default [AGENT_PLATFORM.CURSOR, AGENT_PLATFORM.CLAUDE]
+     */
+    readonly platforms?: ReadonlyArray<AgentPlatform>;
+    /**
+     * Additional agent rules to generate alongside auto-detected and bundled rules.
+     * Custom rules override bundled rules of the same name.
+     */
+    readonly rules?: ReadonlyArray<AgentRule>;
+    /**
+     * Additional skills to generate.
+     */
+    readonly skills?: ReadonlyArray<AgentSkill>;
+    /**
+     * Custom sub-agent definitions.
+     */
+    readonly subAgents?: ReadonlyArray<AgentSubAgent>;
+    /**
+     * MCP server configurations. Cross-platform — rendered to the appropriate
+     * config file for each platform.
+     */
+    readonly mcpServers?: Readonly<Record<string, McpServerConfig>>;
+    /**
+     * Whether to automatically detect and include context-aware rule bundles
+     * based on project introspection.
+     * @default true
+     */
+    readonly autoDetectBundles?: boolean;
+    /**
+     * Explicit list of bundle names to include, regardless of auto-detection.
+     * @example ['vitest', 'aws-cdk']
+     */
+    readonly includeBundles?: ReadonlyArray<string>;
+    /**
+     * Bundle names to exclude even if auto-detection would include them.
+     * @example ['jest']
+     */
+    readonly excludeBundles?: ReadonlyArray<string>;
+    /**
+     * Whether to include the base rule set (project-overview, general conventions).
+     * @default true
+     */
+    readonly includeBaseRules?: boolean;
+    /**
+     * Names of individual rules to exclude from any source.
+     */
+    readonly excludeRules?: ReadonlyArray<string>;
+    /**
+     * Additional content to append to existing rules (from bundles or custom rules).
+     * Keys are rule names, values are markdown content appended after a horizontal rule.
+     * Use this to supplement bundle rules with project-specific additions without
+     * replacing the entire rule.
+     *
+     * @example
+     * ```ts
+     * ruleExtensions: {
+     *   'typescript-conventions': '## Additional Conventions\n\n- Use branded types for IDs',
+     * }
+     * ```
+     */
+    readonly ruleExtensions?: Readonly<Record<string, string>>;
+    /**
+     * Claude Code settings.json configuration.
+     * Generated to .claude/settings.json (committed, team-shared).
+     */
+    readonly claudeSettings?: ClaudeSettingsConfig;
+    /**
+     * Cursor-specific configuration. Generates .cursor/hooks.json for
+     * lifecycle hooks and .cursorignore / .cursorindexingignore for
+     * file visibility control.
+     */
+    readonly cursorSettings?: CursorSettingsConfig;
+}
+
+/**
+ * Generates AI coding assistant configuration files from a common schema.
+ *
+ * Supports Cursor and Claude Code (initial release), with Codex and Copilot
+ * renderers planned for future issues. Rules, skills, and sub-agents are
+ * defined once and rendered into the correct format for each target platform.
+ *
+ * Follows the configulator component pattern: extends Component, static .of()
+ * factory, options interface with JSDoc.
+ *
+ * @example
+ * ```ts
+ * new AgentConfig(project, {
+ *   rules: [{
+ *     name: 'my-rule',
+ *     description: 'Project conventions',
+ *     scope: AGENT_RULE_SCOPE.ALWAYS,
+ *     content: '# My Rule\n\nFollow these conventions...',
+ *   }],
+ * });
+ * ```
+ */
+declare class AgentConfig extends Component {
+    /**
+     * Find the AgentConfig component on a project.
+     */
+    static of(project: Project$1): AgentConfig | undefined;
+    private readonly options;
+    constructor(project: Project$1, options?: AgentConfigOptions);
+    preSynthesize(): void;
+    private resolvePlatforms;
+    private resolveRules;
+    private resolveSkills;
+    private resolveSubAgents;
+}
+
+/**
+ * AWS CDK bundle — auto-detected when `aws-cdk-lib` is in dependencies.
+ */
+declare const awsCdkBundle: AgentRuleBundle;
+
+/**
+ * Base bundle — always included unless `includeBaseRules: false`.
+ * Contains project-overview, interaction-style, and general-conventions rules.
+ */
+declare const baseBundle: AgentRuleBundle;
+
+/**
+ * Jest bundle — auto-detected when Jest is in dependencies.
+ */
+declare const jestBundle: AgentRuleBundle;
+
+/**
+ * PNPM bundle — auto-detected when the PnpmWorkspace component is present.
+ */
+declare const pnpmBundle: AgentRuleBundle;
+
+/**
+ * Projen bundle — auto-detected when `projen` is in dependencies.
+ */
+declare const projenBundle: AgentRuleBundle;
+
+/**
+ * Turborepo bundle — auto-detected when the TurboRepo component is present.
+ */
+declare const turborepoBundle: AgentRuleBundle;
+
+/**
+ * TypeScript bundle — auto-detected when a tsconfig is present.
+ */
+declare const typescriptBundle: AgentRuleBundle;
+
+/**
+ * Vitest bundle — auto-detected when the Vitest component is present.
+ */
+declare const vitestBundle: AgentRuleBundle;
+
+/**
+ * Built-in rule bundles that ship with configulator.
+ * Each bundle is auto-detected based on project introspection.
+ *
+ * Order matters: base is first so its rules can be overridden by
+ * more specific bundles. The base bundle's `appliesWhen` always
+ * returns true; it is filtered by the `includeBaseRules` option
+ * in AgentConfig.
+ */
+declare const BUILT_IN_BUNDLES: ReadonlyArray<AgentRuleBundle>;
+
 /*******************************************************************************
  *
  * Git configs for this repo. This venn diagram has a great deal of overlap
@@ -635,7 +1363,7 @@ declare class PnpmWorkspace extends Component {
      * @param project
      * @returns
      */
-    static of(project: Project): PnpmWorkspace | undefined;
+    static of(project: Project$1): PnpmWorkspace | undefined;
     /**
      * Filename for the pnpm workspace file.
      */
@@ -717,7 +1445,7 @@ declare class PnpmWorkspace extends Component {
             [dependencyName: string]: string;
         };
     };
-    constructor(project: Project, options?: PnpmWorkspaceOptions);
+    constructor(project: Project$1, options?: PnpmWorkspaceOptions);
 }
 
 /*******************************************************************************
@@ -751,11 +1479,11 @@ interface ResetTaskOptions {
     readonly taskName?: string;
 }
 declare class ResetTask extends Component {
-    readonly project: Project;
+    readonly project: Project$1;
     /**
      * Static method to discover reset task in a project.
      */
-    static of(project: Project): ResetTask | undefined;
+    static of(project: Project$1): ResetTask | undefined;
     /**
      * The output directory to delete (from tsconfig or custom).
      */
@@ -768,7 +1496,7 @@ declare class ResetTask extends Component {
      * The name of the task that was created.
      */
     readonly taskName: string;
-    constructor(project: Project, options?: ResetTaskOptions);
+    constructor(project: Project$1, options?: ResetTaskOptions);
 }
 
 /**
@@ -788,7 +1516,7 @@ interface TurboRepoTaskOptions {
     readonly interactive?: boolean;
 }
 declare class TurboRepoTask extends Component$1 {
-    readonly project: Project$1;
+    readonly project: Project;
     readonly name: string;
     dependsOn: Array<string>;
     readonly env: Array<string>;
@@ -803,7 +1531,7 @@ declare class TurboRepoTask extends Component$1 {
      * Include this task in turbo.json output?
      */
     isActive: boolean;
-    constructor(project: Project$1, options: TurboRepoTaskOptions);
+    constructor(project: Project, options: TurboRepoTaskOptions);
     taskConfig(): Record<string, any>;
 }
 
@@ -1005,7 +1733,7 @@ declare class TurboRepo extends Component$1 {
     /**
      * Static method to discovert turbo in a project.
      */
-    static of(project: Project$1): TurboRepo | undefined;
+    static of(project: Project): TurboRepo | undefined;
     static buildWorkflowOptions: (remoteCacheOptions: RemoteCacheOptions) => Partial<BuildWorkflowOptions>;
     /**
      * Version of turborepo to use.
@@ -1318,6 +2046,18 @@ interface MonorepoProjectOptions extends Omit<TypeScriptProjectOptions$1, "defau
      * @default true
      */
     readonly configulatorRegistryConsumer?: boolean;
+    /**
+     * Enable AI agent configuration (Cursor, Claude Code rules).
+     * When true, generates rule files at the monorepo root with auto-detected
+     * bundles based on project and subproject introspection.
+     *
+     * @default false
+     */
+    readonly agentConfig?: boolean;
+    /**
+     * Options for the AgentConfig component. Only used when `agentConfig` is true.
+     */
+    readonly agentConfigOptions?: AgentConfigOptions;
 }
 declare class MonorepoProject extends TypeScriptAppProject {
     /**
@@ -1590,4 +2330,4 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { type ApproveMergeUpgradeOptions, type AwsAccount, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type DeployWorkflowOptions, type GitBranch, type IDependencyResolver, JsiiFaker, MERGE_METHODS, MIMIMUM_RELEASE_AGE, type MergeMethod, MonorepoProject, type MonorepoProjectOptions, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, ResetTask, type ResetTaskOptions, TestRunner, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, getLatestEligibleVersion };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentModel, type AgentPlatform, type AgentPlatformOverrides, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, type AwsAccount, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, type DeployWorkflowOptions, type GitBranch, type IDependencyResolver, JsiiFaker, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, type McpServerConfig, type McpTransport, type MergeMethod, MonorepoProject, type MonorepoProjectOptions, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, ResetTask, type ResetTaskOptions, TestRunner, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, awsCdkBundle, baseBundle, getLatestEligibleVersion, jestBundle, pnpmBundle, projenBundle, turborepoBundle, typescriptBundle, vitestBundle };