ShipIt 🚀

Stop optimizing for humans. Start optimizing for AI.

An SDLC built for AI-assisted development: state in files, tests as truth, gates instead of meetings. Replaces handoffs and docs with executable truth and state-anchored workflows. Production ready — CLI-first; see tests/ISSUES.md for validation.

Repository: github.com/NJLaPrell/ShipIt

Table of Contents

• 1. Quick Start
• 2. Prerequisites
• 3. What You Get
• 4. Core Workflow
• 5. The Problem & The Solution
• 6. Installation
• 7. Key Concepts
• 8. Commands Reference
• 9. Documentation & Help
• 10. FAQ
• 11. License

1. Quick Start

Get from zero to a running project in under two minutes. Steps 3–4 run in Cursor or VS Code as slash commands.

1.1 Install

npm install -g @nlaprell/shipit
# Or: npx @nlaprell/shipit init

1.2 Create a new project (or attach to existing)

# New project
create-shipit-app my-awesome-app

# Existing project
cd my-existing-app && shipit init

You’ll be prompted for tech stack (TypeScript/Node, Python, Other), project description, and high-risk domains.

1.3 Open in editor and run first commands

1. Open the project in Cursor or VS Code.
2. In the editor, run:
   • /scope-project "Build a todo app with auth" — AI-assisted feature breakdown, generates intents and runs release plan + roadmap.
   • /ship F-001 — Runs the full 5-phase workflow (analysis → plan → tests → code → verify → release).

That’s it. The framework drives the rest with progress indicators and gates.

2. Prerequisites

• Node.js 20+
• Cursor or VS Code (with ShipIt extension for VS Code). See Using ShipIt in VS Code.
• Git

3. What You Get

After create-shipit-app or shipit init, your project has:

• project.json — Project metadata and ShipIt version.
• work/intent/ — Features, bugs, tech-debt as markdown (F-001.md, etc.).
• work/workflow-state/ — Active phase and per-intent state (see parallel workflow).
• work/roadmap/ — now / next / later triage.
• work/release/ — Release plan (what ships when).
• scripts/ — Framework scripts (verify, fix, status, workflow-orchestrator, etc.).
• .cursor/ — Slash commands and rules (or equivalent for VS Code).
• _system/ — Architecture (CANON, invariants), artifacts, behaviors, security, drift. Do not edit. Upgraded via shipit upgrade only.
• .override/ — Your customizations (rules, commands, scripts, config); never touched by upgrade.

Do not edit _system/ — framework internals. Use .override/ for customizations.

Optional: dashboard-app/ — Web dashboard; run with pnpm dashboard.

Full tree and planning outputs: docs/DIRECTORY_STRUCTURE.md.

4. Core Workflow

One path: Install CLI → create or init project → open in editor → scope → ship.

| Phase | Commands | | --------------- | --------------------------------------------------------------------------------------------- | | Setup | CLI: create-shipit-app or shipit init. Editor: /scope-project, /status, /dashboard. | | Planning | /new_intent, /generate-release-plan, /generate-roadmap, /fix. | | Execution | /ship <id>, /verify <id>, /status. | | Maintenance | shipit upgrade, /rollback <id>, /kill <id>, /drift_check, /deploy. |

Slash commands run in Cursor or VS Code. Full phase details: AGENTS.md.

┌─────────────────────────────────────────────────────────────────────────┐
│                         ShipIt Workflow                                  │
└─────────────────────────────────────────────────────────────────────────┘

SETUP PHASE
    ├─ create-shipit-app <name>  or  shipit init   (CLI)
    ├─ /scope-project "Description"  →  intents, release plan, roadmap
    └─ /status, /dashboard

PLANNING PHASE
    ├─ /new_intent  →  /generate-release-plan  →  /generate-roadmap
    └─ /fix  (auto-fix intent issues)

EXECUTION PHASE
    ├─ /ship <id>  →  [1] Analysis  →  [2] Plan  →  [3] Tests  →  [4] Code  →  [5] Verify  →  Release
    ├─ /verify <id>, /status
    └─ /rollback <id>, /kill <id>

MAINTENANCE
    ├─ shipit upgrade  (backup in ._shipit_backup/)
    ├─ /drift_check, /deploy
    └─ /test_shipit (framework E2E)

5. The Problem & The Solution

The problem: Traditional SDLC assumes humans are the bottleneck. AI agents need state files, executable tests, explicit gates, and do-not-repeat ledgers — not meetings and handoffs. Most failures are unstated assumptions and ambiguous truth, not coding errors.

The solution: ShipIt optimizes for what counts as truth: tests and invariants over docs, state in files over meetings, explicit gates over tribal knowledge. Add adversarial verification, intent ledger in work/intent/, drift detection, and context-aware suggestions. How the 7 agents (Steward, PM, Architect, Implementer, QA, Security, Docs) work together: AGENTS.md.

6. Installation

6.1 For app developers

See Quick Start for the full flow. Quick reference:

| Action | Command | | ------------------ | ------------------------------------------------- | | Install CLI | npm install -g @nlaprell/shipit | | New project | create-shipit-app my-app | | Attach to existing | cd my-app && shipit init | | Upgrade framework | shipit upgrade (backs up to ._shipit_backup/) | | Check installation | shipit check |

No global install: npx @nlaprell/shipit init from your project root. Full options: docs/CLI_REFERENCE.md.

6.2 From source (contributors)

pnpm is used when developing the framework itself:

git clone https://github.com/NJLaPrell/ShipIt.git
cd ShipIt
pnpm install
pnpm test && pnpm test:cli && pnpm test:shipit -- --clean
# Optional: pnpm validate-cursor  or  pnpm validate-vscode

See docs/CONTRIBUTING.md.

6.3 User customizations (.override/)

Put customizations in .override/rules/, .override/commands/, .override/scripts/, .override/config/. They are never touched by shipit upgrade. docs/USER_OVERRIDES_DESIGN.md.

7. Key Concepts

• Intent ledger — All work lives in work/intent/ as markdown with executable acceptance criteria, confidence scores, invariants, kill criteria, and rollback plan. Use /fix to auto-fix common issues. Templates: AGENTS.md and work/intent/templates/.
• Tests first — The workflow enforces Spec → Tests → Code. QA writes tests (they fail); Implementer writes code (tests pass). No production code before tests.
• Truth hierarchy — When facts conflict: runtime behavior > tests > invariants > specs > architecture > comments > opinion. AGENTS.md.
• High-risk gates — Auth, payments, permissions, infrastructure, PII require human approval before implementation.

More: GitHub integration, usage/cost, security allowlist, confidence calibration → AGENTS.md.

8. Commands Reference

CLI: shipit init | upgrade | check | create | list-backups | restore — see docs/CLI_REFERENCE.md.

Editor (slash commands):

| Category | Commands | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Setup | create-shipit-app / shipit init, /scope-project, /status, /dashboard | | Planning | /new_intent, /generate-release-plan, /generate-roadmap, /fix, /pr, /create-pr, /create-intent-from-issue, /risk, /revert-plan | | Execution | /ship <id>, /verify <id>, /rollback <id>, /kill <id> | | Maintenance | /drift_check, /deploy, /test_shipit | | Utility | /help, /suggest, /dashboard, /usage-record, /usage-report, /calibration-report |

All slash commands are in .cursor/commands/. Scripts: pnpm run <script> (e.g. pnpm fix, pnpm verify). Headless/VS Code: docs/headless-mode.md, docs/vscode-usage.md.

9. Documentation & Help

• docs/CLI_REFERENCE.md — All CLI commands and options
• docs/LIMITATIONS.md — What ShipIt doesn’t do, when not to use
• docs/TROUBLESHOOTING.md — Exit codes, common issues, rollback
• docs/EXAMPLES.md — New project, existing project, upgrade, CI
• docs/PILOT_GUIDE.md — Step-by-step first feature
• docs/DIRECTORY_STRUCTURE.md — Project layout
• docs/STABILITY.md — Stable vs experimental APIs
• AGENTS.md — Roles, workflow, conventions
• CHANGELOG.md — Version history

10. FAQ

Q: How do I install ShipIt?
A: npm install -g @nlaprell/shipit. Then create-shipit-app <name> or shipit init. CLI_REFERENCE.

Q: Can I use ShipIt with an existing project?
A: Yes. Run shipit init in the project root. It merges framework files and package.json. EXAMPLES.

Q: How do I upgrade?
A: shipit upgrade. Backups go to ._shipit_backup/. Use --dry-run first. TROUBLESHOOTING.

Q: Will upgrade overwrite my changes?
A: Framework-owned files are updated (with backup). App code and non-framework paths are not. Use .override/ for customizations so they’re never touched.

Q: How do I customize Cursor/VS Code rules?
A: Add files under .override/rules/. USER_OVERRIDES_DESIGN.

Q: Do I need to understand all 7 agents?
A: No. Use the commands; agents run during /ship. AGENTS.md for depth.

Q: What about deployment?
A: /deploy runs readiness checks; actual deployment is your pipeline. See LIMITATIONS.

Q: Where do I get help?
A: TROUBLESHOOTING, GitHub Issues.

11. License

MIT. See CHANGELOG.md for version history.

Next: Once you’ve created a project, open it in Cursor or VS Code, run /scope-project "your goal", then /ship F-001. Full walkthrough: docs/PILOT_GUIDE.md.