Repo Setup Session

Be honest about what you're unsure of. Don't pad with assumptions.

Step 3: Ask Clarifying Questions

Ask 3–7 questions to fill gaps. Good question categories:

• Users: Who are the primary and secondary users? What's their technical level?
• Auth: Does this need authentication? What kind (email/password, OAuth, SSO)?
• Data: What are the core data entities? Relational DB, document store, or other?
• Deployment: Where will this run? (Vercel, AWS, self-hosted, desktop app, etc.)
• Integrations: Any third-party services? (Stripe, SendGrid, analytics, etc.)
• Scale: Expected user count? Data volume? Performance requirements?
• Team: Solo dev or team? Who else will work on this?
• Timeline: Any deadlines or phased delivery expectations?
• Non-goals: What is explicitly out of scope?
• Existing work: Is there existing code/design to build on, or greenfield?

Don't ask all of these — pick the ones that matter for this specific project.

Step 4: Process User Response

• Update your understanding based on answers and corrections.
• If major new information surfaces, confirm again before writing.
• If answers are clear and complete, proceed to writing.

Writing Phase

Step 5: Create .ai-ingest-docs/project-goals-understanding.md

Write this file FIRST. Structure:

# Project Goals Understanding

> Auto-generated by the repo-setup-agent based on conversational discovery.
> Last updated: [YYYY-MM-DD]

## Project Identity
- **Name:** [project name]
- **One-liner:** [single sentence description]
- **Repository:** [repo path or URL if known]

## Core Purpose
[2-3 paragraphs on what this project does and why it exists]

## Target Users
[Who uses this, their needs, their technical level]

## Key Features & Capabilities
[Bullet list of the main things this project does]

## Tech Stack & Architecture
[Languages, frameworks, databases, infrastructure]

## Scope & Constraints
- **In scope:** [what this project will do]
- **Out of scope:** [what it explicitly won't do]
- **Constraints:** [budget, timeline, team size, technical limitations]

## Key Decisions Made
[Architecture choices, tech stack rationale, trade-offs accepted]

## Open Questions & Assumptions
[Things the AI assumed or that still need user input]

Step 6: Populate Core Planning Docs

Read each existing file in .docs/planning/ to understand its current structure, then overwrite with project-specific content. Always populate:

Step 7: Populate Conditional Docs

Only write these if they're relevant to the project:

Step 8: Create Additional Docs as Needed

Evaluate whether the project needs docs beyond the standard set. Create any that would meaningfully help planning and execution. There is no fixed list — use judgment based on the project.

When creating a new doc:

1. Use kebab-case filename: my-new-doc.md
2. Start with a # Title header
3. Write substantive content, not outlines
4. Add it to README.md index

Step 9: Report Completion

After writing all files, present a summary:

## Repo Setup Complete

### AI Understanding
- `.ai-ingest-docs/project-goals-understanding.md` — [created/updated]

### Planning Docs Written
- `.docs/planning/overview.md` — [created/updated]
- `.docs/planning/prd.md` — [created/updated]
- [... list all files ...]

### New Docs Created
- `.docs/planning/api-design.md` — [why it was needed]
- [... any additional files ...]

### Files Skipped (not relevant)
- `auth-and-subscriptions.md` — project has no auth
- [... any skipped files ...]

Quality Standards

• Write real content based on the conversation, not lorem ipsum or TODOs.
• Match the depth and style of existing planning docs in the repo.
• Use [TBD — needs input] sparingly and only for genuinely unknown details.
• Cross-reference between docs (e.g., milestones should reference PRD features).
• Keep technical specification aligned with the stated tech stack.
• User stories should map to features described in the PRD.

Safety

• Do not overwrite files outside .docs/planning/ and .ai-ingest-docs/ unless explicitly asked.
• If existing planning docs contain real (non-template) content, warn the user before overwriting.
• If access is missing or unclear, stop and request clarification.