---
name: Objective Management
description: Manage the parent objective for this task. Update the objective's details or break it down into sub-objectives. When users ask about parent objectives, ALWAYS invoke this skill first to check - never assume whether a parent objective exists.
argument-hint: update | breakdown
---

# Objective Management Skill

This skill allows you to help the user manage the parent objective that this task was launched from.

**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.

## Proactive Plan Persistence

When you create a plan during this task — whether through a formal planning phase, research analysis, or by identifying a clear breakdown of work — you should **proactively offer to save that plan to the objective hierarchy** so it persists beyond this task session.

**When to offer:**
- You've created an implementation plan or architectural design
- You've identified a multi-step approach that would benefit from being tracked as sub-objectives
- Your research has produced findings that should refine the parent objective's instructions
- You've discovered the objective's scope needs adjustment based on what you learned

**How to offer:**
- After completing your plan, briefly explain that the plan can be saved to the parent objective
- Suggest the most appropriate form: updating the objective instructions (for refined scope/requirements) or creating sub-objectives (for a multi-step breakdown)
- Always get user approval before making changes

**Example:**
```
Agent: I've completed my analysis and have a plan with 4 implementation steps.
Before I proceed with implementation, would you like me to save this plan
to the parent objective? I can either:
1. Update the objective instructions with the refined approach
2. Create sub-objectives for each step so they can be launched independently

This way the plan persists even if this task is stopped or a new task
needs to continue the work.
```

## Available Commands

### 1. Update Parent Objective (`/objective update`)

Use this to help the user update the parent objective's details based on learnings from this task.

**When to use:**
- The user asks to update the parent objective
- Discoveries during this task suggest the objective needs refinement
- The scope or requirements have changed
- You've created a plan or completed research that should be captured in the objective for future task launches

**Process:**
1. Fetch the current objective details
2. Discuss proposed changes with the user
3. Only after user approval, submit the update

### 2. Create Sub-Objectives (`/objective breakdown`)

Use this to help the user break down the parent objective into smaller, more manageable sub-objectives.

**When to use:**
- The user wants to decompose a large objective
- The task reveals the objective is too broad
- Multiple distinct workstreams are identified
- You've created a multi-step plan where each step could be independently launched as its own task

**Process:**
1. Fetch the current objective details and existing children
2. Propose a breakdown structure to the user
3. Only after user approval, create the sub-objectives

## How It Works

This skill communicates with the CoderFlow server via the objective management API. The server URL and task credentials are automatically available in the container environment.

### Environment Variables (automatically set when task has parent objective):
- `SOURCE_OBJECTIVE_ID` - The ID of the parent objective
- `CODERFLOW_SERVER_URL` - The CoderFlow server URL for API calls
- `TASK_ID` - This task's ID (for authentication)
- `REFERENCE_OBJECTIVES_B64` - Base64 JSON snapshot of objective hierarchy context (names + IDs only)

### API Endpoints:
- `GET /api/objective-management/parent` - Fetch parent objective details
- `GET /api/objective-management/objective/:id` - Fetch details for any objective by ID
- `PATCH /api/objective-management/parent` - Update parent objective
- `POST /api/objective-management/sub-objectives` - Create sub-objectives
- `GET /api/objective-management/children` - List existing sub-objectives
- `GET /api/objective-management/siblings` - List sibling objectives

## Reference Objectives Context

When this task is launched from an objective, CoderFlow automatically appends an `Objective Context` section to `task-instructions.md` with a lightweight hierarchy snapshot:

- Current objective
- Ancestor chain (source objective up to root)
- Sibling objectives under the same parent
- Child objectives under the source objective

This snapshot includes objective names + IDs only (not full instructions), so orientation is immediate without extra API calls.

### Read Full Details for Any Objective

Use the read endpoint with an objective ID from the context:

```bash
curl -s "${CODERFLOW_SERVER_URL}/api/objective-management/objective/<ID>" \
  -H "X-Task-Id: ${TASK_ID}"
```

### Machine-Readable Context

The same snapshot is also available as:

- Environment variable: `REFERENCE_OBJECTIVES_B64`
- File: `/task-output/reference-objectives.json`

Decode example:

```bash
echo "$REFERENCE_OBJECTIVES_B64" | base64 --decode | jq .
```

JSON structure:

```json
{
  "sourceObjective": { "id": "1740000000-abc123", "name": "Implement user authentication" },
  "ancestors": [
    { "id": "1740000000-abc123", "name": "Implement user authentication" },
    { "id": "1739999000-def456", "name": "Build security features" },
    { "id": "1739998000-ghi789", "name": "Q1 2026 Product Roadmap" }
  ],
  "siblings": [
    { "id": "1740001000-jkl012", "name": "Implement rate limiting" }
  ],
  "children": [
    { "id": "1740003000-pqr678", "name": "OAuth2 integration" }
  ]
}
```

## Usage Examples

### Updating an Objective

```
User: "Update the parent objective to reflect that we also need to handle edge cases"

Agent: I'll help you update the parent objective. Let me first fetch the current details...

[Fetches objective]

Current objective:
- Name: "Implement user authentication"
- Instructions: "Add login and logout functionality"

I propose updating the instructions to:
"Add login and logout functionality, including edge case handling for:
- Invalid credentials
- Session expiration
- Concurrent login attempts"

Would you like me to apply this update? (Please confirm)

User: "Yes, apply it"

Agent: [Executes update via API]
Updated successfully!
```

### Breaking Down an Objective

```
User: "Break this objective into smaller tasks"

Agent: I'll help break down the parent objective. Let me fetch the details first...

[Fetches objective and existing children]

Current objective: "Build complete e-commerce checkout flow"
Existing sub-objectives: None

I propose breaking this into the following sub-objectives:

1. **Cart Management** - Implement add/remove items, quantity updates
2. **Payment Integration** - Integrate Stripe for payment processing
3. **Order Confirmation** - Create confirmation page and email notifications
4. **Shipping Calculation** - Implement shipping cost calculation

Would you like me to create these sub-objectives? (Please confirm)

User: "Yes, create them"

Agent: [Executes API calls to create sub-objectives]
Created 4 sub-objectives successfully!
```

## Implementation

The skill executes shell commands to interact with the CoderFlow API:

### Fetch Parent Objective Details
```bash
curl -s "${CODERFLOW_SERVER_URL}/api/objective-management/parent" \
  -H "X-Task-Id: ${TASK_ID}"
```

**Response:**
```json
{
  "taskId": "obj-xxx",
  "name": "Objective name",
  "status": "objective",
  "instructions": "Objective instructions...",
  "environment": "my-environment",
  "parentObjectiveId": null,
  "launchCount": 3
}
```

### Update Parent Objective
```bash
curl -s -X PATCH "${CODERFLOW_SERVER_URL}/api/objective-management/parent" \
  -H "Content-Type: application/json" \
  -H "X-Task-Id: ${TASK_ID}" \
  -d '{
    "name": "Updated objective name",
    "instructions": "Updated instructions..."
  }'
```

**Response:**
```json
{
  "success": true,
  "taskId": "obj-xxx",
  "name": "Updated objective name",
  "instructions": "Updated instructions...",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

### Create Sub-Objectives
```bash
curl -s -X POST "${CODERFLOW_SERVER_URL}/api/objective-management/sub-objectives" \
  -H "Content-Type: application/json" \
  -H "X-Task-Id: ${TASK_ID}" \
  -d '{
    "objectives": [
      {
        "name": "Sub-objective 1",
        "instructions": "Details for first sub-objective"
      },
      {
        "name": "Sub-objective 2",
        "instructions": "Details for second sub-objective"
      }
    ]
  }'
```

**Response:**
```json
{
  "success": true,
  "created": 2,
  "objectives": [
    {
      "taskId": "obj-yyy",
      "name": "Sub-objective 1",
      "instructions": "Details for first sub-objective",
      "parentObjectiveId": "obj-xxx",
      "sortOrder": 1000
    },
    {
      "taskId": "obj-zzz",
      "name": "Sub-objective 2",
      "instructions": "Details for second sub-objective",
      "parentObjectiveId": "obj-xxx",
      "sortOrder": 2000
    }
  ]
}
```

### List Existing Sub-Objectives (Children)
```bash
curl -s "${CODERFLOW_SERVER_URL}/api/objective-management/children" \
  -H "X-Task-Id: ${TASK_ID}"
```

**Response:**
```json
{
  "children": [
    {
      "taskId": "obj-yyy",
      "name": "Existing sub-objective",
      "sortOrder": 1000,
      "createdAt": "2024-01-14T09:00:00Z"
    }
  ],
  "parentObjectiveId": "obj-xxx"
}
```

### List Sibling Objectives
```bash
curl -s "${CODERFLOW_SERVER_URL}/api/objective-management/siblings" \
  -H "X-Task-Id: ${TASK_ID}"
```

## Important Notes

1. **User Approval Required**: Never execute updates or create sub-objectives without explicit user confirmation
2. **Explain Changes**: Always clearly explain what changes will be made before asking for approval
3. **Preserve Context**: When updating, preserve any existing context that's still relevant
4. **Check for Existing Children**: Before proposing a breakdown, always check for existing sub-objectives
5. **Atomic Operations**: Each sub-objective should be a self-contained unit of work
6. **Naming Conventions**: Use clear, descriptive names for sub-objectives
7. **Error Handling**: If an API call fails, explain the error to the user and suggest alternatives
