{"_id":"@billiondollarsolo/hotseat","name":"@billiondollarsolo/hotseat","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@billiondollarsolo/hotseat","version":"0.1.1","description":"AI-Powered Planning Interview Tool - Generate PRDs through interactive AI interviews","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"hotseat":"dist/cli/index.js"},"repository":{"type":"git","url":"git+https://github.com/billiondollarsolo/hotseat.git","directory":"cli"},"bugs":{"url":"https://github.com/billiondollarsolo/hotseat/issues"},"homepage":"https://github.com/billiondollarsolo/hotseat/tree/main/cli#readme","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"scripts":{"dev":"tsx src/cli/index.ts","build":"tsc","test":"vitest run","test:watch":"vitest","lint":"eslint src --ext .ts","lint:fix":"eslint src --ext .ts --fix","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && npm run test && npm run lint"},"keywords":["cli","ai","planning","prd","interview","product-requirements","specification","claude","opencode","cursor","copilot","codex"],"author":{"name":"mjtechguy"},"license":"MIT","engines":{"node":">=18.0.0"},"devDependencies":{"@types/node":"^20.10.0","@typescript-eslint/eslint-plugin":"^6.13.0","@typescript-eslint/parser":"^6.13.0","eslint":"^8.55.0","tsx":"^4.6.0","typescript":"^5.3.0","vitest":"^1.0.0"},"dependencies":{"@inquirer/core":"^11.1.1","@inquirer/prompts":"^8.2.0","chalk":"^5.6.2","commander":"^11.1.0","ora":"^9.1.0","yaml":"^2.8.2"},"gitHead":"e971a166cdec4a16477d50f19d17cd8b92d5fff7","_id":"@billiondollarsolo/hotseat@0.1.1","_nodeVersion":"25.8.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-/8HuChV8K6NnesfcKSBGf85h9blBN1EDl5lAzSILXoROS3VBejgoyb4gIV1lGJ4759gLlAFX6kmqcWNLrw2tPA==","shasum":"87261866f0477556d14872969131d88eda9fb96e","tarball":"https://registry.npmjs.org/@billiondollarsolo/hotseat/-/hotseat-0.1.1.tgz","fileCount":78,"unpackedSize":449353,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC2zivwZC5fBb1lh+zAEXkWqgT2WV+Bt+Z85/q0YgadTAIgGQ7NwieGau9n0bKag9IOkHF2R0eqZQsig+T+LB0kGJE="}]},"_npmUser":{"name":"mikejohnsonit","email":"mikejohnsonit@gmail.com"},"directories":{},"maintainers":[{"name":"mikejohnsonit","email":"mikejohnsonit@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hotseat_0.1.1_1778121942281_0.47440569410641475"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-07T02:45:42.203Z","0.1.1":"2026-05-07T02:45:42.617Z","modified":"2026-05-07T02:45:42.867Z"},"maintainers":[{"name":"mikejohnsonit","email":"mikejohnsonit@gmail.com"}],"description":"AI-Powered Planning Interview Tool - Generate PRDs through interactive AI interviews","homepage":"https://github.com/billiondollarsolo/hotseat/tree/main/cli#readme","keywords":["cli","ai","planning","prd","interview","product-requirements","specification","claude","opencode","cursor","copilot","codex"],"repository":{"type":"git","url":"git+https://github.com/billiondollarsolo/hotseat.git","directory":"cli"},"author":{"name":"mjtechguy"},"bugs":{"url":"https://github.com/billiondollarsolo/hotseat/issues"},"license":"MIT","readme":"# Hotseat CLI\n\nAI-Powered Planning Interview Tool - Generate PRDs through interactive AI interviews.\n\nHotseat is a command-line tool that conducts structured interviews with AI assistants to help you plan software features. It guides you through a series of questions about your feature idea and generates comprehensive Product Requirements Documents (PRDs) in both Markdown and JSON formats.\n\n## Features\n\n- **Interactive AI Interviews**: Hotseat uses AI assistants (Claude, OpenCode, Cursor, Codex, or Copilot) to conduct structured planning interviews\n- **Multiple AI Provider Support**: Works with Claude Code, OpenCode, Cursor, Codex, and GitHub Copilot\n- **Smart Codebase Exploration**: Automatically analyzes your project structure to provide context-aware questions\n- **Context File Support**: Include reference documents to inform the AI about existing specifications\n- **First Principles Mode**: Challenge assumptions with foundational questions before detailed planning\n- **Resume Capability**: Interrupted interviews can be resumed from where you left off\n- **Dual Output Formats**: Generates both Markdown (human-readable) and JSON (machine-readable) PRDs\n\n## Installation\n\n```bash\nnpm install -g @billiondollarsolo/hotseat\n```\n\n## Prerequisites\n\nHotseat requires at least one AI CLI tool to be installed:\n\n- **Claude Code**: `claude` CLI from Anthropic\n- **OpenCode**: `opencode` CLI\n- **Cursor**: `cursor` or `agent` CLI\n- **Codex**: `codex` CLI (`npm install -g @openai/codex` or `brew install --cask codex`)\n- **Copilot**: `gh` CLI with Copilot extension\n\n## Usage\n\n### Basic Usage\n\n```bash\nhotseat \"user authentication system\"\n```\n\nThis starts an interactive interview about the feature \"user authentication system\".\n\n### With AI Provider Selection\n\n```bash\nhotseat \"feature description\" --provider claude\nhotseat \"feature description\" --provider opencode\nhotseat \"feature description\" --provider cursor\nhotseat \"feature description\" --provider codex\nhotseat \"feature description\" --provider copilot\n```\n\n### Using Codex CLI\n\nInstall and sign in to Codex first:\n\n```bash\nnpm install -g @openai/codex\ncodex login\n```\n\nThen run Hotseat with the Codex provider:\n\n```bash\nhotseat \"user authentication system\" --provider codex\n```\n\nCodex runs through `codex exec --json`, and Hotseat saves the Codex thread id in `./hotseat/state.yaml`. That lets `hotseat --resume` continue the same Codex session, including Codex goals when they are available.\n\n### With Context Files\n\nInclude reference documents to provide additional context:\n\n```bash\n# Single file\nhotseat \"feature description\" --context docs/spec.md\n\n# Multiple files\nhotseat \"feature description\" --context docs/spec.md docs/api.md\n```\n\n### First Principles Mode\n\nStart with foundational questions that challenge assumptions:\n\n```bash\nhotseat \"feature description\" --first-principles\n```\n\n### Resume an Interrupted Interview\n\n```bash\nhotseat --resume\n```\n\n## Command Reference\n\n```\nUsage: hotseat [options] [feature]\n\nArguments:\n  feature                          Feature description to plan (e.g., \"user authentication\")\n\nOptions:\n  -v, --version                    Display the current version\n  -r, --resume                     Resume a previously interrupted interview session\n  -f, --first-principles           Begin with foundational questions that challenge assumptions\n  -c, --context <files...>         Reference documents to include in AI context\n  -p, --provider <name>            AI provider to use: claude, opencode, cursor, codex, copilot\n  -h, --help                       Display help for command\n```\n\n## Output\n\nHotseat generates PRD files in the `./hotseat/` directory:\n\n- `./hotseat/{feature-slug}.md` - Markdown PRD with overview, user stories, and technical notes\n- `./hotseat/{feature-slug}.json` - JSON PRD for programmatic use\n\n### Markdown Output Structure\n\n```markdown\n# Feature Name\n\n**Generated:** YYYY-MM-DD\n\n## Overview\n[Feature overview and context]\n\n## User Stories\n\n### 1. Story Title\n[Story description]\n\n**Acceptance Criteria:**\n- [ ] Criterion 1\n- [ ] Criterion 2\n\n## Technical Notes\n[Implementation considerations and technical details]\n```\n\n### JSON Output Structure\n\n```json\n{\n  \"$schema\": \"https://hotseat-cli.dev/schemas/prd-v1.json\",\n  \"version\": \"1.0\",\n  \"metadata\": {\n    \"slug\": \"feature-slug\",\n    \"title\": \"Feature Name\",\n    \"generatedAt\": \"2024-01-01T00:00:00.000Z\",\n    \"generator\": \"hotseat-cli\"\n  },\n  \"overview\": \"Feature overview...\",\n  \"userStories\": [\n    {\n      \"id\": 1,\n      \"title\": \"Story Title\",\n      \"description\": \"Story description\",\n      \"acceptanceCriteria\": [\n        { \"id\": 1, \"text\": \"Criterion 1\", \"completed\": false }\n      ]\n    }\n  ],\n  \"technicalNotes\": \"Implementation notes...\"\n}\n```\n\n## Configuration\n\nHotseat stores configuration in `./hotseat/config.yaml`:\n\n```yaml\n# Hotseat CLI Configuration\n# Default AI provider (claude, opencode, cursor, codex, copilot)\ndefaultProvider: claude\n\n# Output directory for generated PRDs\noutputDirectory: ./hotseat\n```\n\nSet `defaultProvider: codex` if you want `hotseat \"feature\"` to use Codex without passing `--provider codex` each time.\n\n## State Management\n\nInterview progress is saved to `./hotseat/state.yaml`, allowing you to:\n\n- Resume interrupted interviews with `hotseat --resume`\n- Recover from network errors or crashes\n- Continue multi-session planning work\n\nState is automatically cleared after successful PRD generation.\n\n## Programmatic Usage\n\nHotseat can also be used as a library:\n\n```typescript\nimport { runInterview, exploreCodebase, generateMarkdown } from '@billiondollarsolo/hotseat';\n\n// Explore codebase\nconst exploration = await exploreCodebase('/path/to/project');\nconsole.log(exploration.summary);\n\n// Generate PRD\nconst prd = {\n  overview: 'Feature overview...',\n  userStories: [...],\n  technicalNotes: '...'\n};\nconst markdown = generateMarkdown(prd, 'feature-slug');\n```\n\n## Supported File Types for Context\n\nHotseat supports the following file types for `--context`:\n\n- **Markdown**: `.md`, `.markdown`\n- **Text**: `.txt`, `.text`\n- **Code**: `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.rb`, `.go`, `.rs`, `.java`\n- **Config**: `.json`, `.yaml`, `.yml`, `.toml`, `.ini`, `.conf`\n- **Web**: `.html`, `.css`, `.scss`, `.less`\n- **Other**: `.xml`, `.sql`, `.graphql`, `.gql`, `.sh`, `.bash`, `.zsh`\n\n## Development\n\n### Prerequisites\n\n- Node.js >= 18.0.0\n- npm\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/billiondollarsolo/hotseat.git\ncd hotseat/cli\n\n# Install dependencies\nnpm install\n```\n\n### Running Locally\n\nDuring development, use `npm run dev` to run the CLI directly without building:\n\n```bash\n# Run CLI with a feature description\nnpm run dev \"user authentication system\"\n\n# With options\nnpm run dev \"feature name\" -- --provider claude --first-principles\n\n# Resume an interrupted session\nnpm run dev -- --resume\n\n# Show help\nnpm run dev -- --help\n```\n\nNote: Use `--` before CLI flags to pass them through npm to the script.\n\n### Building\n\n```bash\n# Compile TypeScript to JavaScript\nnpm run build\n\n# Output is written to ./dist/\n```\n\n### Type Checking\n\n```bash\n# Run TypeScript compiler without emitting files\nnpm run typecheck\n```\n\n### Linting\n\n```bash\n# Check for lint errors\nnpm run lint\n\n# Auto-fix lint errors\nnpm run lint:fix\n```\n\n## Testing\n\nHotseat uses [Vitest](https://vitest.dev/) as its test framework.\n\n### Running Tests\n\n```bash\n# Run all tests once\nnpm test\n\n# Run tests in watch mode (re-runs on file changes)\nnpm run test:watch\n```\n\n### Test Structure\n\nThe test suite includes multiple types of tests:\n\n| Type | Location | Description |\n|------|----------|-------------|\n| Unit | `src/**/*.test.ts` | Tests for individual modules (core, providers, utils) |\n| Integration | `src/integration/` | Tests for interview flow with mocked providers |\n| E2E | `src/e2e/` | Tests against real AI CLI providers |\n| Snapshot | `src/core/prd.snapshot.test.ts` | Validates PRD output formats |\n\n### Test Files Overview\n\n```\nsrc/\n├── cli/\n│   ├── index.test.ts          # CLI command parsing\n│   └── prompt.test.ts         # Interactive prompts\n├── core/\n│   ├── orchestrator.test.ts   # Interview orchestration\n│   ├── state.test.ts          # Session state persistence\n│   ├── prd.test.ts            # PRD generation\n│   ├── prd.snapshot.test.ts   # PRD output snapshots\n│   ├── context.test.ts        # Context file loading\n│   ├── exploration.test.ts    # Codebase analysis\n│   ├── error-recovery.test.ts # Error handling\n│   ├── config.test.ts         # Configuration management\n│   └── interview.test.ts      # Interview wrapper\n├── providers/\n│   ├── claude.test.ts         # Claude provider\n│   ├── opencode.test.ts       # OpenCode provider\n│   ├── cursor.test.ts         # Cursor provider\n│   ├── codex.test.ts          # Codex provider\n│   ├── copilot.test.ts        # Copilot provider\n│   └── index.test.ts          # Provider registry\n├── utils/\n│   └── index.test.ts          # Utility functions\n├── integration/\n│   └── interview.integration.test.ts\n├── e2e/\n│   └── interview.e2e.test.ts\n└── package.test.ts            # NPM package validation\n```\n\n### Running Specific Tests\n\n```bash\n# Run a specific test file\nnpm test src/core/prd.test.ts\n\n# Run tests matching a pattern\nnpm test -- --grep \"orchestrator\"\n\n# Run tests with coverage\nnpm test -- --coverage\n```\n\n### Updating Snapshots\n\nIf you make intentional changes to PRD output formats:\n\n```bash\nnpm test -- --update-snapshots\n```\n\n### E2E Tests\n\nE2E tests require actual AI CLI tools to be installed. They test against real providers and are skipped if the required CLI is not available:\n\n```bash\n# E2E tests automatically skip if CLI tools are not installed\nnpm test src/e2e/\n```\n\n## Project Structure\n\n```\nhotseat-cli/\n├── src/\n│   ├── index.ts              # Public API exports\n│   ├── cli/                  # CLI interface (Commander.js, Inquirer)\n│   ├── core/                 # Core logic (orchestrator, state, PRD generation)\n│   ├── providers/            # AI provider implementations\n│   └── utils/                # Utility functions\n├── dist/                     # Compiled output\n├── hotseat/                     # Default output directory for PRDs\n├── package.json\n├── tsconfig.json\n├── vitest.config.ts\n└── README.md\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-279a4d3c5bb33aca7e28c503f4fdc154"}