lp88

lp88 stands for Launchpad-88.

Launchpad-88 is a small npm CLI that installs a repeatable AI-agent workflow into any project.

It creates project instructions, reusable prompts, local skills, scripts, and CI guardrails so your configured agent starts with the same rules instead of rediscovering them.

Why it exists

Launchpad-88 does not replace your AI agent. It installs the project instructions and guardrails that Codex, Claude, Gemini, OpenCode, Ralphy, or another configured CLI should use.

• lp88 plan prints an agent-ready planning prompt.
• lp88 audit runs deterministic local checks.
• skills/code-structure/SKILL.md guides where logic belongs.
• opensrc is optional for fetching dependency source when package internals matter.
• Superpowers is optional for stronger agent-side brainstorming, TDD, review, and subagent workflows.
• Greploop is for bounded PR review and CI fix loops.
• Ralphy is optional and should only be used after a clear PRD or issue exists.

Install

Run without installing:

npx lp88 init

During interactive init, lp88 offers to install optional external tools:

• opensrc, from https://github.com/vercel-labs/opensrc
• ralphy-cli, from https://github.com/michaelshimeles/ralphy
• Superpowers setup for detected agent CLIs, from https://github.com/obra/superpowers

If supported AI CLIs are detected, lp88 also offers to save:

• a default lp88 planning agent in .lp88/config.env
• a default Ralphy engine in .ralphy/lp88.env

Skip those prompts with:

npx lp88 init --no-optional-installs

Or install globally:

npm install -g lp88
lp88 --version

Usage

npx lp88 init
lp88 doctor
lp88 plan "Improve onboarding flow"
lp88 plan --run --agent codex "Improve onboarding flow"
lp88 implement
lp88 status
lp88 verify
lp88 deps status
lp88 upgrade-plan
lp88 audit
lp88 superpowers

For local development:

npm link
lp88 --help

Commands

npx lp88 init
npx lp88 init --dry-run
npx lp88 init --force
npx lp88 init --no-optional-installs
npx lp88 audit
npx lp88 plan "<task>"
npx lp88 plan --run "<task>"
npx lp88 implement
npx lp88 status
npx lp88 verify
npx lp88 deps status
npx lp88 upgrade-plan
npx lp88 upgrade-plan --write --agent codex
npx lp88 upgrade-plan --deterministic --write
npx lp88 doctor
npx lp88 superpowers
npx lp88 help
lp88 --help
lp88 --version

lp88 init copies templates into the current directory. It skips existing files by default and only overwrites lp88-managed files when --force is used.

lp88 audit runs ./scripts/audit.sh. If the script is missing, run lp88 init first.

lp88 plan "task" prints a prompt you can paste into an agent. It asks the agent to return a combined PRD and implementation plan that can be saved to docs/prd/current.md. It uses .codex/prompts/plan.md from the current project when present, otherwise it falls back to lp88's vendored template. It does not require any specific agent to be installed.

lp88 plan --run "task" calls a configured AI agent CLI directly and writes the returned PRD and implementation plan to docs/prd/current.md. It also writes .lp88/plan-contract.json, a snapshot of lp88 requirement and dependency comments. Built-in runners currently support codex, claude, gemini, and opencode.

lp88 implement runs the bounded Ralphy implementation loop against docs/prd/current.md.

Implementation output is streamed to the terminal and saved under .ralphy/runs/, including .ralphy/runs/latest.log and .ralphy/runs/latest.json.

Before starting, it prints the PRD path, max iterations, configured engine, configured model, config file, working directory, and log path. If no model is configured, it prints CLI default because the selected engine decides its own default model.

lp88 status reports whether the current PRD still has unchecked checklist items, checked items without evidence, missing required dependencies, source drift, missing Ralphy reports, or audit issues. It exits nonzero when anything needs attention.

lp88 report is an alias for lp88 status.

lp88 verify performs the stricter proof pass. It checks the PRD contract, evidence comments, dependency contract, standard scripts, audit summary, and Ralphy reports when present.

lp88 deps status checks dependency contract entries from the PRD or .lp88/plan-contract.json.

lp88 upgrade-plan uses the configured planning agent by default to semantically review and upgrade an existing PRD to the lp88 plan contract. Add --write to save the upgraded PRD in place, create a .bak backup, and write .lp88/plan-contract.json. Use --deterministic for the mechanical non-agent review/upgrade.

lp88 doctor checks whether the expected workflow files exist, whether scripts are executable, whether a package manager and git repo are detected, and whether CI is present.

It also reports optional external tools:

✅ opensrc CLI detected
ℹ️ Superpowers-compatible agents detected: codex, gemini
ℹ️ Ralphy CLI not installed (optional; install with `npm install -g ralphy-cli`)
ℹ️ lp88 planning agent: codex
ℹ️ Ralphy engine preference: codex

lp88 superpowers shows Superpowers setup instructions for detected agent CLIs.

Recommended Workflow

1. Create or open a project.
2. Run npx lp88 init.
3. Run lp88 doctor.
4. Optionally run lp88 superpowers and install Superpowers for your agent.
5. Run lp88 plan --run "<task>" to generate docs/prd/current.md.
6. Or run lp88 plan "<task>" and paste the output into your agent manually.
7. Review and approve the plan before implementation.
8. Run lp88 implement to execute the approved plan with Ralphy.
9. Run lp88 status to see unchecked work, source drift, evidence gaps, dependency gaps, and latest Ralphy/audit reports.
10. Run lp88 verify before treating checked boxes as done.
11. Run lp88 audit.
12. Open your agent, or use lp88 plan --run, and ask it to use AGENTS.md and the relevant skill.
13. Use Greptile/greploop for PR review fixes.

Using With Agents

After initialization, start your agent in the project and point it at the installed files:

Use AGENTS.md and skills/audit-repo/SKILL.md. Run ./scripts/audit.sh and give me a prioritized improvement plan.

For planning without calling an agent, run:

lp88 plan "Improve onboarding flow"

That prints an agent-ready prompt like:

Use AGENTS.md, skills/plan-project/SKILL.md, and skills/code-structure/SKILL.md.

Task:
Improve onboarding flow

Return a combined PRD and implementation plan that can be saved to:

  docs/prd/current.md

Use this structure:

# PRD

## Goal

## User / Actor

## Problem

## Source Requirements

- [ ] Requirement text
  <!-- lp88:req id=area.short-name level=mandatory source=source-requirements -->

## Derived First PR Scope

## Dependency Contract

- `package-name`
  <!-- lp88:dep name=package-name manifest=package.json required=true -->

## Acceptance Evidence

- [ ] Acceptance item
  <!-- lp88:req id=area.acceptance level=mandatory source=derived-first-pr-scope -->
  <!-- lp88:evidence file=path/to/file contains="expected text" -->

# Implementation Plan

## Assumptions

## Architecture Impact

## Files Likely To Change

## Implementation Steps

## Tests Required

Rules:
- Do not implement yet.
- Ask only blocking questions.
- Prefer small PR-sized changes.

Paste that output into your agent. The agent should return the plan; it should not start implementing until you approve the plan.

After you approve it, save the returned PRD and implementation plan to:

docs/prd/current.md

That file is the default input for:

lp88 implement

To have lp88 call the agent directly, run:

lp88 plan --run --agent codex "Improve onboarding flow"

That writes the agent output to:

docs/prd/current.md

Planning can take a while. Use --verbose to show the underlying agent command and stream progress from the agent:

lp88 plan --run --verbose --agent codex "Improve onboarding flow"

Built-in planning agents:

codex
claude
gemini
opencode

If --agent is omitted, lp88 uses:

1. --agent
2. LP88_AGENT
3. .lp88/config.env
4. detected local CLIs

You can pass a model:

lp88 plan --run --agent codex --model gpt-5.5 "Improve onboarding flow"
lp88 plan --run --agent claude --model claude-sonnet-4-6 "Improve onboarding flow"
lp88 plan --run --agent opencode --model anthropic/claude-sonnet-4-6 "Improve onboarding flow"

For agent CLIs without a built-in runner, set LP88_AGENT_COMMAND. Use {prompt} where lp88 should insert the generated prompt:

LP88_AGENT_COMMAND='my-agent --print {prompt}' lp88 plan --run "Improve onboarding flow"

Example .lp88/config.env:

LP88_AGENT="${LP88_AGENT:-codex}"
LP88_MODEL="${LP88_MODEL:-gpt-5.5}"

The per-command flags always win:

lp88 plan --run --agent gemini "Improve onboarding flow"
lp88 plan --run --agent codex --model gpt-5.5 "Improve onboarding flow"

Plan Contract

Launchpad-88 treats checklists as claims, not proof. New PRDs should include machine-readable comments that preserve requirement provenance and evidence:

## Source Requirements

- [ ] Use `panes` for resizable IDE shell
  <!-- lp88:req id=shell.panes level=mandatory source=source-requirements -->

## Dependency Contract

- `panes`
  <!-- lp88:dep name=panes manifest=pubspec.yaml required=true -->

## Acceptance Evidence

- [x] Add `panes`
  <!-- lp88:req id=shell.panes level=mandatory source=derived-first-pr-scope -->
  <!-- lp88:evidence file=pubspec.yaml contains="panes:" -->

When lp88 plan --run writes docs/prd/current.md, it also snapshots the contract to:

.lp88/plan-contract.json

lp88 status is read-only and reports categories such as:

Complete
Unchecked
Checked but unverified
Missing dependency
Source drift
No Ralphy report
Audit issues

lp88 verify is the stricter gate. It fails if mandatory requirements disappear, are downgraded, are deferred, or remain unchecked; if checked items have no valid evidence; if required dependencies are missing; or if standard checks fail.

For existing projects with older PRDs, run the agent-assisted review first:

lp88 upgrade-plan --prd docs/prd/current.md

When ready, let the agent upgrade in place:

lp88 upgrade-plan --write --prd docs/prd/current.md

To use the deterministic mechanical upgrader instead:

lp88 upgrade-plan --deterministic --write --prd docs/prd/current.md

This writes a backup beside the PRD:

docs/prd/current.md.bak

The upgraded PRD preserves the old plan under ## Original Plan Notes and creates a contract snapshot at .lp88/plan-contract.json.

Supported dependency manifests in v1:

package.json
pubspec.yaml
requirements.txt
pyproject.toml

Superpowers

Superpowers is an optional agent-side methodology plugin from https://github.com/obra/superpowers.

It complements lp88 rather than replacing it:

• Superpowers makes the agent better at brainstorming, TDD, review, worktrees, and subagent execution.
• lp88 makes the repo ready for agent work with project files, scripts, CI, a predictable PRD path, and Ralphy/status commands.

Use:

lp88 superpowers

That prints setup instructions for detected agent CLIs. During interactive lp88 init, Launchpad-88 also offers Superpowers setup after checking optional tools.

For agents that support shell-based plugin installation, lp88 can run the setup command. For agents that require marketplace or chat-command installation, lp88 prints the exact steps to run inside that agent.

Keep docs/prd/current.md as the lp88 source of truth. If Superpowers is installed, let it improve the planning conversation and implementation discipline, then still write the approved PRD and plan to docs/prd/current.md before running lp88 implement.

Greptile And Greploop

Use skills/greploop/SKILL.md when a PR has Greptile, CI, or reviewer feedback. The loop is intentionally bounded:

• group feedback by theme
• fix actionable comments only
• run relevant tests
• stop after 3 iterations
• summarize what changed and what remains

opensrc

opensrc is an optional external tool from https://github.com/vercel-labs/opensrc. It gives coding agents access to dependency source code when public docs and type definitions are not enough.

lp88 does not depend on opensrc directly. During interactive lp88 init, you can choose to install it. To install manually:

npm install -g opensrc

Then run:

./scripts/opensrc.sh zod

The wrapper calls:

opensrc path "$TARGET"

Use skills/opensrc/SKILL.md when dependency internals are needed for implementation, debugging, or review.

Ralphy / Ralph Wiggum

skills/ralphy-run/SKILL.md is a custom lp88 safety wrapper skill around the upstream Ralphy project: https://github.com/michaelshimeles/ralphy

Ralphy is an implementation grinder, not the architect. Use it only after a clear PRD, issue, or approved implementation plan exists.

lp88 does not depend on Ralphy directly. To use the wrapper, install Ralphy separately:

npm install -g ralphy-cli

Then run:

lp88 implement

After the run, lp88 saves the report to:

.ralphy/runs/latest.log
.ralphy/runs/latest.json

Check completion with:

lp88 status
lp88 verify

That calls the wrapper:

ralphy --prd "$TASK_FILE" --max-iterations "$MAX_ITERATIONS"

You can also pass a specific PRD file:

lp88 implement --prd docs/prd/billing.md --max-iterations 3

You can configure the engine in .ralphy/lp88.env:

RALPHY_ENGINE="${RALPHY_ENGINE:-codex}"
RALPHY_MODEL="${RALPHY_MODEL:-}"

Or override it per run:

RALPHY_ENGINE=cursor RALPHY_MODEL=composer-2.5 ./scripts/ralphy.sh docs/prd/current.md

Supported engine values:

claude, codex, cursor, opencode, qwen, droid, copilot, gemini, default

With RALPHY_ENGINE=codex, the wrapper calls:

ralphy --codex --prd "$TASK_FILE" --max-iterations "$MAX_ITERATIONS"

Code Structure Skill

skills/code-structure/SKILL.md helps decide what belongs in actions, services, utilities, and routes/controllers:

• actions orchestrate workflows and business rules
• services contain reusable operational mechanics
• utilities are pure helpers
• controllers and routes stay thin
• shared abstractions should earn their keep

Vendored Skills

skills/code-structure/SKILL.md is vendored into lp88 for deterministic installs.

• Vendored file: skills/code-structure/SKILL.md
• Source URL: https://raw.githubusercontent.com/michaelshimeles/skills/main/code-structure/SKILL.md
• Runtime behavior: lp88 init copies the local vendored file from this package and does not fetch it from GitHub.

Users should review third-party skill files before trusting them.

Safety Rules

The installed AGENTS.md tells agents to:

• plan before broad changes
• prefer PR-sized changes
• avoid unrelated refactors
• avoid new dependencies unless justified
• never commit secrets
• never weaken security checks to make tests pass
• ask before destructive operations
• treat auth, authorization, payments, data deletion, migrations, encryption, secrets, and security-sensitive code as high risk

Updating Templates

Edit files under templates/. lp88 init copies this directory into the target project.

To update the vendored code-structure skill, fetch the source raw GitHub file during lp88 package development and commit the resulting templates/skills/code-structure/SKILL.md. Do not add runtime fetching to lp88 init.

To customize the planning prompt for a project, edit .codex/prompts/plan.md. Keep {{TASK}} where the task should be inserted. If the placeholder is missing, lp88 plan appends the task at the end.