chore: track Claude Code project config and reference docs

- .gitignore: add .kotlin/ scratch dir + .claude/settings.local.json
  (local user permission overrides should not be shared)
- .claude/: hooks (post-tool-call, pre-bash, on-stop), settings.json
  (project hook config), skills (api-feature, code-review, debugging,
  pr-artifacts), and adr command — all project-shared
- 08-kore-runtime.md: original feature spec referenced from CLAUDE.md
- claude-code-harness-engineering-guide-v2.md: harness engineering
  reference also cited from CLAUDE.md
- .planning/config.json: persist _auto_chain_active flag

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hermanngeorge15

.claude/commands/adr.md

@@ -0,0 +1,9 @@
+You are creating an Architecture Decision Record for the kore-runtime Kotlin/Spring WebFlux project.
+
+1. Use a sub-agent to research the decision context by reading the relevant code,
+   existing ADRs in docs/adr/, and the current GH issue if one is open.
+2. Number the new ADR: `ls docs/adr/ | sort | tail -1` -> increment NNNN.
+3. Use the template at `.claude/skills/pr-artifacts/adr_template.md`.
+4. Write the ADR in a sub-agent with a clean context — do not inline it.
+5. Output the final file path and first 10 lines as confirmation.
+6. Create a GH issue for discussion: `gh issue create --label adr --title "ADR NNNN: title"`

.claude/hooks/on-stop.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+# Skip if no Gradle wrapper yet (project not scaffolded)
+[ -f "./gradlew" ] || exit 0
+
+# 1. Run fast unit tests silently — surface errors only
+TEST_OUTPUT=$(./gradlew test -q 2>&1)
+if [ $? -ne 0 ]; then
+  echo "Unit tests failed:" >&2
+  echo "$TEST_OUTPUT" >&2
+  exit 2
+fi
+
+# 2. Coverage check — re-engage agent if it drops
+COVERAGE=$(./gradlew jacocoTestCoverageVerification -q 2>&1)
+if [ $? -ne 0 ]; then
+  echo "Coverage dropped below threshold. Increase test coverage before finishing." >&2
+  exit 2
+fi
+
+# 3. Verify GH issue is linked on feature branches
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+if [[ "$BRANCH" == feature/* ]] || [[ "$BRANCH" == feat/* ]]; then
+  ISSUE_LINKED=$(git log origin/main..HEAD --format="%s %b" 2>/dev/null | grep -cE "#[0-9]+")
+  if [ "$ISSUE_LINKED" -eq 0 ]; then
+    echo "No GitHub issue linked in commit history. Add before finishing." >&2
+    exit 2
+  fi
+
+  # Create draft PR if it doesn't exist
+  gh pr create --fill --draft 2>/dev/null || true
+fi

.claude/hooks/post-tool-call.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+# Skip if no Gradle wrapper yet (project not scaffolded)
+[ -f "./gradlew" ] || exit 0
+
+# Run ktlint + compile in parallel, silent on success
+OUTPUT=$(./gradlew ktlintCheck compileKotlin -q 2>&1)
+
+if [ $? -ne 0 ]; then
+  echo "Build/lint errors:" >&2
+  echo "$OUTPUT" >&2
+  exit 2   # exit 2 = re-engage agent to fix errors before finishing
+fi
+
+# SUCCESS: completely silent — nothing added to context

.claude/hooks/pre-bash.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+COMMAND="$CLAUDE_TOOL_INPUT_COMMAND"
+
+# Block direct Flyway migration runs
+if echo "$COMMAND" | grep -qE "flyway:migrate|flywayMigrate|migrate --env"; then
+  echo "ERROR: Do not run migrations directly. Ask the user to run them." >&2
+  exit 1
+fi
+
+# Block production deployments
+if echo "$COMMAND" | grep -qE "deploy.*(prod|production)|helm upgrade.*prod"; then
+  echo "ERROR: Production deployments require explicit human approval." >&2
+  exit 1
+fi
+
+# Block force-push
+if echo "$COMMAND" | grep -q "git push --force\|git push -f"; then
+  echo "ERROR: Force push is not allowed. Use --force-with-lease and confirm with user." >&2
+  exit 1
+fi
+
+# Block dropping databases
+if echo "$COMMAND" | grep -qiE "drop (database|schema)"; then
+  echo "ERROR: Dropping databases requires human confirmation." >&2
+  exit 1
+fi

.claude/settings.json

@@ -0,0 +1,20 @@
+{
+  "hooks": {
+    "postToolCall": [
+      {
+        "matcher": "Write|Edit",
+        "command": ".claude/hooks/post-tool-call.sh"
+      }
+    ],
+    "preBash": [
+      {
+        "command": ".claude/hooks/pre-bash.sh"
+      }
+    ],
+    "stop": [
+      {
+        "command": ".claude/hooks/on-stop.sh"
+      }
+    ]
+  }
+}

.claude/skills/api-feature/SKILL.md

@@ -0,0 +1,22 @@
+# API Feature Development Skill
+Follow this 7-phase workflow for new features in kore-runtime.
+
+## Phases
+1. **Discovery** — read existing similar modules; identify patterns in hexagonal architecture
+2. **Exploration** — use a sub-agent to trace the relevant port/adapter boundaries
+3. **Clarifying Questions** — surface ambiguities before writing any code
+4. **Architecture** — define contracts (port interfaces, sealed result types, DTOs)
+   -> If decision has architectural impact: create ADR draft in docs/adr/
+5. **Implementation** — port interface -> adapter -> service -> tests for each layer
+6. **Quality Review** — run `./gradlew ktlintCheck test` and fix all issues
+7. **PR Preparation** — write changelog entry, update KDoc, run /skill pr-artifacts
+
+## Kore-Runtime Patterns
+- All LLM backends implement the same port interface
+- AgentResult sealed class: Success | BudgetExceeded | ToolError | LLMError
+- Event bus is pluggable: Kotlin Flows default, Kafka opt-in
+- Every LLM call and tool use gets an OpenTelemetry span
+- Coroutines everywhere — no blocking calls
+
+## Response Template
+After each phase, state: what was done, what was decided, what's next.

.claude/skills/code-review/SKILL.md

@@ -0,0 +1,20 @@
+# Code Review Skill
+You are performing a code review for the kore-runtime Kotlin/Spring WebFlux codebase.
+
+## Review Checklist
+- [ ] Coroutine usage correct (no blocking calls in suspend context)
+- [ ] Error handling — sealed classes (AgentResult), no silent catches, proper logging
+- [ ] Test coverage — new public functions have tests
+- [ ] No hardcoded configuration — use @ConfigurationProperties or application.yml
+- [ ] No `var` — always `val`, refactor if mutation seems needed
+- [ ] No `!!` without a comment explaining why it's safe
+- [ ] Hexagonal architecture respected — LLM backends, storage, event bus are ports/adapters
+- [ ] No Thread.sleep() or raw threads — use coroutines
+- [ ] Function length < 30 lines; complexity reasonable
+- [ ] Immutable data classes for value objects
+- [ ] No credentials or secrets in code
+- [ ] KDoc on all public APIs
+
+## Output Format
+Return: summary, blocking issues (must fix), suggestions (nice to have).
+Cite each issue as `filepath:line — description`.

.claude/skills/debugging/SKILL.md

@@ -0,0 +1,22 @@
+# Debugging Skill
+You are debugging an issue in the kore-runtime Kotlin/Spring WebFlux codebase.
+
+## Process
+1. **Reproduce** — write a failing test that demonstrates the bug
+2. **Isolate** — use a sub-agent to trace the call chain from entry point to failure
+3. **Hypothesize** — form a single testable hypothesis before changing code
+4. **Fix** — make the minimal change that fixes the failing test
+5. **Verify** — run `./gradlew test` to confirm fix and no regressions
+6. **Document** — add a comment if the bug was non-obvious
+
+## Common kore-runtime Pitfalls
+- Blocking call inside a coroutine scope (use withContext(Dispatchers.IO) for blocking I/O)
+- Missing suspend modifier on function that calls suspend functions
+- MCP protocol message serialization/deserialization mismatch
+- Agent loop not breaking on BudgetExceeded result
+- OpenTelemetry span not closed on error path
+
+## What NOT to do
+- Do not change multiple things at once — one hypothesis, one change, one test
+- Do not add try/catch to silence the error — find the root cause
+- Do not skip writing the regression test

.claude/skills/pr-artifacts/SKILL.md

@@ -0,0 +1,67 @@
+# PR Artifacts Skill
+You are preparing a pull request for the kore-runtime Kotlin/Spring WebFlux codebase.
+Produce ALL of the following before calling /gsd:ship or opening a PR for review.
+
+## 1. GitHub Issue
+- Verify the PR is linked to a GH issue: `gh issue view <N>` or create one:
+  `gh issue create --title "<summary>" --body "..."`
+- Set the issue reference in the PR body: "Closes #N"
+
+## 2. ADR (Architecture Decision Record)
+Required when the PR introduces or changes:
+- A new framework, library, or runtime dependency
+- An infrastructure or deployment topology change
+- A security or authentication pattern
+- A data model or schema decision with long-term impact
+- A cross-module contract (MCP protocol, LLM backend interface, event schema)
+
+Not required for: bug fixes, refactors within existing patterns, test additions.
+
+Use the template at `adr_template.md`. File as `docs/adr/NNNN-short-title.md`.
+NNNN = next sequential number. Commit with message: `docs(adr): NNNN short title`
+
+## 3. Documentation Update
+Update whichever of the following applies:
+- `docs/` — API docs, runbooks, architecture diagrams
+- `README.md` — setup instructions, environment variables
+- KDoc on all public APIs — if public interface changed
+- `CHANGELOG.md` — one-line entry under Unreleased: `- <summary>`
+
+## 4. Tests
+Verify the following before shipping:
+- [ ] Unit tests for every new public function (`*Test.kt` in same package)
+- [ ] Integration test for any new endpoint or MCP handler
+- [ ] Test names follow: `should <expected behaviour> when <condition>`
+- [ ] `./gradlew test` passes silently
+- [ ] `./gradlew jacocoTestCoverageVerification` passes (80% minimum)
+
+## 5. Verification Report
+Produce a brief checklist in the PR description:
+- [ ] All unit tests pass
+- [ ] Coverage >= 80%
+- [ ] ktlint clean (no new violations)
+- [ ] ADR written (or explicitly not required — state why)
+- [ ] Docs updated
+- [ ] GH issue linked
+- [ ] Manual smoke test: describe what you tested and the outcome
+
+## PR Description Template
+```
+## Summary
+[1-2 sentences: what changed and why]
+
+## Changes
+- [bullet: concrete change]
+- [bullet: concrete change]
+
+## Verification
+- [ ] Unit tests pass
+- [ ] Coverage >= 80%
+- [ ] ktlint clean
+- [ ] ADR: docs/adr/NNNN-title.md (or: not required because ...)
+- [ ] Docs updated: [which files]
+- [ ] Issue: Closes #N
+
+## Manual Testing
+[What you ran and what you observed]
+```

.claude/skills/pr-artifacts/adr_template.md

@@ -0,0 +1,24 @@
+# NNNN. [Short Title]
+
+Date: YYYY-MM-DD
+Status: [Proposed | Accepted | Deprecated | Superseded by NNNN]
+
+## Context
+[What is the situation? What problem are we solving? What constraints exist?]
+
+## Decision
+[What did we decide to do?]
+
+## Consequences
+
+### Positive
+- [benefit]
+
+### Negative / Trade-offs
+- [cost or risk]
+
+### Neutral
+- [side effect]
+
+## Alternatives Considered
+[What else was evaluated and why was it rejected?]