Ladder Init

Bootstrap .ladder/ directory structure with OVERVIEW.md and progress.md.

When to Use

• User says "ladder init," "initialize ladder," "set up specs," "bootstrap phases," or "/ladder-init"

• Starting phased spec-driven development on a new or existing project

• Run once per project

When NOT to Use

• .ladder/OVERVIEW.md already exists → will exit gracefully (idempotency gate)

• User wants to create a phase spec → use /ladder-create

• User wants to fix a malformed spec → use /ladder-refine

• User wants to implement a phase → use /ladder-execute

Quick Reference

Field Value

Input Project name, vision, tech stack, architecture (from user)

Output .ladder/OVERVIEW.md , .ladder/progress.md , .ladder/specs/ , .ladder/refs/

Commits chore(ladder): initialize project structure

Prerequisites None — this is the entry point

Iron Laws

• Specs are immutable after creation — only progress.md is a living document.

• Evidence before completion — never claim a step is done without proof.

• progress.md is the single source of truth for execution state.

• User approval before persistent actions — always confirm before writing files or committing.

Hard Gates

Workflow

Phase A: Validation

1. Idempotency Check

If .ladder/OVERVIEW.md already exists → STOP (see Hard Gate above).

2. Discover Existing Specs

Scan .ladder/specs/ for L-*.md files. Extract phase number and title from each filename. Store as the discovered phase list for the Phase Registry.

Phase B: Information Gathering

3. Gather Project Info

Ask the user one question at a time (use AskUserQuestion):

• Project name — short name for the product

• Vision — one-line product vision

• Tech stack — languages, frameworks, platforms

• Architecture — 2-3 sentence architecture summary

4. Map Reference Docs

If .ladder/refs/ contains files, list them and ask the user:

"Which phases does each reference doc relate to?"

Build a mapping table (document → relevant phase numbers).

5. Brownfield Detection

Ask: "Is this an existing project with prior work?"

If yes (brownfield):

• Scan project structure: key directories, package files, README, config files

• Ask user to summarize key components and known technical debt

• Build a Baseline section for progress.md (see references/progress-format.md )

If no (greenfield): skip baseline.

Phase C: Scaffold

6. Create Directory Structure

Create .ladder/specs/ and .ladder/refs/ if they don't already exist.

7. Write OVERVIEW.md

Create .ladder/OVERVIEW.md using this format:

<Name> — Product Overview

Vision

<one-line vision>

Tech Stack

• <items>

Architecture

<2-3 sentences>

Reference Docs

Phase Registry

8. Write progress.md

Create .ladder/progress.md :

Progress

If brownfield, add the Baseline section immediately after the heading. See references/progress-format.md for the Baseline format.

Phase D: Finalize

9. Commit

Stage .ladder/OVERVIEW.md and .ladder/progress.md only.

chore(ladder): initialize project structure

10. Summary

Print what was created and suggest:

"Run /ladder-refine <spec-path> to bring a spec to canonical format, or /ladder-create to add a new phase."

Common Mistakes

Mistake Why It Fails Fix

Writing files before gathering all user info Produces incomplete OVERVIEW.md, requires re-editing Collect all 4 answers first (Hard Gate)

Skipping brownfield detection Misses existing state, phases lack context Always ask about prior work

Ignoring existing specs in .ladder/specs/

Phase Registry is incomplete Scan for L-*.md files first

Creating progress.md with phase entries Only /ladder-execute adds phase entries Create with just # Progress heading

Red Flags — STOP

Thought Reality

"I'll create the files and fill in details later" All info must be gathered BEFORE file creation

"The user probably wants greenfield" Always ask — brownfield detection is mandatory

"I can skip the reference docs step" Missing mappings break phase context

"OVERVIEW.md exists but I'll overwrite it" Idempotency check is a HARD GATE — STOP

"I'll just use defaults for tech stack" Every field must come from the user

Integration

Direction Skill Signal

Enables /ladder-create

OVERVIEW.md exists with Phase Registry

Enables /ladder-refine

.ladder/specs/ directory exists

Required by All other Ladder skills OVERVIEW.md is the project root