docs: add quickstart guide (from chore/workflow-and-quickstart branch)

2026-07-07 16:24:57 +02:00
parent 2e35796f37
commit e24013ce54
1 changed files with 87 additions and 0 deletions
@@ -0,0 +1,87 @@
+# Quickstart: Monorepo auf neuem Rechner
+
+## 1. Repo klonen
+
+```bash
+git clone https://github.com/DoctoDre/Orchestrator.git
+cd Orchestrator
+```
+
+## 2. Python-Umgebung einrichten
+
+```bash
+cd shared/tools/monorepo-cli
+python -m venv .venv
+
+# Windows:
+.venv\Scripts\activate
+# Linux/Mac:
+source .venv/bin/activate
+
+pip install -e ".[dev]"
+```
+
+Danach verf├╝gbar:
+- `ctx-guard` ÔÇö Monorepo-Verwaltungs-CLI
+- `ctx-guard knowledge capture "Notiz"` ÔÇö Quick Knowledge Capture
+
+## 3. LLM-Tooling (Kiro / MCP)
+
+Das Monorepo nutzt Kiro als prim├ñres LLM-Werkzeug. Die Konfiguration liegt in:
+
+```
+.kiro/settings/mcp.json       ÔåÉ MCP-Server-Konfiguration
+.kiro/steering/*.md            ÔåÉ Verhaltensregeln f├╝r den Agenten
+.kiro/specs/                   ÔåÉ Feature-Spezifikationen
+```
+
+### MCP-Server aktivieren
+
+Die MCP-Server werden automatisch erkannt wenn du den Ordner in Kiro ├Âffnest.
+Aktuell konfigurierte Server:
+- **orgmylife-api** ÔÇö Task-/Projektboard-Zugriff
+- **dbctx** ÔÇö DB-interne Wissensbasis und Build-IT-Suche
+- **atlassian-jira** ÔÇö Jira-Anbindung
+
+### Steering-Dateien
+
+Steering steuert wie Kiro mit dem Repo arbeitet:
+- `workspace-notes.md` ÔÇö Kontextzuordnung, Key Decisions, Pr├ñferenzen
+- `git-path.md` ÔÇö Git-Pfad, Branch-Workflow (PRs, nie direkt auf master)
+
+### Ohne Kiro (alternative LLM-Nutzung)
+
+Die Knowledge-Pipeline unterst├╝tzt auch LiteLLM als Fallback:
+```bash
+export LLM_PROVIDER=openai   # oder anthropic, etc.
+export LLM_MODEL=gpt-4o
+ctx-guard knowledge ingest --context bahn
+```
+
+## 4. Secrets
+
+Secrets sind NICHT im Repo. Du brauchst:
+- `.secrets`-Datei im Root (manuell anlegen, ist gitignored)
+- Umgebungsvariablen f├╝r API-Tokens (JIRA_API_TOKEN, CONFLUENCE_API_TOKEN, etc.)
+
+## 5. Tests laufen lassen
+
+```bash
+cd shared/tools/monorepo-cli
+python -m pytest tests/ -x --tb=short -q
+```
+
+F├╝r schnelle Checks (ohne Hypothesis-PBT):
+```bash
+python -m pytest tests/test_e2e_integration.py tests/test_knowledge_cli.py -q
+```
+
+## 6. Workflow
+
+1. Neuen Branch erstellen: `git checkout -b feat/mein-feature`
+2. Arbeiten, committen
+3. Pushen: `git push -u origin feat/mein-feature`
+4. PR auf GitHub erstellen
+5. Mergen
+
+Nie direkt auf `master` pushen.