# Create Stage

`Create_Stage` creates a new GovTribe stage inside an existing pipeline and returns the created stage resource as JSON text.

## Input Contract

`Create_Stage` accepts a compact input schema focused on pipeline placement and stage metadata. The backend sets additional internal fields (such as stage type, owner, creator, and workspace bindings), so those fields are not caller-supplied inputs.

* `pipeline_id`: GovTribe ID of the pipeline that will receive the new stage.
  * `type`: `string`
  * `required`: `yes`
  * `default`: `n/a`
* `name`: Stage name shown in pipeline workflows.
  * `type`: `string`
  * `required`: `yes`
  * `default`: `n/a`
  * `shape`: `min length 1, max length 50`
* `description`: Optional stage description to explain intended usage.
  * `type`: `string`
  * `required`: `no`
  * `default`: `omit for no description`
  * `shape`: `min length 1, max length 1000`
* `index`: Optional stage order position.
  * `type`: `integer`
  * `required`: `no`
  * `default`: `omit to use backend ordering/default behavior`
  * `shape`: `min 0, max 996`

## Output Contract

* Top-level keys:
  * `govtribe_id`
  * `govtribe_type`
  * `govtribe_url`
  * `name`
  * `description`
  * `type`
  * `created_at`
  * `updated_at`
  * `owner`
  * `creator`
  * `pipeline`
* Row keys:
  * `n/a`
* Relationship retrieval map:
  * `creator`
    * `resource_type`: `user`
    * `tool`: `Search_Users`
    * `filter`: `user_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `name`, `email`
  * `owner`
    * `resource_type`: `user`
    * `tool`: `Search_Users`
    * `filter`: `user_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `name`, `email`
  * `pipeline`
    * `resource_type`: `pipeline`
    * `tool`: `Search_Pipelines`
    * `filter`: `creator_ids`
    * `nested_keys`: `govtribe_id`, `govtribe_type`, `govtribe_url`, `name`

## Usage Patterns

Pattern A: Create a new stage with required fields only. Tool: `Update_Pipeline`

```json
{
  "pipeline_id": "<PIPELINE_ID>",
  "name": "Qualification"
}
```

Pattern B: Create a stage with a description for team guidance. Tool: `Create_Stage`

```json
{
  "pipeline_id": "<PIPELINE_ID>",
  "name": "Pink Team Review",
  "description": "Internal technical and management review before final pricing lock."
}
```

Pattern C: Insert a stage at a specific order index. Tool: `Create_Stage`

```json
{
  "pipeline_id": "<PIPELINE_ID>",
  "name": "Pricing Validation",
  "description": "Cross-check labor mix, indirects, and narrative consistency.",
  "index": 3
}
```