{"_id":"@alex.botez/elaborate","_rev":"3-5b2e49a008576143d319c025a2ed5c46","name":"@alex.botez/elaborate","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alex.botez/elaborate","version":"1.0.0","keywords":["ai","agent-skill","claude-code","discovery","elaboration","interview","project-scoping","requirements","socratic","specification"],"license":"MIT","_id":"@alex.botez/elaborate@1.0.0","maintainers":[{"name":"alex.botez","email":"alex.botez@gmail.com"}],"homepage":"https://github.com/alexbot/elaborate#readme","bugs":{"url":"https://github.com/alexbot/elaborate/issues"},"dist":{"shasum":"265f5622a45fc75db19d354b15c187da83983f4f","tarball":"https://registry.npmjs.org/@alex.botez/elaborate/-/elaborate-1.0.0.tgz","fileCount":162,"integrity":"sha512-FodtPrfbezVBhVx8JVs+0+hZj+yVB+FyCmoOw4WOi6w41mbnjrVoY5/rUxdpVerSjI3YdEtzfakqoPtBbJbGnA==","signatures":[{"sig":"MEYCIQDrXnO3geGUDwE8SJ4UES8astuGTEHUkiwoqRNTXnWUQAIhAKHXA4kFD9EUeddy76iBM58poed0Oef0fmRit2qOEs4q","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alex.botez%2felaborate@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":773521},"type":"module","engines":{"node":">=22.0.0"},"exports":{"./skill":{"types":"./dist/skill/index.d.ts","import":"./dist/skill/index.js"},"./phases":{"types":"./dist/phases/index.d.ts","import":"./dist/phases/index.js"},"./durable":{"types":"./dist/durable/index.d.ts","import":"./dist/durable/index.js"},"./interview":{"types":"./dist/interview/index.d.ts","import":"./dist/interview/index.js"}},"gitHead":"df8091d0957f2fcbd0db98b76b9464fed59c1442","scripts":{"dev":"tsc --watch","eval":"vitest run --config vitest.eval.config.ts","lint":"eslint src/","test":"vitest","build":"tsc","test:run":"vitest run","typecheck":"tsc --noEmit","build:skill":"node scripts/build-skill.mjs","deploy:skill":"node scripts/build-skill.mjs && node -e \"const fs=require('fs');fs.mkdirSync('.claude/skills/elaborate/scripts',{recursive:true});fs.copyFileSync('skills/elaborate/SKILL.md','.claude/skills/elaborate/SKILL.md');fs.copyFileSync('skills/elaborate/scripts/elaborate.cjs','.claude/skills/elaborate/scripts/elaborate.cjs');fs.copyFileSync('skills/elaborate/scripts/elaborate.cjs.map','.claude/skills/elaborate/scripts/elaborate.cjs.map')\" && echo Deployed to .claude/skills/elaborate/"},"_npmUser":{"name":"alex.botez","email":"alex.botez@gmail.com"},"repository":{"url":"git+https://github.com/alexbot/elaborate.git","type":"git"},"_npmVersion":"10.9.7","description":"Agent skill that runs a Socratic interview inside your coding agent — turning vague ideas into structured intent","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.0.0","yaml":"^2.8.3"},"_hasShrinkwrap":false,"devDependencies":{"ai":"^6.0.168","eslint":"^9.0.0","vitest":"^2.0.0","esbuild":"^0.27.4","typescript":"^5.0.0","@types/node":"^20.0.0","@ai-sdk/google":"^3.0.64","@ai-sdk/openai":"^3.0.53","@ai-sdk/anthropic":"^3.0.71","typescript-eslint":"^8.0.0","zod-to-json-schema":"^3.25.2","@openrouter/ai-sdk-provider":"^2.9.0"},"_npmOperationalInternal":{"tmp":"tmp/elaborate_1.0.0_1779216827658_0.2923714930223691","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to @alex.botez/clarifying-ideas — install that instead."}},"time":{"created":"2026-05-19T18:53:47.477Z","modified":"2026-06-23T22:04:53.027Z","1.0.0":"2026-05-19T18:53:47.864Z"},"bugs":{"url":"https://github.com/alexbot/elaborate/issues"},"license":"MIT","homepage":"https://github.com/alexbot/elaborate#readme","keywords":["ai","agent-skill","claude-code","discovery","elaboration","interview","project-scoping","requirements","socratic","specification"],"repository":{"url":"git+https://github.com/alexbot/elaborate.git","type":"git"},"description":"Agent skill that runs a Socratic interview inside your coding agent — turning vague ideas into structured intent","maintainers":[{"name":"alex.botez.user","email":"alex.botez@gmail.com"}],"readme":"# Elaborate\n\nAn agent skill that runs a Socratic interview inside your coding agent — turning vague ideas into structured intent before you write a line of code.\n\nWorks with Claude Code, Cursor, GitHub Copilot, and any agent that supports the [agentskills.io](https://agentskills.io) standard.\n\n[![CI](https://github.com/alexbot/elaborate/actions/workflows/ci.yml/badge.svg)](https://github.com/alexbot/elaborate/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n![Elaborate demo — library revival interview](docs/examples/library-demo.gif)\n\n## The Problem\n\nMost projects start with a gap between \"I have an idea\" and \"I know what to build.\" People either jump straight to code or hand an AI a one-line prompt and hope for a spec. Both skip the hard part: figuring out what success looks like, who cares, where the boundaries are, and which assumptions will bite you later.\n\nTraditional methods for this exist — but they depend on trained facilitators and structured workshops. Solo developers, founders, and small teams skip them entirely. The result: projects start with vague goals and discover critical gaps mid-build.\n\n## What Elaborate Does\n\nElaborate runs a structured interview — 25-32 questions across seven phases — that moves you from a vague idea to a scoped project definition.\n\n| Phase | What it covers |\n|-------|---------------|\n| **Opening** | Context and framing — greenfield or existing project? |\n| **Purpose** | What problem are you solving? What does success look like? |\n| **Goals** | Concrete, measurable outcomes with rationale |\n| **Stakeholders** | Who cares, what they need, where interests conflict |\n| **Scope** | What's in, what's out, why the boundary sits there |\n| **Assumptions** | What you're taking for granted that could invalidate everything |\n| **Validation** | Review and confirm — or revise before you build |\n\nEvery goal, stakeholder, scope decision, and assumption in the output traces back to the conversation turn that produced it.\n\n## Quick Start\n\nRequires **Node.js 18+**.\n\n```bash\nnpx skills add alexbot/elaborate\n```\n\nTo install for a specific agent:\n\n```bash\nnpx skills add alexbot/elaborate -a claude-code   # Claude Code only\nnpx skills add alexbot/elaborate -a cursor   # Cursor only\nnpx skills add alexbot/elaborate -a github-copilot  # GitHub Copilot only\n```\n\nThen:\n\n```bash\n/elaborate\n# or just say it naturally:\n\"I'd like to elaborate my latest idea about a neighborhood recycling app\"\n```\n\nElaborate responds to both the slash command and natural language that signals intent to elaborate an idea.\n\n> **Note on model quality:** The interview process completes reliably on any model, but the depth of insight depends on model capability. Stronger models extract more nuance and produce richer artifacts. Smaller models may miss subtlety or generate shallow extractions.\n\n## Example: Saving a Library Branch\n\nA volunteer wants to save their neighborhood library from closure. The input:\n\n> *\"The city's talking about closing it because foot traffic has dropped. I don't want to see that happen — the library's been part of this neighborhood for a long time. I want to figure out how to bring people back.\"*\n\nAfter 28 questions, the respondent had reversed their own premise: \"I've been working backwards — I never stopped to ask whether the library is actually what the neighborhood needs.\" What started as \"bring people back\" became a research phase that could confirm or kill the original idea — and the respondent was the one who got there, not the tool.\n\n[Read the full brief →](docs/examples/library.brief.md)\n\nSee also: [Elaborate interviews itself](docs/examples/elaborate.brief.md) (the tool pointed at its own premise) and [selling cookies at the farmers market](docs/examples/cookies.brief.md) (a $500 hobby that might be a business). More examples across domains — from [federal spending oversight](docs/examples/federalspending.brief.md) to [elderly independent living](docs/examples/alfred.brief.md) — in [docs/examples/](docs/examples/).\n\n### Output\n\nThe interview produces a session file (`.elaborate/session.yaml`) — a structured YAML artifact with every goal, stakeholder, scope item, and assumption traced to the conversation turn that produced it. This is machine-consumable: designed as input for spec-driven development tools, code generators, or any pipeline that needs structured intent.\n\nIf you want something presentable — for a business plan, a stakeholder pitch, or a project kickoff — run `/project-brief` on the session file to generate a readable markdown brief. The skill prompt is in [`skills/project-brief/SKILL.md`](skills/project-brief/SKILL.md).\n\nAll examples above are generated by the automated test suite using a simulated respondent (an LLM playing the person with the idea). The briefs are generated from those sessions using the project-brief skill. You can reproduce both by running the scenario harness yourself.\n\n## How It Works\n\nThe interview is complex — 7 phases, state persistence, extraction cycles, deviation handling. Rather than relying on the model to follow a long prompt correctly, Elaborate splits the work: a compiled Node.js script handles all process decisions (what to ask, when to transition, how to store artifacts) while the model handles only semantic work (understanding what you said, extracting meaning, composing follow-up questions). The model can't skip phases or lose track — the script drives.\n\nThe interview techniques draw on qualitative research traditions:\n\n- **Kvale & Patton** — semi-structured interview design\n- **Miller & Rollnick** — motivational interviewing (surfacing ambivalence without pushing)\n- **Reynolds & Gutman** — means-end laddering (climbing from features to underlying values)\n- **KAOS** — goal decomposition (structuring what emerges into testable hierarchies)\n\nThe AI asks questions, flags ambiguity, and structures what you say. It never fills gaps on its own — you decide everything.\n\nSee [docs/decisions/](docs/decisions/) for the full architecture story.\n\n## Development\n\nRequires **Node 22+**.\n\n```bash\nnpm install\nnpm run build          # TypeScript compilation\nnpm run build:skill    # esbuild bundle → dist/skill/\nnpx vitest run         # Run tests\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup, architecture, and how to pick up work.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}