projen 0.81.17__py3-none-any.whl → 0.98.25__py3-none-any.whl

projen/__init__.py

@@ -1,4 +1,4 @@
-'''
+r'''
 <p align="center">
   <a href="https://projen.io">
     <img src="https://raw.githubusercontent.com/projen/projen/main/logo/projen.svg">
@@ -286,14 +286,6 @@ projen has an unofficial [VS Code extension](https://marketplace.visualstudio.co
 The projen community can be found within the #projen channel in the [cdk.dev](https://cdk.dev/)
 community Slack workspace.
 
-### Virtual Meetup
-
-* Thursday June 30, 2022
-* 1-2pm America/New_York (EDT)
-* [CFP](https://bit.ly/3NEc0UQ) a Google Form
-* CFP Closes Saturday April 30, 2022
-* Hosted on [Zoom](https://zoom.us/j/92399854777?pwd=OUZybHlobHNoZUs1VVordWhaRTVGdz09#success)
-
 ## Contributions
 
 Contributions of all kinds are welcome! Check out our [contributor's
@@ -304,8 +296,8 @@ For a quick start, check out a development environment:
 ```bash
 $ git clone git@github.com:projen/projen
 $ cd projen
-$ yarn
-$ yarn watch # compile in the background
+$ npm ci
+$ npm run watch # compile in the background
 ```
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -585,13 +577,185 @@ import jsii
 import publication
 import typing_extensions
 
-from typeguard import check_type
+import typeguard
+from importlib.metadata import version as _metadata_package_version
+TYPEGUARD_MAJOR_VERSION = int(_metadata_package_version('typeguard').split('.')[0])
+
+def check_type(argname: str, value: object, expected_type: typing.Any) -> typing.Any:
+    if TYPEGUARD_MAJOR_VERSION <= 2:
+        return typeguard.check_type(argname=argname, value=value, expected_type=expected_type) # type:ignore
+    else:
+        if isinstance(value, jsii._reference_map.InterfaceDynamicProxy): # pyright: ignore [reportAttributeAccessIssue]
+           pass
+        else:
+            if TYPEGUARD_MAJOR_VERSION == 3:
+                typeguard.config.collection_check_strategy = typeguard.CollectionCheckStrategy.ALL_ITEMS # type:ignore
+                typeguard.check_type(value=value, expected_type=expected_type) # type:ignore
+            else:
+                typeguard.check_type(value=value, expected_type=expected_type, collection_check_strategy=typeguard.CollectionCheckStrategy.ALL_ITEMS) # type:ignore
 
 from ._jsii import *
 
 import constructs as _constructs_77d1e7e8
 
 
+@jsii.enum(jsii_type="projen.AiAgent")
+class AiAgent(enum.Enum):
+    '''(experimental) Supported AI coding assistants and their instruction file locations.
+
+    :stability: experimental
+    '''
+
+    GITHUB_COPILOT = "GITHUB_COPILOT"
+    '''(experimental) GitHub Copilot - .github/copilot-instructions.md.
+
+    :stability: experimental
+    '''
+    CURSOR = "CURSOR"
+    '''(experimental) Cursor IDE - .cursor/rules/project.md.
+
+    :stability: experimental
+    '''
+    CLAUDE = "CLAUDE"
+    '''(experimental) Claude Code - CLAUDE.md.
+
+    :stability: experimental
+    '''
+    AMAZON_Q = "AMAZON_Q"
+    '''(experimental) Amazon Q - .amazonq/rules/project.md.
+
+    :stability: experimental
+    '''
+    KIRO = "KIRO"
+    '''(experimental) Kiro - .kiro/steering/project.md.
+
+    :stability: experimental
+    '''
+    CODEX = "CODEX"
+    '''(experimental) OpenAI Codex - AGENTS.md.
+
+    :stability: experimental
+    '''
+
+
+@jsii.data_type(
+    jsii_type="projen.AiInstructionsOptions",
+    jsii_struct_bases=[],
+    name_mapping={
+        "agents": "agents",
+        "agent_specific_instructions": "agentSpecificInstructions",
+        "include_default_instructions": "includeDefaultInstructions",
+        "instructions": "instructions",
+    },
+)
+class AiInstructionsOptions:
+    def __init__(
+        self,
+        *,
+        agents: typing.Optional[typing.Sequence[AiAgent]] = None,
+        agent_specific_instructions: typing.Optional[typing.Mapping[builtins.str, typing.Sequence[builtins.str]]] = None,
+        include_default_instructions: typing.Optional[builtins.bool] = None,
+        instructions: typing.Optional[typing.Sequence[builtins.str]] = None,
+    ) -> None:
+        '''(experimental) Options for configuring AI tool instruction files.
+
+        :param agents: (experimental) Which AI agents to generate instruction files for. Default: - All agents: [AiAgent.GITHUB_COPILOT, AiAgent.CURSOR, AiAgent.CLAUDE, AiAgent.AMAZON_Q, AiAgent.KIRO, AiAgent.CODEX]
+        :param agent_specific_instructions: (experimental) Per-agent custom instructions. Allows different instructions for different AI tools. Default: - no agent specific instructions
+        :param include_default_instructions: (experimental) Include default instructions for projen and general best practices. Default instructions will only be included for agents provided in the ``agents`` option. If ``agents`` is not provided, default instructions will be included for all agents. Default: true
+        :param instructions: (experimental) General instructions applicable to all agents. Default: - no agent specific instructions
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__5bf7714efdf83cf2031e4ef3aa1d0cb9511cb921777751c76a0f501c0c56e247)
+            check_type(argname="argument agents", value=agents, expected_type=type_hints["agents"])
+            check_type(argname="argument agent_specific_instructions", value=agent_specific_instructions, expected_type=type_hints["agent_specific_instructions"])
+            check_type(argname="argument include_default_instructions", value=include_default_instructions, expected_type=type_hints["include_default_instructions"])
+            check_type(argname="argument instructions", value=instructions, expected_type=type_hints["instructions"])
+        self._values: typing.Dict[builtins.str, typing.Any] = {}
+        if agents is not None:
+            self._values["agents"] = agents
+        if agent_specific_instructions is not None:
+            self._values["agent_specific_instructions"] = agent_specific_instructions
+        if include_default_instructions is not None:
+            self._values["include_default_instructions"] = include_default_instructions
+        if instructions is not None:
+            self._values["instructions"] = instructions
+
+    @builtins.property
+    def agents(self) -> typing.Optional[typing.List[AiAgent]]:
+        '''(experimental) Which AI agents to generate instruction files for.
+
+        :default: - All agents: [AiAgent.GITHUB_COPILOT, AiAgent.CURSOR, AiAgent.CLAUDE, AiAgent.AMAZON_Q, AiAgent.KIRO, AiAgent.CODEX]
+
+        :stability: experimental
+        '''
+        result = self._values.get("agents")
+        return typing.cast(typing.Optional[typing.List[AiAgent]], result)
+
+    @builtins.property
+    def agent_specific_instructions(
+        self,
+    ) -> typing.Optional[typing.Mapping[builtins.str, typing.List[builtins.str]]]:
+        '''(experimental) Per-agent custom instructions.
+
+        Allows different instructions for different AI tools.
+
+        :default: - no agent specific instructions
+
+        :stability: experimental
+
+        Example::
+
+            {
+              [AiAgent.GITHUB_COPILOT]: {
+                instructions: ["Use descriptive commit messages."]
+              },
+              [AiAgent.CURSOR]: {
+                instructions: ["Prefer functional patterns.", "Always add tests."]
+              }
+            }
+        '''
+        result = self._values.get("agent_specific_instructions")
+        return typing.cast(typing.Optional[typing.Mapping[builtins.str, typing.List[builtins.str]]], result)
+
+    @builtins.property
+    def include_default_instructions(self) -> typing.Optional[builtins.bool]:
+        '''(experimental) Include default instructions for projen and general best practices.
+
+        Default instructions will only be included for agents provided in the ``agents`` option.
+        If ``agents`` is not provided, default instructions will be included for all agents.
+
+        :default: true
+
+        :stability: experimental
+        '''
+        result = self._values.get("include_default_instructions")
+        return typing.cast(typing.Optional[builtins.bool], result)
+
+    @builtins.property
+    def instructions(self) -> typing.Optional[typing.List[builtins.str]]:
+        '''(experimental) General instructions applicable to all agents.
+
+        :default: - no agent specific instructions
+
+        :stability: experimental
+        '''
+        result = self._values.get("instructions")
+        return typing.cast(typing.Optional[typing.List[builtins.str]], result)
+
+    def __eq__(self, rhs: typing.Any) -> builtins.bool:
+        return isinstance(rhs, self.__class__) and rhs._values == self._values
+
+    def __ne__(self, rhs: typing.Any) -> builtins.bool:
+        return not (rhs == self)
+
+    def __repr__(self) -> str:
+        return "AiInstructionsOptions(%s)" % ", ".join(
+            k + "=" + repr(v) for k, v in self._values.items()
+        )
+
+
 class Component(
     _constructs_77d1e7e8.Construct,
     metaclass=jsii.JSIIMeta,
@@ -895,6 +1059,33 @@ class Dependencies(Component, metaclass=jsii.JSIIMeta, jsii_type="projen.Depende
             check_type(argname="argument type", value=type, expected_type=type_hints["type"])
         return typing.cast("Dependency", jsii.invoke(self, "getDependency", [name, type]))
 
+    @jsii.member(jsii_name="isDependencySatisfied")
+    def is_dependency_satisfied(
+        self,
+        name: builtins.str,
+        type: "DependencyType",
+        expected_range: builtins.str,
+    ) -> builtins.bool:
+        '''(experimental) Checks if an existing dependency satisfies a dependency requirement.
+
+        :param name: The name of the dependency to check (without the version).
+        :param type: The dependency type.
+        :param expected_range: The version constraint to check (e.g. ``^3.4.0``). The constraint of the dependency must be a subset of the expected range to satisfy the requirements.
+
+        :return:
+
+        ``true`` if the dependency exists and its version satisfies the provided constraint. ``false`` otherwise.
+        Notably returns ``false`` if a dependency exists, but has no version.
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__628e50591481575ad249671e7cf61edd1bb37d5aeab5e143a0783051e3167dcc)
+            check_type(argname="argument name", value=name, expected_type=type_hints["name"])
+            check_type(argname="argument type", value=type, expected_type=type_hints["type"])
+            check_type(argname="argument expected_range", value=expected_range, expected_type=type_hints["expected_range"])
+        return typing.cast(builtins.bool, jsii.invoke(self, "isDependencySatisfied", [name, type, expected_range]))
+
     @jsii.member(jsii_name="removeDependency")
     def remove_dependency(
         self,
@@ -2588,6 +2779,35 @@ class DockerComposeVolumeMount:
         )
 
 
+@jsii.enum(jsii_type="projen.EndOfLine")
+class EndOfLine(enum.Enum):
+    '''(experimental) The end of line characters supported by git.
+
+    :stability: experimental
+    '''
+
+    AUTO = "AUTO"
+    '''(experimental) Maintain existing (mixed values within one file are normalised by looking at what's used after the first line).
+
+    :stability: experimental
+    '''
+    CRLF = "CRLF"
+    '''(experimental) Carriage Return + Line Feed characters (\\r\\n), common on Windows.
+
+    :stability: experimental
+    '''
+    LF = "LF"
+    '''(experimental) Line Feed only (\\n), common on Linux and macOS as well as inside git repos.
+
+    :stability: experimental
+    '''
+    NONE = "NONE"
+    '''(experimental) Disable and do not configure the end of line character.
+
+    :stability: experimental
+    '''
+
+
 class FileBase(
     Component,
     metaclass=jsii.JSIIAbstractClass,
@@ -2713,7 +2933,7 @@ class FileBase(
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__3fed3e4c76496e254ef32ce4556e7e1b3b0cef6929de044486dda20248a06c4d)
             check_type(argname="argument value", value=value, expected_type=type_hints["value"])
-        jsii.set(self, "executable", value)
+        jsii.set(self, "executable", value) # pyright: ignore[reportArgumentType]
 
     @builtins.property
     @jsii.member(jsii_name="readonly")
@@ -2729,7 +2949,7 @@ class FileBase(
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__c20fcd33148f053d9de2f2152439cc9f0687a0e328bf05cb8b38721095832ea5)
             check_type(argname="argument value", value=value, expected_type=type_hints["value"])
-        jsii.set(self, "readonly", value)
+        jsii.set(self, "readonly", value) # pyright: ignore[reportArgumentType]
 
 
 class _FileBaseProxy(FileBase):
@@ -2886,16 +3106,24 @@ class GitAttributesFile(
     :stability: experimental
     '''
 
-    def __init__(self, scope: _constructs_77d1e7e8.IConstruct) -> None:
+    def __init__(
+        self,
+        scope: _constructs_77d1e7e8.IConstruct,
+        *,
+        end_of_line: typing.Optional[EndOfLine] = None,
+    ) -> None:
         '''
         :param scope: -
+        :param end_of_line: (experimental) The default end of line character for text files. endOfLine it's useful to keep the same end of line between Windows and Unix operative systems for git checking/checkout operations. Hence, it can avoid simple repository mutations consisting only of changes in the end of line characters. It will be set in the first line of the .gitattributes file to make it the first match with high priority but it can be overriden in a later line. Can be disabled by setting explicitly: ``{ endOfLine: EndOfLine.NONE }``. Default: EndOfLine.LF
 
         :stability: experimental
         '''
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__a914753a9db7cc6bfa6a166cf7ee02794375210a09b1d8e2c62496abf14b4d21)
             check_type(argname="argument scope", value=scope, expected_type=type_hints["scope"])
-        jsii.create(self.__class__, self, [scope])
+        options = GitAttributesFileOptions(end_of_line=end_of_line)
+
+        jsii.create(self.__class__, self, [scope, options])
 
     @jsii.member(jsii_name="addAttributes")
     def add_attributes(self, glob: builtins.str, *attributes: builtins.str) -> None:
@@ -2933,6 +3161,23 @@ class GitAttributesFile(
         '''
         return typing.cast(None, jsii.invoke(self, "preSynthesize", []))
 
+    @jsii.member(jsii_name="removeAttributes")
+    def remove_attributes(self, glob: builtins.str, *attributes: builtins.str) -> None:
+        '''(experimental) Removes attributes from a set of files.
+
+        If no attributes are provided, the glob pattern will be removed completely.
+
+        :param glob: Glob pattern to modify.
+        :param attributes: Attributes to remove from matched files.
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__573b65747d3cd070f990730baa2e2b06016818d32122c7fbc2696b8513582a7d)
+            check_type(argname="argument glob", value=glob, expected_type=type_hints["glob"])
+            check_type(argname="argument attributes", value=attributes, expected_type=typing.Tuple[type_hints["attributes"], ...]) # pyright: ignore [reportGeneralTypeIssues]
+        return typing.cast(None, jsii.invoke(self, "removeAttributes", [glob, *attributes]))
+
     @jsii.member(jsii_name="synthesizeContent")
     def _synthesize_content(self, _: "IResolver") -> typing.Optional[builtins.str]:
         '''(experimental) Implemented by derived classes and returns the contents of the file to emit.
@@ -2946,6 +3191,15 @@ class GitAttributesFile(
             check_type(argname="argument _", value=_, expected_type=type_hints["_"])
         return typing.cast(typing.Optional[builtins.str], jsii.invoke(self, "synthesizeContent", [_]))
 
+    @builtins.property
+    @jsii.member(jsii_name="endOfLine")
+    def end_of_line(self) -> EndOfLine:
+        '''(experimental) The default end of line character for text files.
+
+        :stability: experimental
+        '''
+        return typing.cast(EndOfLine, jsii.get(self, "endOfLine"))
+
     @builtins.property
     @jsii.member(jsii_name="hasLfsPatterns")
     def has_lfs_patterns(self) -> builtins.bool:
@@ -2956,30 +3210,96 @@ class GitAttributesFile(
         return typing.cast(builtins.bool, jsii.get(self, "hasLfsPatterns"))
 
 
+@jsii.data_type(
+    jsii_type="projen.GitAttributesFileOptions",
+    jsii_struct_bases=[],
+    name_mapping={"end_of_line": "endOfLine"},
+)
+class GitAttributesFileOptions:
+    def __init__(self, *, end_of_line: typing.Optional[EndOfLine] = None) -> None:
+        '''(experimental) Options for ``GitAttributesFile``.
+
+        :param end_of_line: (experimental) The default end of line character for text files. endOfLine it's useful to keep the same end of line between Windows and Unix operative systems for git checking/checkout operations. Hence, it can avoid simple repository mutations consisting only of changes in the end of line characters. It will be set in the first line of the .gitattributes file to make it the first match with high priority but it can be overriden in a later line. Can be disabled by setting explicitly: ``{ endOfLine: EndOfLine.NONE }``. Default: EndOfLine.LF
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__82a54cc3274f754056a1301deb3e7902a7a31057da6ade20b64dae8487831db5)
+            check_type(argname="argument end_of_line", value=end_of_line, expected_type=type_hints["end_of_line"])
+        self._values: typing.Dict[builtins.str, typing.Any] = {}
+        if end_of_line is not None:
+            self._values["end_of_line"] = end_of_line
+
+    @builtins.property
+    def end_of_line(self) -> typing.Optional[EndOfLine]:
+        '''(experimental) The default end of line character for text files.
+
+        endOfLine it's useful to keep the same end of line between Windows and Unix operative systems for git checking/checkout operations. Hence, it can avoid simple repository mutations consisting only of changes in the end of line characters. It will be set in the first line of the .gitattributes file to make it the first match with high priority but it can be overriden in a later line. Can be disabled by setting explicitly: ``{ endOfLine: EndOfLine.NONE }``.
+
+        :default: EndOfLine.LF
+
+        :stability: experimental
+        '''
+        result = self._values.get("end_of_line")
+        return typing.cast(typing.Optional[EndOfLine], result)
+
+    def __eq__(self, rhs: typing.Any) -> builtins.bool:
+        return isinstance(rhs, self.__class__) and rhs._values == self._values
+
+    def __ne__(self, rhs: typing.Any) -> builtins.bool:
+        return not (rhs == self)
+
+    def __repr__(self) -> str:
+        return "GitAttributesFileOptions(%s)" % ", ".join(
+            k + "=" + repr(v) for k, v in self._values.items()
+        )
+
+
 @jsii.data_type(
     jsii_type="projen.GitOptions",
     jsii_struct_bases=[],
-    name_mapping={"lfs_patterns": "lfsPatterns"},
+    name_mapping={"end_of_line": "endOfLine", "lfs_patterns": "lfsPatterns"},
 )
 class GitOptions:
     def __init__(
         self,
         *,
+        end_of_line: typing.Optional[EndOfLine] = None,
         lfs_patterns: typing.Optional[typing.Sequence[builtins.str]] = None,
     ) -> None:
         '''(experimental) Git configuration options.
 
+        :param end_of_line: (experimental) The default end of line character for text files. endOfLine it's useful to keep the same end of line between Windows and Unix operative systems for git checking/checkout operations. Hence, it can avoid simple repository mutations consisting only of changes in the end of line characters. It will be set in the first line of the .gitattributes file to make it the first match with high priority but it can be overriden in a later line. Can be disabled by setting: ``endOfLine: EndOfLine.NONE``. Default: EndOfLine.LF
         :param lfs_patterns: (experimental) File patterns to mark as stored in Git LFS. Default: - No files stored in LFS
 
         :stability: experimental
         '''
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__ee7f1b3b819a95ebdb112752cdc122d5362da95c419decd69ec24018f344bace)
+            check_type(argname="argument end_of_line", value=end_of_line, expected_type=type_hints["end_of_line"])
             check_type(argname="argument lfs_patterns", value=lfs_patterns, expected_type=type_hints["lfs_patterns"])
         self._values: typing.Dict[builtins.str, typing.Any] = {}
+        if end_of_line is not None:
+            self._values["end_of_line"] = end_of_line
         if lfs_patterns is not None:
             self._values["lfs_patterns"] = lfs_patterns
 
+    @builtins.property
+    def end_of_line(self) -> typing.Optional[EndOfLine]:
+        '''(experimental) The default end of line character for text files.
+
+        endOfLine it's useful to keep the same end of line between Windows and Unix operative systems for git checking/checkout operations.
+        Hence, it can avoid simple repository mutations consisting only of changes in the end of line characters.
+        It will be set in the first line of the .gitattributes file to make it the first match with high priority but it can be overriden in a later line.
+        Can be disabled by setting: ``endOfLine: EndOfLine.NONE``.
+
+        :default: EndOfLine.LF
+
+        :stability: experimental
+        '''
+        result = self._values.get("end_of_line")
+        return typing.cast(typing.Optional[EndOfLine], result)
+
     @builtins.property
     def lfs_patterns(self) -> typing.Optional[typing.List[builtins.str]]:
         '''(experimental) File patterns to mark as stored in Git LFS.
@@ -3705,6 +4025,52 @@ class GroupRunnerOptions:
         )
 
 
+@jsii.interface(jsii_type="projen.ICompareString")
+class ICompareString(typing_extensions.Protocol):
+    '''
+    :stability: experimental
+    '''
+
+    @jsii.member(jsii_name="compare")
+    def compare(self, a: builtins.str, b: builtins.str) -> jsii.Number:
+        '''
+        :param a: The first string.
+        :param b: The second string.
+
+        :return: It is expected to return a negative value if the first argument is less than the second argument, zero if they're equal, and a positive value otherwise.
+
+        :stability: experimental
+        '''
+        ...
+
+
+class _ICompareStringProxy:
+    '''
+    :stability: experimental
+    '''
+
+    __jsii_type__: typing.ClassVar[str] = "projen.ICompareString"
+
+    @jsii.member(jsii_name="compare")
+    def compare(self, a: builtins.str, b: builtins.str) -> jsii.Number:
+        '''
+        :param a: The first string.
+        :param b: The second string.
+
+        :return: It is expected to return a negative value if the first argument is less than the second argument, zero if they're equal, and a positive value otherwise.
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__63d4f6e150362668f5e26d2f58f8b0a32cff82cf2eb8cb736d2c4333d0b01d09)
+            check_type(argname="argument a", value=a, expected_type=type_hints["a"])
+            check_type(argname="argument b", value=b, expected_type=type_hints["b"])
+        return typing.cast(jsii.Number, jsii.invoke(self, "compare", [a, b]))
+
+# Adding a "__jsii_proxy_class__(): typing.Type" function to the interface
+typing.cast(typing.Any, ICompareString).__jsii_proxy_class__ = lambda : _ICompareStringProxy
+
+
 @jsii.interface(jsii_type="projen.IDevEnvironment")
 class IDevEnvironment(typing_extensions.Protocol):
     '''(experimental) Abstract interface for container-based development environments, such as Gitpod and GitHub Codespaces.
@@ -5504,7 +5870,7 @@ class ObjectFile(
 
            "compilerOptions": {
              "exclude": ["node_modules"],
-             "lib": ["es2019"]
+             "lib": ["es2020"]
              ...
            }
            ...
@@ -5518,7 +5884,7 @@ class ObjectFile(
 
            "compilerOptions": {
              "exclude": ["node_modules", "coverage"],
-             "lib": ["es2019", "dom", "dom.iterable", "esnext"]
+             "lib": ["es2020", "dom", "dom.iterable", "esnext"]
              ...
            }
            ...
@@ -5542,7 +5908,7 @@ class ObjectFile(
 
            "compilerOptions": {
              "exclude": ["node_modules"],
-             "lib": ["es2019"]
+             "lib": ["es2020"]
              ...
            }
            ...
@@ -6706,7 +7072,7 @@ class ProjectTree(Component, metaclass=jsii.JSIIMeta, jsii_type="projen.ProjectT
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__dd1d331084783b1e11404a33c550a54f472b9e2d656ca02bdc7287828f96e2fb)
             check_type(argname="argument value", value=value, expected_type=type_hints["value"])
-        jsii.set(self, "file", value)
+        jsii.set(self, "file", value) # pyright: ignore[reportArgumentType]
 
 
 @jsii.enum(jsii_type="projen.ProjectType")
@@ -6994,6 +7360,10 @@ class ProjenrcOptions(ProjenrcJsonOptions):
 class ReleasableCommits(metaclass=jsii.JSIIMeta, jsii_type="projen.ReleasableCommits"):
     '''(experimental) Find commits that should be considered releasable to decide if a release is required.
 
+    This setting only controls whether a release is triggered, yes or no. The
+    paths used here are independent of the code that controls what commits are inspected
+    to determine the version number.
+
     :stability: experimental
     '''
 
@@ -7093,7 +7463,7 @@ class ReleasableCommits(metaclass=jsii.JSIIMeta, jsii_type="projen.ReleasableCom
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__e1c46f6c8bc57788436baf6da521f9e5812106db6aa16bda9534549c8cbb078d)
             check_type(argname="argument value", value=value, expected_type=type_hints["value"])
-        jsii.set(self, "cmd", value)
+        jsii.set(self, "cmd", value) # pyright: ignore[reportArgumentType]
 
 
 class Renovatebot(Component, metaclass=jsii.JSIIMeta, jsii_type="projen.Renovatebot"):
@@ -7631,7 +8001,7 @@ class SampleFile(Component, metaclass=jsii.JSIIMeta, jsii_type="projen.SampleFil
         :param project: - the project to tie this file to.
         :param file_path: - the relative path in the project to put the file.
         :param contents: (experimental) The contents of the file to write.
-        :param source_path: (experimental) Absolute path to a file to copy the contents from (does not need to be a text file). If your project is Typescript-based and has configured ``testdir`` to be a subdirectory of ``src``, sample files should outside of the ``src`` directory, otherwise they may not be copied. For example:: new SampleFile(this, 'assets/icon.png', { source: path.join(__dirname, '..', 'sample-assets', 'icon.png') });
+        :param source_path: (experimental) Absolute path to a file to copy the contents from (does not need to be a text file). If your project is Typescript-based and has configured ``testdir`` to be a subdirectory of ``src``, sample files should outside of the ``src`` directory, otherwise they may not be copied. For example:: new SampleFile(this, 'assets/icon.png', { sourcePath: path.join(__dirname, '..', 'sample-assets', 'icon.png') });
 
         :stability: experimental
         '''
@@ -7667,7 +8037,7 @@ class SampleFileOptions:
         '''(experimental) Options for the SampleFile object.
 
         :param contents: (experimental) The contents of the file to write.
-        :param source_path: (experimental) Absolute path to a file to copy the contents from (does not need to be a text file). If your project is Typescript-based and has configured ``testdir`` to be a subdirectory of ``src``, sample files should outside of the ``src`` directory, otherwise they may not be copied. For example:: new SampleFile(this, 'assets/icon.png', { source: path.join(__dirname, '..', 'sample-assets', 'icon.png') });
+        :param source_path: (experimental) Absolute path to a file to copy the contents from (does not need to be a text file). If your project is Typescript-based and has configured ``testdir`` to be a subdirectory of ``src``, sample files should outside of the ``src`` directory, otherwise they may not be copied. For example:: new SampleFile(this, 'assets/icon.png', { sourcePath: path.join(__dirname, '..', 'sample-assets', 'icon.png') });
 
         :stability: experimental
         '''
@@ -7698,7 +8068,7 @@ class SampleFileOptions:
         subdirectory of ``src``, sample files should outside of the ``src`` directory,
         otherwise they may not be copied. For example::
 
-           new SampleFile(this, 'assets/icon.png', { source: path.join(__dirname, '..', 'sample-assets', 'icon.png') });
+           new SampleFile(this, 'assets/icon.png', { sourcePath: path.join(__dirname, '..', 'sample-assets', 'icon.png') });
 
         :stability: experimental
         '''
@@ -8241,7 +8611,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
 
         :stability: experimental
         '''
@@ -8259,6 +8629,21 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
 
         return typing.cast(None, jsii.invoke(self, "exec", [command, options]))
 
+    @jsii.member(jsii_name="insertStep")
+    def insert_step(self, index: jsii.Number, *steps: "TaskStep") -> None:
+        '''(experimental) Insert one or more steps at a given index.
+
+        :param index: Steps will be inserted before this index. May be negative to count backwards from the end, or may be ``== steps().length`` to insert at the end.
+        :param steps: The steps to insert.
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__f45a21d1f9e615dd1b225d6cafbe381a43b42811d1d21efd5a3f6630613e94af)
+            check_type(argname="argument index", value=index, expected_type=type_hints["index"])
+            check_type(argname="argument steps", value=steps, expected_type=typing.Tuple[type_hints["steps"], ...]) # pyright: ignore [reportGeneralTypeIssues]
+        return typing.cast(None, jsii.invoke(self, "insertStep", [index, *steps]))
+
     @jsii.member(jsii_name="lock")
     def lock(self) -> None:
         '''(experimental) Forbid additional changes to this task.
@@ -8287,7 +8672,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
 
         :deprecated: use ``prependExec()``
 
@@ -8327,7 +8712,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
 
         :stability: experimental
         '''
@@ -8365,7 +8750,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
 
         :stability: experimental
         '''
@@ -8403,7 +8788,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
 
         :stability: experimental
         '''
@@ -8453,7 +8838,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
 
         :stability: experimental
         '''
@@ -8491,7 +8876,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
 
         :stability: experimental
         '''
@@ -8529,7 +8914,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
 
         :stability: experimental
         '''
@@ -8574,7 +8959,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
 
         :stability: experimental
         '''
@@ -8651,7 +9036,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__063f23ecf0aa952acdfe114ecbbc1ac116753acf58aa564cd47b3ea5fbd99ad8)
             check_type(argname="argument value", value=value, expected_type=type_hints["value"])
-        jsii.set(self, "cwd", value)
+        jsii.set(self, "cwd", value) # pyright: ignore[reportArgumentType]
 
     @builtins.property
     @jsii.member(jsii_name="description")
@@ -8669,7 +9054,7 @@ class Task(metaclass=jsii.JSIIMeta, jsii_type="projen.Task"):
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__740ba1ef0d399dc76efb91309b9d1c8426213faa31da03d8c0abbc94a3d02e03)
             check_type(argname="argument value", value=value, expected_type=type_hints["value"])
-        jsii.set(self, "description", value)
+        jsii.set(self, "description", value) # pyright: ignore[reportArgumentType]
 
 
 @jsii.data_type(
@@ -9003,12 +9388,14 @@ class TaskRuntime(metaclass=jsii.JSIIMeta, jsii_type="projen.TaskRuntime"):
         name: builtins.str,
         parents: typing.Optional[typing.Sequence[builtins.str]] = None,
         args: typing.Optional[typing.Sequence[typing.Union[builtins.str, jsii.Number]]] = None,
+        env: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
     ) -> None:
         '''(experimental) Runs the task.
 
         :param name: The task name.
         :param parents: -
         :param args: -
+        :param env: -
 
         :stability: experimental
         '''
@@ -9017,7 +9404,8 @@ class TaskRuntime(metaclass=jsii.JSIIMeta, jsii_type="projen.TaskRuntime"):
             check_type(argname="argument name", value=name, expected_type=type_hints["name"])
             check_type(argname="argument parents", value=parents, expected_type=type_hints["parents"])
             check_type(argname="argument args", value=args, expected_type=type_hints["args"])
-        return typing.cast(None, jsii.invoke(self, "runTask", [name, parents, args]))
+            check_type(argname="argument env", value=env, expected_type=type_hints["env"])
+        return typing.cast(None, jsii.invoke(self, "runTask", [name, parents, args, env]))
 
     @jsii.member(jsii_name="tryFindTask")
     def try_find_task(self, name: builtins.str) -> typing.Optional["TaskSpec"]:
@@ -9251,7 +9639,7 @@ class TaskStepOptions:
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
 
         :stability: experimental
         '''
@@ -9364,6 +9752,9 @@ class TaskStepOptions:
         If ``true``, args are passed through at the end of the ``exec`` shell command.
         The position of the args can be changed by including the marker ``$@`` inside the command string.
 
+        If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating
+        the whitespace preserving behavior of bash variable expansion.
+
         If the step spawns a subtask, args are passed to the subtask.
         The subtask must define steps receiving args for this to have any effect.
 
@@ -9862,7 +10253,7 @@ class TomlFile(ObjectFile, metaclass=jsii.JSIIMeta, jsii_type="projen.TomlFile")
 
     def __init__(
         self,
-        project: Project,
+        scope: _constructs_77d1e7e8.IConstruct,
         file_path: builtins.str,
         *,
         obj: typing.Any = None,
@@ -9874,7 +10265,7 @@ class TomlFile(ObjectFile, metaclass=jsii.JSIIMeta, jsii_type="projen.TomlFile")
         readonly: typing.Optional[builtins.bool] = None,
     ) -> None:
         '''
-        :param project: -
+        :param scope: -
         :param file_path: -
         :param obj: (experimental) The object that will be serialized. You can modify the object's contents before synthesis. Serialization of the object is similar to JSON.stringify with few enhancements: - values that are functions will be called during synthesis and the result will be serialized - this allow to have lazy values. - ``Set`` will be converted to array - ``Map`` will be converted to a plain object ({ key: value, ... }}) - ``RegExp`` without flags will be converted to string representation of the source Default: {} an empty object (use ``file.obj`` to mutate).
         :param omit_empty: (experimental) Omits empty objects and arrays. Default: false
@@ -9888,7 +10279,7 @@ class TomlFile(ObjectFile, metaclass=jsii.JSIIMeta, jsii_type="projen.TomlFile")
         '''
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__de7c08620aabeb578ce8c0c54b1073a9df1f34c7815d8ae6fdebff7eb411c3d8)
-            check_type(argname="argument project", value=project, expected_type=type_hints["project"])
+            check_type(argname="argument scope", value=scope, expected_type=type_hints["scope"])
             check_type(argname="argument file_path", value=file_path, expected_type=type_hints["file_path"])
         options = TomlFileOptions(
             obj=obj,
@@ -9900,7 +10291,7 @@ class TomlFile(ObjectFile, metaclass=jsii.JSIIMeta, jsii_type="projen.TomlFile")
             readonly=readonly,
         )
 
-        jsii.create(self.__class__, self, [project, file_path, options])
+        jsii.create(self.__class__, self, [scope, file_path, options])
 
     @jsii.member(jsii_name="synthesizeContent")
     def _synthesize_content(self, resolver: IResolver) -> typing.Optional[builtins.str]:
@@ -10085,18 +10476,22 @@ class Version(Component, metaclass=jsii.JSIIMeta, jsii_type="projen.Version"):
 
     def __init__(
         self,
-        project: Project,
+        scope: _constructs_77d1e7e8.IConstruct,
         *,
         artifacts_directory: builtins.str,
         version_input_file: builtins.str,
+        bump_package: typing.Optional[builtins.str] = None,
+        next_version_command: typing.Optional[builtins.str] = None,
         releasable_commits: typing.Optional[ReleasableCommits] = None,
         tag_prefix: typing.Optional[builtins.str] = None,
         versionrc_options: typing.Optional[typing.Mapping[builtins.str, typing.Any]] = None,
     ) -> None:
         '''
-        :param project: -
+        :param scope: -
         :param artifacts_directory: (experimental) The name of the directory into which ``changelog.md`` and ``version.txt`` files are emitted.
         :param version_input_file: (experimental) A name of a .json file to set the ``version`` field in after a bump.
+        :param bump_package: (experimental) The ``commit-and-tag-version`` compatible package used to bump the package version, as a dependency string. This can be any compatible package version, including the deprecated ``standard-version@9``. Default: "commit-and-tag-version@12"
+        :param next_version_command: (experimental) A shell command to control the next version to release. If present, this shell command will be run before the bump is executed, and it determines what version to release. It will be executed in the following environment: - Working directory: the project directory. - ``$VERSION``: the current version. Looks like ``1.2.3``. - ``$LATEST_TAG``: the most recent tag. Looks like ``prefix-v1.2.3``, or may be unset. - ``$SUGGESTED_BUMP``: the suggested bump action based on commits. One of ``major|minor|patch|none``. The command should print one of the following to ``stdout``: - Nothing: the next version number will be determined based on commit history. - ``x.y.z``: the next version number will be ``x.y.z``. - ``major|minor|patch``: the next version number will be the current version number with the indicated component bumped. Default: - The next version will be determined based on the commit history and project settings.
         :param releasable_commits: (experimental) Find commits that should be considered releasable Used to decide if a release is required. Default: ReleasableCommits.everyCommit()
         :param tag_prefix: (experimental) The tag prefix corresponding to this version.
         :param versionrc_options: (experimental) Custom configuration for versionrc file used by standard-release.
@@ -10105,25 +10500,76 @@ class Version(Component, metaclass=jsii.JSIIMeta, jsii_type="projen.Version"):
         '''
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__9cf64d1b29258435f8a7749178e947fcedd27d55f323782081a21714be909595)
-            check_type(argname="argument project", value=project, expected_type=type_hints["project"])
+            check_type(argname="argument scope", value=scope, expected_type=type_hints["scope"])
         options = VersionOptions(
             artifacts_directory=artifacts_directory,
             version_input_file=version_input_file,
+            bump_package=bump_package,
+            next_version_command=next_version_command,
             releasable_commits=releasable_commits,
             tag_prefix=tag_prefix,
             versionrc_options=versionrc_options,
         )
 
-        jsii.create(self.__class__, self, [project, options])
+        jsii.create(self.__class__, self, [scope, options])
+
+    @jsii.member(jsii_name="envForBranch")
+    def env_for_branch(
+        self,
+        *,
+        major_version: typing.Optional[jsii.Number] = None,
+        min_major_version: typing.Optional[jsii.Number] = None,
+        minor_version: typing.Optional[jsii.Number] = None,
+        prerelease: typing.Optional[builtins.str] = None,
+        tag_prefix: typing.Optional[builtins.str] = None,
+    ) -> typing.Mapping[builtins.str, builtins.str]:
+        '''(experimental) Return the environment variables to modify the bump command for release branches.
+
+        These options are used to modify the behavior of the version bumping script
+        for additional branches, by setting environment variables.
+
+        No settings are inherited from the base ``Version`` object (but any parameters that
+        control versions do conflict with the use of a ``nextVersionCommand``).
+
+        :param major_version: (experimental) The major versions released from this branch.
+        :param min_major_version: (experimental) The minimum major version to release.
+        :param minor_version: (experimental) The minor versions released from this branch.
+        :param prerelease: (experimental) Bump the version as a pre-release tag. Default: - normal releases
+        :param tag_prefix: (experimental) Automatically add the given prefix to release tags. Useful if you are releasing on multiple branches with overlapping version numbers. Note: this prefix is used to detect the latest tagged version when bumping, so if you change this on a project with an existing version history, you may need to manually tag your latest release with the new prefix. Default: - no prefix
+
+        :stability: experimental
+        '''
+        branch_options = VersionBranchOptions(
+            major_version=major_version,
+            min_major_version=min_major_version,
+            minor_version=minor_version,
+            prerelease=prerelease,
+            tag_prefix=tag_prefix,
+        )
+
+        return typing.cast(typing.Mapping[builtins.str, builtins.str], jsii.invoke(self, "envForBranch", [branch_options]))
 
     @jsii.python.classproperty
     @jsii.member(jsii_name="STANDARD_VERSION")
     def STANDARD_VERSION(cls) -> builtins.str:
         '''
-        :stability: experimental
+        :deprecated: use ``version.bumpPackage`` on the component instance instead
+
+        :stability: deprecated
         '''
         return typing.cast(builtins.str, jsii.sget(cls, "STANDARD_VERSION"))
 
+    @builtins.property
+    @jsii.member(jsii_name="bumpPackage")
+    def bump_package(self) -> builtins.str:
+        '''(experimental) The package used to bump package versions, as a dependency string.
+
+        This is a ``commit-and-tag-version`` compatible package.
+
+        :stability: experimental
+        '''
+        return typing.cast(builtins.str, jsii.get(self, "bumpPackage"))
+
     @builtins.property
     @jsii.member(jsii_name="bumpTask")
     def bump_task(self) -> Task:
@@ -10169,12 +10615,130 @@ class Version(Component, metaclass=jsii.JSIIMeta, jsii_type="projen.Version"):
 
 
 @jsii.data_type(
-    jsii_type="projen.VersionOptions",
+    jsii_type="projen.VersionBranchOptions",
     jsii_struct_bases=[],
     name_mapping={
-        "artifacts_directory": "artifactsDirectory",
-        "version_input_file": "versionInputFile",
-        "releasable_commits": "releasableCommits",
+        "major_version": "majorVersion",
+        "min_major_version": "minMajorVersion",
+        "minor_version": "minorVersion",
+        "prerelease": "prerelease",
+        "tag_prefix": "tagPrefix",
+    },
+)
+class VersionBranchOptions:
+    def __init__(
+        self,
+        *,
+        major_version: typing.Optional[jsii.Number] = None,
+        min_major_version: typing.Optional[jsii.Number] = None,
+        minor_version: typing.Optional[jsii.Number] = None,
+        prerelease: typing.Optional[builtins.str] = None,
+        tag_prefix: typing.Optional[builtins.str] = None,
+    ) -> None:
+        '''(experimental) Options to pass to ``modifyBranchEnvironment``.
+
+        :param major_version: (experimental) The major versions released from this branch.
+        :param min_major_version: (experimental) The minimum major version to release.
+        :param minor_version: (experimental) The minor versions released from this branch.
+        :param prerelease: (experimental) Bump the version as a pre-release tag. Default: - normal releases
+        :param tag_prefix: (experimental) Automatically add the given prefix to release tags. Useful if you are releasing on multiple branches with overlapping version numbers. Note: this prefix is used to detect the latest tagged version when bumping, so if you change this on a project with an existing version history, you may need to manually tag your latest release with the new prefix. Default: - no prefix
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__62987907aa24cc1b84e9b6e9b755bd286708fa4a219baa7b979fb3ea61401603)
+            check_type(argname="argument major_version", value=major_version, expected_type=type_hints["major_version"])
+            check_type(argname="argument min_major_version", value=min_major_version, expected_type=type_hints["min_major_version"])
+            check_type(argname="argument minor_version", value=minor_version, expected_type=type_hints["minor_version"])
+            check_type(argname="argument prerelease", value=prerelease, expected_type=type_hints["prerelease"])
+            check_type(argname="argument tag_prefix", value=tag_prefix, expected_type=type_hints["tag_prefix"])
+        self._values: typing.Dict[builtins.str, typing.Any] = {}
+        if major_version is not None:
+            self._values["major_version"] = major_version
+        if min_major_version is not None:
+            self._values["min_major_version"] = min_major_version
+        if minor_version is not None:
+            self._values["minor_version"] = minor_version
+        if prerelease is not None:
+            self._values["prerelease"] = prerelease
+        if tag_prefix is not None:
+            self._values["tag_prefix"] = tag_prefix
+
+    @builtins.property
+    def major_version(self) -> typing.Optional[jsii.Number]:
+        '''(experimental) The major versions released from this branch.
+
+        :stability: experimental
+        '''
+        result = self._values.get("major_version")
+        return typing.cast(typing.Optional[jsii.Number], result)
+
+    @builtins.property
+    def min_major_version(self) -> typing.Optional[jsii.Number]:
+        '''(experimental) The minimum major version to release.
+
+        :stability: experimental
+        '''
+        result = self._values.get("min_major_version")
+        return typing.cast(typing.Optional[jsii.Number], result)
+
+    @builtins.property
+    def minor_version(self) -> typing.Optional[jsii.Number]:
+        '''(experimental) The minor versions released from this branch.
+
+        :stability: experimental
+        '''
+        result = self._values.get("minor_version")
+        return typing.cast(typing.Optional[jsii.Number], result)
+
+    @builtins.property
+    def prerelease(self) -> typing.Optional[builtins.str]:
+        '''(experimental) Bump the version as a pre-release tag.
+
+        :default: - normal releases
+
+        :stability: experimental
+        '''
+        result = self._values.get("prerelease")
+        return typing.cast(typing.Optional[builtins.str], result)
+
+    @builtins.property
+    def tag_prefix(self) -> typing.Optional[builtins.str]:
+        '''(experimental) Automatically add the given prefix to release tags. Useful if you are releasing on multiple branches with overlapping version numbers.
+
+        Note: this prefix is used to detect the latest tagged version
+        when bumping, so if you change this on a project with an existing version
+        history, you may need to manually tag your latest release
+        with the new prefix.
+
+        :default: - no prefix
+
+        :stability: experimental
+        '''
+        result = self._values.get("tag_prefix")
+        return typing.cast(typing.Optional[builtins.str], result)
+
+    def __eq__(self, rhs: typing.Any) -> builtins.bool:
+        return isinstance(rhs, self.__class__) and rhs._values == self._values
+
+    def __ne__(self, rhs: typing.Any) -> builtins.bool:
+        return not (rhs == self)
+
+    def __repr__(self) -> str:
+        return "VersionBranchOptions(%s)" % ", ".join(
+            k + "=" + repr(v) for k, v in self._values.items()
+        )
+
+
+@jsii.data_type(
+    jsii_type="projen.VersionOptions",
+    jsii_struct_bases=[],
+    name_mapping={
+        "artifacts_directory": "artifactsDirectory",
+        "version_input_file": "versionInputFile",
+        "bump_package": "bumpPackage",
+        "next_version_command": "nextVersionCommand",
+        "releasable_commits": "releasableCommits",
         "tag_prefix": "tagPrefix",
         "versionrc_options": "versionrcOptions",
     },
@@ -10185,6 +10749,8 @@ class VersionOptions:
         *,
         artifacts_directory: builtins.str,
         version_input_file: builtins.str,
+        bump_package: typing.Optional[builtins.str] = None,
+        next_version_command: typing.Optional[builtins.str] = None,
         releasable_commits: typing.Optional[ReleasableCommits] = None,
         tag_prefix: typing.Optional[builtins.str] = None,
         versionrc_options: typing.Optional[typing.Mapping[builtins.str, typing.Any]] = None,
@@ -10193,6 +10759,8 @@ class VersionOptions:
 
         :param artifacts_directory: (experimental) The name of the directory into which ``changelog.md`` and ``version.txt`` files are emitted.
         :param version_input_file: (experimental) A name of a .json file to set the ``version`` field in after a bump.
+        :param bump_package: (experimental) The ``commit-and-tag-version`` compatible package used to bump the package version, as a dependency string. This can be any compatible package version, including the deprecated ``standard-version@9``. Default: "commit-and-tag-version@12"
+        :param next_version_command: (experimental) A shell command to control the next version to release. If present, this shell command will be run before the bump is executed, and it determines what version to release. It will be executed in the following environment: - Working directory: the project directory. - ``$VERSION``: the current version. Looks like ``1.2.3``. - ``$LATEST_TAG``: the most recent tag. Looks like ``prefix-v1.2.3``, or may be unset. - ``$SUGGESTED_BUMP``: the suggested bump action based on commits. One of ``major|minor|patch|none``. The command should print one of the following to ``stdout``: - Nothing: the next version number will be determined based on commit history. - ``x.y.z``: the next version number will be ``x.y.z``. - ``major|minor|patch``: the next version number will be the current version number with the indicated component bumped. Default: - The next version will be determined based on the commit history and project settings.
         :param releasable_commits: (experimental) Find commits that should be considered releasable Used to decide if a release is required. Default: ReleasableCommits.everyCommit()
         :param tag_prefix: (experimental) The tag prefix corresponding to this version.
         :param versionrc_options: (experimental) Custom configuration for versionrc file used by standard-release.
@@ -10203,6 +10771,8 @@ class VersionOptions:
             type_hints = typing.get_type_hints(_typecheckingstub__fb94d39bdc04d188bb2447acba8747de3d6ec275231c8a512d647916d69a54f5)
             check_type(argname="argument artifacts_directory", value=artifacts_directory, expected_type=type_hints["artifacts_directory"])
             check_type(argname="argument version_input_file", value=version_input_file, expected_type=type_hints["version_input_file"])
+            check_type(argname="argument bump_package", value=bump_package, expected_type=type_hints["bump_package"])
+            check_type(argname="argument next_version_command", value=next_version_command, expected_type=type_hints["next_version_command"])
             check_type(argname="argument releasable_commits", value=releasable_commits, expected_type=type_hints["releasable_commits"])
             check_type(argname="argument tag_prefix", value=tag_prefix, expected_type=type_hints["tag_prefix"])
             check_type(argname="argument versionrc_options", value=versionrc_options, expected_type=type_hints["versionrc_options"])
@@ -10210,6 +10780,10 @@ class VersionOptions:
             "artifacts_directory": artifacts_directory,
             "version_input_file": version_input_file,
         }
+        if bump_package is not None:
+            self._values["bump_package"] = bump_package
+        if next_version_command is not None:
+            self._values["next_version_command"] = next_version_command
         if releasable_commits is not None:
             self._values["releasable_commits"] = releasable_commits
         if tag_prefix is not None:
@@ -10241,6 +10815,46 @@ class VersionOptions:
         assert result is not None, "Required property 'version_input_file' is missing"
         return typing.cast(builtins.str, result)
 
+    @builtins.property
+    def bump_package(self) -> typing.Optional[builtins.str]:
+        '''(experimental) The ``commit-and-tag-version`` compatible package used to bump the package version, as a dependency string.
+
+        This can be any compatible package version, including the deprecated ``standard-version@9``.
+
+        :default: "commit-and-tag-version@12"
+
+        :stability: experimental
+        '''
+        result = self._values.get("bump_package")
+        return typing.cast(typing.Optional[builtins.str], result)
+
+    @builtins.property
+    def next_version_command(self) -> typing.Optional[builtins.str]:
+        '''(experimental) A shell command to control the next version to release.
+
+        If present, this shell command will be run before the bump is executed, and
+        it determines what version to release. It will be executed in the following
+        environment:
+
+        - Working directory: the project directory.
+        - ``$VERSION``: the current version. Looks like ``1.2.3``.
+        - ``$LATEST_TAG``: the most recent tag. Looks like ``prefix-v1.2.3``, or may be unset.
+        - ``$SUGGESTED_BUMP``: the suggested bump action based on commits. One of ``major|minor|patch|none``.
+
+        The command should print one of the following to ``stdout``:
+
+        - Nothing: the next version number will be determined based on commit history.
+        - ``x.y.z``: the next version number will be ``x.y.z``.
+        - ``major|minor|patch``: the next version number will be the current version number
+          with the indicated component bumped.
+
+        :default: - The next version will be determined based on the commit history and project settings.
+
+        :stability: experimental
+        '''
+        result = self._values.get("next_version_command")
+        return typing.cast(typing.Optional[builtins.str], result)
+
     @builtins.property
     def releasable_commits(self) -> typing.Optional[ReleasableCommits]:
         '''(experimental) Find commits that should be considered releasable Used to decide if a release is required.
@@ -10589,7 +11203,7 @@ class YamlFile(ObjectFile, metaclass=jsii.JSIIMeta, jsii_type="projen.YamlFile")
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__e48f409d84ffd5e2a23ba998b62ea6bdf1343878ddf6bbdba39669e9e45b8464)
             check_type(argname="argument value", value=value, expected_type=type_hints["value"])
-        jsii.set(self, "lineWidth", value)
+        jsii.set(self, "lineWidth", value) # pyright: ignore[reportArgumentType]
 
 
 @jsii.data_type(
@@ -10771,6 +11385,217 @@ class YamlFileOptions(ObjectFileOptions):
         )
 
 
+class AiInstructions(
+    Component,
+    metaclass=jsii.JSIIMeta,
+    jsii_type="projen.AiInstructions",
+):
+    '''(experimental) Generates instruction files for AI coding assistants with projen-specific guidance.
+
+    This component creates configuration files that help AI tools like GitHub Copilot,
+    Cursor IDE, Claude Code, and Amazon Q understand that the project is managed by projen
+    and should follow projen conventions.
+
+    :stability: experimental
+
+    Example::
+
+        const project = new TypeScriptProject({
+          name: "my-project",
+          defaultReleaseBranch: "main",
+        });
+        
+        // Basic usage - generates files for all supported AI agents
+        new AiInstructions(project);
+        
+        // Custom usage - specify which agents and add custom instructions
+        new AiInstructions(project, {
+          agents: [AiAgent.GITHUB_COPILOT, AiAgent.CURSOR],
+          agentSpecificInstructions: {
+            [AiAgent.GITHUB_COPILOT]: ["Always use descriptive commit messages."],
+          },
+        });
+        
+        // Add more instructions after instantiation
+        const ai = new AiInstructions(project);
+        ai.addInstructions("Use functional programming patterns.");
+        ai.addInstructions("Always write comprehensive tests.");
+    '''
+
+    def __init__(
+        self,
+        project: Project,
+        *,
+        agents: typing.Optional[typing.Sequence[AiAgent]] = None,
+        agent_specific_instructions: typing.Optional[typing.Mapping[builtins.str, typing.Sequence[builtins.str]]] = None,
+        include_default_instructions: typing.Optional[builtins.bool] = None,
+        instructions: typing.Optional[typing.Sequence[builtins.str]] = None,
+    ) -> None:
+        '''
+        :param project: -
+        :param agents: (experimental) Which AI agents to generate instruction files for. Default: - All agents: [AiAgent.GITHUB_COPILOT, AiAgent.CURSOR, AiAgent.CLAUDE, AiAgent.AMAZON_Q, AiAgent.KIRO, AiAgent.CODEX]
+        :param agent_specific_instructions: (experimental) Per-agent custom instructions. Allows different instructions for different AI tools. Default: - no agent specific instructions
+        :param include_default_instructions: (experimental) Include default instructions for projen and general best practices. Default instructions will only be included for agents provided in the ``agents`` option. If ``agents`` is not provided, default instructions will be included for all agents. Default: true
+        :param instructions: (experimental) General instructions applicable to all agents. Default: - no agent specific instructions
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__6ade3e0209730c28511c6c65af7db0ef1d8f6d736618b1a95064af6bf4e829b8)
+            check_type(argname="argument project", value=project, expected_type=type_hints["project"])
+        options = AiInstructionsOptions(
+            agents=agents,
+            agent_specific_instructions=agent_specific_instructions,
+            include_default_instructions=include_default_instructions,
+            instructions=instructions,
+        )
+
+        jsii.create(self.__class__, self, [project, options])
+
+    @jsii.member(jsii_name="bestPractices")
+    @builtins.classmethod
+    def best_practices(cls, project: Project) -> builtins.str:
+        '''(experimental) Returns development best practices instructions for AI agents.
+
+        :param project: -
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__9b3a19a4e1f7d40bf00205a6394247af85d2428c672a0ecb7904470daaabda2f)
+            check_type(argname="argument project", value=project, expected_type=type_hints["project"])
+        return typing.cast(builtins.str, jsii.sinvoke(cls, "bestPractices", [project]))
+
+    @jsii.member(jsii_name="projen")
+    @builtins.classmethod
+    def projen(cls, project: Project) -> builtins.str:
+        '''(experimental) Returns projen-specific instructions for AI agents.
+
+        :param project: -
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__065453e2727d00b362bd1cf1f58d194d6c355b2a9c2f575e92c43eb627f6eb89)
+            check_type(argname="argument project", value=project, expected_type=type_hints["project"])
+        return typing.cast(builtins.str, jsii.sinvoke(cls, "projen", [project]))
+
+    @jsii.member(jsii_name="addAgentSpecificInstructions")
+    def add_agent_specific_instructions(
+        self,
+        agent: AiAgent,
+        *instructions: builtins.str,
+    ) -> None:
+        '''(experimental) Add instructions for a specific AI agent.
+
+        This can also be used to add instructions for an AI agent that was previously not enabled.
+
+        :param agent: The AI agent to add instructions for.
+        :param instructions: The instruction(s) to add.
+
+        :stability: experimental
+
+        Example::
+
+            aiInstructions.addAgentSpecificInstructions(AiAgent.GITHUB_COPILOT, "Use descriptive commit messages.");
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__9ff14bf0a463b0f887b122f5949af2eedda259c6426a05e006686653e81b8fc8)
+            check_type(argname="argument agent", value=agent, expected_type=type_hints["agent"])
+            check_type(argname="argument instructions", value=instructions, expected_type=typing.Tuple[type_hints["instructions"], ...]) # pyright: ignore [reportGeneralTypeIssues]
+        return typing.cast(None, jsii.invoke(self, "addAgentSpecificInstructions", [agent, *instructions]))
+
+    @jsii.member(jsii_name="addInstructions")
+    def add_instructions(self, *instructions: builtins.str) -> None:
+        '''(experimental) Adds instructions that will be included for all selected AI agents.
+
+        :param instructions: The instructions to add.
+
+        :stability: experimental
+
+        Example::
+
+            aiInstructions.addInstructions("Always use TypeScript strict mode.");
+            aiInstructions.addInstructions("Prefer functional programming.", "Avoid mutations.");
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__da44882109eef43fd7d698b3f301b9241d695eb97a717ffa73265862f39698ba)
+            check_type(argname="argument instructions", value=instructions, expected_type=typing.Tuple[type_hints["instructions"], ...]) # pyright: ignore [reportGeneralTypeIssues]
+        return typing.cast(None, jsii.invoke(self, "addInstructions", [*instructions]))
+
+
+class AiInstructionsFile(
+    FileBase,
+    metaclass=jsii.JSIIMeta,
+    jsii_type="projen.AiInstructionsFile",
+):
+    '''
+    :stability: experimental
+    '''
+
+    def __init__(
+        self,
+        scope: _constructs_77d1e7e8.IConstruct,
+        file_path: builtins.str,
+        *,
+        committed: typing.Optional[builtins.bool] = None,
+        edit_gitignore: typing.Optional[builtins.bool] = None,
+        executable: typing.Optional[builtins.bool] = None,
+        marker: typing.Optional[builtins.bool] = None,
+        readonly: typing.Optional[builtins.bool] = None,
+    ) -> None:
+        '''
+        :param scope: -
+        :param file_path: -
+        :param committed: (experimental) Indicates whether this file should be committed to git or ignored. By default, all generated files are committed and anti-tamper is used to protect against manual modifications. Default: true
+        :param edit_gitignore: (experimental) Update the project's .gitignore file. Default: true
+        :param executable: (experimental) Whether the generated file should be marked as executable. Default: false
+        :param marker: (experimental) Adds the projen marker to the file. Default: - marker will be included as long as the project is not ejected
+        :param readonly: (experimental) Whether the generated file should be readonly. Default: true
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__4b11da88a3895fa642ead3d82823bc49f77ad84be5d7816af5a52334434c5c79)
+            check_type(argname="argument scope", value=scope, expected_type=type_hints["scope"])
+            check_type(argname="argument file_path", value=file_path, expected_type=type_hints["file_path"])
+        options = FileBaseOptions(
+            committed=committed,
+            edit_gitignore=edit_gitignore,
+            executable=executable,
+            marker=marker,
+            readonly=readonly,
+        )
+
+        jsii.create(self.__class__, self, [scope, file_path, options])
+
+    @jsii.member(jsii_name="addInstructions")
+    def add_instructions(self, *instructions: builtins.str) -> None:
+        '''(experimental) Adds instructions to the instruction file.
+
+        :param instructions: -
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__da3f715a19bd0c18e2cc2d3bda06afae637174acbe15ef75ef39bb7c26f0ff90)
+            check_type(argname="argument instructions", value=instructions, expected_type=typing.Tuple[type_hints["instructions"], ...]) # pyright: ignore [reportGeneralTypeIssues]
+        return typing.cast(None, jsii.invoke(self, "addInstructions", [*instructions]))
+
+    @jsii.member(jsii_name="synthesizeContent")
+    def _synthesize_content(self, resolver: IResolver) -> typing.Optional[builtins.str]:
+        '''(experimental) Implemented by derived classes and returns the contents of the file to emit.
+
+        :param resolver: -
+
+        :stability: experimental
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__af1c3edb2730dd42712c19d9f2ebd48921303c4efd980f8910326afc111d82cc)
+            check_type(argname="argument resolver", value=resolver, expected_type=type_hints["resolver"])
+        return typing.cast(typing.Optional[builtins.str], jsii.invoke(self, "synthesizeContent", [resolver]))
+
+
 @jsii.data_type(
     jsii_type="projen.Dependency",
     jsii_struct_bases=[DependencyCoordinates],
@@ -11900,7 +12725,7 @@ class TaskStep(TaskStepOptions):
         :param cwd: (experimental) The working directory for this step. Default: - determined by the task
         :param env: (experimental) Defines environment variables for the execution of this step (``exec`` and ``builtin`` only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. ``$(echo "foo")``. Default: - no environment variables defined in step
         :param name: (experimental) Step name. Default: - no name
-        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
+        :param receive_args: (experimental) Should this step receive args passed to the task. If ``true``, args are passed through at the end of the ``exec`` shell command. The position of the args can be changed by including the marker ``$@`` inside the command string. If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion. If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect. Default: false
         :param builtin: (experimental) The name of a built-in task to execute. Built-in tasks are node.js programs baked into the projen module and as component runtime helpers. The name is a path relative to the projen lib/ directory (without the .task.js extension). For example, if your built in builtin task is under ``src/release/resolve-version.task.ts``, then this would be ``release/resolve-version``. Default: - do not execute a builtin task
         :param exec: (experimental) Shell command to execute. Default: - don't execute a shell command
         :param say: (experimental) Print a message. Default: - don't say anything
@@ -12029,6 +12854,9 @@ class TaskStep(TaskStepOptions):
         If ``true``, args are passed through at the end of the ``exec`` shell command.
         The position of the args can be changed by including the marker ``$@`` inside the command string.
 
+        If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating
+        the whitespace preserving behavior of bash variable expansion.
+
         If the step spawns a subtask, args are passed to the subtask.
         The subtask must define steps receiving args for this to have any effect.
 
@@ -12107,6 +12935,10 @@ class TaskStep(TaskStepOptions):
 
 
 __all__ = [
+    "AiAgent",
+    "AiInstructions",
+    "AiInstructionsFile",
+    "AiInstructionsOptions",
     "Component",
     "CreateProjectOptions",
     "Dependencies",
@@ -12129,9 +12961,11 @@ __all__ = [
     "DockerComposeServicePort",
     "DockerComposeVolumeConfig",
     "DockerComposeVolumeMount",
+    "EndOfLine",
     "FileBase",
     "FileBaseOptions",
     "GitAttributesFile",
+    "GitAttributesFileOptions",
     "GitOptions",
     "Gitpod",
     "GitpodOnOpen",
@@ -12143,6 +12977,7 @@ __all__ = [
     "GitpodPrebuilds",
     "GitpodTask",
     "GroupRunnerOptions",
+    "ICompareString",
     "IDevEnvironment",
     "IDockerComposeNetworkBinding",
     "IDockerComposeNetworkConfig",
@@ -12212,6 +13047,7 @@ __all__ = [
     "TomlFile",
     "TomlFileOptions",
     "Version",
+    "VersionBranchOptions",
     "VersionOptions",
     "XmlFile",
     "XmlFileOptions",
@@ -12253,6 +13089,16 @@ from . import typescript
 from . import vscode
 from . import web
 
+def _typecheckingstub__5bf7714efdf83cf2031e4ef3aa1d0cb9511cb921777751c76a0f501c0c56e247(
+    *,
+    agents: typing.Optional[typing.Sequence[AiAgent]] = None,
+    agent_specific_instructions: typing.Optional[typing.Mapping[builtins.str, typing.Sequence[builtins.str]]] = None,
+    include_default_instructions: typing.Optional[builtins.bool] = None,
+    instructions: typing.Optional[typing.Sequence[builtins.str]] = None,
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__e4ee40327ed6d04e3e377e300d915d402c50029248a86452fd19fd6372386d4b(
     scope: _constructs_77d1e7e8.IConstruct,
     id: typing.Optional[builtins.str] = None,
@@ -12305,6 +13151,14 @@ def _typecheckingstub__3683be12709967dd63dafbe536558d7717d255f3a86dfad1e17c19c9d
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__628e50591481575ad249671e7cf61edd1bb37d5aeab5e143a0783051e3167dcc(
+    name: builtins.str,
+    type: DependencyType,
+    expected_range: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__4260bbdc4d6b4d5249dbb539f6f4fe1f865c069d0179abe451af2807f194bf7d(
     name: builtins.str,
     type: typing.Optional[DependencyType] = None,
@@ -12583,6 +13437,8 @@ def _typecheckingstub__177d8a347651b29224d730dd6e1bbec48e6dd46e5dcfd4d25e3798e67
 
 def _typecheckingstub__a914753a9db7cc6bfa6a166cf7ee02794375210a09b1d8e2c62496abf14b4d21(
     scope: _constructs_77d1e7e8.IConstruct,
+    *,
+    end_of_line: typing.Optional[EndOfLine] = None,
 ) -> None:
     """Type checking stubs"""
     pass
@@ -12600,14 +13456,29 @@ def _typecheckingstub__ed3c05c2bc87434261501604cb4ca8386e08b16567b40f693170ab90f
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__573b65747d3cd070f990730baa2e2b06016818d32122c7fbc2696b8513582a7d(
+    glob: builtins.str,
+    *attributes: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__4d57ceb4d14bb3b3eac67478ac542d99ca5c6994286fdea034dacdf4b64fd14b(
     _: IResolver,
 ) -> None:
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__82a54cc3274f754056a1301deb3e7902a7a31057da6ade20b64dae8487831db5(
+    *,
+    end_of_line: typing.Optional[EndOfLine] = None,
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__ee7f1b3b819a95ebdb112752cdc122d5362da95c419decd69ec24018f344bace(
     *,
+    end_of_line: typing.Optional[EndOfLine] = None,
     lfs_patterns: typing.Optional[typing.Sequence[builtins.str]] = None,
 ) -> None:
     """Type checking stubs"""
@@ -12668,6 +13539,13 @@ def _typecheckingstub__a3547c7b706a8285f987ddb1847fd162ec961a77abbdd5059da647f1a
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__63d4f6e150362668f5e26d2f58f8b0a32cff82cf2eb8cb736d2c4333d0b01d09(
+    a: builtins.str,
+    b: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__c2360e8cae8e57d0e5268d03b1ee0bcf2a5d56c20a3ca26e5369ddc34c43f0ff(
     image: DevEnvironmentDockerImage,
 ) -> None:
@@ -13454,6 +14332,13 @@ def _typecheckingstub__866645d9e72b430281a892f9aec648a8a4d11dfd83393ea8d1cf161c6
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__f45a21d1f9e615dd1b225d6cafbe381a43b42811d1d21efd5a3f6630613e94af(
+    index: jsii.Number,
+    *steps: TaskStep,
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__72dcbc585fdab7a308274ba33cb7b5bcf9e106aaf01bef404fbb15b6c60db4c4(
     shell: builtins.str,
     *,
@@ -13616,6 +14501,7 @@ def _typecheckingstub__9f502dc8ce342b578300faffc5bd3c8c920c8565849215d7cec099d78
     name: builtins.str,
     parents: typing.Optional[typing.Sequence[builtins.str]] = None,
     args: typing.Optional[typing.Sequence[typing.Union[builtins.str, jsii.Number]]] = None,
+    env: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
 ) -> None:
     """Type checking stubs"""
     pass
@@ -13747,7 +14633,7 @@ def _typecheckingstub__ba0f4dd58b9e223b379bf709c046d112cede147b9481878f22a671a9d
     pass
 
 def _typecheckingstub__de7c08620aabeb578ce8c0c54b1073a9df1f34c7815d8ae6fdebff7eb411c3d8(
-    project: Project,
+    scope: _constructs_77d1e7e8.IConstruct,
     file_path: builtins.str,
     *,
     obj: typing.Any = None,
@@ -13781,10 +14667,12 @@ def _typecheckingstub__eab22f277a63768ddf4f6605743ad2816e10bd46ac73de98867b0f280
     pass
 
 def _typecheckingstub__9cf64d1b29258435f8a7749178e947fcedd27d55f323782081a21714be909595(
-    project: Project,
+    scope: _constructs_77d1e7e8.IConstruct,
     *,
     artifacts_directory: builtins.str,
     version_input_file: builtins.str,
+    bump_package: typing.Optional[builtins.str] = None,
+    next_version_command: typing.Optional[builtins.str] = None,
     releasable_commits: typing.Optional[ReleasableCommits] = None,
     tag_prefix: typing.Optional[builtins.str] = None,
     versionrc_options: typing.Optional[typing.Mapping[builtins.str, typing.Any]] = None,
@@ -13792,10 +14680,23 @@ def _typecheckingstub__9cf64d1b29258435f8a7749178e947fcedd27d55f323782081a21714b
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__62987907aa24cc1b84e9b6e9b755bd286708fa4a219baa7b979fb3ea61401603(
+    *,
+    major_version: typing.Optional[jsii.Number] = None,
+    min_major_version: typing.Optional[jsii.Number] = None,
+    minor_version: typing.Optional[jsii.Number] = None,
+    prerelease: typing.Optional[builtins.str] = None,
+    tag_prefix: typing.Optional[builtins.str] = None,
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__fb94d39bdc04d188bb2447acba8747de3d6ec275231c8a512d647916d69a54f5(
     *,
     artifacts_directory: builtins.str,
     version_input_file: builtins.str,
+    bump_package: typing.Optional[builtins.str] = None,
+    next_version_command: typing.Optional[builtins.str] = None,
     releasable_commits: typing.Optional[ReleasableCommits] = None,
     tag_prefix: typing.Optional[builtins.str] = None,
     versionrc_options: typing.Optional[typing.Mapping[builtins.str, typing.Any]] = None,
@@ -13879,6 +14780,67 @@ def _typecheckingstub__ca9e5a70f67f8e3db454227249c58dd5464be1446a55fcf3be780621f
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__6ade3e0209730c28511c6c65af7db0ef1d8f6d736618b1a95064af6bf4e829b8(
+    project: Project,
+    *,
+    agents: typing.Optional[typing.Sequence[AiAgent]] = None,
+    agent_specific_instructions: typing.Optional[typing.Mapping[builtins.str, typing.Sequence[builtins.str]]] = None,
+    include_default_instructions: typing.Optional[builtins.bool] = None,
+    instructions: typing.Optional[typing.Sequence[builtins.str]] = None,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__9b3a19a4e1f7d40bf00205a6394247af85d2428c672a0ecb7904470daaabda2f(
+    project: Project,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__065453e2727d00b362bd1cf1f58d194d6c355b2a9c2f575e92c43eb627f6eb89(
+    project: Project,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__9ff14bf0a463b0f887b122f5949af2eedda259c6426a05e006686653e81b8fc8(
+    agent: AiAgent,
+    *instructions: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__da44882109eef43fd7d698b3f301b9241d695eb97a717ffa73265862f39698ba(
+    *instructions: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__4b11da88a3895fa642ead3d82823bc49f77ad84be5d7816af5a52334434c5c79(
+    scope: _constructs_77d1e7e8.IConstruct,
+    file_path: builtins.str,
+    *,
+    committed: typing.Optional[builtins.bool] = None,
+    edit_gitignore: typing.Optional[builtins.bool] = None,
+    executable: typing.Optional[builtins.bool] = None,
+    marker: typing.Optional[builtins.bool] = None,
+    readonly: typing.Optional[builtins.bool] = None,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__da3f715a19bd0c18e2cc2d3bda06afae637174acbe15ef75ef39bb7c26f0ff90(
+    *instructions: builtins.str,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__af1c3edb2730dd42712c19d9f2ebd48921303c4efd980f8910326afc111d82cc(
+    resolver: IResolver,
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__d3a39137d5e4f9c51c84e6a659a0e0d16c23ba1927ed8fe7f3f96ecd5d0110dc(
     *,
     name: builtins.str,
@@ -14080,3 +15042,6 @@ def _typecheckingstub__6e32d65dbc737f8fd131c5593ecf206bcf2a76757ddb7c5f42945d730
 ) -> None:
     """Type checking stubs"""
     pass
+
+for cls in [ICompareString, IDevEnvironment, IDockerComposeNetworkBinding, IDockerComposeNetworkConfig, IDockerComposeServiceName, IDockerComposeVolumeBinding, IDockerComposeVolumeConfig, IResolvable, IResolver]:
+    typing.cast(typing.Any, cls).__protocol_attrs__ = typing.cast(typing.Any, cls).__protocol_attrs__ - set(['__jsii_proxy_class__', '__jsii_type__'])