@thynameisjayvee/alpha-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thynameisjayvee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# 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
+
+```bash
+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**).
+
+```bash
+# 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
+
+```bash
+# 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
+
+```typescript
+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`:
+
+```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
+
+```bash
+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

package/bin/alpha.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+/**
+ * Alpha CLI entry point.
+ *
+ * Thin wrapper that delegates to the compiled CLI in dist/ so that `alpha`,
+ * `pnpm alpha`, and `npx alpha` all share one implementation.
+ */
+
+import { run } from '../dist/cli.js';
+
+run().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Alpha CLI — thin, non-interactive-by-default wrapper over the Alpha harness.
+ *
+ * Alpha never edits code and never spawns agents. Commands emit structured
+ * output on stdout (human logs go to stderr); pass --json for an envelope and
+ * --interactive to drive a command through human prompts.
+ */
+import { Command } from 'commander';
+export declare function buildProgram(): Command;
+export declare function run(argv?: string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,wBAAgB,YAAY,IAAI,OAAO,CAuGtC;AAED,wBAAsB,GAAG,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE"}

package/dist/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * Alpha CLI — thin, non-interactive-by-default wrapper over the Alpha harness.
+ *
+ * Alpha never edits code and never spawns agents. Commands emit structured
+ * output on stdout (human logs go to stderr); pass --json for an envelope and
+ * --interactive to drive a command through human prompts.
+ */
+import { Command } from 'commander';
+import { Alpha } from './core/alpha.js';
+import { setJsonMode } from './utils/logger.js';
+function applyGlobals(thisCommand) {
+    const opts = thisCommand.optsWithGlobals();
+    if (opts.json) {
+        setJsonMode(true);
+    }
+}
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name('alpha')
+        .description('AI development assistive harness (LLM-driven, non-interactive by default)')
+        .version('0.1.0')
+        .option('--json', 'emit machine-readable JSON envelopes on stdout')
+        .option('-i, --interactive', 'use human-facing interactive prompts')
+        .hook('preAction', (thisCommand) => applyGlobals(thisCommand));
+    program
+        .command('init')
+        .description('Scaffold .alpha/ and generate agent skill files (AGENTS.md, etc.)')
+        .option('--agents <list>', 'comma-separated targets: universal,claude,cursor')
+        .option('--force', 'overwrite existing generated files')
+        .action(async (opts) => {
+        const alpha = await Alpha.open();
+        await alpha.init({ agents: opts.agents, force: opts.force });
+    });
+    program
+        .command('gather')
+        .alias('requirements')
+        .description('Capture project requirements (emit questionnaire or ingest answers)')
+        .option('--input <file>', 'JSON answers/context file (otherwise reads stdin)')
+        .action(async (opts, cmd) => {
+        const alpha = await Alpha.open();
+        await alpha.gatherRequirements({
+            input: opts.input,
+            interactive: cmd.optsWithGlobals().interactive,
+        });
+    });
+    program
+        .command('stack')
+        .alias('advise-stack')
+        .description('Decide the tech stack (emit reference stacks or ingest a decision)')
+        .option('--input <file>', 'JSON stack/decision file (otherwise reads stdin)')
+        .action(async (opts, cmd) => {
+        const alpha = await Alpha.open();
+        await alpha.adviseStack({
+            input: opts.input,
+            interactive: cmd.optsWithGlobals().interactive,
+        });
+    });
+    program
+        .command('spec')
+        .alias('generate-spec')
+        .description('Author a specification (emit template/skeleton or ingest a spec)')
+        .option('--input <file>', 'JSON spec file (otherwise reads stdin)')
+        .option('--title <title>', 'write a skeleton spec with this title')
+        .option('--type <type>', 'feature | bugfix | refactor | enhancement')
+        .option('--description <text>', 'short description for the skeleton')
+        .action(async (opts, cmd) => {
+        const alpha = await Alpha.open();
+        await alpha.spec({
+            input: opts.input,
+            title: opts.title,
+            type: opts.type,
+            description: opts.description,
+            interactive: cmd.optsWithGlobals().interactive,
+        });
+    });
+    program
+        .command('review')
+        .description('Run deterministic static analysis and write a findings report')
+        .option('--target <path>', 'directory to analyze (default: cwd)')
+        .action(async (opts) => {
+        const alpha = await Alpha.open();
+        await alpha.review({ target: opts.target });
+    });
+    program
+        .command('implement')
+        .alias('fix')
+        .description('Emit a fix plan from the latest review report (does not edit code)')
+        .option('--severity <list>', 'comma-separated severities, e.g. critical,high')
+        .option('--findings <list>', 'comma-separated finding ids or indexes')
+        .option('--verify', 're-run deterministic checks on selected findings')
+        .option('--cleanup', 'delete the report when verification fully passes')
+        .action(async (opts, cmd) => {
+        const alpha = await Alpha.open();
+        await alpha.implement({
+            severity: opts.severity,
+            findings: opts.findings,
+            verify: opts.verify,
+            cleanup: opts.cleanup,
+            interactive: cmd.optsWithGlobals().interactive,
+        });
+    });
+    program
+        .command('workflow')
+        .description('Run gather → stack → spec → review → implement in sequence')
+        .action(async (_opts, cmd) => {
+        const alpha = await Alpha.open();
+        await alpha.workflow({ interactive: cmd.optsWithGlobals().interactive });
+    });
+    return program;
+}
+export async function run(argv = process.argv) {
+    await buildProgram().parseAsync(argv);
+}
+// Auto-run only when invoked directly (e.g. `tsx src/cli.ts` or `node dist/cli.js`),
+// not when imported by the bin wrapper.
+const entry = process.argv[1] ?? '';
+if (entry.endsWith('cli.ts') || entry.endsWith('cli.js')) {
+    run().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,SAAS,YAAY,CAAC,WAAoB;IACxC,MAAM,IAAI,GAAG,WAAW,CAAC,eAAe,EAAE,CAAC;IAC3C,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,WAAW,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,OAAO,CAAC;SACb,WAAW,CAAC,2EAA2E,CAAC;SACxF,OAAO,CAAC,OAAO,CAAC;SAChB,MAAM,CAAC,QAAQ,EAAE,gDAAgD,CAAC;SAClE,MAAM,CAAC,mBAAmB,EAAE,sCAAsC,CAAC;SACnE,IAAI,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC;IAEjE,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,mEAAmE,CAAC;SAChF,MAAM,CAAC,iBAAiB,EAAE,kDAAkD,CAAC;SAC7E,MAAM,CAAC,SAAS,EAAE,oCAAoC,CAAC;SACvD,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACrB,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,KAAK,CAAC,cAAc,CAAC;SACrB,WAAW,CAAC,qEAAqE,CAAC;SAClF,MAAM,CAAC,gBAAgB,EAAE,mDAAmD,CAAC;SAC7E,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,KAAK,CAAC,kBAAkB,CAAC;YAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,GAAG,CAAC,eAAe,EAAE,CAAC,WAAW;SAC/C,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,OAAO,CAAC;SAChB,KAAK,CAAC,cAAc,CAAC;SACrB,WAAW,CAAC,oEAAoE,CAAC;SACjF,MAAM,CAAC,gBAAgB,EAAE,kDAAkD,CAAC;SAC5E,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,KAAK,CAAC,WAAW,CAAC;YACtB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,GAAG,CAAC,eAAe,EAAE,CAAC,WAAW;SAC/C,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,KAAK,CAAC,eAAe,CAAC;SACtB,WAAW,CAAC,kEAAkE,CAAC;SAC/E,MAAM,CAAC,gBAAgB,EAAE,wCAAwC,CAAC;SAClE,MAAM,CAAC,iBAAiB,EAAE,uCAAuC,CAAC;SAClE,MAAM,CAAC,eAAe,EAAE,2CAA2C,CAAC;SACpE,MAAM,CAAC,sBAAsB,EAAE,oCAAoC,CAAC;SACpE,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,KAAK,CAAC,IAAI,CAAC;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,GAAG,CAAC,eAAe,EAAE,CAAC,WAAW;SAC/C,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,+DAA+D,CAAC;SAC5E,MAAM,CAAC,iBAAiB,EAAE,qCAAqC,CAAC;SAChE,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACrB,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,WAAW,CAAC;SACpB,KAAK,CAAC,KAAK,CAAC;SACZ,WAAW,CAAC,oEAAoE,CAAC;SACjF,MAAM,CAAC,mBAAmB,EAAE,gDAAgD,CAAC;SAC7E,MAAM,CAAC,mBAAmB,EAAE,wCAAwC,CAAC;SACrE,MAAM,CAAC,UAAU,EAAE,kDAAkD,CAAC;SACtE,MAAM,CAAC,WAAW,EAAE,kDAAkD,CAAC;SACvE,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,KAAK,CAAC,SAAS,CAAC;YACpB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,GAAG,CAAC,eAAe,EAAE,CAAC,WAAW;SAC/C,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,4DAA4D,CAAC;SACzE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QAC3B,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,KAAK,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,eAAe,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;IAEL,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,OAAiB,OAAO,CAAC,IAAI;IACrD,MAAM,YAAY,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,qFAAqF;AACrF,wCAAwC;AACxC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACpC,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzD,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACpB,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACtE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/core/alpha.d.ts

@@ -0,0 +1,64 @@
+import { type Config } from '../utils/config.js';
+import { type GatherOptions } from './requirements/index.js';
+import { type StackOptions } from './stack/index.js';
+import { type SpecOptions } from './generator/index.js';
+import { type ReviewOptions } from './reviewer/index.js';
+import { type ImplementOptions } from './implementation/index.js';
+import { type InitOptions } from './init/index.js';
+import type { ProjectContext, StackRecommendation, Specification, ReviewReport } from '../types/index.js';
+/**
+ * Alpha - programmatic entry point for the assistive harness.
+ *
+ * Alpha never edits code and never spawns agents. The calling LLM (or a human
+ * via --interactive) drives these methods; each one either emits a
+ * template/prompt or ingests + persists caller-provided content under .alpha/.
+ *
+ * @example
+ * ```typescript
+ * import { Alpha } from '@thynameisjayvee/alpha-cli';
+ *
+ * const alpha = await Alpha.open();
+ * const review = await alpha.review({ target: 'src/' });
+ * await alpha.implement({ severity: 'critical,high' });
+ * ```
+ */
+export declare class Alpha {
+    private projectRoot;
+    private alphaDir;
+    private config;
+    private constructor();
+    /**
+     * Open an Alpha instance for the current project.
+     * @param projectRoot - Optional project root path (defaults to nearest package.json)
+     */
+    static open(projectRoot?: string): Promise<Alpha>;
+    private initialize;
+    getProjectRoot(): string;
+    getAlphaDir(): string;
+    getConfig(): Config | null;
+    /** Scaffold .alpha/ and generate the agent skill surface. */
+    init(options?: InitOptions): Promise<void>;
+    /** Capture project requirements (emit questionnaire or ingest answers). */
+    gatherRequirements(options?: GatherOptions): Promise<ProjectContext | null>;
+    /** Decide the tech stack (emit reference stacks or ingest a decision). */
+    adviseStack(options?: StackOptions): Promise<StackRecommendation | null>;
+    /** Author a specification (emit template/skeleton or ingest a finished spec). */
+    spec(options?: SpecOptions): Promise<Specification | null>;
+    /** Run deterministic static review and persist a report. */
+    review(options?: ReviewOptions): Promise<ReviewReport>;
+    /** Emit a fix plan from the latest review report (does not edit code). */
+    implement(options?: ImplementOptions): Promise<void>;
+    /**
+     * Run the complete Alpha workflow:
+     * gather → stack → spec → review → implement.
+     */
+    workflow(options?: {
+        interactive?: boolean;
+    }): Promise<{
+        context: ProjectContext | null;
+        stack: StackRecommendation | null;
+        spec: Specification | null;
+        review: ReviewReport;
+    }>;
+}
+//# sourceMappingURL=alpha.d.ts.map

package/dist/core/alpha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alpha.d.ts","sourceRoot":"","sources":["../../src/core/alpha.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,YAAY,EACb,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAuB;IAErC,OAAO;IAKP;;;OAGG;WACU,IAAI,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;YAOzC,UAAU;IAKxB,cAAc,IAAI,MAAM;IAIxB,WAAW,IAAI,MAAM;IAIrB,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,6DAA6D;IACvD,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,2EAA2E;IACrE,kBAAkB,CACtB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAIjC,0EAA0E;IACpE,WAAW,CACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAItC,iFAAiF;IAC3E,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAIpE,4DAA4D;IACtD,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAIhE,0EAA0E;IACpE,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D;;;OAGG;IACG,QAAQ,CACZ,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAO,GACtC,OAAO,CAAC;QACT,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;QAC/B,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;QAClC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;QAC3B,MAAM,EAAE,YAAY,CAAC;KACtB,CAAC;CAWH"}

package/dist/core/alpha.js

@@ -0,0 +1,94 @@
+import { getProjectRoot, getAlphaDir, ensureAlphaDir } from '../utils/paths.js';
+import { loadConfig } from '../utils/config.js';
+import { gatherRequirements } from './requirements/index.js';
+import { adviseStack } from './stack/index.js';
+import { generateSpec } from './generator/index.js';
+import { runReview } from './reviewer/index.js';
+import { runImplementation, } from './implementation/index.js';
+import { runInit } from './init/index.js';
+/**
+ * Alpha - programmatic entry point for the assistive harness.
+ *
+ * Alpha never edits code and never spawns agents. The calling LLM (or a human
+ * via --interactive) drives these methods; each one either emits a
+ * template/prompt or ingests + persists caller-provided content under .alpha/.
+ *
+ * @example
+ * ```typescript
+ * import { Alpha } from '@thynameisjayvee/alpha-cli';
+ *
+ * const alpha = await Alpha.open();
+ * const review = await alpha.review({ target: 'src/' });
+ * await alpha.implement({ severity: 'critical,high' });
+ * ```
+ */
+export class Alpha {
+    projectRoot;
+    alphaDir;
+    config = null;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+        this.alphaDir = getAlphaDir();
+    }
+    /**
+     * Open an Alpha instance for the current project.
+     * @param projectRoot - Optional project root path (defaults to nearest package.json)
+     */
+    static async open(projectRoot) {
+        const root = projectRoot || getProjectRoot();
+        const alpha = new Alpha(root);
+        await alpha.initialize();
+        return alpha;
+    }
+    async initialize() {
+        ensureAlphaDir();
+        this.config = await loadConfig();
+    }
+    getProjectRoot() {
+        return this.projectRoot;
+    }
+    getAlphaDir() {
+        return this.alphaDir;
+    }
+    getConfig() {
+        return this.config;
+    }
+    /** Scaffold .alpha/ and generate the agent skill surface. */
+    async init(options = {}) {
+        return await runInit(options);
+    }
+    /** Capture project requirements (emit questionnaire or ingest answers). */
+    async gatherRequirements(options = {}) {
+        return await gatherRequirements(options);
+    }
+    /** Decide the tech stack (emit reference stacks or ingest a decision). */
+    async adviseStack(options = {}) {
+        return await adviseStack(options);
+    }
+    /** Author a specification (emit template/skeleton or ingest a finished spec). */
+    async spec(options = {}) {
+        return await generateSpec(options);
+    }
+    /** Run deterministic static review and persist a report. */
+    async review(options = {}) {
+        return await runReview(options);
+    }
+    /** Emit a fix plan from the latest review report (does not edit code). */
+    async implement(options = {}) {
+        return await runImplementation(options);
+    }
+    /**
+     * Run the complete Alpha workflow:
+     * gather → stack → spec → review → implement.
+     */
+    async workflow(options = {}) {
+        const passthrough = { interactive: options.interactive };
+        const context = await this.gatherRequirements(passthrough);
+        const stack = await this.adviseStack(passthrough);
+        const spec = await this.spec(passthrough);
+        const review = await this.review();
+        await this.implement(passthrough);
+        return { context, stack, spec, review };
+    }
+}
+//# sourceMappingURL=alpha.js.map

package/dist/core/alpha.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alpha.js","sourceRoot":"","sources":["../../src/core/alpha.ts"],"names":[],"mappings":"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"}

package/dist/core/generator/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { Specification } from '../../types/index.js';
+export interface SpecOptions {
+    /** Run the human-facing interactive flow (inquirer). */
+    interactive?: boolean;
+    /** Path to a JSON spec file (otherwise stdin is used). */
+    input?: string;
+    /** Spec title (enables skeleton generation in default/emit mode). */
+    title?: string;
+    /** Spec type. */
+    type?: Specification['type'];
+    /** Short description. */
+    description?: string;
+}
+export declare function generateSpec(options?: SpecOptions): Promise<Specification | null>;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/generator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/generator/index.ts"],"names":[],"mappings":";AAMA,OAAO,EACL,aAAa,EAMd,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB;IACjB,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,yBAAyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAmOD,wBAAsB,YAAY,CAChC,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAiD/B"}