flowchart LR
  brief([Plain-English brief]) --> gen
  docs([Company BRD / PRD]) --> rag
  subgraph THREE [3 · Ground]
    rag[Retrieve relevant chunks]
  end
  subgraph ONE [1 · Structure]
    gen[Generate backlog]
  end
  rag -. context .-> gen
  gen --> backlog[(Structured backlog)]
  subgraph TWO [2 · Measure]
    eval[Score quality]
  end
  backlog --> eval
  subgraph FOUR [4 · Act]
    agent[Agent + tools] --> jira[(Jira board)]
  end
  backlog --> agent
  agent -. exposed via .-> mcp{{MCP server}}
  mcp -. any AI client .-> ext([Claude Desktop])

backend/
  core/     Phase 1 — schema (models.py), prompt (story_generator.py), CLI
  evals/    Phase 2 — golden dataset, scorers, runner
  rag/      Phase 3 — chunking, vector store, retriever, Q&A guardrail
  agent/    Phase 4 — tools (local Jira), agent loop, MCP server
  llm/      provider interface + Gemini implementation

# 1. Create and activate a virtual environment
python -m venv venv
venv\Scripts\activate        # Windows PowerShell
# source venv/bin/activate   # macOS/Linux

# 2. Install dependencies
python -m pip install -r requirements.txt

# 3. Add your API key
copy .env.example .env       # then edit .env and paste your Gemini key

# Phase 1 — brief → structured backlog
python -m backend.core.cli
python -m backend.core.cli "Build an app for tracking gym workouts"

# Phase 2 — evals
python -m backend.evals.test_scorers      # offline: scorers vs a bad backlog (no API)
python -m backend.evals.runner myrun      # live: generate + score the golden dataset

# Phase 3 — RAG
python -m backend.rag.demo                # index a doc → retrieve → grounded backlog
python -m backend.rag.ask "How long before my appointment can I cancel?"

# Phase 4 — agent + tools
python -m backend.agent.tools.jira_demo   # the tool alone (no AI)
python -m backend.agent.demo              # the agent drives the tool from an instruction

{
  "mcpServers": {
    "storyforge-jira": {
      "command": "C:\\path\\to\\storyforge\\venv\\Scripts\\python.exe",
      "args": ["-m", "backend.agent.mcp_server"],
      "cwd": "C:\\path\\to\\storyforge",
      "env": { "PYTHONPATH": "C:\\path\\to\\storyforge" }
    }
  }
}