---
stage: quickstart
requires: business-context
outputs: "{wiki_dir}/quickstart.md"
version: 2.1.0
estimated_tokens: 2000

guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Grep
    - Glob
    - Bash
  forbidden_actions:
    - "Delete any files"
    - "Modify any source files"
  read_only: true
---
# Stage 3: Quick Start Guide

Generate a Quick Start guide enabling new developers to run the project in under 30 minutes.

## Prerequisites

- Stage 02 completed with business context saved
- Mode: `{REPOIX_MODE}` (if "cli", convert MCP calls per AGENTS.md)
- Business context must be populated (non-empty `project_name`)

## Critical Rules

| Rule | Action |
|------|--------|
| Business context required | **MUST** verify business_context populated before proceeding |
| Entry point required | **MUST** identify at least 1 package file OR entry point |
| Prerequisites section | **MUST** include in generated quickstart.md |

---

{{include:ai-cache-enforcement.md}}

{{include:understand-fast-path.md}}

## Step 1: Verify Previous Stage

```bash
civyk-hatch deepwiki-update-state show --wiki-dir={wiki_dir}
```

Confirm:

- `02-business-context` in `stages_complete`
- `business_context_file` is set
- `business_context.project_name` exists

**Stop if business context is empty.**

---

## Step 2: Detect Git Remote

```bash
git remote -v 2>/dev/null || echo "No remotes configured"
```

Extract URL for clone instructions. Use placeholder if no remote found.

---

## Step 3: Gather Project Information

Find package/dependency files:

```text
files(pattern="**/package.json", limit=20)
files(pattern="**/pyproject.toml", limit=10)
files(pattern="**/requirements*.txt", limit=20)
files(pattern="**/Cargo.toml", limit=10)
files(pattern="**/go.mod", limit=10)
```

Find config files:

```text
files(pattern="**/.env*", limit=20)
files(pattern="**/docker-compose*.yml", limit=10)
files(pattern="**/Makefile", limit=10)
```

**Read key files:** README.md for setup instructions, main package file for dependencies/scripts.

```text
# Use understand-fast-path: recall before reading, store after analysis
# Key files: README.md, package.json / pyproject.toml / Cargo.toml
```

---

## Step 4: Identify Entry Points

```text
# Python
search(action="code", query="if __name__", file_pattern="*.py", limit=50)
search(action="code", query="@click.command", limit=30)

# Node.js
search(action="code", query="\"scripts\":", file_pattern="package.json", limit=20)

# Go/Rust/Java
search(action="code", query="func main", file_pattern="*.go", limit=20)
search(action="code", query="fn main", file_pattern="*.rs", limit=20)
search(action="code", query="public static void main", limit=20)

# API endpoints
architecture(action="endpoints", limit=100)
```

**Target:** At least 1 entry point (package script, main function, CLI command, OR API endpoint).

---

## Step 5: Generate Quick Start

Write to `{wiki_dir}/quickstart.md` using this template:

{{include:wiki/quickstart-template.md}}

**Fill placeholders with discovered information from Steps 2-4.**

---

## Step 6: Complete Stage

```bash
civyk-hatch deepwiki-update-state stage --stage=03-quickstart --status=completed --artifacts="{wiki_dir}/quickstart.md" --wiki-dir={wiki_dir}
```

---

## Output Format

```text
===========================================================
  STAGE COMPLETE: 03-quickstart

  Summary:
    - Generated: {wiki_dir}/quickstart.md
    - Git remote: {URL or "placeholder"}
    - Prerequisites: {count} identified
    - Entry points: {count} found

  Next: Run {next_command}
===========================================================
```

---

## Edge Cases

| Scenario | Action |
|----------|--------|
| No package files | Look for Makefile, Dockerfile, shell scripts |
| No entry points | Check bin/, scripts/ folders; document as library if applicable |
| Mixed languages | Document prerequisites for each language |

---

## Next Stage

Run `{next_command}` - CLI auto-detects current stage and emits next prompt.
