lo-setup

LO Setup

Scaffolds the .lo/ directory convention in the current repository root. Creates the project identity, backlog, stream, and directory structure that all other LO skills depend on.

When to Use

• User invokes /lo:setup
• User says "setup lo", "new lo project", "scaffold lo", "add lo to this repo"
• A repo needs LO project tracking added for the first time

Critical Rules

• Check for an existing .lo/ directory FIRST. If one exists, warn the user and ask for explicit confirmation before overwriting. Do not silently replace project data.
• project.yml is pure YAML — no frontmatter delimiters (---), no markdown body.
• Always generate a fresh proj_ UUID for new projects. Never reuse an existing ID.
• Consult references/project-yml-format.md for the authoritative format spec.

Flow

### Step 1: Check for Existing .lo/

Before creating anything, check if .lo/ exists at the repo root.

If it exists:

A .lo/ directory already exists in this repo.
Overwriting will replace project.yml, BACKLOG.md, and STREAM.md.

Proceed? (yes / no)

HARD GATE: Do not continue unless the user explicitly confirms. If they say no, stop.

Also check if this is a git repo:

git rev-parse --is-inside-work-tree 2>/dev/null

If not a git repo, warn but proceed:

This directory is not a git repository. LO will work, but GitHub automation
(Step 8) will be skipped. Consider running git init first.

Step 2: Gather Project Metadata

Ask the user for four values:

Title — project name (e.g., "Nexus", "Platform"). If README.md or package.json exists, suggest a value from those.

Description — one-sentence description of what this project does. Suggest from README or package.json if available.

Status (default: explore):

• explore — Vibing on an idea. Minimal ceremony.
• build — Committed to production-ready software. Full CI/CD.
• open — Multi-tenant ready. Public-facing polish.
• closed — No longer active.

State (default: private):

• public — Publicly visible
• private — Internal only

Step 3: Generate project.yml

Generate a project ID:

echo "proj_$(uuidgen | tr '[:upper:]' '[:lower:]')"

Write .lo/project.yml — pure YAML, five fields, no extras. See references/project-yml-format.md for the format contract.

id: "proj_[generated-uuid]"
title: "[title from Step 2]"
description: "[description from Step 2]"
status: "[status from Step 2]"
state: "[state from Step 2]"

Step 4: Create Directory Structure

mkdir -p .lo/park .lo/work .lo/solutions

The full structure after setup:

.lo/
  project.yml
  BACKLOG.md
  STREAM.md
  park/           ← conversation captures (/lo:park)
  work/           ← active plans and execution (/lo:plan, /lo:work)
  solutions/      ← reusable knowledge (/lo:solution)

No .lo/research/ directory — research happens in conversation, not files.

Step 5: Create BACKLOG.md

Write .lo/BACKLOG.md with frontmatter counters for safe ID allocation:

---
updated: YYYY-MM-DD
last_feature: 0
last_task: 0
---

## Features

## Tasks

Use today's date for updated. The last_feature and last_task counters start at 0 and are incremented by /lo:park, /lo:plan, and /lo:work when creating new items. These counters prevent ID collisions when done items are pruned from the backlog.

Step 6: Create STREAM.md

Write .lo/STREAM.md with type frontmatter:

---
type: stream
---

Stream entries are added later via /lo:stream or during /lo:ship release mode.

### Step 7: Scan for TODOs (Optional)

Ask the user:

Scan the repo for TODO/FIXME/HACK comments and add them to the backlog? (yes / no)

If yes:

1. Search the codebase for TODO, FIXME, HACK comments
2. Present findings to the user for review
3. For each approved item, add as a task entry in BACKLOG.md
4. Increment last_task in frontmatter for each added item
5. Update the updated date

If no, skip.

### Step 8: Reconcile GitHub Automation (Optional)

Skip this step if the repo has no git remote or is not a git repo.

If a remote exists, check for the sync script:

"$(git rev-parse --show-toplevel)/scripts/lo-github-sync.sh" --fix

If the script exists, run it. For explore projects this creates minimal CI config. For build or open projects it sets up full automation.

If the script doesn't exist:

GitHub sync script not found at scripts/lo-github-sync.sh.
Skipping automation setup. You can configure CI/CD manually or add the script later.

Step 9: Write .gitkeep Files and Report

Write empty .gitkeep files in directories that start empty:

• .lo/park/.gitkeep
• .lo/work/.gitkeep
• .lo/solutions/.gitkeep

Report what was created:

.lo/ directory created:

  project.yml
    id: proj_[generated]
    title: [title]
    description: [description]
    status: [status]
    state: [state]

  BACKLOG.md         (empty, counters at 0)
  STREAM.md          (empty)
  park/              conversation captures
  work/              plans and execution
  solutions/         reusable knowledge

  GitHub automation: [applied / skipped (no remote) / skipped (script not found)]

Next steps:
  /lo:park         — capture an idea
  /lo:plan         — design a feature
  /lo:work         — start building
  /lo:status       — view project dashboard

Error Handling

• .lo/ already exists → warn and require explicit confirmation (Step 1)
• Not a git repo → warn but proceed; skip Step 8
• uuidgen not available → fall back to generating a UUID via other means
• Sync script missing → skip with informative message (Step 8)
• Sync script fails → report the error, continue (setup is still valid without automation)

Validation

Before reporting, verify:

• .lo/project.yml exists with valid YAML and all five required fields
• status is one of: explore, build, open, closed
• state is one of: public, private
• id is first field in project.yml, format: proj_ + lowercase UUID v4
• .lo/BACKLOG.md exists with frontmatter counters
• .lo/STREAM.md exists with type: stream frontmatter
• All three subdirectories exist: park/, work/, solutions/
• .gitkeep files exist in all three subdirectories

User: /lo:setup

Checking for existing .lo/ directory... none found.

What's the project title?

User: Nexus

One-sentence description?

User: A coordination server for multi-agent engineering teams.

Status (explore/build/open/closed)? Default: explore

User: explore

State (public/private)? Default: private

User: public

.lo/ directory created:

project.yml id: proj_a8f23bc1-4d91-4e7a-b392-1f8c5e6d9a04 title: Nexus description: A coordination server for multi-agent engineering teams. status: explore state: public

BACKLOG.md (empty, counters at 0) STREAM.md (empty) park/ conversation captures work/ plans and execution solutions/ reusable knowledge

GitHub automation: applied (explore — dormant CI)

Next steps: /lo:park — capture an idea /lo:plan — design a feature /lo:work — start building /lo:status — view project dashboard