---
name: Environment Templates
description: View and manage task templates for this environment. Use this when users want to create, update, or view templates that define reusable task patterns.
argument-hint: list | view <name> | update <name> | create <name>
---

# Environment Templates Skill

This skill allows you to help the user manage task templates for the environment this task is running in. Templates define reusable task patterns with pre-configured instructions and parameters.

**IMPORTANT**: This skill requires explicit user approval before making any changes. Always explain what changes you're proposing and ask the user to confirm before executing.

## Available Commands

### 1. List Templates (`/environment-templates list`)

List all available templates in the environment.

**When to use:**
- The user wants to see what templates exist
- You need to understand the template landscape before making changes

### 2. View Template (`/environment-templates view <name>`)

View a specific template's content and metadata.

**When to use:**
- The user wants to see a template's details
- You need to understand an existing template before proposing updates

### 3. Create Template (`/environment-templates create <name>`)

Create a new task template.

**When to use:**
- The user wants to create a reusable task pattern
- A common task type should be formalized as a template
- The user identifies a pattern worth capturing

### 4. Update Template (`/environment-templates update <name>`)

Update an existing template.

**When to use:**
- The user wants to improve an existing template
- Template instructions need refinement
- Template parameters need adjustment

### 5. Delete Template (`/environment-templates delete <name>`)

Remove a template from the environment.

**When to use:**
- A template is no longer needed
- The user explicitly requests deletion

## How It Works

This skill communicates with the CoderFlow server via the environment management API.

### Environment Variables (automatically set):
- `CODERFLOW_SERVER_URL` - The CoderFlow server URL for API calls
- `TASK_ID` - This task's ID (for authentication)

### API Endpoints:
- `GET /api/environment-management/templates` - List all templates
- `GET /api/environment-management/templates/:name` - Get specific template
- `PUT /api/environment-management/templates/:name` - Create or update template
- `DELETE /api/environment-management/templates/:name` - Delete template

## Template Structure

Templates consist of two files:
1. **`<name>.md`** - The template content (markdown with instructions)
2. **`<name>.json`** (optional) - Template metadata (description, parameters)

### Metadata JSON Structure
```json
{
  "description": "Brief description shown in template picker",
  "parameters": [
    {
      "name": "feature_name",
      "label": "Feature Name",
      "type": "string",
      "required": true
    }
  ]
}
```

### Template Content Syntax

**CRITICAL**: Template parameters must use `${parameter_name}` syntax (dollar sign + curly braces), NOT `{{parameter_name}}`.

CoderFlow's template rendering engine works in two passes:
1. **First pass**: Replaces `${variable}` with parameter values
2. **Second pass**: Processes EJS syntax (e.g., `<%= variable %>`)

**Correct syntax:**
```markdown
# Task: ${task_name}

Create a ${component_type} component with the following features:
- ${feature_description}
```

**Wrong syntax (will NOT work):**
```markdown
# Task: {{task_name}}  ❌ WRONG - parameters won't be substituted

Create a {{component_type}} component  ❌ WRONG
```

**Alternative (EJS syntax, also works):**
```markdown
# Task: <%= task_name %>

Create a <%= component_type %> component
```

## Usage Examples

### Listing Templates

```
User: "What templates are available?"

Agent: I'll list the available templates for this environment.

[Executes API call]

Available templates:
1. **bug-fix** - Template for fixing bugs
2. **feature-implementation** - Template for implementing new features
3. **refactor** - Template for code refactoring tasks

Would you like to view or modify any of these?
```

### Creating a Template

```
User: "Create a template for API endpoint tasks"

Agent: I'll help you create a new template. What should the template include?

User: "It should guide the agent to create RESTful endpoints with proper error handling and tests"

Agent: I'll create an "api-endpoint" template with the following content:

**Template Content (api-endpoint.md):**
```markdown
# API Endpoint Implementation

## Task
Implement a RESTful API endpoint with the following requirements:
- Follow RESTful conventions
- Include proper error handling
- Add input validation
- Write unit tests

## Parameters
- Endpoint path: ${endpoint_path}
- HTTP method: ${http_method}
- Description: ${description}
```

**Template Metadata (api-endpoint.json):**
```json
{
  "description": "Create a new API endpoint with tests",
  "parameters": [
    {"name": "endpoint_path", "label": "Endpoint Path", "type": "string", "required": true},
    {"name": "http_method", "label": "HTTP Method", "type": "string", "required": true},
    {"name": "description", "label": "Description", "type": "string", "required": false}
  ]
}
```

Would you like me to create this template? (Please confirm)

User: "Yes, create it"

Agent: [Executes API call]
Template "api-endpoint" created successfully!
```

## Implementation

### List Templates
```bash
curl -s "${CODERFLOW_SERVER_URL}/api/environment-management/templates" \
  -H "X-Task-Id: ${TASK_ID}"
```

**Response:**
```json
{
  "templates": [
    {"name": "bug-fix", "filename": "bug-fix.md", "description": "Fix a bug", "hasMetadata": true}
  ],
  "environment": "my-environment"
}
```

### Get Template
```bash
curl -s "${CODERFLOW_SERVER_URL}/api/environment-management/templates/bug-fix" \
  -H "X-Task-Id: ${TASK_ID}"
```

**Response:**
```json
{
  "name": "bug-fix",
  "content": "# Bug Fix Template\n\n...",
  "metadata": {"description": "Fix a bug", "parameters": []},
  "environment": "my-environment"
}
```

### Create/Update Template

**IMPORTANT**: When creating templates with parameters, always use a temporary file to avoid JSON array mangling in bash. Never embed complex JSON with arrays directly in `-d '{...}'`.

```bash
# Create a temporary file with the complete JSON payload
cat > /tmp/template-payload.json <<'EOF'
{
  "content": "# API Endpoint Implementation\n\n...",
  "metadata": {
    "description": "Create a new API endpoint",
    "parameters": [
      {"name": "endpoint_path", "label": "Endpoint Path", "type": "string", "required": true},
      {"name": "http_method", "label": "HTTP Method", "type": "string", "required": true},
      {"name": "description", "label": "Description", "type": "string", "required": false}
    ]
  }
}
EOF

# Use the temp file with curl
curl -s -X PUT "${CODERFLOW_SERVER_URL}/api/environment-management/templates/api-endpoint" \
  -H "Content-Type: application/json" \
  -H "X-Task-Id: ${TASK_ID}" \
  -d @/tmp/template-payload.json
```

**Alternative using heredoc directly:**
```bash
curl -s -X PUT "${CODERFLOW_SERVER_URL}/api/environment-management/templates/api-endpoint" \
  -H "Content-Type: application/json" \
  -H "X-Task-Id: ${TASK_ID}" \
  -d @- <<'EOF'
{
  "content": "# API Endpoint Implementation\n\n...",
  "metadata": {
    "description": "Create a new API endpoint",
    "parameters": [
      {"name": "endpoint_path", "label": "Endpoint Path", "type": "string", "required": true}
    ]
  }
}
EOF
```

### Delete Template
```bash
curl -s -X DELETE "${CODERFLOW_SERVER_URL}/api/environment-management/templates/old-template" \
  -H "X-Task-Id: ${TASK_ID}"
```

## Important Notes

1. **User Approval Required**: Never execute changes without explicit user confirmation
2. **Template Names**: Use lowercase letters, numbers, and hyphens only
3. **Preserve Existing**: When updating, consider preserving parts that are still relevant
4. **Document Parameters**: Clearly define what parameters a template accepts
5. **Test Templates**: Consider testing template content before finalizing
6. **Impact Awareness**: Remember that templates affect how future tasks are created
7. **JSON Payload Handling**: When creating templates with parameters, ALWAYS use a temp file (`cat > /tmp/file.json` + `-d @/tmp/file.json`) or heredoc (`-d @- <<'EOF'`). Never use inline `-d '{...}'` with complex nested JSON containing arrays, as bash shell escaping will corrupt the array structure and turn it into an object with numeric keys (0, 1, 2, 3 instead of proper array elements)
