---
description: Create a structured objective through guided conversation
---

# /erk:objective-create

Create a new objective through an interactive, guided process. You describe what you want to accomplish, and Claude proposes a structured objective for your approval.

## Usage

```bash
/erk:objective-create
```

---

## Agent Instructions

### Step 1: Prompt for Description

Ask the user to describe what they want to accomplish:

```
What do you want to accomplish? Describe it however makes sense to you - goals,
constraints, design decisions you've already made, context about the codebase, etc.

I'll structure it into a formal objective for your review.
```

Wait for the user's response. They may provide:

- A brief summary
- A detailed brain dump
- Existing notes or documentation
- A combination of the above

### Step 2: Analyze and Explore

Based on the user's description:

1. **Identify key elements:**
   - What is the transformation/goal?
   - What design decisions are mentioned or implied?
   - What constraints exist?
   - What's the scope?

2. **Explore the codebase if needed:**
   - If the user references specific code, read it to understand context
   - If architecture decisions are mentioned, verify current state
   - Gather enough context to propose realistic phases

3. **Capture context for downstream implementers:**

   During objective creation, you gather valuable context that would otherwise be lost: web searches, codebase exploration, user feedback, and your reasoning. **This context belongs in the objective issue.**

   Ask yourself: "What would a future agent (or human) implementing this need to know?"

   Examples of valuable context:
   - **Inventories**: Grep results showing all instances of a pattern, categorized by type
   - **Root cause analysis**: Why the current state exists, what caused the problem
   - **Codebase findings**: Relevant files, existing patterns, architectural constraints
   - **External research**: API docs, library behavior, migration guides discovered via web search
   - **Design rationale**: Why certain approaches were chosen or rejected
   - **User preferences**: Feedback and decisions made during the conversation

   This context goes in a dedicated section after the Roadmap (see template below)

### Step 3: Ask for Structure Preference

After understanding the user's goals, present structure options using AskUserQuestion:

```
How would you like the objective structured?
```

**Options:**

1. **Steelthread (Recommended)** - Phase 1 is a minimal vertical slice proving the concept works end-to-end, followed by Phase 2 to complete the feature. Best when you can demonstrate value with a partial implementation.
2. **Linear** - Sequential phases, each building on the previous. Good when infrastructure must exist before any use case works (e.g., database schema before queries).
3. **Single** - One phase, one PR. For small, focused objectives that don't need phasing.
4. **Custom** - User describes their preferred structure

**Selection guidelines:**

- **Steelthread**: Default choice. Use when feasible - it de-risks the approach early by proving the concept works.
- **Linear**: Use when a steelthread doesn't make sense - e.g., building a new abstraction layer that has no value until complete.
- **Single**: Use for objectives small enough to implement in one PR (typically 1-2 days of work).
- **Custom**: Use when the user has a specific structure in mind.

### Step 4: Propose Structured Objective

Write a structured objective proposal and show it to the user. Use the appropriate template based on their structure choice:

**Generating the Roadmap Section**

Do NOT manually write roadmap tables or metadata blocks. Instead, construct a JSON object describing the phases and steps, then generate the complete roadmap section:

```bash
echo '<json>' | erk exec objective-render-roadmap
```

This outputs a complete `## Roadmap` section with phase headers, tables, test sections, and a machine-readable metadata block (auto-generated, guaranteed consistent with tables). Include the command's output directly in the objective body.

**JSON input format:** Each phase needs `name` (string) and `steps` (list of `{"id": "...", "description": "..."}`). Optional fields: `description` (phase description), `pr_count` (defaults to "1 PR"), `test` (acceptance test description). Each step can optionally include `"slug": "kebab-case-slug"` — if omitted, a slug is auto-generated from the description.

#### Steelthread Template (Recommended)

The objective body follows this structure. The `## Roadmap` section is generated by `erk exec objective-render-roadmap`.

```markdown
# Objective: [Clear, Concise Title]

[1-2 sentence summary of the transformation]

## Goal

[What the end state looks like - concrete examples of the new API/behavior/architecture]

## Design Decisions

- **[Decision 1]**: [rationale]
- **[Decision 2]**: [rationale]

## Roadmap

[INSERT OUTPUT from: echo '<json>' | erk exec objective-render-roadmap]

## Implementation Context

[Current architecture, target architecture, patterns to follow - include if helpful]

## Exploration Notes

[Context gathered during objective creation that implementers will need]

## Related Documentation

- Skills to load: [relevant skills]
- Docs to reference: [relevant docs]
```

**Steelthread JSON example:**

```json
{
  "phases": [
    {
      "name": "[Name] Steelthread",
      "description": "Minimal vertical slice proving the concept works end-to-end.",
      "steps": [
        { "id": "1.1", "description": "[Minimal infrastructure]" },
        { "id": "1.2", "description": "[Wire into one command/path]" }
      ],
      "test": "[End-to-end acceptance test for steelthread]"
    },
    {
      "name": "Complete [Name]",
      "description": "Fill out remaining functionality.",
      "steps": [
        { "id": "2.1", "description": "[Extend to remaining commands]" },
        { "id": "2.2", "description": "[Full test coverage]" }
      ],
      "test": "[Full acceptance criteria]"
    }
  ]
}
```

#### Linear Template

Same body structure as Steelthread. Use this JSON pattern for the roadmap:

```json
{
  "phases": [
    {
      "name": "[Foundation]",
      "description": "[Infrastructure needed by subsequent phases]",
      "steps": [{ "id": "1.1", "description": "..." }],
      "test": "[Verification criteria]"
    },
    {
      "name": "[Build on Foundation]",
      "description": "[Uses Phase 1 infrastructure]",
      "steps": [{ "id": "2.1", "description": "..." }],
      "test": "[Verification criteria]"
    }
  ]
}
```

#### Single Template

Same body structure with one phase:

```json
{
  "phases": [
    {
      "name": "[Implementation]",
      "steps": [
        { "id": "1", "description": "..." },
        { "id": "2", "description": "..." }
      ],
      "test": "[Acceptance criteria]"
    }
  ]
}
```

**Key structuring principles:**

1. **One PR per phase**: Each phase should be a self-contained PR that:
   - Has a coherent, reviewable scope
   - Includes its own tests (unit + integration as appropriate)
   - Leaves the system in a working state when merged

2. **Always shippable**: After each merged PR, the system must remain functional. Never leave the codebase in a broken state between phases.

3. **Test per phase**: Every phase needs a **Test:** section describing acceptance criteria. This becomes the definition of "done" for that PR.

**Section guidelines:**

- **Goal**: Always include - this is the north star
- **Design Decisions**: Include if there are meaningful choices already made
- **Roadmap**: Include for bounded objectives - break into shippable phases (1 PR each typically)
- **Principles/Guidelines**: Include for perpetual objectives instead of a roadmap
- **Implementation Context**: Include for larger refactors where current/target state matters
- **Exploration Notes**: Include when you gathered valuable context during creation (inventories, research, reasoning). This is often the most valuable section for implementers
- **Related Documentation**: Include if specific skills or docs are relevant

**For perpetual objectives**, replace the Roadmap section with:

```markdown
## Principles

- [Guiding principle 1]
- [Guiding principle 2]
```

After showing the proposal, ask:

```
Does this capture what you're thinking? I can adjust any section, add more detail
to the roadmap, or restructure the phases.
```

### Step 5: Iterate Until Approved

The user may:

- **Approve as-is**: Proceed to Step 6
- **Request changes**: Make the requested adjustments and show again
- **Add information**: Incorporate new details and show again
- **Restructure**: Reorganize phases/nodes based on feedback

Continue iterating until the user approves.

### Step 6: Write to Plan File and Create Objective

Once approved:

1. **Write the objective to scratch storage:**

   ```bash
   mkdir -p .erk/scratch/sessions/${CLAUDE_SESSION_ID}/
   ```

   Write the approved objective content to:

   ```
   .erk/scratch/sessions/${CLAUDE_SESSION_ID}/objective-body.md
   ```

   This is the Priority 1 lookup path for `objective-save-to-issue --session-id`.

2. **Generate a slug** from the objective content:
   - Create a concise, descriptive slug (3-5 words, kebab-case) that captures the essence of the objective
   - **Pattern:** `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
   - **Length:** 3-40 characters
   - **Rules:** lowercase only, must start with a letter, hyphens between words only, no consecutive hyphens, no underscores/spaces/dots
   - **Valid:** `build-auth-system`, `refactor-gateway`, `add-dark-mode`, `fix-tui-layout`
   - **Invalid:** `Build-Auth` (uppercase), `123-start` (starts with digit), `my--slug` (consecutive hyphens), `ab` (too short)
   - If the backend rejects the slug, fix it according to the rules above and retry

3. **Create the objective with validation:**

   ```bash
   erk exec objective-save-to-issue --session-id=<session-id> --slug=<generated-slug> --format=display --validate
   ```

   This creates the objective and validates the roadmap in one step.
   If validation fails, fix the objective content and re-run.

4. **Report success:**

   ```
   Objective #<number> created
   URL: <issue-url>
   Roadmap validation: clean

   Next steps:
   - Use /local:objective-view <number> to view the dependency graph
   - Use /erk:objective-plan <number> to create plans for specific nodes
   - Track progress by updating node status in the issue
   ```

---

## Output Format

- **Start**: Single prompt asking what they want to accomplish
- **After description**: Ask for structure preference
- **After structure choice**: Show proposed structured objective
- **Iteration**: Show updated objective after each change
- **Success**: Issue number, URL, and next steps

---

## Differences from /erk:plan-save

| Feature          | /erk:plan-save      | /erk:objective-create           |
| ---------------- | ------------------- | ------------------------------- |
| Label            | `erk-plan`          | `erk-objective` only            |
| Purpose          | Implementation plan | Roadmap or perpetual focus area |
| Title prefix     | `[erk-plan]`        | None                            |
| Metadata block   | Yes                 | No                              |
| Commands section | Yes                 | No                              |
| Body content     | Metadata only       | Objective directly              |
| Input            | Existing plan file  | Interactive creation            |

---

## Types of Objectives

**Bounded objectives** - Have a clear end state and roadmap:

- "Refactor GitHub gateway into facade pattern"
- "Add dark mode support"

**Perpetual objectives** - Ongoing areas of focus without a defined end:

- "Improve test coverage"
- "Documentation maintenance"
- "Performance optimization"

The structure adapts to the type - perpetual objectives may have principles/guidelines instead of a phased roadmap.

---

## Error Cases

| Scenario                     | Action                           |
| ---------------------------- | -------------------------------- |
| User provides no description | Re-prompt with examples          |
| Not authenticated            | Report GitHub auth error         |
| Issue creation fails         | Report API error, offer to retry |
| Plan file write fails        | Report error with path           |
