vertical-ai-dev

CLI developer helper: read documents, run Ralph-based develop from task docs, install cursor-agent. Built with TypeScript (Node.js).

Install in any project

Install as a dev dependency so you can use dev-helper in that project:

# From a local path (e.g. after cloning this repo)
npm install /path/to/vertical-ai-dev

# Or link from the vertical-ai-dev repo (global usage)
cd /path/to/vertical-ai-dev && npm run build && npm link
# Then in any project: dev-helper develop docs/spec.md

If you publish to npm, users can run:

npm install -D vertical-ai-dev
npx dev-helper develop docs/spec.md

Ralph scripts are resolved from the package installation directory, so the CLI works the same when installed in any project.

Development (this repo)

npm install
npm run build

Usage

Read one or more documents

# One file
dev-helper read path/to/doc.md

# Multiple files (positional)
dev-helper read doc1.md doc2.txt README.md

# Multiple files (comma-separated option)
dev-helper read --files doc1.md,doc2.txt,README.md

# Quiet: only file contents, no "read {{file_name}}" headers
dev-helper read --quiet doc1.md doc2.md

Paths are resolved relative to the current working directory.

Develop (documents → RALPH_TASK → Ralph)

Parses one or more documents into the RALPH_TASK format, then runs Ralph setup. Document content is placed in the Task Details section; a short description at the top is generated by cursor-agent. The generated task file is then passed to ralph-setup.sh.

# One document → generate RALPH_TASK.md → run Ralph
dev-helper develop docs/spec.md

# Multiple documents (each processed one at a time: parse → Ralph → next)
dev-helper develop doc1.md doc2.md

# Custom task file path (default: RALPH_TASK.md)
dev-helper develop spec.md -o docs/my-task.md

Or via npm:

npm run develop -- docs/spec.md

Run from the project root. Requires cursor-agent in PATH for description generation; if it fails, a fallback description is used.

Install dependencies (cursor-agent)

Ensures cursor-agent is installed; if not, runs the official Cursor install script (curl https://cursor.com/install -fsS | bash).

dev-helper install-dependencies

Or via npm:

npm run install-dependencies

Development

• npm run dev -- read <paths...> – run CLI with tsx (no build)
• npm run build – compile TypeScript to dist/
• npm start -- read <paths...> – run compiled CLI from dist/

Example

dev-helper read README.md package.json

Output:

--- read /path/to/your/project/README.md ---

(... contents ...)

--- read /path/to/your/project/package.json ---

(... contents ...)