Commit
Add README
commit
b03d7f8
1 changed file with +50 and −0
added README.md +50 −0
| @@ -0,0 +1,50 @@ | ||
| 1 | +# VoiceTask | |
| 2 | + | |
| 3 | +Talk through what you want to build. An AI interviewer asks one targeted question at a time (voice in, voice out), tracks coverage across nine spec categories, and writes a Claude-Code-ready spec pack (SPEC, PLAN, TASKS, VERIFICATION, HANDOFF) into your target project. Every requirement carries `[S<n>]` provenance markers pointing to the exact transcript segment you said it in. | |
| 4 | + | |
| 5 | +## Quick start | |
| 6 | + | |
| 7 | +``` | |
| 8 | +npm install | |
| 9 | + | |
| 10 | +# Offline demo, no API keys needed (deterministic mock providers): | |
| 11 | +MOCK_PROVIDERS=1 npm run dev | |
| 12 | + | |
| 13 | +# Real mode: | |
| 14 | +cp .env.example .env # fill in the keys | |
| 15 | +npm run dev | |
| 16 | +``` | |
| 17 | + | |
| 18 | +Open the printed Vite URL in Chrome or Edge. Hold the mic button (or space) to talk, or type. Say "done" or click the done link to finish, then generate the spec pack. | |
| 19 | + | |
| 20 | +## APIs and models | |
| 21 | + | |
| 22 | +| Purpose | Provider | Env vars | Default model | Alternatives | | |
| 23 | +|---|---|---|---|---| | |
| 24 | +| Interview + spec generation | Anthropic Messages API | `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL` | `claude-opus-4-8` | `claude-sonnet-4-6` (cheaper, faster) | | |
| 25 | +| Speech-to-text | OpenAI audio transcriptions | `OPENAI_API_KEY`, `STT_MODEL` | `gpt-4o-mini-transcribe` | `gpt-4o-transcribe` (higher accuracy), `whisper-1` | | |
| 26 | +| Text-to-speech | Browser `speechSynthesis` | none | best installed voice | none (free, local) | | |
| 27 | + | |
| 28 | +Notes: | |
| 29 | + | |
| 30 | +- The interviewer uses structured outputs (`output_config.format` with a zod schema) with adaptive thinking, so every turn comes back as a validated `InterviewTurn`. A schema-mismatch is retried once, then surfaced as an error. | |
| 31 | +- Spec pack files are generated one Anthropic call per file, streamed, with adaptive thinking. | |
| 32 | +- `MOCK_PROVIDERS=1` swaps both providers for deterministic mocks; all tests run this way and need no network. | |
| 33 | +- Keys are read from the environment (a local `.env` is loaded if present) and never logged or written to disk. | |
| 34 | + | |
| 35 | +## Environment variables | |
| 36 | + | |
| 37 | +See `.env.example`. Summary: `MOCK_PROVIDERS`, `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`, `OPENAI_API_KEY`, `STT_MODEL`, `PORT` (default 3001). | |
| 38 | + | |
| 39 | +## Commands | |
| 40 | + | |
| 41 | +``` | |
| 42 | +npm run dev # server (3001) + client (Vite) with proxy | |
| 43 | +npm run typecheck # tsc --noEmit over shared, server, client | |
| 44 | +npm test # vitest, mock providers enforced | |
| 45 | +npm run build # production build to dist/ | |
| 46 | +``` | |
| 47 | + | |
| 48 | +## Project docs | |
| 49 | + | |
| 50 | +Product spec and implementation plan live in `spec/`. Guardrails for coding-agent sessions are in `CLAUDE.md`, blocker protocol in `BLOCKED.md`. |