PRD: AI-Powered Client Scoping Tool

[tkowalczyk]

Problem Statement

Non-technical business owners who need software built cannot articulate their requirements in a way developers can execute on. They hire freelancers/agencies and hope the right questions get asked. When discovery is poor, they get a product that misses the mark and a budget that's blown. There's no affordable, structured way for them to think through what they actually need before a single dollar is spent on development.

Solution

A web application hosted on *.auditmos.com that lets non-technical clients go through a structured AI-powered interview to produce a comprehensive, dev-ready specification. The tool serves a solo consulting practice (~3 clients/month).

Client experience: Receives a link (no login required), chats with an AI that guides them through discovery, requirements, planning, and task breakdown across multiple sessions. Once complete, the same link shows their finalized spec and real-time progress on implementation tasks.

Developer (admin) experience: Reviews and edits AI-generated specs via a dashboard, pushes approved tasks as GitHub issues to a chosen repo, and the client's tracking page updates automatically.

User Stories

Client (non-technical project owner)

1. As a client, I want to receive a single link that gives me access to everything, so that I don't need to create an account or remember a password.
2. As a client, I want to chat with an AI that asks me structured questions about my project, so that I can articulate what I need without technical knowledge.
3. As a client, I want to close my browser and resume the conversation days later from where I left off, so that I can answer at my own pace.
4. As a client, I want the AI to automatically transition from discovery to requirements to planning without me managing the process, so that the experience feels seamless.
5. As a client, I want to see a clear spec document once the interview is complete, so that I understand what will be built.
6. As a client, I want to see a list of tasks with their current status (done/not done), so that I can track implementation progress.
7. As a client, I want the spec and task tracking on the same link (separate views), so that I have one place to check everything.
8. As a client, I want the tracking page to show plain-language task names and status, so that I can understand progress without technical knowledge.
9. As a client, I want to access the tracking page at any time without logging in, so that checking progress is frictionless.

Developer (admin)

10. As the developer, I want a dashboard listing all client projects and their status, so that I can manage my practice.
11. As the developer, I want to review the AI-generated spec before it's finalized, so that I can ensure quality.
12. As the developer, I want to edit specs using a markdown editor, so that I can refine the output.
13. As the developer, I want to select which GitHub repo to push tasks to per client, so that I can organize work per project.
14. As the developer, I want to push approved tasks as GitHub issues with one action, so that handoff is fast.
15. As the developer, I want the client's tracking page to reflect GitHub issue status, so that I don't have to manually update a separate system.
16. As the developer, I want to create a new project and get a unique shareable link, so that I can onboard a client quickly.
17. As the developer, I want to see the full conversation history for each client, so that I can understand context.

AI Conversation

18. As the AI system, I want to run a structured discovery interview (problem, users, constraints, business model), so that requirements are thorough.
19. As the AI system, I want to synthesize discovery into a formal requirements document, so that the spec is comprehensive.
20. As the AI system, I want to break requirements into a phased implementation plan with vertical slices, so that the work is actionable.
21. As the AI system, I want to generate a task breakdown from the plan, so that tasks map to GitHub issues.
22. As the AI system, I want to clearly signal phase transitions to the client, so that they understand the process.
23. As the AI system, I want to handle long conversations without losing context, so that multi-day sessions produce coherent output.

Implementation Decisions

Major Functional Components

1. Chat Engine — Claude API integration with system prompts replicating the 4-phase interview process (discovery → requirements → plan → task breakdown). Auto-transitions between phases. Messages persisted to Neon Postgres. Resumable via unique project link.

2. Client Page — Two views behind the same unique link:

   • Chat view: Active during the interview phase. Standard chat interface.
   • Spec & Tracking view: Available once spec is finalized. Rendered markdown spec at top, task list with status below.

3. Admin Dashboard — Authenticated via Better Auth (developer login only). Lists all client projects with status. Provides markdown editor for spec review/editing. Repo picker and "push to GitHub issues" action per project.

4. GitHub Sync — Outbound: Creates GitHub issues from approved task breakdown using a personal access token stored as a Cloudflare secret. Inbound: Polls GitHub API for issue status on client page load to update task status display.

5. Project/Session Management — CRUD for projects. Each project gets a unique deep link (UUID or similar). Stores conversation history, generated spec, task breakdown, and GitHub issue mapping.

Architecture

• Stack: Built on the auditmos/saas-on-cf template — TanStack Start (frontend), Hono (API), Drizzle ORM, Neon Postgres, Cloudflare Workers.
• AI: Claude API called from the Hono data-service worker. System prompts encode the interview methodology. No sandbox or tool use — conversation only.
• Auth: Better Auth for admin access only. Client pages are public (link = access, no authentication).
• GitHub: Personal access token stored as Cloudflare Worker secret. No OAuth app needed at this scale.
• Domain: Hosted under *.auditmos.com (subdomain TBD).

Data Model (conceptual)

• Project: id, name, unique_slug, status (interviewing | review | active | complete), github_repo, created_at
• Message: id, project_id, role (user | assistant | system), content, phase, created_at
• Spec: id, project_id, content_markdown, version, created_at
• Task: id, project_id, title, description, status, github_issue_number, github_issue_url, sort_order

Validation Strategy

Chat Engine

• Client can send messages and receive AI responses
• Conversation resumes correctly after browser close/reopen
• AI transitions between all 4 phases without manual intervention
• Phase transitions are clearly communicated to the client
• Long conversations (50+ messages) maintain coherence

Client Page

• Unique link loads chat view during interview phase
• Unique link loads spec & tracking view after spec is finalized
• Spec renders correctly from markdown
• Task status reflects current GitHub issue state on page load
• Page works without any authentication

Admin Dashboard

• Login works for admin only
• All projects listed with current status
• Markdown editor loads and saves spec content
• Repo picker shows available GitHub repos
• "Push to GitHub" creates correct issues in selected repo
• Conversation history viewable per project

GitHub Sync

• Tasks create as individual GitHub issues with title and description
• Issue status (open/closed) correctly reflected on client tracking page
• Polling on page load returns fresh status

Out of Scope

• Client authentication / account creation
• Multiple admin users (single developer practice)
• Billing / payments
• Email or push notifications for progress updates
• Real-time GitHub webhook sync (polling on load is sufficient)
• Jira / Linear / other project management integrations
• Multi-language support
• Mobile app (responsive web is sufficient)
• Custom branding per client
• AI tool use / sandbox execution (API + system prompts only)
• Product naming and subdomain selection

Further Notes

• At ~3 clients/month, cost and scale concerns are minimal. Optimize for development speed over infrastructure efficiency.
• The system prompts encoding the interview methodology are the core IP — these should be iterable without code changes (stored in DB or config, not hardcoded in source).
• Context window management for long conversations (multi-day sessions) may require a summarization strategy. To be addressed during implementation.
• The auditmos/saas-on-cf template provides auth, DB, CRUD patterns, and multi-env deployment out of the box — significant headstart.