Alpha

Alpha is an assistive harness for AI-driven development. It is not an agent: it never edits your code and never spawns or triggers other agents (Cursor, Claude, etc.).

Instead, the LLM agent is the brain and Alpha is the tooling it calls. The agent invokes alpha <command> (or pnpm alpha <command> / npx alpha <command>, or a generated /alpha-* slash command), and Alpha:

• emits structured templates, questionnaires, and plans for the agent to act on, and
• ingests the agent's content, validates it, and persists artifacts under .alpha/, and
• runs deterministic analysis (e.g. static code review) that needs no LLM at all.

The agent reads Alpha's output and applies any code changes itself.

Why this design

• No hidden magic. Alpha never guesses with fake "AI" heuristics and never silently drives another agent. What it does is deterministic and inspectable.
• Agent-drivable. Commands are non-interactive by default and print machine-readable output to stdout (human logs go to stderr). Add --json for a { ok, command, data } envelope.
• Human-friendly too. Add --interactive to any authoring command to answer prompts yourself.
• Cross-agent. alpha init generates a universal AGENTS.md/SKILL.md plus Claude (.claude/commands + CLAUDE.md) and Cursor (.cursor/commands) command files from one source of truth.

Install

npm install -D @thynameisjayvee/alpha-cli
# then generate the agent skill files:
npx alpha init

Postinstall creates .alpha/ and adds it to .gitignore. alpha init generates the agent-facing skill/command files.

Commands

| Command | What it does | |---------|--------------| | alpha init | Scaffold .alpha/ and generate agent skill files (AGENTS.md, SKILL.md, .cursor/, .claude/). | | alpha gather | Emit a requirements questionnaire, or ingest answers into .alpha/project-context.json. | | alpha stack | Emit reference tech stacks, or ingest a chosen/custom stack into .alpha/tech-stack.json. | | alpha spec | Emit a spec authoring template / skeleton, or ingest a finished spec into .alpha/specs/. | | alpha review | Run deterministic static analysis and write a findings report to .alpha/reports/. | | alpha implement | Parse the latest report and emit a per-finding fix plan for you to apply. | | alpha workflow | Run gather → stack → spec → review → implement in sequence. |

Global options

• --json — emit a machine-readable JSON envelope on stdout.
• -i, --interactive — use human-facing prompts instead of emit/ingest.

The emit / ingest pattern

Steps that require judgement don't fake intelligence. They either hand you a template (emit) or accept your content (ingest).

# 1. EMIT: ask Alpha what it needs
alpha gather
#    → prints a questionnaire (markdown), or use --json for structured form

# 2. INGEST: give Alpha the answers (file or stdin via `-`)
alpha gather --input answers.json
echo '{ "project_name": "Demo", "primary_goal": "ship fast" }' | alpha gather --input -

Stdin is only read when you pass --input -, so a bare command never blocks.

Review then implement

# Deterministic analysis → report on disk
alpha review --target src/

# Turn the latest report into an actionable plan (you apply the edits)
alpha implement --severity critical,high

# After applying changes, re-check and clean up the report when resolved
alpha implement --severity critical,high --verify --cleanup

alpha implement emits prompts; it does not modify files. You (or your agent) make the changes.

Programmatic API

import { Alpha } from '@thynameisjayvee/alpha-cli';

const alpha = await Alpha.open();

await alpha.init();
const review = await alpha.review({ target: 'src/' });
await alpha.implement({ severity: 'critical,high', verify: true });

Individual functions are also exported: runInit, gatherRequirements, adviseStack, generateSpec, runReview, runImplementation, plus the emit / setJsonMode helpers and path/fs utilities.

Artifacts

your-project/
├── .alpha/                    # gitignored
│   ├── config.json
│   ├── project-context.json   # from `gather`
│   ├── tech-stack.json        # from `stack`
│   ├── specs/                 # from `spec`
│   └── reports/               # from `review`, consumed by `implement`
├── AGENTS.md                  # generated by `alpha init`
├── SKILL.md                   # generated by `alpha init`
├── .cursor/commands/alpha-*.md
└── .claude/commands/alpha-*.md

Configuration

.alpha/config.json:

{
  "version": "0.1.0",
  "output": {
    "alphaDir": ".alpha",
    "specsDir": ".alpha/specs",
    "reportsDir": ".alpha/reports"
  },
  "review": {
    "defaultChecks": ["quality", "security", "performance"]
  },
  "implementation": {
    "autoVerify": false,
    "cleanupOnVerify": false
  }
}

Development

npm install
npm run build      # tsc → dist/
npm run dev        # tsx src/cli.ts
npm test           # vitest

The CLI entry (bin/alpha.js) is a thin wrapper over the compiled dist/cli.js, so alpha, pnpm alpha, and npx alpha all share one implementation.

License

MIT