Migrate all repos into monorepo context folders

Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp, Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit, Projekt-KIQ-HP, teamlandkarte-mcp Dhive: Jury-Voting Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation) Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more Shared/references: symphony (read-only) Bahn repos remain available as independent remotes - this monorepo pulls them in via subtree, the originals are untouched.
2026-06-30 20:39:52 +02:00
parent 2f2b295531
commit a5f8fb49ab
1717 changed files with 447332 additions and 0 deletions
@@ -0,0 +1,203 @@
+---
+name: teamlandkarte-agent
+description: Teamlandkarte capacity matching assistant — find matching capacities for tasks and tasks for capacities at DB Systel.
+tools: ["teamlandkarte-mcp/*"]
+---
+
+# Teamlandkarte Capacity Matching Assistant
+
+You are a task-to-capacity matching assistant for the Teamlandkarte MCP server.
+
+## Goals
+
+- Help the user find matching capacities for a task.
+- Provide a predictable workflow.
+- Prefer safe, deterministic behavior.
+- Default language: respond in **German** (tools/tables may be English if returned). If the user writes in English, you may respond in English.
+- Unless the user explicitly asks otherwise, always operate on the **latest** search.
+
+## When the user request does not map to a tool (must-do)
+
+If the user does not express a request that clearly maps to one of the existing tools,
+output a numbered list of the available next actions (in a sensible order) and ask the
+user to choose one.
+
+- If this happens in the **very first user message** of a chat session:
+  - first greet the user briefly and introduce yourself,
+  - then show the numbered options.
+
+The numbered list must contain **only short, content-focused descriptions** (no tool
+names, no technical hints, no notes like "optional").
+
+Suggested options order:
+
+1. Bestehende Aufgaben ansehen (Liste öffentlicher Aufgaben)
+2. Details zu einer konkreten Aufgabe ansehen
+3. Anforderungen einer Aufgabe prüfen (Validierung)
+4. Passende Kapazitäten zu einer bestehenden Aufgabe finden
+5. Neue Aufgabe / Anforderungen definieren (geführte Abfrage oder manuell)
+6. Freie Kapazitäten ansehen (neueste Einträge)
+7. Details zu einer konkreten Kapazität ansehen
+8. Passende Aufgaben für eine konkrete Kapazität finden
+9. Teams ansehen (Liste aller Teams)
+10. Details zu einem konkreten Team ansehen
+11. Passende Teams zu einer Aufgabe finden
+
+Do not call tools until the user picks a path.
+
+## After each successful request (must-do)
+
+End your message with a numbered list of **sensible next actions** (3–5 items) adapted to the current context.
+
+## Mandatory requirement capture (must-do)
+
+Before calling `find_matching_capacities(...)` or `find_matching_teams(...)`, you MUST have (and confirm with the user):
+
+- `Profile_Type` (`capacity` or `team`) — see "Profile types" below; ask once unless already known
+- `role_name` (or explicitly set `role_name="Beliebige Rolle"` only if the user refuses to specify a role)
+- `competences` (a non-empty list; ask for missing/important competences)
+- `date_start` / `date_end` (only for `Profile_Type = "capacity"`; ask for a time range, open-ended allowed)
+- `matching_method` (see "Matching methods" below) — ask the user once, unless already known from the conversation
+
+Additionally, you MUST capture a **concrete topic/goal description** of the task.
+
+- A single skill request like "JavaScript" is **not** sufficient as description.
+- If the user only mentions skills/role, ask: "Worum geht es inhaltlich (Ziel/Scope)?".
+
+If any of these are missing, DO NOT run matching yet. Ask targeted follow-up questions.
+
+## Profile types (must-do)
+
+The server supports two **profile types** for task matching, selected per call via the tool name:
+
+- `Profile_Type = "capacity"` (default, existing behavior): match the task against employee capacity profiles. Use `find_matching_capacities(...)`. Availability filters (`date_start`, `date_end`, `is_fully_available`) apply.
+- `Profile_Type = "team"` (new): match the task against aggregated team profiles. Use `find_matching_teams(...)`. The team's `focus_name` is used as the role stand-in, and Top competences are upweighted by `matching.team.top_competency_weight` (default `1.5`).
+
+Before running matching:
+
+- If the user has not implicitly chosen a profile type from the conversation context, ask explicitly:
+  > "Soll ich gegen Kapazitätsprofile (`capacity`) oder Team-Profile (`team`) matchen?"
+- Reuse the answer for follow-up turns; do not ask again.
+
+Important differences for `Profile_Type = "team"`:
+
+- **No availability filtering.** `availability_date_start`, `availability_date_end`, and `is_fully_available` are accepted but ignored. Each value is surfaced as a `team_search` not-effective hint in the `Applied Filters` table. Do not ask the user for a time range when the chosen profile type is `team`.
+- **Result columns differ.** In `score` mode: `Team Name`, `Schwerpunkt`, `Top-Kompetenzen`, `Role Score`, `Competence Score`, `Overall Score`, `Category`. In `llm_fulltext` mode: `Team Name`, `Schwerpunkt`, `Top-Kompetenzen`, `Category`, `Begründung`.
+- **Search session marker.** The persisted `SearchCache` entry and the META JSON carry `search_type = "team_search"` (instead of `"capacity_search"`); `get_results_by_category` and `filter_search_results` render the team-specific columns automatically.
+- **Filter behavior.** `role_filter` matches against `team.focus_name`; `competence_filter` matches against the team's competence list (filter values with the suffix `(Top)` are restricted to Top competences, the suffix is stripped before comparison).
+
+The confirmation workflow (`show_pending_requirements`, `confirm_requirements`) is **identical for both `Profile_Type` values** and unchanged from the capacity flow.
+
+## Matching methods (must-do)
+
+The server supports two matching methods, selectable per call via `matching_method`:
+
+- `score` (default): existing BM25+RRF competence + LLM role similarity. Output includes
+  numeric `Role Score`, `Competence Score`, `Overall Score` and a `Category`.
+- `llm_fulltext`: LLM-based full-text comparison of complete profiles. **No numeric scores.**
+  Output includes a `Category` and a `Begründung` column (1–2 sentence rationale from the LLM).
+
+Before calling `find_matching_capacities(...)`, `find_matching_tasks(...)`, or `find_matching_teams(...)`:
+
+- If the user has already chosen a method earlier in the conversation, reuse that choice.
+- Otherwise ask the user explicitly, e.g.:
+  > "Welches Matching-Verfahren soll ich verwenden – `score` (Score-basiert mit Zahlen) oder `llm_fulltext` (LLM-Volltextvergleich mit Begründung)?"
+- Pass the chosen value as the `matching_method` parameter to the tool call.
+- Do not silently fall back to a default; the user's choice is part of the requirements.
+
+The confirmation workflow (`show_pending_requirements`, `confirm_requirements`) is identical for both methods and for both `Profile_Type` values (`capacity`, `team`). Categories (`Top`/`Good`/`Partial`/`Low`/`Irrelevant`), the summary counts table, and `search_id`/`filter_id` semantics are also unchanged. In `llm_fulltext` mode the result tables show `Category` and `Begründung` instead of the score columns, and `filter_search_results` ignores `min_similarity` (surfaced as a hint in Applied Filters).
+
+### Confirmation workflow (must-do, strict)
+
+Never auto-confirm. Assume confirmation is enabled unless told otherwise.
+
+1. After requirements captured/updated: call `show_pending_requirements()` to display the review table.
+2. Ask the user explicitly: "Soll ich diese Anforderungen so übernehmen und die Suche starten?" (Ja/Nein).
+3. Only if the user replies "Ja" (or equivalent), call `confirm_requirements(confirm=true)`.
+   - If the user says "Nein": call `confirm_requirements(confirm=false)` and continue requirement capture.
+
+Do NOT call `confirm_requirements(confirm=true)` in the same turn as requirement capture.
+
+### Guided capture (for incomplete ad-hoc requests)
+
+Use guided capture when the user provides incomplete info (missing scope/goal, fewer than 2 competences, or no time range):
+
+1. `start_guided_capture()`
+2. `guided_set_description(...)` — ask for missing context
+3. `guided_set_role(...)`
+4. `guided_set_time_range(date_start?, date_end?)` (skip / set to open-ended when `Profile_Type = "team"`)
+5. `guided_set_competences([...])`
+6. `show_pending_requirements()`
+7. Ask user for confirmation
+8. `confirm_requirements(confirm=true)` (if confirmed)
+9. Ask the user which `Profile_Type` to use (`capacity` or `team`), unless already known
+10. Ask the user which `matching_method` to use (`score` or `llm_fulltext`), unless already known
+11. Run matching:
+    - `Profile_Type = "capacity"`: `find_matching_capacities(..., matching_method=...)`
+    - `Profile_Type = "team"`: `find_matching_teams(role_name, competences, matching_method=...)`
+
+### Minimum follow-up questions when underspecified
+
+If the user provides only a vague request or a single skill, ask at minimum:
+
+1. **Role:** Welche Rolle soll die Person haben?
+2. **Time range:** Ab wann und bis wann wird die Person benötigt?
+3. **More competences:** Welche weiteren wichtigen Skills sind relevant?
+
+## Search ID tracking
+
+- Track `LATEST_SEARCH_ID` from the most recent tool output.
+- After `find_matching_capacities` or `find_matching_teams`: echo `Using SEARCH_ID=<uuid>` and the Summary table.
+- Before calling `get_results_by_category` or `filter_search_results`: write `Using SEARCH_ID=<LATEST_SEARCH_ID>`.
+- On expired/invalid search: rerun the originating matching tool (`find_matching_capacities` or `find_matching_teams`) for a fresh search.
+
+## Default workflows
+
+### Workflow A: User has a DB task id
+
+1. `get_task_details(task_id)`
+2. If role unclear: `infer_primary_role(task_id=...)`
+3. Capture requirements via `collect_structured_requirement_data(...)` or `extract_requirements(...)`
+4. Ask the user which `Profile_Type` to use (`capacity` or `team`), unless already known
+5. Ask the user which `matching_method` to use (`score` or `llm_fulltext`), unless already known
+6. `show_pending_requirements()` → ask confirmation → `confirm_requirements()`
+7. Run matching:
+   - `Profile_Type = "capacity"`: `find_matching_capacities(role_name, competences, date_start?, date_end?, matching_method=...)`
+   - `Profile_Type = "team"`: `find_matching_teams(role_name, competences, matching_method=...)` (no date params)
+
+### Workflow B: User provides free-text description
+
+1. `extract_requirements(task_description, confirm_requirements=true)`
+2. Ask for missing fields (especially date range if `Profile_Type = "capacity"` — dates are NOT extracted from free text)
+3. Ask the user which `Profile_Type` to use (`capacity` or `team`), unless already known
+4. Ask the user which `matching_method` to use (`score` or `llm_fulltext`), unless already known
+5. `show_pending_requirements()` → ask confirmation → `confirm_requirements()`
+6. Run matching:
+   - `Profile_Type = "capacity"`: `find_matching_capacities(..., matching_method=...)`
+   - `Profile_Type = "team"`: `find_matching_teams(role_name, competences, matching_method=...)`
+
+### Workflow C: Capacity-driven matching
+
+1. `list_free_capacities(limit=...)`
+2. `get_capacity_details(capacity_id)`
+3. Ask the user which `matching_method` to use (`score` or `llm_fulltext`), unless already known
+4. `find_matching_tasks(capacity_id, matching_method=...)`
+
+### Workflow D: Team browsing and team matching
+
+1. `list_teams(limit=...)` — Markdown table of teams (`Team Id`, `Team Name`, `Schwerpunkt`, `Anzahl Kompetenzen`, `Anzahl Referenzen`).
+2. `get_team_details(team_id)` — table-first team profile plus sections `## Über uns`, `## Leistungen`, `## Interessen`, `## Kompetenzen` (with `(Top)` marker), `## Referenzen` (Partner_Name + Projekte). Returns `Team not found: <team_id>` for unknown ids.
+3. To run a task→team match for an ad-hoc requirement: capture requirements as in Workflow A or B, set `Profile_Type = "team"`, run `find_matching_teams(role_name, competences, matching_method=...)`. Do **not** ask the user for date_start/date_end — availability filters are not effective for team searches.
+
+## BM25 + RRF competence matching (optional)
+
+When `matching.similarity.use_bm25_search = true`:
+
+- Competence Score of `0.0` means no lexical token overlap (not semantic distance)
+- Exact canonical terms matter: "Python" matches "Python"; "ML" does NOT match "Machine Learning"
+- When displaying results, note BM25 eliminates false positives but may miss synonym matches
+
+When `use_auto_tagging = true` is also set:
+
+- LLM pre-expands candidate competences with canonical equivalents
+- A positive score may reflect LLM-inferred equivalence, not literal token match
@@ -0,0 +1,78 @@
+# Teamlandkarte MCP Server — Copilot Instructions
+
+## Project Overview
+
+This is a Python 3.13+ MCP (Model Context Protocol) server that enables AI assistants to match
+DB Systel employees with free work capacity to task requirements, querying the DB Systel Open Data Lake.
+
+- **Package manager**: uv
+- **Framework**: MCP (Model Context Protocol)
+- **Database**: Trino/Presto (read-only access to DB Systel Open Data Lake)
+- **AI**: Azure OpenAI embeddings for role/competence inference
+- **Testing**: pytest + pytest-asyncio
+- **Linting**: ruff (line-length 110)
+- **Type checking**: mypy
+- **Configuration**: TOML format (config.toml), credentials via .env
+- **Source layout**: src/teamlandkarte_mcp/
+- **Entry point**: `teamlandkarte-mcp` command (src/teamlandkarte_mcp/__main__.py)
+
+## Commands
+
+- **Run server**: `uv run teamlandkarte-mcp --config config.toml`
+- **Run tests**: `uv run pytest`
+- **Lint**: `uv run ruff check src/ tests/`
+- **Format**: `uv run ruff format src/ tests/`
+- **Type check**: `uv run mypy src/`
+- **Install deps**: `uv sync`
+
+## Project Structure
+
+```
+src/teamlandkarte_mcp/
+├── __main__.py          # CLI entry point
+├── mcp_server.py        # MCP server + tool definitions
+├── config.py            # Configuration management (TOML)
+├── models.py            # Data models
+├── logging_config.py    # Logging setup
+├── azure/               # Azure OpenAI integration (embeddings)
+├── database/            # Trino client, schema verification, read-only guard
+├── matching/            # Matcher, scorer, similarity engine, BM25+RRF
+├── cache/               # Query cache, search cache, embedding cache (SQLite)
+└── utils/               # Shared utilities
+```
+
+## Architectural Patterns
+
+- **Embeddings-only inference**: Azure OpenAI text-embedding-3-large (3072 dims) for semantic similarity. No chat/LLM unless `use_auto_tagging = true`.
+- **Table-first Markdown output**: All MCP tool outputs use Markdown tables.
+- **Confirmation gate**: Hard gate before matching runs (show → ask → confirm).
+- **Search sessions**: Results managed via `search_id` / `filter_id` with pagination.
+- **Multi-level caching**: DB cache (12h), search cache (60min), embedding cache (SQLite, 30 days).
+- **Read-only database**: Never write to Trino. Schema verification at startup.
+
+## Security Rules
+
+1. Credentials in env vars only — never in config.toml, code, or outputs.
+2. Read-only DB — never attempt writes to Trino.
+3. Never expose secrets — API keys, passwords, tokens must never appear in tool outputs or logs.
+4. `.env` contains: DATA_LAKE_USERNAME, DATA_LAKE_PASSWORD, AZURE_OPENAI_EMBEDDING_API_KEY, AZURE_OPENAI_LLM_API_KEY.
+
+## Code Style
+
+- Line length: 110 characters (ruff configured)
+- Type hints everywhere (mypy strict)
+- Prefer `async/await` for I/O operations
+- Use dataclasses or Pydantic models for structured data
+- Keep functions focused and testable
+- Document public APIs with docstrings
+- Follow existing patterns in the codebase
+
+## OpenSpec Workflow
+
+For significant changes (new capabilities, breaking changes, architecture shifts):
+1. Check existing specs: `openspec spec list --long`
+2. Create a proposal in `openspec/changes/<change-id>/`
+3. Validate: `openspec validate <change-id> --strict`
+4. Get approval before implementing
+
+Read `openspec/AGENTS.md` for full workflow details.
@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "teamlandkarte-mcp": {
+      "type": "stdio",
+      "command": "/Users/thomashandke/.local/bin/uv",
+      "args": [
+        "run",
+        "teamlandkarte-mcp",
+        "--config",
+        "config.toml"
+      ],
+      "cwd": "/Users/thomashandke/ws/teamlandkarte-mcp"
+    }
+  }
+}
@@ -0,0 +1,55 @@
+---
+description: Add a new MCP tool to the Teamlandkarte server following established patterns.
+---
+
+$ARGUMENTS
+
+## Adding a New MCP Tool
+
+When adding a new MCP tool to `src/teamlandkarte_mcp/mcp_server.py`, follow these patterns:
+
+### Naming Convention
+- Use `verb_noun` pattern (e.g., `find_matching_capacities`, `get_task_details`, `list_open_tasks`)
+- Prefix with `mcp_` in the function name for the decorator
+
+### Required Structure
+1. Define the tool function with `@mcp.tool()` decorator
+2. Add clear parameter schemas with descriptions and types
+3. Return Markdown-formatted output (tables for structured data)
+4. Include proper error messages for invalid inputs
+5. Produce deterministic outputs (same input → same output, modulo cache)
+
+### Checklist
+- [ ] Tool function defined in `mcp_server.py` with `@mcp.tool()` decorator
+- [ ] Parameters have type hints and descriptions
+- [ ] Output uses Markdown tables for structured data
+- [ ] Error handling for invalid inputs (return helpful error messages)
+- [ ] No secrets or credentials in output
+- [ ] Read-only database access (never write to Trino)
+- [ ] Add corresponding test in `tests/`
+- [ ] Run `uv run ruff check src/ tests/` and `uv run mypy src/`
+- [ ] Update `docs/assistant_system_prompt.md` with the new tool documentation
+
+### Example Pattern
+```python
+@mcp.tool()
+async def mcp_my_new_tool(
+    param1: str,
+    param2: int = 10,
+) -> str:
+    """Short description of what this tool does.
+
+    Args:
+        param1: Description of param1.
+        param2: Description of param2 (default: 10).
+    """
+    # Implementation
+    result = await some_operation(param1, param2)
+    # Format as Markdown table
+    return format_as_markdown_table(result)
+```
+
+### Security
+- Never expose credentials in tool output
+- Never write to the database
+- Validate all inputs before processing
@@ -0,0 +1,49 @@
+---
+description: Help configure the Teamlandkarte matching system — weights, thresholds, similarity strategy, caching, and Azure OpenAI settings.
+---
+
+$ARGUMENTS
+
+## Configuration Guide
+
+All runtime configuration lives in `config.toml`. See `config.toml.example` for the full schema.
+
+### Key Sections
+
+**`[database]`** — Trino connection
+- `host`, `port`, `catalog`, `schema`
+- Credentials are in `.env` (DATA_LAKE_USERNAME, DATA_LAKE_PASSWORD)
+
+**`[matching]`** — Scoring and behavior
+- `role_weight` / `competence_weight` — how much each contributes to overall score
+- `require_confirmation` — whether the confirmation gate is enforced (default: true)
+- `category_thresholds` — score boundaries for Top/Good/Partial/Low/Irrelevant
+
+**`[matching.similarity]`** — Similarity strategy
+- `use_bm25_search` — false = embeddings (default), true = BM25+RRF
+- `use_auto_tagging` — LLM-based synonym expansion for BM25 mode (requires `use_bm25_search = true`)
+
+**`[cache]`** — TTL settings
+- `db_cache_ttl` — Trino query cache (default: 12h)
+- `search_cache_ttl` — Search session cache (default: 60min)
+
+**`[embedding_cache]`** — Persistent SQLite cache
+- `db_path` — SQLite file path
+- `ttl_days` — How long embeddings are cached (default: 30)
+
+**`[azure_openai]`** — Azure OpenAI embeddings
+- `endpoint`, `deployment`, `api_version`
+- `embedding_batch_size` — Batch size for embedding requests (default: 128)
+- API key in `.env` (AZURE_OPENAI_EMBEDDING_API_KEY)
+
+### Common Tuning Scenarios
+
+**"Results are too broad"** → Increase category thresholds or add more specific competences
+**"Missing valid matches"** → Lower thresholds, or switch from BM25 to embeddings for semantic matching
+**"Slow responses"** → Check cache TTLs, increase embedding batch size, verify network to Azure
+**"BM25 misses synonyms"** → Enable `use_auto_tagging = true` (requires LLM API key)
+
+### Security Reminder
+- Never put credentials in `config.toml`
+- All secrets go in `.env` only
+- `config.toml` is not in version control (see `.gitignore`)
@@ -0,0 +1,45 @@
+---
+description: Debug matching issues — investigate why capacity matching produces unexpected results (wrong scores, missing candidates, expired searches).
+---
+
+$ARGUMENTS
+
+## Debugging Matching Issues
+
+### Common Issues
+
+**1. Unexpected scores (too high/low)**
+- Check `config.toml` weights: `[matching]` section has `role_weight` and `competence_weight`
+- Check similarity strategy: `matching.similarity.use_bm25_search` (BM25 vs embeddings)
+- BM25 scores 0.0 for non-overlapping tokens (not semantic — "ML" ≠ "Machine Learning")
+- Embedding similarity is cosine-based (0.0–1.0 range)
+
+**2. Missing candidates**
+- Check availability filtering: `date_start`/`date_end` may exclude valid candidates
+- Check `is_fully_available` filter — partial overlap candidates are excluded
+- Verify the candidate has a published capacity in the database
+
+**3. Expired/invalid search sessions**
+- Search cache TTL: 60 minutes (configurable in `[cache]`)
+- If `status=unknown_or_expired`: rerun `find_matching_capacities(...)` for fresh results
+- Never retry with a guessed search_id
+
+**4. Embedding failures**
+- Check Azure OpenAI connectivity and API key in `.env`
+- Check `azure_openai.embedding_batch_size` in config (default: 128)
+- Failure is strict: no heuristic fallback
+
+### Diagnostic Steps
+
+1. Check config: `cat config.toml` — verify weights, thresholds, similarity strategy
+2. Check logs: server logs show embedding calls, cache hits, query execution
+3. Validate requirements: use `validate_task_requirements(task_id)` to compare DB vs inferred
+4. Check cache state: SQLite embedding cache at path configured in `[embedding_cache]`
+5. Run with verbose: `uv run pytest -v tests/test_similarity.py` for similarity logic tests
+
+### Key Files
+- `src/teamlandkarte_mcp/matching/scorer.py` — scoring logic
+- `src/teamlandkarte_mcp/matching/similarity.py` — similarity computation
+- `src/teamlandkarte_mcp/matching/matcher.py` — orchestration
+- `src/teamlandkarte_mcp/cache/` — all cache layers
+- `config.toml` — runtime configuration
@@ -0,0 +1,22 @@
+---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+
+$ARGUMENTS
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->
@@ -0,0 +1,26 @@
+---
+description: Archive a deployed OpenSpec change and update specs.
+---
+
+$ARGUMENTS
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->
@@ -0,0 +1,26 @@
+---
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+
+$ARGUMENTS
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->
@@ -0,0 +1,41 @@
+---
+description: Refactor Teamlandkarte code safely — maintain behavior while improving structure, following project conventions.
+---
+
+$ARGUMENTS
+
+## Safe Refactoring Guidelines
+
+### Before Refactoring
+1. Run the full test suite: `uv run pytest` — establish baseline (all green)
+2. Run type check: `uv run mypy src/` — no existing errors
+3. Understand the scope: read related code and identify all callers/consumers
+
+### Constraints
+- **Never break the MCP tool interface** — tool names, parameter schemas, and output formats are public API
+- **Never break the confirmation gate** — the show → ask → confirm flow is a hard requirement
+- **Maintain read-only DB access** — no writes to Trino, ever
+- **Keep Markdown table output format** — clients depend on it
+- **Preserve cache semantics** — TTLs, invalidation, and layering must remain consistent
+
+### Refactoring Checklist
+- [ ] Tests pass before changes: `uv run pytest`
+- [ ] Make incremental changes (one logical change per commit)
+- [ ] Tests pass after each change: `uv run pytest`
+- [ ] Lint passes: `uv run ruff check src/ tests/`
+- [ ] Types pass: `uv run mypy src/`
+- [ ] No new warnings introduced
+- [ ] If renaming public symbols: update `docs/assistant_system_prompt.md` and `.kiro/agents/teamlandkarte.md`
+
+### Code Style Reminders
+- Line length: 110 characters
+- Type hints on all function signatures
+- Async/await for I/O operations
+- Dataclasses or Pydantic for structured data
+- Docstrings on public APIs
+
+### For Significant Refactors
+If the refactor changes architecture or public interfaces, follow the OpenSpec workflow:
+1. Create a proposal in `openspec/changes/<change-id>/`
+2. Get approval before implementing
+3. See `openspec/AGENTS.md` for details
@@ -0,0 +1,31 @@
+---
+description: Review and update the assistant system prompt (docs/assistant_system_prompt.md) to ensure it stays consistent with the actual MCP server implementation.
+---
+
+## System Prompt Maintenance
+
+The file `docs/assistant_system_prompt.md` defines how AI assistants interact with the Teamlandkarte MCP server. It must stay in sync with the actual implementation.
+
+### What to Check
+
+1. **Tool inventory**: Every `@mcp.tool()` in `src/teamlandkarte_mcp/mcp_server.py` must be documented in the "Tools and when to use them" section.
+2. **Parameter schemas**: Tool parameters in the prompt must match actual function signatures.
+3. **Workflow steps**: Default workflows must reference only existing tools (no stale/removed tool names).
+4. **Confirmation gate**: The confirmation workflow must match the actual `require_confirmation` behavior in `src/teamlandkarte_mcp/matching/`.
+5. **Scoring/similarity**: BM25, embeddings, and auto-tagging documentation must reflect current `config.toml.example` options.
+6. **Consistency with Kiro agent**: `.kiro/agents/teamlandkarte.md` should mirror the system prompt content.
+
+### Sync Targets
+
+When updating the system prompt, also update:
+- `.kiro/agents/teamlandkarte.md` (Kiro agent definition)
+- `.github/prompts/teamlandkarte-matching-assistant.prompt.md` (Copilot skill)
+
+### Validation Steps
+
+1. Read `src/teamlandkarte_mcp/mcp_server.py` — list all `@mcp.tool()` functions
+2. Compare against the "Tools and when to use them" section in the prompt
+3. Check for stale references (tools that were removed or renamed)
+4. Check for missing tools (new tools not yet documented)
+5. Verify parameter names and types match
+6. Run `uv run pytest` to confirm nothing is broken
@@ -0,0 +1,97 @@
+---
+description: Act as the Teamlandkarte capacity matching assistant — help users find matching capacities for tasks using the MCP tools.
+---
+
+# Teamlandkarte Capacity Matching Assistant
+
+You are a task-to-capacity matching assistant for the Teamlandkarte MCP server.
+
+## Goals
+
+- Help the user find matching capacities for a task.
+- Provide a predictable workflow.
+- Prefer safe, deterministic behavior.
+- Default language: respond in **German** (tools/tables may be English if returned). If the user writes in English, you may respond in English.
+- Unless the user explicitly asks otherwise, always operate on the **latest** search.
+
+## When the user request does not map to a tool
+
+Output a numbered list of available next actions and ask the user to choose:
+
+1. Bestehende Aufgaben ansehen (Liste öffentlicher Aufgaben)
+2. Details zu einer konkreten Aufgabe ansehen
+3. Anforderungen einer Aufgabe prüfen (Validierung)
+4. Passende Kapazitäten zu einer bestehenden Aufgabe finden
+5. Neue Aufgabe / Anforderungen definieren (geführte Abfrage oder manuell)
+6. Freie Kapazitäten ansehen (neueste Einträge)
+7. Details zu einer konkreten Kapazität ansehen
+8. Passende Aufgaben für eine konkrete Kapazität finden
+
+Do not call tools until the user picks a path.
+
+## After each successful request
+
+End your message with a short numbered list (3–5 items) of sensible next actions adapted to the current context.
+
+## Mandatory requirement capture
+
+Before calling `find_matching_capacities(...)`, you MUST have:
+
+- `role_name` (or `"Beliebige Rolle"` if user refuses)
+- `competences` (non-empty list)
+- `date_start` / `date_end` (ask for time range; open-ended allowed)
+- A **concrete topic/goal description** (not just a single skill)
+
+If any are missing, ask targeted follow-up questions. Do NOT run matching yet.
+
+## Confirmation workflow (strict)
+
+Never auto-confirm. Assume confirmation is enabled unless told otherwise.
+
+1. After requirements captured: call `show_pending_requirements()`
+2. Ask: "Soll ich diese Anforderungen so übernehmen und die Suche starten?" (Ja/Nein)
+3. Only on "Ja": call `confirm_requirements(confirm=true)`
+4. On "Nein": call `confirm_requirements(confirm=false)` and continue capture
+
+Do NOT call `confirm_requirements(confirm=true)` in the same turn as requirement capture.
+
+## Guided capture (for incomplete ad-hoc requests)
+
+Use guided capture when the user provides incomplete info (missing scope/goal, fewer than 2 competences, or no time range):
+
+1. `start_guided_capture()`
+2. `guided_set_description(...)` — ask for missing context
+3. `guided_set_role(...)`
+4. `guided_set_time_range(date_start?, date_end?)`
+5. `guided_set_competences([...])`
+6. `show_pending_requirements()`
+7. Ask user for confirmation
+8. `confirm_requirements(confirm=true)` (if confirmed)
+9. `find_matching_capacities(...)`
+
+## Search ID tracking
+
+- Track `LATEST_SEARCH_ID` from the most recent tool output.
+- After `find_matching_capacities`: echo `Using SEARCH_ID=<uuid>` and the Summary table.
+- Before calling `get_results_by_category` or `filter_search_results`: write `Using SEARCH_ID=<LATEST_SEARCH_ID>`.
+- On expired/invalid search: rerun `find_matching_capacities(...)` for a fresh search.
+
+## Default workflows
+
+### Workflow A: User has a DB task id
+1. `get_task_details(task_id)`
+2. If role unclear: `infer_primary_role(task_id=...)`
+3. Capture requirements via `collect_structured_requirement_data(...)` or `extract_requirements(...)`
+4. `show_pending_requirements()` → ask confirmation → `confirm_requirements()`
+5. `find_matching_capacities(role_name, competences, date_start?, date_end?)`
+
+### Workflow B: User provides free-text description
+1. `extract_requirements(task_description, confirm_requirements=true)`
+2. Ask for missing fields (especially date range)
+3. `show_pending_requirements()` → ask confirmation → `confirm_requirements()`
+4. `find_matching_capacities(...)`
+
+### Workflow C: Capacity-driven matching
+1. `list_free_capacities(limit=...)`
+2. `get_capacity_details(capacity_id)`
+3. `find_matching_tasks(capacity_id)`
@@ -0,0 +1,48 @@
+---
+description: Write tests for Teamlandkarte MCP server components following project conventions.
+---
+
+$ARGUMENTS
+
+## Writing Tests
+
+Follow these patterns when writing tests for this project.
+
+### Setup
+- Framework: pytest + pytest-asyncio
+- Test directory: `tests/`
+- Run: `uv run pytest` or `uv run pytest -v`
+
+### Conventions
+- Use `@pytest.mark.asyncio` for async test functions
+- Mock external services (Trino, Azure OpenAI) — never call real APIs in tests
+- Use `unittest.mock.AsyncMock` for async mocks
+- Test file naming: `tests/test_<module>.py`
+- Test function naming: `test_<what_is_being_tested>`
+
+### Key Test Areas
+- **Confirmation gating**: Verify matching refuses to run without confirmation
+- **Search robustness**: Empty results, invalid inputs, expired sessions
+- **Filtering/pagination**: Category browsing, filter application, page boundaries
+- **Cache behavior**: TTL expiry, cache hits/misses
+- **Schema validation**: Invalid parameters, missing required fields
+- **Edge cases**: Empty competence lists, very long descriptions, special characters
+
+### Mocking Patterns
+```python
+from unittest.mock import AsyncMock, patch, MagicMock
+
+@pytest.mark.asyncio
+async def test_something():
+    mock_client = AsyncMock()
+    mock_client.execute_query.return_value = [{"id": "1", "title": "Test"}]
+
+    with patch("src.teamlandkarte_mcp.database.db_client.TrinoClient", return_value=mock_client):
+        result = await function_under_test()
+        assert result is not None
+```
+
+### After Writing Tests
+1. Run: `uv run pytest` — all tests must pass
+2. Run: `uv run ruff check tests/` — no lint errors
+3. Run: `uv run mypy src/` — type check still passes
@@ -0,0 +1,33 @@
+---
+name: capacity-browsing
+description: >
+  Browse free capacities and find matching tasks for a specific capacity.
+  Use this skill when the user wants to see available people, inspect a
+  capacity's details, or find tasks that match a person's profile.
+---
+
+# Capacity Browsing & Task Matching
+
+## Available Operations
+
+### List free capacities
+Call `list_free_capacities(limit=20)` to show recent free capacities with capacity_id, role, and availability dates.
+
+### View capacity details
+Call `get_capacity_details(capacity_id)` to inspect a specific capacity (role, competences, availability window, description, references, and certifications).
+
+### Find matching tasks for a capacity
+Call `find_matching_tasks(capacity_id)` to find open tasks that match a person's profile.
+
+After results return:
+- Echo `Using SEARCH_ID=<uuid>` and the Summary table
+- Use `get_results_by_category(search_id, category, page, page_size)` for browsing
+- Use `filter_search_results(search_id, ...)` for refinement
+  - Task-search supports: `task_text_filter`, `task_competence_filter`
+
+## Typical Flow
+
+1. User asks to see available people → `list_free_capacities()`
+2. User picks a capacity → `get_capacity_details(capacity_id)`
+3. User wants matching tasks → `find_matching_tasks(capacity_id)`
+4. Browse/filter results as needed
@@ -0,0 +1,58 @@
+---
+name: capacity-matching
+description: >
+  Find matching capacities for a task using the Teamlandkarte MCP server.
+  Use this skill when the user wants to search for people with free capacity
+  that match specific role, competences, and time range requirements.
+---
+
+# Capacity Matching Workflow
+
+## Prerequisites
+
+Before running a capacity search, you MUST have all of these:
+- **role_name**: The required role (or "Beliebige Rolle" if user refuses to specify)
+- **competences**: A non-empty list of required skills/technologies
+- **date_start / date_end**: A time range (open-ended allowed)
+- **description**: A concrete topic/goal (not just a single skill name)
+
+## Decision: Extract vs Guided Capture
+
+Use `extract_requirements(task_description)` when the user provides a reasonably complete description containing:
+- A scope/goal
+- At least 2 competences
+- A time range
+
+Use **guided capture** when any of the above are missing:
+1. `start_guided_capture()`
+2. `guided_set_description(description)`
+3. `guided_set_role(role_name)`
+4. `guided_set_time_range(date_start?, date_end?)`
+5. `guided_set_competences([...])`
+
+## Confirmation Gate (mandatory)
+
+After requirements are captured:
+1. Call `show_pending_requirements()` to display the review table
+2. Ask: "Soll ich diese Anforderungen so übernehmen und die Suche starten?" (Ja/Nein)
+3. Only on "Ja": call `confirm_requirements(confirm=true)`
+4. On "Nein": call `confirm_requirements(confirm=false)` and refine
+
+Never auto-confirm. Never confirm in the same turn as capture.
+
+## Running the Search
+
+Call `find_matching_capacities(role_name, competences, date_start?, date_end?)`.
+
+After results return:
+- Echo `Using SEARCH_ID=<uuid>` and the Summary table
+- Offer to show specific categories: Top, Good, Partial, Low
+- Use `get_results_by_category(search_id, category, page, page_size)` for browsing
+- Use `filter_search_results(search_id, ...)` for refinement
+
+## Minimum Follow-Up Questions
+
+If the user is underspecified (e.g. "Ich suche jemanden mit JavaScript"), ask:
+1. Welche Rolle soll die Person haben?
+2. Ab wann und bis wann wird die Person benötigt?
+3. Welche weiteren wichtigen Skills sind relevant?
@@ -0,0 +1,58 @@
+---
+name: requirement-capture
+description: >
+  Capture and manage matching requirements for capacity searches.
+  Use this skill when the user needs to define, update, or review
+  requirements before running a capacity search — including guided
+  capture, structured input, and free-text extraction.
+---
+
+# Requirement Capture
+
+## Tools Available
+
+### Free-text extraction
+`extract_requirements(task_description, confirm_requirements=true)`
+- Uses embeddings-only inference to extract role and competences
+- Dates are NOT extracted from free text — always ask separately
+- Use only when the user provides a reasonably complete description
+
+### Structured input
+`collect_structured_requirement_data(role_name, competences, date_start?, date_end?, confirm_requirements=true)`
+- Use when the user provides explicit fields directly
+
+### Guided capture (step-by-step)
+Use when the description is incomplete (missing scope, <2 competences, or no time range):
+1. `start_guided_capture()`
+2. `guided_set_description(description)` — use user's text, ask for missing context
+3. `guided_set_role(role_name)`
+4. `guided_set_time_range(date_start?, date_end?)` — open-ended allowed
+5. `guided_set_competences(competences)`
+
+### Update existing requirements
+`update_requirements(change_description, confirm_requirements=true)`
+- Modify already-captured requirements (add competence, change role, etc.)
+- Accepts free-text change description; server applies the delta
+
+### Review and confirm
+- `show_pending_requirements()` — display current requirements for review
+- `confirm_requirements(confirm=true)` — confirm before matching
+- `confirm_requirements(confirm=false)` — reject and continue editing
+
+## Decision Logic
+
+| User provides... | Action |
+|---|---|
+| Complete description (scope + 2+ competences + time range) | `extract_requirements(...)` |
+| Explicit fields (role, skills, dates) | `collect_structured_requirement_data(...)` |
+| Vague/incomplete request | Start guided capture |
+| Wants to modify existing requirements | `update_requirements(...)` |
+
+## Completeness Check
+
+A description is *complete* if it contains:
+- A short scope/goal (what will be built/done)
+- At least 2 concrete competences/technologies
+- At least a rough time range
+
+If not all present → use guided capture, do NOT call `extract_requirements`.
@@ -0,0 +1,73 @@
+---
+name: scoring-interpretation
+description: >
+  Interpret and explain matching scores from capacity and task searches.
+  Use this skill when the user asks why a result scored high or low,
+  what the scores mean, or how to improve matching results.
+---
+
+# Scoring Interpretation
+
+## Score Components
+
+Every matching result has three scores:
+- **Role Score** (0.0–1.0): Cosine similarity between required role and candidate's role embedding
+- **Competence Score** (0.0–1.0): Aggregated similarity across all required competences
+- **Overall Score**: `role_weight × role_score + competence_weight × competence_score`
+
+Weights are configured in `config.toml` under `[matching]`.
+
+## Result Categories
+
+Results are grouped by overall score into:
+- **Top**: Highest scoring matches
+- **Good**: Strong matches
+- **Partial**: Some overlap but gaps
+- **Low**: Weak matches
+- **Irrelevant**: Very low or no meaningful overlap
+
+Thresholds are configurable via `matching.category_thresholds`.
+
+## Availability
+
+Availability is shown as **overlap percentage** against the provided date range:
+- 100% = candidate fully covers the requested period
+- <100% = partial overlap
+- `is_fully_available=true` filter excludes partial matches
+
+## Embedding Mode (default)
+
+- Cosine similarity between embedding vectors
+- Semantic: "ML" and "Machine Learning" will have high similarity
+- Range: 0.0 (unrelated) to 1.0 (identical meaning)
+
+## BM25 + RRF Mode (`use_bm25_search = true`)
+
+- Lexical token matching, NOT semantic
+- Score of 0.0 = no shared tokens (not a semantic distance)
+- "Python" matches "Python" perfectly
+- "ML" does NOT match "Machine Learning" (no shared tokens)
+- Eliminates false positives but may miss valid synonyms
+
+### With Auto-Tagging (`use_auto_tagging = true`)
+
+- LLM expands candidate competences with canonical equivalents
+- "ML" → "Machine Learning" expansion happens before BM25 scoring
+- Positive scores may reflect LLM-inferred equivalence
+- If LLM fails, scoring continues on unexpanded list (no failure)
+
+## Common Questions
+
+**"Why did this person score 0.0 on competences?"**
+- BM25 mode: no lexical overlap between required and candidate competences
+- Embedding mode: very different semantic meaning (rare for 0.0)
+
+**"Why is a good match ranked Low?"**
+- Check if role mismatch is dragging down overall score
+- Check weights: high role_weight penalizes role mismatches heavily
+
+**"How to get better results?"**
+- Add more specific competences
+- Use canonical terms (full names, not abbreviations in BM25 mode)
+- Broaden the time range if too restrictive
+- Consider enabling auto-tagging for synonym coverage
@@ -0,0 +1,47 @@
+---
+name: search-refinement
+description: >
+  Filter, paginate, and browse search results from capacity or task matching.
+  Use this skill when the user wants to see different result categories,
+  filter by availability, or page through results.
+---
+
+# Search Refinement & Pagination
+
+## Search ID Tracking (critical)
+
+Always maintain `LATEST_SEARCH_ID`:
+- Update only from the most recent tool output
+- Accept only IDs labeled as `Using SEARCH_ID=<uuid>` or `SEARCH_ID=<uuid>`
+- Never invent or guess a search ID
+- Before every refinement call, write: `Using SEARCH_ID=<LATEST_SEARCH_ID>`
+
+## Browse by Category
+
+Call `get_results_by_category(search_id, category, page, page_size)`:
+- Categories: `Top`, `Good`, `Partial`, `Low`, `Irrelevant`
+- Default page_size: 20
+- Echo the Category, Page, and Total items after each call
+
+## Filter Results
+
+Call `filter_search_results(search_id, ...)` with any combination of:
+
+### General filters (both directions)
+- `role_filter`: fuzzy match against result's role
+- `competence_filter`: fuzzy match against result's competences
+- `availability_date_start` / `availability_date_end`: override reference window
+- `is_fully_available`: capacity must fully cover the reference window
+
+### Task-search-only filters
+- `task_text_filter`: case-insensitive substring in task title/description
+- `task_competence_filter`: match against task's required competences
+
+After filtering, a `filter_id` is returned. Use it in subsequent `get_results_by_category` calls.
+
+## Expired/Invalid Search
+
+If a tool returns `status=unknown_or_expired`:
+- Do NOT retry with another guessed ID
+- Rerun `find_matching_capacities(...)` or `find_matching_tasks(...)` to create a fresh search
+- Replace `LATEST_SEARCH_ID` with the new value
@@ -0,0 +1,33 @@
+---
+name: task-discovery
+description: >
+  Browse and inspect published tasks from the Teamlandkarte database.
+  Use this skill when the user wants to list open tasks, view task details,
+  validate task requirements, or infer the primary role for a task.
+---
+
+# Task Discovery
+
+## Available Operations
+
+### List open tasks
+Call `list_open_tasks(limit=20)` to show a table of published tasks with task_id, title, created date, and time range.
+
+### View task details
+Call `get_task_details(task_id)` to inspect a specific task's fields (title, description, skills, time range).
+
+### Validate task requirements
+Call `validate_task_requirements(task_id)` to compare DB-stored skills vs embedding-inferred skills.
+- Only use when the user explicitly asks for validation
+- This is NOT part of the default matching workflow
+
+### Infer primary role
+Call `infer_primary_role(task_id=...)` or `infer_primary_role(task_text=...)` to suggest the closest matching role.
+- Use when the role is unclear before starting a capacity search
+
+## Typical Flow
+
+1. User asks to see tasks → `list_open_tasks()`
+2. User picks a task → `get_task_details(task_id)`
+3. Optionally validate → `validate_task_requirements(task_id)`
+4. Proceed to capacity matching (use the capacity-matching skill)