# CodePipelineStepDefinition

A step of a code pipeline phase: one prompt to one agent.

**Kind:** an object, used in requests and responses. In a request it is called `CodePipelineStepDefinitionInput`.

## In a request

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` |  | The step's name, unique within its phase. |
| `agentName` | `string` |  | The agent that runs the step. When set, `targetRole` and `targetTags` are ignored; when empty, the step runs on an agent matching them. |
| `targetRole` | [`CodePipelineAgentRole`](https://docs.maitento.com/reference/types/code-pipeline-agent-role.md)`\| null` |  | Instead of naming an agent, run on any agent with this role. Chosen when the run starts; parallel steps that name the same role are spread across different agents where there are enough. |
| `targetTags` | `string[] \| null` |  | Instead of naming an agent, run on any agent carrying at least one of these tags (ignoring case). With `targetRole` as well, the agent must match both. |
| `prompt` | `string` |  | The step's prompt. It can use the same template syntax as interactions: `%%input:name%%` for a run input, `%%name%%` for a variable, `{{if}}` and `{{unless}}` blocks, and `@prompt(name)`, replaced with a prompt file when you deploy. |
| `dependsOn` | `string[] \| null` |  | Other steps in the same phase that must finish before this one starts. One agent's steps always run in their listed order without it. |
| `isCommitable` | `boolean` |  | Whether the agent's code changes are committed when the step finishes. |
| `commitRepoName` | `string \| null` |  | For a run with several repositories, the `name` of the one this step commits to. Null: the first repository. |
| `isStructuredOutput` | `boolean` |  | Whether to ask the agent, after the step, for a structured summary of how it went (recorded as the step's `outputStructured`). |
| `outputJsonSchema` | `string \| null` |  | A JSON schema the step's final result must match. Output that doesn't match is repaired where possible. |
| `isOutputSchemaRequired` | `boolean` |  | Whether the step fails when its result can't be made to match `outputJsonSchema`. |
| `outputVariableName` | `string \| null` |  | A variable to store the step's final result in, so later step prompts (`%%name%%`) and hooks can use it. |
| `outputFileName` | `string \| null` |  | A file name to write the step's output to, in the run's `output_files/` folder. |
| `preHook` | `string \| null` |  | The name of a hook (a Cogniscript method in the pipeline's hooks) to run before the step. |
| `postHook` | `string \| null` |  | The name of a hook to run after the step finishes. |
| `onFailHook` | `string \| null` |  | The name of a hook to run when the step fails. It returns JSON with a `decision`: `"continue"` marks the step skipped and carries on, `"retry"` runs the step again, and `"fail"` fails it as usual. |
| `isNewSession` | `boolean` |  | Whether the agent starts a fresh session for this step instead of continuing from its previous step. Use it for independent pieces of work, where earlier context would only confuse. Default `false`. |
| `runChallengeLoop` | `boolean` |  | Whether, after the step succeeds, the same agent is asked whether its work is really built and tested, and is sent its open concerns back until it says it is done or `maxCheckLoops` rounds have run. Each round is recorded in the step's `challengeLoopTurns`. |
| `durationWarning` | `timespan \| null` |  | Not used by code pipeline runs. |
| `durationAutoTermination` | `timespan \| null` |  | The longest the step may run before it is stopped. Null: the phase's value, then the pipeline's, applies. |
| `durationActivityTimeout` | `timespan \| null` |  | How long the step may go without activity before it is stopped. Null: the phase's value, then the pipeline's, applies. |

```json
{
  "name": "...",
  "agentName": "...",
  "targetRole": "Architect",
  "targetTags": [
    "..."
  ],
  "prompt": "...",
  "dependsOn": [
    "..."
  ],
  "isCommitable": false,
  "commitRepoName": "...",
  "isStructuredOutput": false,
  "outputJsonSchema": "...",
  "isOutputSchemaRequired": false,
  "outputVariableName": "...",
  "outputFileName": "...",
  "preHook": "...",
  "postHook": "...",
  "onFailHook": "...",
  "isNewSession": false,
  "runChallengeLoop": false,
  "durationWarning": "00:05:00",
  "durationAutoTermination": "00:05:00",
  "durationActivityTimeout": "00:05:00"
}
```

## In a response

Every field is present in a response; empty ones are `null`.

| Field | Type | Description |
|---|---|---|
| `name` | `string` | The step's name, unique within its phase. |
| `agentName` | `string` | The agent that runs the step. When set, `targetRole` and `targetTags` are ignored; when empty, the step runs on an agent matching them. |
| `targetRole` | [`CodePipelineAgentRole`](https://docs.maitento.com/reference/types/code-pipeline-agent-role.md)`\| null` | Instead of naming an agent, run on any agent with this role. Chosen when the run starts; parallel steps that name the same role are spread across different agents where there are enough. |
| `targetTags` | `string[] \| null` | Instead of naming an agent, run on any agent carrying at least one of these tags (ignoring case). With `targetRole` as well, the agent must match both. |
| `prompt` | `string` | The step's prompt. It can use the same template syntax as interactions: `%%input:name%%` for a run input, `%%name%%` for a variable, `{{if}}` and `{{unless}}` blocks, and `@prompt(name)`, replaced with a prompt file when you deploy. |
| `dependsOn` | `string[] \| null` | Other steps in the same phase that must finish before this one starts. One agent's steps always run in their listed order without it. |
| `isCommitable` | `boolean` | Whether the agent's code changes are committed when the step finishes. |
| `commitRepoName` | `string \| null` | For a run with several repositories, the `name` of the one this step commits to. Null: the first repository. |
| `isStructuredOutput` | `boolean` | Whether to ask the agent, after the step, for a structured summary of how it went (recorded as the step's `outputStructured`). |
| `outputJsonSchema` | `string \| null` | A JSON schema the step's final result must match. Output that doesn't match is repaired where possible. |
| `isOutputSchemaRequired` | `boolean` | Whether the step fails when its result can't be made to match `outputJsonSchema`. |
| `outputVariableName` | `string \| null` | A variable to store the step's final result in, so later step prompts (`%%name%%`) and hooks can use it. |
| `outputFileName` | `string \| null` | A file name to write the step's output to, in the run's `output_files/` folder. |
| `preHook` | `string \| null` | The name of a hook (a Cogniscript method in the pipeline's hooks) to run before the step. |
| `postHook` | `string \| null` | The name of a hook to run after the step finishes. |
| `onFailHook` | `string \| null` | The name of a hook to run when the step fails. It returns JSON with a `decision`: `"continue"` marks the step skipped and carries on, `"retry"` runs the step again, and `"fail"` fails it as usual. |
| `isNewSession` | `boolean` | Whether the agent starts a fresh session for this step instead of continuing from its previous step. Use it for independent pieces of work, where earlier context would only confuse. Default `false`. |
| `runChallengeLoop` | `boolean` | Whether, after the step succeeds, the same agent is asked whether its work is really built and tested, and is sent its open concerns back until it says it is done or `maxCheckLoops` rounds have run. Each round is recorded in the step's `challengeLoopTurns`. |
| `durationWarning` | `timespan \| null` | Not used by code pipeline runs. |
| `durationAutoTermination` | `timespan \| null` | The longest the step may run before it is stopped. Null: the phase's value, then the pipeline's, applies. |
| `durationActivityTimeout` | `timespan \| null` | How long the step may go without activity before it is stopped. Null: the phase's value, then the pipeline's, applies. |

```json
{
  "name": "...",
  "agentName": "...",
  "targetRole": "Architect",
  "targetTags": [
    "..."
  ],
  "prompt": "...",
  "dependsOn": [
    "..."
  ],
  "isCommitable": false,
  "commitRepoName": "...",
  "isStructuredOutput": false,
  "outputJsonSchema": "...",
  "isOutputSchemaRequired": false,
  "outputVariableName": "...",
  "outputFileName": "...",
  "preHook": "...",
  "postHook": "...",
  "onFailHook": "...",
  "isNewSession": false,
  "runChallengeLoop": false,
  "durationWarning": "00:05:00",
  "durationAutoTermination": "00:05:00",
  "durationActivityTimeout": "00:05:00"
}
```

## Where it's used

- Inside [`CodePipelinePhaseDefinition`](https://docs.maitento.com/reference/types/code-pipeline-phase-definition.md)
- Inside [`CodePipelineProcessAdditionalSteps`](https://docs.maitento.com/reference/types/code-pipeline-process-additional-steps.md)