# PROMPT TEMPLATES
 I need you to help me write a feature. First, we need to define it, so you will ask me questions one-by-one to make sure we have a shared understanding of the scope
  and expectating. - The feature we want is a way for your clients to report bugs/suggestions/requests from within our app. It should not be intrusive. It should allow
  them to take a screen capture, put annotation, describe their request and/or issue. Then, as a dev, i will want to collect and review them.

## Purpose
This document standardizes how we interact with AI coding agents (Codex, Claude, etc).

Goals:
- Reduce prompt variability
- Prevent architectural drift
- Improve consistency and reliability
- Enable repeatable workflows

---

# 🧠 Core Principle

The AI is NOT the source of truth.

The source of truth is:
- docs/PRODUCT.md
- docs/ARCHITECTURE.md
- docs/CONVENTIONS.md
- docs/DECISIONS.md
- docs/tasks/*.md

All prompts MUST reference these.

---

# 🔁 Standard Workflow

1. PLAN
2. BREAKDOWN (optional)
3. IMPLEMENT (step-by-step)
4. REVIEW

Never skip directly to implementation for non-trivial features.

---

# 🧩 Prompt Templates

---

## 1. PLAN (default starting point)

### When to use
- New feature
- Complex change
- Refactor
- Anything unclear

### Prompt

You are working inside an existing repository.

Before doing anything:
1. Read:
   - AGENTS.md
   - docs/PRODUCT.md
   - docs/ARCHITECTURE.md
   - docs/CONVENTIONS.md
   - docs/DECISIONS.md
2. Read the task:
   - docs/tasks/TASK-XXX.md

Do NOT modify code.

Output:
1. Summary (<=10 lines)
2. Relevant architecture
3. Files likely involved
4. Implementation plan
5. Risks / ambiguities

---

## 2. BREAKDOWN

### When to use
- Task is too large
- You want step-by-step execution

### Prompt

Break this task into atomic steps.

For each step:
- goal
- files involved
- dependencies
- risks

Constraints:
- 3–7 steps max
- each step must be independently implementable
- keep changes small

---

## 3. IMPLEMENT

### When to use
- After plan is validated

### Prompt

Implement ONLY the agreed plan.

Read first:
- AGENTS.md
- docs/*
- docs/tasks/TASK-XXX.md

Rules:
- Minimal diff
- No refactor outside scope
- No new libraries
- Respect architecture and conventions

At the end:
1. Modified files
2. Summary of changes
3. Commands to test
4. Remaining risks

---

## 4. STEP IMPLEMENTATION

### When to use
- When using breakdown approach

### Prompt

Implement ONLY step X.

Do not touch anything outside this step.

Stop after completion.

---

## 5. REVIEW

### When to use
- Before commit
- After major change

### Prompt

Review the implementation against:

- docs/tasks/TASK-XXX.md
- docs/ARCHITECTURE.md
- docs/CONVENTIONS.md

Check:
- acceptance criteria
- architecture violations
- regression risks
- missing edge cases

Output:
1. Issues
2. Fix suggestions
3. Risk level
4. Ready to commit? (yes/no)

---

## 6. ANALYSIS (no code)

### When to use
- Debugging
- Understanding codebase
- Investigating issues

### Prompt

Do NOT modify code.

Analyze:
- architecture consistency
- state management
- API usage
- potential bugs

Output:
- what is correct
- what is fragile
- what should be improved

---

## 7. TASK GENERATION

### When to use
- Turning feature idea into executable task

### Prompt

Generate a TASK.md file.

Include:
- Objective
- Scope
- Out of scope
- Backend section
- Frontend section
- API contract
- Files involved
- Acceptance criteria
- Edge cases
- Constraints

Must be:
- clear
- complete
- self-contained

---

## 8. STRICT MODE

### When to use
- Agent starts drifting
- Too many unexpected changes

### Prompt

STRICT MODE:

- No assumptions
- No extra features
- No refactoring
- No architecture changes

Do ONLY what is defined.

If unclear → stop and ask.

---

## 9. ANTI-HALLUCINATION

### When to use
- Missing info
- Unclear requirements

### Prompt

If information is missing:
- do NOT assume
- do NOT invent

Instead:
- list missing info
- propose options

Wait for clarification.

---

## 10. STACK-SPECIFIC (Vue + .NET)

### When to use
- Reinforce stack constraints

### Prompt

You are working on:

Frontend:
- Vue 3
- Pinia
- Tailwind

Backend:
- .NET FastEndpoints
- Modular DbContexts

Rules:

Backend:
- follow FastEndpoints pattern
- no cross-module DbContext coupling

Frontend:
- use Pinia for state
- no business logic in components
- use API client

Always align with docs.

---

# 🚨 Rules

- Never start coding without reading docs
- Never trust conversation history alone
- Always constrain scope
- Always review before commit

---

# 🧭 Summary

Bad:
"Add profile feature"

Good:
- PLAN
- IMPLEMENT step 1
- REVIEW
- repeat

---

# 🔥 Recommended Usage with CLI

scripts/ai-task plan docs/tasks/TASK-XXX.md
scripts/ai-task implement docs/tasks/TASK-XXX.md
scripts/ai-task review docs/tasks/TASK-XXX.md

---

End of document.