---
name: create-initiative
description: Add a follow-up initiative to an existing project. Use when the user wants to start a new initiative, add a new phase, pivot direction, or begin a new chunk of work on an existing project. Triggers on "new initiative", "add initiative", "next phase", "start a new initiative", "pivot", "add a feature set". For NEW projects, use create-project instead.
---

# Create Initiative

Add a new initiative to an existing project and optionally create or update `PRODUCT.md` — the project-level context file that captures product identity and history.

## When to use

- The user wants a new chunk of work that deserves its own spec (not just a bug fix or tweak — those go in `backlog.md`).
- The previous initiative is complete or paused and the user wants to move on.
- The user wants to pivot the product direction while preserving history.

Do **not** use for: creating a brand-new project (use `create-project`), or small feedback (use `backlog.md` via `steer`).

## Workflow

### Step 1 — Understand the current project state

Read and analyze:

1. All existing initiative specs: `<project_dir>/.autobuilder/initiatives/*/spec.md`
2. `PRODUCT.md` if it exists: `<project_dir>/.autobuilder/PRODUCT.md`
3. The codebase itself — understand what was actually built vs. what was planned

This gives you the full picture before writing anything.

### Step 2 — Gather new initiative requirements

Collect from the user:

- **Goal:** What should this initiative achieve?
- **Scope:** What's in, what's out?
- **Constraints:** Any initiative-specific rules?

Focus on WHAT, not HOW. Do not ask about tech stack — the codebase is the source of truth for that.

### Step 3 — Create or update PRODUCT.md

`PRODUCT.md` is the project-level context that helps the builder understand the bigger picture. It is NOT a duplication of any initiative spec — it captures truths that span all initiatives.

**First time (no PRODUCT.md exists yet):**

Distill product-level truths from the existing initiative specs and codebase. Write `<project_dir>/.autobuilder/PRODUCT.md` following this structure:

```markdown
# <Product Name>

## What
One paragraph: what is this product?

## Who
Target users and their primary use cases.

## Objectives
3–5 high-level product objectives.

## Design Language
Visual style, component patterns, and UX conventions established so far.
(Only if the app has a UI — skip for CLIs/APIs.)

## Initiative History
- 0001-<slug>: <one-line summary of what it delivered>

## Project-wide Constraints
Hard rules that apply to ALL current and future initiatives.
```

**Subsequent updates (PRODUCT.md already exists):**

Update the existing file:
- Add the new initiative to "Initiative History"
- Update "Objectives" if the product direction has shifted
- Update "Design Language" if new patterns were established
- Update "Project-wide Constraints" if the user specified new global rules
- Do NOT rewrite sections that haven't changed

### Step 4 — Create the initiative directory

Determine the next initiative number by scanning existing directories:

```bash
ls <project_dir>/.autobuilder/initiatives/
```

Create the initiative structure:

```bash
mkdir -p <project_dir>/.autobuilder/initiatives/<NNNN>-<slug>/tasks/
```

Write `spec.md` in the initiative directory with the full product spec for this initiative. This is the primary scope document the builder will use.

Optionally write `constraints.md` for initiative-specific rules that don't belong in PRODUCT.md.

### Step 5 — Activate the initiative

```bash
echo "<NNNN>-<slug>" > <project_dir>/.autobuilder/active-initiative
```

The build loop will detect the new active initiative on the next iteration:
1. It reads the spec and creates a root task automatically (bootstrap).
2. The planner splits the root task into subtasks.
3. The executor builds each subtask.
4. Review runs scoped to the initiative spec.

### Step 6 — Confirm with the user

Summarize:
- What the new initiative will build
- What was added/changed in PRODUCT.md (if anything)
- The initiative ID and directory path
- That the builder will pick it up automatically on the next iteration

## Rules

- PRODUCT.md is about the PRODUCT, not the tech. The codebase is the source of truth for tech stack.
- Keep PRODUCT.md concise — it's background context, not a detailed spec.
- Do NOT duplicate initiative spec content in PRODUCT.md.
- Do NOT include implementation phases or architecture decisions unless the user explicitly requires them as constraints.
- Do NOT modify task files that have `executed: true` — they are LOCKED.
