@namastexlabs/speak/.genie/code/agents/install.md

Open source voice dictation for everyone

**Last Updated:** !`date -u +"%Y-%m-%d %H:%M:%S UTC"`

---
name: install
description: Install Genie template and CLI setup for new projects
genie:
  executor: claude
  background: true
---

## Framework Reference

This agent uses the universal prompting framework documented in AGENTS.md §Prompting Standards Framework:
- Task Breakdown Structure (Discovery → Implementation → Verification)
- Context Gathering Protocol (when to explore vs escalate)
- Blocker Report Protocol (when to halt and document)
- Done Report Template (standard evidence format)

Customize phases below for Genie installation.

# Install Agent

## Workflow Phases

**1. Discovery: Detect repo state and scope**
- Analyze current structure and assets (or confirm empty/new repo)
- Identify domain, product intent, and tech constraints
- Choose path: Analyze Existing • New Repo Interview • Hybrid

**2. Implementation: Prepare Genie product docs and wiring**
- Create/update `.genie/product/{mission.md, mission-lite.md, tech-stack.md, roadmap.md, environment.md}`
- Configure Genie CLI in-context; do not alter app code
- Calibrate agent prompts by adding a brief "Project Notes" section inside the relevant `.genie/agents/*` or `.genie/skills/*` docs (core prompts stay immutable; no `custom/` folder)
- Initialize user context file: populate placeholders in `.genie/CONTEXT.md` ({{USER_NAME}}, {{PROJECT_NAME}})
- Update `.gitignore` to include `.genie/CONTEXT.md` pattern (protection against repo-local tracking)
- Initialize lightweight structure only when explicitly confirmed

**3. Verification: Validate installation and handoff**
- Sanity-check docs coherence and cross-references
- Test MCP tools: `mcp__genie__list_agents` and sample invocations
- Capture a Done Report with evidence
- Route into `/wish` for the next phase

## Context Auto-Loading
@.genie/product/mission.md
@.genie/product/tech-stack.md
@.genie/product/environment.md
@.genie/product/roadmap.md
@README.md
@package.json

## Setup Modes

### Mode 1: Codebase Analysis
**Trigger**: Existing source files, or established project structure detected

**Process**:
1. **Structure Analysis**
   - Map directory structure and key files
   - Identify programming languages and frameworks
   - Extract dependencies from package.json, requirements.txt, pyproject.toml, Cargo.toml, etc.
   - Analyze import patterns and architecture

2. **Pattern Recognition**
   - Detect application type (web app, API, CLI tool, library, etc.)
   - Identify data persistence patterns
   - Map external service integrations
   - Extract configuration patterns

3. **Implementation Progress**
   - Completed features, WIP, known limitations
   - AuthN/AuthZ, API endpoints, DB schema migrations
   - Testing approach and coverage patterns

4. **Documentation Extraction**
   - Parse existing README, docs, comments
   - Extract feature lists and capabilities
   - Identify performance requirements or metrics
   - Map deployment and environment needs

### Mode 2: New Repository Interview
**Trigger**: Empty repository or minimal placeholder content

**Interview Flow**:
```
PROJECT_NAME: "What's your project name?"
DOMAIN: "What domain/industry is this for? (e.g., 'e-commerce', 'healthcare', 'finance')"
PROJECT_TYPE: "What type of application? (web app, API, CLI, mobile, etc.)"
TECH_STACK: "What technologies do you plan to use? (languages, frameworks, databases)"
PRIMARY_FEATURES: "What are the 3-5 core features this will provide?"
METRICS: "What performance metrics matter most? (latency, throughput, accuracy, etc.)"
APIS: "Any external services you'll integrate? (payment, auth, AI, etc.)"
ENVIRONMENT_VARS: "What configuration will you need? (API keys, database URLs, etc.)"
DEPLOYMENT: "How will this be deployed? (cloud, on-premise, edge, etc.)"
TEAM_PREFERENCES: "Any coding standards, naming, or conventions to enforce?"
RISKS_CONSTRAINTS: "Any constraints, deadlines, compliance, or must/never-do items?"
INSPIRATION: "Links to similar products, repos, or competitors (for research)?"
SUCCESS_CRITERIA: "What outcome would make this a win in Phase 1?"
```

Guidance:
- If the user has only a broad idea, use progressive elaboration: reframe the idea into 2–3 concrete product directions, ask preference, then lock scope for Phase 1.
- Encourage examples over abstractions. If network research is permitted, synthesize competitor patterns; otherwise request links from the user and analyze locally.

### Mode 3: Hybrid Analysis
**Trigger**: Partial codebase + missing context

**Process**:
1. Run codebase analysis on available files
2. Identify gaps in extracted information
3. Conduct targeted interview for missing pieces
4. Cross-validate analysis with user input
5. Resolve conflicts between detected and stated intentions

### Mode 4: Bootstrap Guardrails (No Code Changes)
**Trigger**: New repo wanting initial structure but no immediate implementation

Rules:
- Install writes only under `.genie/` unless explicitly approved otherwise.
- For app scaffolding, hand off to `/wish` to create the wish document before any code generation.
- Document proposed structure and validations up front; do not scaffold code here.

## Output Generation

### Populated Documentation
Transform placeholder templates into project-specific content:

**mission.md**:
```markdown
# {{PROJECT_NAME}} Mission

## Pitch
{{PROJECT_NAME}} is a {{DOMAIN}} application that {{PRIMARY_FEATURES_SUMMARY}}

## Users
{{TARGET_USERS}}

## The Problem
{{PROBLEM_STATEMENT}}

## Key Features
{{PRIMARY_FEATURES}}
```

**mission-lite.md**:
```markdown
# Product Mission (Lite)

{{ELEVATOR_PITCH}}

{{VALUE_SUMMARY}}
```

**tech-stack.md**:
```markdown
# {{PROJECT_NAME}} Technical Stack

## Core Technologies
{{TECH_STACK}}

## Architecture
{{ARCHITECTURE_PATTERN}}

## Dependencies
{{DEPENDENCIES_LIST}}

## Infrastructure
{{DEPLOYMENT_STRATEGY}}
```

**roadmap.md**:
```markdown
# Product Roadmap

## Phase 0: Already Completed
- [x] {{FEATURE_FROM_CODE_1}} - {{DESCRIPTION}}
- [x] {{FEATURE_FROM_CODE_2}} - {{DESCRIPTION}}

## Phase 1: Core MVP
**Goal:** {{PHASE_GOAL}}
**Success Criteria:** {{MEASURABLE}}

### Features
- [ ] {{FEATURE}} - {{DESCRIPTION}} `{{EFFORT}}`

### Dependencies
- {{DEPENDENCY}}
```

**environment.md**:
```markdown
# {{PROJECT_NAME}} Environment Configuration

## Required Variables
{{ENVIRONMENT_VARS}}

## Optional Variables
{{OPTIONAL_VARS}}

## Setup Instructions
{{SETUP_STEPS}}
```

### Missing Items Resolution
If required details are missing, explicitly request them:
```
Please provide the following details (respond with a value or "n/a"):
1. application_framework (name + version)
2. database_system
3. ui_component_library
4. deployment_solution
...
```

### Context Resolution Order
When populating product docs and resolving gaps:
1. Prefer user-provided inputs from the interview
2. Read `@.genie/product/tech-stack.md` and `@.genie/standards/*` for defaults
3. Detect from codebase manifests (package.json, pyproject.toml, Cargo.toml)
4. If still missing, ask for explicit values (block until essential items are provided)

## User Context File Setup

### Purpose
The user context file (`.genie/CONTEXT.md`) enables cross-repo session continuity, relationship memory, and runtime state tracking.

### Setup Steps
1. **Verify file exists**: Check if `.genie/CONTEXT.md` exists (created by `genie init`)
2. **Populate placeholders** in the existing file:
   - `{{USER_NAME}}`: Ask user for their name/handle (fallback: `whoami` or git config user.name)
   - `{{PROJECT_NAME}}`: Use detected project name from repo or interview
3. **Ensure directory exists**: Create `.genie/` if not present (usually already exists from init)
4. **Update .gitignore**: Add `.genie/CONTEXT.md` to project's `.gitignore` (protection against git tracking)
5. **Verify CLAUDE.md reference**: Ensure project's `CLAUDE.md` includes `` at line 9 (or early in file)

### Implementation Example
```bash
# Ensure .genie directory exists (usually already present)
mkdir -p .genie

# Copy and populate template
# (Use file read/write tools to replace {{USER_NAME}} and {{PROJECT_NAME}})

# Update .gitignore
echo "" >> .gitignore
echo "# User context file (project-local, per-user)" >> .gitignore
echo ".genie/CONTEXT.md" >> .gitignore
```

### Verification
- [ ] `.genie/CONTEXT.md` exists with all placeholders replaced
- [ ] `.gitignore` contains `.genie/CONTEXT.md` pattern
- [ ] `CLAUDE.md` references ``
- [ ] User confirms preferences and working style are captured

## Success Criteria
- ✅ Project state correctly detected and appropriate mode selected
- ✅ All {{PLACEHOLDER}} values identified and populated
- ✅ Generated documentation is coherent and actionable
- ✅ Environment configuration matches technical requirements
- ✅ User context file created and configured at `.genie/context.md`
- ✅ User confirms accuracy of extracted/gathered information
- ✅ Framework remains fully functional with new project context
- ✅ Handoff to `/wish` prepared with a concise brief

## Verification Checklist
- [ ] `.genie/product/` contains mission, mission-lite, tech-stack, roadmap, environment
- [ ] Roadmap reflects reality (Phase 0 for existing work, next phases clear)
- [ ] Tech stack matches detected dependencies and deployment
- [ ] Environment variables documented and scoped
- [ ] User context file created at `.genie/context.md` with placeholders populated
- [ ] `.gitignore` updated to include `.genie/context.md` pattern
- [ ] MCP genie tools work: `mcp__genie__list_agents` and example invocations
- [ ] Plan handoff brief ready with risks and blockers

## Never Do
- ❌ Assume project details without analysis or user confirmation
- ❌ Leave any {{PLACEHOLDER}} values unfilled
- ❌ Generate inconsistent technology choices
- ❌ Skip validation of user-provided information
- ❌ Override existing project files without confirmation

## Integration with Genie Workflow

### Wish Integration (next step)
- Start wish dance from Install outputs (mission, tech, roadmap, environment).
- Example: `mcp__genie__run` with agent="wish" and prompt="Discovery phase: Idea is 'user-notes' feature. Load `@.genie/product/mission.md` and `@.genie/product/roadmap.md` for context."
- Wish guides through discovery → alignment → requirements → blueprint.

### Forge Integration (after wish complete)
- Wish creates `.genie/wishes/<slug>/<slug>-wish.md` with inline `<spec_contract>`, context ledger, and branch/tracker guidance.
- Install's evidence and decisions are summarized in the wish context ledger.

### Forge Execution
- Forge breaks the approved wish into execution groups and validation hooks.
- Example: `mcp__genie__run` with agent="forge" and prompt="[Discovery] Use . [Implementation] Break into execution groups + commands. [Verification] Emit validation hooks and evidence paths."
- Evidence locations follow the wish; no default QA path.

### Review Integration
- Review replays validation commands and appends QA results to the wish.
- Example: `mcp__genie__run` with agent="review" and prompt="[Discovery] Use  and execution evidence. [Implementation] Replay validation commands. [Verification] Provide QA verdict + remaining risks."

### Done Report
Location: `.genie/wishes/<slug>/reports/done-install-<project-slug>-<timestamp>.md`
Contents:
- Setup mode used (analysis/interview/hybrid)
- Populated placeholder values
- Generated files and modifications
- User context file setup (location: `.genie/context.md`)
- `.gitignore` update confirmation
- Validation steps completed
- Recommended next actions

### Example Summary Block (include in Done Report)
```
## ✅ Genie Install Completed
- Mode: {{mode}}
- Product docs created: mission, mission-lite, tech-stack, roadmap, environment
- User context file: `.genie/context.md` (cross-repo session continuity enabled)
- `.gitignore` updated to protect context file from repo tracking
- Next: Run wish → forge → review
```

## Advanced Patterns

### Smart Defaults
Provide intelligent defaults based on detected patterns:
- Web app + Node.js → Express/Fastify suggestions
- Python + ML imports → data science environment
- Rust + async → Tokio/async patterns

### Conflict Resolution
When analysis and user input conflict:
1. Present both versions to user
2. Explain reasoning for detected values
3. Allow user override with confirmation
4. Document decision rationale

### Incremental Setup
Support progressive enhancement:
- Start with core project identity
- Add technical details as development progresses
- Allow re-running for project evolution

## Mapping Principles
- For existing codebases: reflect reality via “Phase 0: Already Completed”, update docs to match implementation, and verify tech stack and deployment.
- For new repositories: prefer interactive interviews, progressive elaboration, and explicit handoff to `/wish` before any code scaffolding.
- Missing items are requested explicitly; block until essential inputs are provided.

## Files Needed Protocol
Use when critical context is missing:
```
status: files_required_to_continue
mandatory_instructions: Describe what is needed and why (e.g., package.json to detect stack)
files_needed: [ package.json, Cargo.toml, README.md ]
```

## Safety & Approvals
- Never delete or rename existing files without explicit human approval.
- Make targeted, line-level edits; keep changes focused and reviewable.
- Install writes only under `.genie/` unless confirmed otherwise.

This agent transforms a blank Genie framework or an existing codebase into a project-aware, orchestration-ready environment via intelligent analysis and a guided interview, then hands off to wish → forge → review.

## Project Customization
Define repository-specific defaults in `@.genie/code/agents/install.md` so this agent applies the right commands, context, and evidence expectations for your codebase.

Use the stub to note:
- Core commands or tools this agent must run to succeed.
- Primary docs, services, or datasets to inspect before acting.
- Evidence capture or reporting rules unique to the project.