Upload folder using huggingface_hub

.claude/commands/benchmark.md

@@ -0,0 +1,61 @@
+Run a TAU-bench evaluation end-to-end and present results.
+
+**Syntax:** `/benchmark <config> [mode] [extra-args]`
+
+**Arguments:**
+
+- `config` (from $ARGUMENTS, first word) — profile name: `haiku`, `sonnet`, `gpt4.1-mini`, `gpt4.1`, `fast`, `default`
+- `mode` (from $ARGUMENTS, second word, optional) — `baseline` (default), `compare`, or `ace-only`
+- `extra-args` (from $ARGUMENTS, remaining words) — forwarded verbatim to the CLI
+
+**Workflow:**
+
+1. **Parse arguments** from `$ARGUMENTS`:
+   - Split into: `config` (first word), `mode` (second word if it matches baseline/compare/ace-only, else default to baseline), and `extra-args` (the rest)
+
+2. **Build the command:**
+   ```
+   uv run python scripts/run_tau_benchmark.py --config <config> --save-detailed <mode-flag> <extra-args>
+   ```
+   Mode flags:
+   - `baseline` → `--skip-ace`
+   - `compare` → `--compare`
+   - `ace-only` → (no flag)
+
+3. **Show the command** to the user before running
+
+4. **Run the command** with a 10-minute timeout (TAU-bench runs are long)
+
+5. **Find the latest result**: list `tau_benchmark_results/` sorted by modification time, pick the newest `*_summary.json`
+
+6. **Read the summary JSON** and present results using this format:
+
+   For baseline runs:
+   ```
+   ## <Mode>: <Model Short Name> — <Domain> (test split, k=<k>)
+
+   | Setting | Value |
+   |---------|-------|
+   | Model | <exact model id> |
+   | User LLM | <user_llm> |
+   | Domain | <domain> |
+   | Split | <split> (<N> tasks) |
+   | Max steps | <max_steps> |
+   | Seed | <seed> |
+
+   | Metric | Score |
+   |--------|-------|
+   | pass^1 | XX.XX% |
+   | pass^2 | XX.XX% |
+   | ... | ... |
+   ```
+
+   For comparison runs, add Baseline / ACE / Delta columns.
+
+**Examples:**
+- `/benchmark haiku` → baseline haiku run
+- `/benchmark haiku compare` → baseline vs ACE comparison
+- `/benchmark fast` → quick smoke test (3 tasks, k=1)
+- `/benchmark sonnet compare --domain retail` → sonnet comparison on retail
+
+**Key fields** to always include in the results table: exact model ID, user LLM, domain, split + task count, skillbook status, and all pass^k metrics.

.claude/commands/checkout-branch.md

@@ -0,0 +1,64 @@
+Switch to an existing branch by checking out its worktree, or creating one if needed.
+
+**Arguments:** $ARGUMENTS should be the branch name (full or partial match)
+
+**Examples:**
+- `/checkout-branch feature/john/add-caching` → switch to branch (create worktree if needed)
+- `/checkout-branch add-caching` → partial match, resolve to full branch name
+- `/checkout-branch fix` → if multiple matches, list them and ask to be specific
+
+**Steps:**
+1. Parse branch name from arguments
+2. Fetch latest from remote: `git fetch --prune`
+3. Get all branches (local + remote): `git branch -a --format='%(refname:short)'`
+4. Resolve branch name:
+   - Exact match: use directly
+   - Partial match: find branches containing the search term
+   - No match: show error with similar branches (if any)
+5. Get worktree list: `git worktree list --porcelain`
+6. Check if resolved branch has an existing worktree
+7. If worktree exists:
+   - Show path and suggest `cd <path>`
+8. If no worktree:
+   - Construct worktree path: `../<sanitized-branch-name>` (replace all `/` with `-`)
+   - If remote-only branch (starts with `origin/`): `git worktree add <path> -b <local-name> <remote-name>`
+   - If local branch: `git worktree add <path> <branch>`
+   - Symlink `.env`: if `<main-worktree>/.env` exists (get main worktree from `git worktree list --porcelain | head -1`), run `ln -s <main-worktree>/.env <new-worktree>/.env`
+   - Show path and suggest `cd <path>`
+
+**On success (worktree exists), output:**
+```
+✓ Branch already has worktree at: <worktree-path>
+
+To switch to the worktree:
+  cd <worktree-path>
+```
+
+**On success (worktree created from local branch), output:**
+```
+✓ Created worktree: <worktree-path>
+✓ Linked .env → <main-worktree>/.env
+
+To switch to the worktree:
+  cd <worktree-path>
+```
+
+**On success (worktree created from remote branch), output:**
+```
+✓ Created local branch: <branch-name> (tracking origin/<branch-name>)
+✓ Created worktree: <worktree-path>
+✓ Linked .env → <main-worktree>/.env
+
+To switch to the worktree:
+  cd <worktree-path>
+```
+
+**Error handling:**
+- Branch not found: "Branch not found: <name>. Did you mean one of these?" (list similar branches)
+- Multiple partial matches: "Multiple branches match '<term>':" (list matches, ask to be more specific)
+- No branches at all: "No branches found matching '<term>'"
+
+**Branch resolution priority:**
+1. Exact match on full branch name
+2. Exact match on last segment (e.g., "add-caching" matches "feature/john/add-caching")
+3. Partial substring match anywhere in branch name

.claude/commands/create-branch.md

@@ -0,0 +1,39 @@
+Create a new git branch with an associated worktree following the project naming convention.
+
+**Format:** `<type>/<developer>/<description>`
+**Worktree:** `../<sanitized-branch-name>` (sibling to current worktree)
+
+**Arguments:** $ARGUMENTS should be in format: `<type> <description>`
+
+**Examples:**
+- `/create-branch feature add-caching` → branch: `feature/<dev>/add-caching`, worktree: `../feature-<dev>-add-caching`
+- `/create-branch fix login-error` → branch: `fix/<dev>/login-error`, worktree: `../fix-<dev>-login-error`
+
+**Steps:**
+1. Parse type and description from arguments (validate type is one of: feature, fix, docs, refactor, test, chore)
+2. Get developer name from `git config user.name` (sanitize: lowercase, replace spaces with hyphens)
+3. Construct branch name: `<type>/<developer>/<description>`
+4. Construct worktree path: `../<type>-<developer>-<description>` (replace all `/` with `-`)
+5. Create branch and worktree atomically: `git worktree add -b <branch> <worktree-path>`
+6. Symlink `.env` from the main worktree into the new worktree:
+   - Get the main worktree path: `git worktree list --porcelain | head -1` (first `worktree` line)
+   - If `<main-worktree>/.env` exists, create symlink: `ln -s <main-worktree>/.env <new-worktree>/.env`
+   - If `.env` doesn't exist in main worktree, skip silently
+7. Report success with the created branch name and worktree path
+
+**Valid types:** feature, fix, docs, refactor, test, chore
+
+**On success, output:**
+```
+✓ Created branch: <branch-name>
+✓ Created worktree: <worktree-path>
+✓ Linked .env → <main-worktree>/.env
+
+To switch to the new worktree:
+  cd <worktree-path>
+```
+
+**Error handling:**
+- If type is invalid, show valid types and abort
+- If branch already exists, suggest checking it out instead
+- If worktree path exists, suggest using existing worktree

.claude/commands/create-pr.md

@@ -0,0 +1,56 @@
+Create a pull request for the current branch against main.
+
+**Arguments:** $ARGUMENTS (optional) — base branch override (defaults to `main`)
+
+**Steps:**
+
+1. **Validate branch state:**
+   - Get current branch: `git branch --show-current`
+   - If on `main`, abort with error: "You're on main. Switch to a feature branch first."
+   - Determine base branch: use $ARGUMENTS if provided, otherwise `main`
+
+2. **Check for unmerged commits:**
+   - Run `git log <base>..HEAD --oneline`
+   - If no commits, abort: "No unmerged commits against <base>. Nothing to PR."
+
+3. **Gather context (run in parallel):**
+   - `git diff <base>...HEAD --stat` — file change summary
+   - `git log <base>..HEAD --format='%h %s'` — commit list
+   - `git diff <base>...HEAD` — full diff for understanding changes
+
+4. **Draft PR title and body:**
+   - Analyze the commits and diff to understand the change
+   - Write a short PR title (under 70 chars, imperative mood)
+   - Write the body using this format:
+     ```
+     ## Summary
+     <1-3 bullet points explaining the changes>
+
+     ## Changes
+     <bulleted list of key file/module changes>
+
+     ## Test plan
+     <how to verify the changes work>
+     ```
+
+5. **Present draft to user:**
+   - Show the proposed title and body
+   - Ask: "Push and create this PR?" with options: Yes (create), Edit (let me revise), Cancel
+
+6. **On approval:**
+   - Check if branch has upstream: `git rev-parse --abbrev-ref @{upstream}`
+   - Push branch: `git push -u origin HEAD`
+   - Create PR: `gh pr create --title "<title>" --body "<body>" --base <base>`
+   - Show the resulting PR URL
+
+**On success, output:**
+```
+✓ Pushed branch: <branch-name>
+✓ Created PR: <pr-url>
+```
+
+**Error handling:**
+- If `gh` is not installed: "GitHub CLI (gh) is required. Install it: https://cli.github.com"
+- If not authenticated: "Run `gh auth login` first."
+- If PR already exists: show the existing PR URL with `gh pr view --web`
+- If push fails: show the git error and abort

.claude/commands/finalize.md

@@ -0,0 +1,79 @@
+Finalize the current work: format, test, fix, commit, and push.
+
+Run this command after making code changes to complete the development cycle. It handles formatting, testing (with auto-fix retries), committing, and pushing.
+
+**Arguments:** $ARGUMENTS is an optional commit message override. If not provided, compose one automatically from the diff.
+
+**Workflow:**
+
+1. **Format code**
+   - Run `uv run black ace/ tests/ examples/`
+
+2. **Update CLAUDE.md**
+   - Run `/init` to update the project's CLAUDE.md file with current codebase context
+
+3. **Review test coverage**
+   - Check if the changes have adequate test coverage
+   - Look at which lines/branches are untested for the modified files
+   - If coverage gaps exist for the changed code, add targeted tests before proceeding
+   - Focus on: new functions, error paths, edge cases, and branches introduced by this changeset
+
+4. **Run tests**
+   - Run `uv run pytest`
+
+5. **Test-fix loop (max 3 retries)**
+   - If tests pass, continue to step 6
+   - If tests fail:
+     - Analyze the failure output
+     - Fix the failing code or tests
+     - Add missing tests if the failures reveal gaps
+     - Re-run formatter: `uv run black ace/ tests/ examples/`
+     - Re-run tests: `uv run pytest`
+     - If tests still fail after 3 total attempts, **stop entirely** and report the failures. Never commit broken code.
+
+6. **Security review**
+   - Run `/security-review` to scan changed code for vulnerabilities
+   - If Critical or High severity issues are found, fix them before proceeding
+   - After fixing, re-run formatter (`uv run black ace/ tests/ examples/`) and tests (`uv run pytest`)
+   - If issues can't be auto-fixed, report them and stop
+
+7. **Review changes**
+   - Run `git diff` to review all changes
+   - Run `git status` to see untracked/modified files
+   - Determine which files to stage
+
+8. **Stage files selectively**
+   - Use explicit `git add <file>` for each file. **Never use `git add -A` or `git add .`**
+   - **Never stage:** `.env`, credentials, secrets, `__pycache__/`, `*.pyc`, large binaries, `.DS_Store`
+   - **Only stage `uv.lock`** if dependency changes in `pyproject.toml` were intentional
+   - If unsure about a file, ask the user
+
+9. **Compose commit message**
+   - If $ARGUMENTS was provided, use it as the commit message
+   - Otherwise, compose a Conventional Commit message: `<type>(<scope>): <short description>`
+   - Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `style`
+   - Derive scope from the primary changed file path (e.g., `ace/skillbook.py` -> `skillbook`, `ace/integrations/litellm.py` -> `integrations`, `tests/test_foo.py` -> `tests`)
+   - Keep messages short and imperative
+
+10. **Check branch safety**
+    - Run `git branch --show-current` to get the current branch
+    - If on `main` or `master`, **warn the user** and ask for explicit confirmation before committing
+    - If denied, stop without committing
+
+11. **Commit and push**
+    - Commit with the composed message
+    - Push to remote: `git push` (or `git push -u origin <branch>` if no upstream is set)
+
+12. **Report summary**
+    - Commit hash (short)
+    - Branch name
+    - Files changed count
+    - Test results (pass count)
+    - Any warnings encountered
+
+**Error handling:**
+- If no changes exist (clean working tree), report "Nothing to finalize" and stop
+- If tests fail after 3 retries, report failures and stop without committing
+- If push fails, report the error but keep the local commit
+- If formatter fails, report the error and stop
+- If security review finds unfixable Critical/High issues, report and stop without committing

.claude/commands/list-branches.md

@@ -0,0 +1,40 @@
+List project branches with their worktree status.
+
+**Arguments:** $ARGUMENTS (optional filters)
+- No args: List all branches matching naming convention `<type>/<developer>/<description>`
+- `--all`: Include all branches (not just convention-named)
+- `--worktrees`: Only show branches with active worktrees
+- `<type>`: Filter by type (feature, fix, docs, refactor, test, chore)
+
+**Examples:**
+- `/list-branches` → all convention-named branches
+- `/list-branches feature` → only feature branches
+- `/list-branches --worktrees` → only branches with worktrees
+- `/list-branches --all` → all branches including main
+
+**Steps:**
+1. Get all local branches: `git branch --format='%(refname:short)'`
+2. Get worktree list: `git worktree list --porcelain`
+3. Parse worktree output to map branches to paths
+4. Filter branches based on arguments
+5. Format and display results
+
+**Output format:**
+```
+Branch                              Worktree                         Status
+──────────────────────────────────────────────────────────────────────────────
+* main                              .                                current
+  feature/john/add-caching          ../feature-john-add-caching      active
+  fix/jane/login-error              (no worktree)                    -
+
+Summary: 3 branches, 2 with worktrees
+```
+
+**Column meanings:**
+- `*` indicates current branch
+- Worktree shows path relative to repo root, or "(no worktree)" if none
+- Status: "current" (HEAD), "active" (has worktree), "-" (no worktree)
+
+**Tips shown after output:**
+- To create a worktree for a branch: `git worktree add ../<path> <branch>`
+- To remove a branch with worktree: use `/remove-branch <branch>`

.claude/commands/release.md

@@ -0,0 +1,75 @@
+Release a new version: bump version, update changelog, tag, push, and create a GitHub release.
+
+**Arguments:** $ARGUMENTS — the new version number (e.g. `0.9.0`). Required.
+
+**Steps:**
+
+1. **Validate inputs**
+   - If $ARGUMENTS is empty, abort: "Usage: /release <version> (e.g. /release 0.9.0)"
+   - Strip leading `v` if present (e.g. `v0.9.0` → `0.9.0`)
+   - Validate format matches `X.Y.Z` (semver)
+
+2. **Validate branch state**
+   - Must be on `main`: `git branch --show-current`
+   - If not on main, abort: "Switch to main first."
+   - Pull latest: `git pull origin main`
+   - Working tree must be clean: `git status --porcelain`
+
+3. **Check version isn't already used**
+   - Read current version from `pyproject.toml` (line with `version = "..."`)
+   - If new version equals current version, abort: "Version <ver> is already set."
+   - Check tag doesn't exist: `git tag -l v<version>`
+   - If tag exists, abort: "Tag v<version> already exists."
+
+4. **Build changelog entry from git history**
+   - Find the latest tag: `git describe --tags --abbrev=0`
+   - Get commits since that tag: `git log <last-tag>..HEAD --format='%s'`
+   - Get merged PRs since that tag: `gh pr list --state merged --base main --search "merged:>=$(git log -1 --format=%ci <last-tag> | cut -d' ' -f1)" --json title,number --limit 50`
+   - From the commits/PRs, compose a changelog section with **only `### Added` items** — user-facing features. Skip fixes, refactors, chores, docs-only changes, and CI changes.
+   - Format:
+     ```
+     ## [X.Y.Z] - YYYY-MM-DD
+
+     ### Added
+     - **Feature name** — short description
+     - **Feature name** — short description
+     ```
+   - Also prepare a compare link for the bottom of CHANGELOG.md:
+     `[X.Y.Z]: https://github.com/Kayba-ai/agentic-context-engine/compare/v<prev>...vX.Y.Z`
+
+5. **Present draft to user**
+   - Show: new version, changelog entry, and the release note (same as changelog "Added" bullets)
+   - Ask: "Create this release?" with options: Yes, Edit (let me revise), Cancel
+
+6. **On approval — apply changes**
+   - Update `pyproject.toml`: replace `version = "<old>"` with `version = "<new>"`
+   - Insert the changelog entry in `CHANGELOG.md` after line 7 (before the previous release)
+   - Add the compare link at the bottom of CHANGELOG.md
+   - Stage files: `git add pyproject.toml CHANGELOG.md`
+   - Commit: `git commit -m "chore(release): bump version to <version>"`
+
+7. **Tag and push**
+   - `git tag v<version>`
+   - `git push origin main --tags`
+
+8. **Create GitHub release**
+   - Title: `v<version>`
+   - Notes: **only the "Added" bullets** from the changelog entry — short and clean, no preamble
+   - Append: `**Full Changelog**: https://github.com/kayba-ai/agentic-context-engine/compare/v<prev>...v<version>`
+   - Run: `gh release create v<version> --title "v<version>" --notes "<notes>"`
+   - This triggers `.github/workflows/publish.yml` → PyPI publish
+
+9. **Report summary**
+   ```
+   Released v<version>
+   - Commit: <short-hash>
+   - Tag: v<version>
+   - Release: <github-release-url>
+   - PyPI: publishing via workflow (check Actions tab)
+   ```
+
+**Error handling:**
+- If `gh` is not installed: "GitHub CLI (gh) is required. Install it: https://cli.github.com"
+- If not authenticated: "Run `gh auth login` first."
+- If push fails: report error, keep local commit (user can retry)
+- If `gh release create` fails: show the error, suggest manual creation

.claude/commands/remove-branch.md

@@ -0,0 +1,41 @@
+Remove a branch and its associated worktree.
+
+**Arguments:** $ARGUMENTS should be the branch name (full or partial match)
+- `--force`: Skip confirmations and force delete unmerged branches
+
+**Examples:**
+- `/remove-branch feature/john/add-caching` → remove branch and worktree
+- `/remove-branch add-caching` → partial match, will prompt to confirm
+- `/remove-branch feature/john/add-caching --force` → skip all confirmations
+
+**Steps:**
+1. Parse branch name and flags from arguments
+2. Resolve branch name (support partial matching if unique)
+3. Safety checks:
+   - Abort if trying to remove main/master
+   - Abort if trying to remove current branch (must switch first)
+   - Warn if branch has unmerged commits (show `git log main..<branch> --oneline`)
+4. Check if branch has an associated worktree: `git worktree list`
+5. If worktree exists:
+   - Remove worktree first: `git worktree remove <path>` (or `--force` if needed)
+   - Prune worktree list: `git worktree prune`
+6. Delete the branch: `git branch -d <branch>` (or `-D` with `--force`)
+7. Confirm success
+
+**On success, output:**
+```
+✓ Removed worktree: <worktree-path>
+✓ Removed branch: <branch-name>
+```
+
+**Error handling:**
+- Multiple partial matches: list matches and ask user to be more specific
+- Unmerged commits without --force: show commits and ask for confirmation
+- Protected branches (main/master): refuse with explanation
+- Current branch: instruct user to switch branches first
+
+**Protected branches:** main, master
+
+**Confirmation prompts (unless --force):**
+- "Branch has N unmerged commits. Remove anyway? (show commits first)"
+- For partial match: "Did you mean <full-branch-name>?"

.claude/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

.claude/projects/-home-david-projects-Kayba-agentic-context-engine/memory/feedback_bedrock_only.md

@@ -0,0 +1,11 @@
+---
+name: Always use Bedrock
+description: Never use direct Anthropic API key or fall back to OpenAI — always use Bedrock via AWS_BEARER_TOKEN_BEDROCK
+type: feedback
+---
+
+Always use Bedrock for LLM calls. Never use the Anthropic API key directly, never fall back to OpenAI or any other provider.
+
+**Why:** The user has Bedrock configured with `AWS_BEARER_TOKEN_BEDROCK` and does not want direct Anthropic API usage (burns quota/money on the wrong account). Fallback logic is unacceptable — it silently uses the wrong provider.
+
+**How to apply:** In integration tests and any code that needs an LLM model string, use `bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0` (or similar Bedrock model). Never write fallback chains like "if ANTHROPIC_KEY else OPENAI". Just use Bedrock, period.

.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run pytest:*)",
+      "Bash(uv run black:*)"
+    ]
+  }
+}

.claude/skills/kayba-pipeline/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: kayba-pipeline
+description: End-to-end agent evaluation and improvement pipeline. Takes a traces folder and optional HITL flag, then orchestrates sub-agents through 7 stages — each stage is its own skill invoked by a dedicated sub-agent. Trigger when the user says "run the pipeline", "kayba pipeline", "evaluate and fix", "full eval", "analyze traces and fix", or provides a traces folder with intent to improve their agent.
+---
+
+# kayba-pipeline
+
+End-to-end pipeline: analyze traces → define metrics → build rubric → plan fixes → implement fixes.
+
+Each stage is a separate skill file that can be run independently or as part of this pipeline.
+
+## Inputs
+
+The user provides two things:
+
+1. **`TRACES_FOLDER`** — path to a directory containing trace JSON files
+2. **`HITL`** — `true` or `false` — whether to pause for human review before implementing fixes
+
+If the user doesn't specify HITL, default to `true` (safe default).
+
+---
+
+## Pipeline overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  Stage 1: Kayba API Analysis        → skill: kayba-pipeline:stage-1-api-analysis   │
+│  Stage 2: Domain Context Gathering  → skill: kayba-pipeline:stage-2-domain-context │
+│  ─── stages 1 & 2 run in parallel ───                                              │
+│  Stage 3: Metrics & Analysis        → skill: kayba-pipeline:stage-3-metrics        │
+│  Stage 4: Rubric Definition         → skill: kayba-pipeline:stage-4-rubric         │
+│  Stage 5: Action Plan               → skill: kayba-pipeline:stage-5-action-plan    │
+│  Stage 6: HITL Gate                 → skill: kayba-pipeline:stage-6-hitl           │
+│  Stage 7: Fix Implementation        → skill: kayba-pipeline:stage-7-fixer          │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Orchestration instructions
+
+You are the orchestrator. Your job is to:
+1. Create the `eval/` directory and `eval/pipeline_log.md`
+2. Spawn sub-agents that invoke stage skills via the Skill tool
+3. Coordinate stage ordering and handle the HITL gate
+
+### Setup
+
+Create `eval/` directory and initialize `eval/pipeline_log.md`:
+
+```markdown
+# Pipeline Log
+
+| Stage | Name | Status | Started | Completed | Notes |
+|-------|------|--------|---------|-----------|-------|
+| 1 | Kayba API Analysis | pending | | | |
+| 2 | Domain Context | pending | | | |
+| 3 | Metrics & Analysis | pending | | | |
+| 4 | Rubric Definition | pending | | | |
+| 5 | Action Plan | pending | | | |
+| 6 | HITL Gate | pending | | | |
+| 7 | Fix Implementation | pending | | | |
+```
+
+### Stages 1 & 2 — run in parallel
+
+Spawn two sub-agents in parallel using the Agent tool:
+
+**Agent 1:**
+- Name: `api-analyst`
+- Type: `general-purpose`
+- Prompt: `Invoke the skill "kayba-pipeline:stage-1-api-analysis" using the Skill tool. The traces folder is: {TRACES_FOLDER}. Follow the skill instructions completely.`
+
+**Agent 2:**
+- Name: `domain-scout`
+- Type: `general-purpose`
+- Prompt: `Invoke the skill "kayba-pipeline:stage-2-domain-context" using the Skill tool. The traces folder is: {TRACES_FOLDER}. Follow the skill instructions completely.`
+
+Wait for both to complete before proceeding.
+
+### Stage 3 — sequential
+
+Spawn one sub-agent after stages 1 & 2 complete:
+
+- Name: `metric-engineer`
+- Type: `general-purpose`
+- Prompt: `Invoke the skill "kayba-pipeline:stage-3-metrics" using the Skill tool. The traces folder is: {TRACES_FOLDER}. Follow the skill instructions completely — this includes iterating on the metrics until you're satisfied.`
+
+### Stage 4 — sequential
+
+Spawn one sub-agent after stage 3 completes:
+
+- Name: `rubric-builder`
+- Type: `general-purpose`
+- Prompt: `Invoke the skill "kayba-pipeline:stage-4-rubric" using the Skill tool. Follow the skill instructions completely.`
+
+### Stage 5 — sequential
+
+Spawn one sub-agent after stage 4 completes:
+
+- Name: `action-planner`
+- Type: `general-purpose`
+- Prompt: `Invoke the skill "kayba-pipeline:stage-5-action-plan" using the Skill tool. Follow the skill instructions completely.`
+
+### Stage 6 — HITL Gate
+
+**If `HITL` is `true`:**
+
+Spawn one sub-agent after stage 5 completes:
+
+- Name: `hitl-reviewer`
+- Type: `general-purpose`
+- Prompt: `Invoke the skill "kayba-pipeline:stage-6-hitl" using the Skill tool. Follow the skill instructions completely. Present the full review to the user and collect their decision before proceeding.`
+
+Wait for the sub-agent to complete. Check `eval/stage6_decision.md` for the outcome:
+- If decision is "Approve all" or "Approve with modifications" — proceed to Stage 7
+- If decision is "Reject" — re-run Stage 5 with the user feedback recorded in `eval/stage6_decision.md`, then re-run Stage 6
+- Only proceed to Stage 7 after a clear approval is recorded
+
+**If `HITL` is `false`:**
+- Skip to Stage 7
+- Log "HITL skipped" in `eval/pipeline_log.md`
+
+### Stage 7 — sequential
+
+Spawn one sub-agent after stage 6 completes (or is skipped):
+
+- Name: `fixer`
+- Type: `general-purpose`
+- Prompt: `Invoke the skill "kayba-pipeline:stage-7-fixer" using the Skill tool. Follow the skill instructions completely.`
+
+---
+
+## Error handling
+
+- If any stage fails, log the failure in `eval/pipeline_log.md` with the stage number and error
+- Do not proceed to dependent stages if a prerequisite failed
+- If Stage 1 fails (kayba CLI issues), ask the user whether to proceed without API insights — if yes, skip Stage 1 and have Stage 3 work from domain context + raw traces only
+
+## After completion
+
+Update `eval/pipeline_log.md` with final status for all stages. Report to the user:
+- How many stages completed successfully
+- Summary of metrics (from rubric)
+- Summary of fixes applied (from changes log)

.claude/skills/kayba-pipeline/stage-1-api-analysis/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: kayba-stage-1-api-analysis
+description: Fetch pre-computed insights from the Kayba API and build a structured summary. Does NOT upload traces or trigger generation — analysis is assumed to already exist. Trigger when the user says "run stage 1", "get insights", "fetch skills", "kayba analyze", or when invoked by the kayba-pipeline orchestrator. Requires the kayba CLI to be installed and KAYBA_API_KEY to be set.
+---
+
+# Stage 1: Kayba API Analysis (Fetch-Only Mode)
+
+Fetch pre-computed insights from the Kayba API. Traces have already been uploaded and analyzed — this stage only pulls results.
+
+## Inputs
+
+- **`TRACES_FOLDER`** — passed by the orchestrator but **ignored** in this stage. Traces are already uploaded and analyzed on the Kayba side. Do NOT upload, validate, or read trace files.
+
+## Process
+
+### Step 1: Setup
+
+Ensure `eval/` directory exists at the project root.
+
+### Step 2: Fetch insights
+
+```
+kayba insights list --json > eval/insights.json
+```
+
+If `kayba` is not found in PATH, search common locations (`.venv/bin/kayba`, project virtualenvs). If found, use the full path. If not found anywhere, report the error and stop.
+
+If `KAYBA_API_KEY` is not set, report the error and stop.
+
+### Step 3: Insight quality gate
+
+Read `eval/insights.json` and run quality checks before building the summary:
+
+1. **Empty check**: if the insights array is empty (0 insights returned), report this as a warning. Write a minimal summary noting "0 insights generated" and stop — downstream stages cannot proceed without insights.
+2. **Duplicate detection**: compare insight `content` fields pairwise. If two insights cover substantially the same behavior (same section, overlapping evidence traces, similar corrective action), flag them as potential duplicates in the summary. Do not remove them — just annotate.
+3. **Evidence coverage**: for each insight, check if the `evidence` field references specific traces (e.g., "task_7 turn 4"). Insights with no trace-specific evidence are lower quality — flag as "low-evidence" in the summary.
+4. **Vote signal**: insights with `status: "accepted"` and `helpful > 0` have been human-validated. Insights with `status: "new"` and `helpful: 0, harmful: 0` are unvalidated — note this distinction in the summary.
+
+Log the quality gate result: `"Insight quality: {total} insights, {accepted} accepted, {new_unvalidated} unvalidated, {duplicates} potential duplicate pairs, {low_evidence} low-evidence"`
+
+### Step 4: Build structured summary
+
+Extract a structured summary of each insight:
+- Insight ID and title/summary (use the `section` field as the title)
+- Status
+- Evidence citations — specific trace references, error strings, behavioral patterns the reflector identified
+- Justification / reasoning chain — the reflector's full analysis of why this is a real pattern
+- Confidence score if available
+- Helpful/harmful counts if available
+- Quality flags from Step 3 (potential duplicate, low-evidence, unvalidated)
+
+Write the structured summary to `eval/stage1_insights_summary.md` using this format:
+
+```markdown
+# Kayba Insights Summary
+
+Generated from: Kayba API (pre-computed analysis)
+Total insights: N
+Quality: {accepted} accepted, {unvalidated} unvalidated, {duplicate_pairs} potential duplicate pairs, {low_evidence} low-evidence
+
+## Insight: [ID] — [section title]
+**Status:** [status] [quality flags if any, e.g., "[potential duplicate with ID]", "[low-evidence]", "[unvalidated]"]
+**Confidence:** [score if available]
+**Evidence:**
+- [citation 1 — trace reference, error string, or behavioral pattern]
+- [citation 2]
+**Justification:** [reflector's reasoning for why this is a real pattern]
+**Helpful/Harmful:** [counts if available]
+
+---
+[repeat for each insight]
+```
+
+## Error handling
+
+- If `kayba` is not found in PATH or common locations, report the error and stop
+- If `KAYBA_API_KEY` is not set, report the error and stop
+- If `kayba insights list` fails (network error, auth error), report the error and stop
+- If 0 insights are returned, write a minimal summary and stop — downstream stages need insights
+
+## Outputs
+
+- `eval/insights.json` — raw API response
+- `eval/stage1_insights_summary.md` — structured summary with quality annotations for downstream stages

.claude/skills/kayba-pipeline/stage-2-domain-context/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: kayba-stage-2-domain-context
+description: Gather domain context about the repository and agent — system prompt, tool definitions, domain docs, and behavior patterns from traces. Trigger when the user says "run stage 2", "gather context", "domain context", or when invoked by the kayba-pipeline orchestrator.
+---
+
+# Stage 2: Domain Context Gathering
+
+Understand the agent's world — what it does, what tools it has, and what "success" looks like.
+
+## Inputs
+
+- **`TRACES_FOLDER`** — path to directory containing trace JSON files
+
+## Process
+
+### 0. Detect trace format
+
+Before reading traces, identify the framework that produced them. Read 1 trace file and check:
+
+| Signal | Framework |
+|--------|-----------|
+| `info.agent_info.implementation`, `info.environment_info`, `simulation.messages[]` with `role`/`tool_calls`/`turn_idx` | **tau2-bench** |
+| `runs[].steps[]` with `type: "tool"`, `lc_kwargs` | **LangChain / LangSmith** |
+| `events[]` with `event_type`, `span_id`, `parent_id` | **LlamaIndex** |
+| `choices[].message.tool_calls[]` at top level | **Raw OpenAI API logs** |
+| `trace.spans[]` with `attributes`, `trace_id` | **OpenTelemetry / Arize / Langfuse** |
+
+Record the detected format in the output under **Trace Format**. All subsequent trace-reading steps use the field paths appropriate for that format.
+
+If the format is unrecognized, note the top-level keys and structure, then proceed best-effort with field names found in the data.
+
+### 1. Detect architecture
+
+Read 2-3 traces and determine if this is a single-agent or multi-agent system:
+
+- **Single agent**: one `agent_info` entry, one conversation thread, tool calls from one identity
+- **Multi-agent / router**: look for multiple `agent_info` entries, routing tool calls (e.g., `transfer_to_*`, `delegate_to_*`), sub-conversation arrays, or distinct system prompts per agent identity
+
+If multi-agent: document each agent separately (name, role, tools, handoff triggers) and note the routing logic. The remaining steps apply per-agent.
+
+### 2. Find the system prompt
+
+Use a fallback chain — stop at the first hit:
+
+1. **Config files** — grep for keys: `system_prompt`, `system_message`, `instructions`, `AGENT_INSTRUCTION`, `SYSTEM_PROMPT` in YAML/JSON/TOML/Python/JS files
+2. **Source code** — search for prompt template strings, f-strings, or `.format()` calls that build the system message (look in agent implementation files)
+3. **Trace extraction** — read 3 trace files from `{TRACES_FOLDER}`:
+   - Check `info.environment_info.policy` (tau2-bench format)
+   - Check first message with `role: "system"` in the messages array
+   - Check `raw_data` fields for system-level content
+4. **Not found** — if none of the above yields a system prompt, explicitly record `SYSTEM_PROMPT_STATUS: NOT_FOUND` in the output and flag this for the orchestrator. Do not fabricate or guess.
+
+When found, record both the prompt content and its **source location** (file path + line, or trace field path).
+
+### 3. Extract tool definitions
+
+Two-pass approach: source code first (ground truth), then traces (usage evidence).
+
+**Pass 1 — Source code discovery:**
+- Search for tool/function definition patterns: `@tool`, `@is_tool`, `def tool_`, function schema arrays, OpenAPI specs, `tools=[]` arguments
+- For each tool, extract from source:
+  - Name
+  - Input parameters with types and defaults
+  - Return type / output schema (document the structure, not just "returns a dict")
+  - Side effects: READ (no state change), WRITE (mutates state), GENERIC (neither)
+  - Validation rules the tool does NOT enforce (critical — grep for comments like "API does not check", "agent must enforce")
+
+**Pass 2 — Trace usage evidence:**
+- Read ALL traces (if <= 20) or a stratified sample (see step 4 for sampling)
+- Extract every unique `tool_calls[].name` from assistant messages
+- Extract every `role: "tool"` response to document actual output shapes
+- For each tool, record one example input/output pair from traces
+
+**Reconcile the two passes:**
+- Tools in source but NOT in traces = "available but unused" — flag these; they may be relevant for edge cases the agent should handle
+- Tools in traces but NOT in source = possible dynamic tools or external APIs — investigate
+
+Output the full tool inventory as a table with columns: Name, Category, Input Schema, Output Schema, Observed in Traces (Y/N), Unvalidated Rules.
+
+### 4. Find domain documentation
+
+- READMEs, product docs, wiki links
+- Policy files (e.g., `data/*/policy.md`, domain-specific docs)
+- Inline code comments explaining business logic
+- Test files that describe expected behavior
+- Anything that explains what the agent does and what "success" means for its users
+
+### 5. Catalogue agent behavior patterns
+
+**Trace selection — stratified sampling** (do not just grab "5-10 random traces"):
+
+1. Count total traces in `{TRACES_FOLDER}`. If <= 20, read ALL of them.
+2. If > 20, select a stratified sample:
+   - Sort by `termination_reason` — include at least 2 per unique reason
+   - Sort by conversation length (message count) — include shortest, longest, and 2 median
+   - Sort by tool call count — include lowest and highest
+   - If task outcomes are available (pass/fail), include at least 3 of each
+   - Target: ~15 traces total, or 30% of the corpus, whichever is larger
+
+For each selected trace, document:
+- **Function call frequency** — which tools are called most, in what order
+- **Tool call sequences** — common tool chains (e.g., get_user -> get_reservation -> cancel)
+- **Success patterns** — what does a thread that accomplishes its goal look like?
+- **Failure patterns** — what does a thread that fails or gets stuck look like?
+- **Error patterns** — what error strings appear in tool outputs? Group by root cause
+- **Policy violation patterns** — where does the agent break its own rules? (e.g., multiple tool calls per turn, acting without confirmation)
+- **User feedback signals** — reverts, ratings, explicit corrections, escalations, stop tokens, transfer tokens
+
+### 6. Write findings
+
+Write all findings to `eval/stage2_domain_context.md`:
+
+```markdown
+# Domain Context
+
+## Trace Format
+- Framework: [detected framework name]
+- Key field paths: [e.g., simulation.messages[], info.environment_info.policy]
+
+## Architecture
+- Type: [single-agent | multi-agent]
+- [If multi-agent: agent roster with roles and handoff triggers]
+
+## Agent Purpose
+[1-2 sentence summary of what this agent does]
+
+## System Prompt
+- **Source**: [file path + line, or trace field path, or NOT_FOUND]
+- **Status**: [verbatim | reconstructed | not_found]
+
+[The system prompt content, or "NOT_FOUND — downstream stages should account for missing system prompt"]
+
+## Tools
+| Tool | Category | Input Schema | Output Schema | In Traces? | Unvalidated Rules |
+|------|----------|-------------|---------------|------------|-------------------|
+| tool_name | READ/WRITE/GENERIC | `{param: type}` | `{field: type}` | Y/N | "API does not check X" |
+
+### Tools available but never called in traces
+- [tool_name — why it matters]
+
+## Domain Rules
+[Key business rules, constraints, policies the agent must follow]
+
+## Behavior Patterns
+
+### Success patterns
+- [pattern 1]
+
+### Failure patterns
+- [pattern 1]
+
+### Policy violation patterns
+- [violation with frequency: N/M turns]
+
+### Error patterns
+| Error | Frequency | Root cause |
+|-------|-----------|------------|
+| error string | N traces | cause |
+
+### User feedback signals
+- [signal 1]
+```
+
+## Outputs
+
+- `eval/stage2_domain_context.md`

.claude/skills/kayba-pipeline/stage-3-metrics/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: kayba-stage-3-metrics
+description: Define metrics from Kayba insights, implement them as Python measurement code, run against traces, and iterate until the metrics are clean and meaningful. Trigger when the user says "run stage 3", "define metrics", "build metrics", "compute baselines", or when invoked by the kayba-pipeline orchestrator. Requires eval/stage1_insights_summary.md and eval/stage2_domain_context.md to exist.
+---
+
+# Stage 3: Metrics and Programmatic Analysis
+
+Define metrics from insights, implement as code, run, review, iterate.
+
+## Inputs
+
+- **`TRACES_FOLDER`** — path to directory containing trace JSON files
+- **`eval/stage1_insights_summary.md`** — output from Stage 1
+- **`eval/stage2_domain_context.md`** — output from Stage 2
+
+Read both input files before starting.
+
+## Process
+
+This stage is iterative. You cycle through define → implement → run → review, with a hard cap of **3 iterations**. A metric set is "clean" when ALL of the following hold:
+
+1. **No small-sample metrics in the priority set** — every metric used for priority ranking has denominator >= 5. Metrics with denominator < 5 are kept but labeled `"confidence": "directional-only"` and excluded from priority sorting.
+2. **No unexplained extremes** — no metric reads 0% or 100% unless you can write a one-sentence justification (e.g., "0% is correct because the agent never calls send_certificate anywhere in the dataset"). Record the justification in the metric's `"extreme_justification"` field.
+3. **No redundant pairs** — no two metrics share > 70% of their denominator events. Check this: for each pair, compute `|events_A ∩ events_B| / min(|events_A|, |events_B|)`. If > 0.70, merge or drop one.
+4. **Script runs without errors** on the full trace set.
+
+If after 3 iterations the set is not fully clean, ship what you have and log remaining issues in `eval/baseline_metrics.json` under a top-level `"warnings"` key.
+
+### Step 1: Define metrics
+
+For each insight from the Kayba analysis, use the evidence fields to identify observable signals in the traces:
+
+1. Read the insights summary — focus on evidence citations, error strings, behavioral patterns
+2. For each valid insight, determine what trace signal would change if the agent followed the skill
+3. Classify each metric by detector pattern type:
+
+**Recovery detectors** — consecutive calls to the same function where first has error, next succeeds
+```python
+def has_recovery(calls, function_name):
+    for i in range(len(calls) - 1):
+        if calls[i]['name'] == function_name and is_error(calls[i]['output']):
+            if calls[i+1]['name'] == function_name and is_success(calls[i+1]['output']):
+                return True
+    return False
+```
+
+**Loop detectors** — N+ consecutive calls to the same function (stuck agent)
+
+**Give-up detectors** — regex match agent output for abandonment phrases ("I'm unable to", "cannot complete", "beyond my capabilities")
+
+**Error classifiers** — match function outputs against domain-specific error patterns. Build a pattern table:
+```python
+ERROR_PATTERNS = {
+    'pattern_name': r'regex matching the error',
+    # one entry per distinct error type
+}
+```
+
+**Over-exploration detectors** — ratio of explore vs action calls. Use the tool categories from Stage 2. If explore ratio exceeds threshold AND task didn't complete → analysis paralysis
+
+**Ground-truth comparison detectors** — agent claims a value (dollar amount, flight number, policy rule) in natural language, and the preceding tool response contains the actual value. Extract candidate values from agent text via regex, then compare against structured fields in the tool response JSON. Examples:
+```python
+# Extract dollar amounts from agent text
+DOLLAR_PATTERN = r'\$\s?([\d,]+(?:\.\d{2})?)'
+
+# Extract flight numbers (3 letters + 3 digits)
+FLIGHT_PATTERN = r'\b([A-Z]{2,3}\d{3,4})\b'
+
+def check_agent_claims_against_tool(agent_text, preceding_tool_response):
+    """Compare values the agent states against the tool response ground truth."""
+    claimed_amounts = re.findall(DOLLAR_PATTERN, agent_text)
+    actual_amounts = extract_amounts_from_json(preceding_tool_response)
+    # A claim is fabricated if it doesn't match any actual value
+    fabricated = [c for c in claimed_amounts if not any(matches(c, a) for a in actual_amounts)]
+    return len(fabricated) == 0, fabricated
+```
+This pattern covers data accuracy (fabricated prices/flights), post-action verification (quoted vs actual cost), and policy accuracy (claimed restrictions vs policy text). These are NOT qualitative-only — regex + JSON comparison is noisy but produces a real signal. Build the detector even if it's imperfect; a noisy metric that produces a fix is better than a clean classification that produces nothing.
+
+**Ordering/sequencing detectors** — agent performs actions in the wrong order (e.g., searches for flights before checking if the reservation is even modifiable). Check whether tool call A appears before tool call B when B should come first.
+
+**Clean success** — threads where all tasks completed with no errors and no other tags
+
+4. **Validate each detector before coding it at scale.** Pick 2-3 traces where you already know the ground truth from Stage 1 evidence. Run your detector logic mentally (or in a scratch script) against those traces. If it misclassifies any of them, fix the logic before writing the full implementation. This catches regex and pattern bugs early — the Stage 3 trace showed multiple iterations wasted on broken confirmation-phrase matching that a quick manual check would have caught.
+
+### Step 2: Implement and run
+
+1. Write `eval/compute_baselines.py` with:
+   - CLI args: `--traces-dir` (required), `--output` (default: `eval/baseline_metrics.json`)
+   - `load_traces(traces_dir)` — loads all JSON trace files
+   - Error pattern table built from reading 20-30 traces
+   - `tag_thread(thread)` — combines all detectors, returns list of tags
+   - One measurement function per metric, computing `numerator / denominator`
+   - `compute_all_baselines(traces_dir)` — runs all metrics, returns dict
+   - Main block that runs everything and prints summary
+
+2. Run it:
+   ```
+   python eval/compute_baselines.py --traces-dir {TRACES_FOLDER} --output eval/baseline_metrics.json
+   ```
+
+### Step 3: Review and iterate
+
+Run these checks in order after every run. Each check either passes or produces a concrete fix action.
+
+**Check A — Script health.** Did the script error or produce `null` values? → fix and re-run. This is iteration 0-cost; don't count it toward the 3-iteration cap.
+
+**Check B — Small-sample guard.** For each metric, examine the denominator:
+- denominator >= 5 → full-confidence metric, usable for priority ranking
+- denominator 1-4 → label `"confidence": "directional-only"` in the output JSON. The metric stays in the report but is excluded from priority sorting in Stage 4. Do NOT drop it — small-sample metrics can still inform qualitative analysis.
+- denominator 0 → the detector found no applicable events. Either the detector is broken (fix it) or the behavior genuinely doesn't occur in this trace set (log as `"confidence": "not-observed"` and move on).
+
+**Check C — Extreme-value triage.** For any metric at exactly 0% or 100%:
+- Ask: "Is there a plausible trace where this metric would NOT be extreme?" If yes → detector is likely broken, fix it.
+- If no (the behavior legitimately always/never happens in this dataset) → write a one-sentence justification and add it as `"extreme_justification"` in the output. Example: M5=0% is correct because both cancellations in the dataset were on ineligible reservations.
+- Do NOT reflexively drop 0%/100% metrics. A metric that correctly reads 0% is a strong signal for Stage 5 action planning.
+- **Ceiling/floor flag for 100% and 0% metrics:** If a metric baseline is already at 100% (or 0% where 0% is the desired direction), add `"at_ceiling": true` (or `"at_floor": true`) to its entry in the output JSON. This signals to Stage 4 (direction setting) and Stage 5 (action planning) that the metric is already optimal and should NOT be listed as needing improvement. Stage 4 must set its direction to `"↑ maintain"` or `"— already optimal"`, never bare `"↑"`.
+
+**Check D — Correlation / overlap audit.** For every pair of metrics, compute event overlap: `|denom_A ∩ denom_B| / min(|denom_A|, |denom_B|)`. If > 0.70:
+- The two metrics are measuring overlapping populations. Keep the one with the sharper behavioral distinction (measures a more specific failure mode). Drop or merge the other.
+- In the Stage 3 trace, M1 and M2 shared identical denominators (29 tool-calling turns) and were never flagged. They survived because they measure different *properties* of the same events — this is acceptable only if the numerator overlap is also checked. If both numerators move in lockstep (one is a strict subset of the other), merge them.
+
+**Check E — Coverage (strict).** For EVERY Stage 1 insight, verify it has a corresponding metric. If an insight has no metric:
+- First, try harder to build one. Can you extract values from agent text and compare against tool responses? Can you detect the wrong tool-call ordering? Can you pattern-match the failure mode with keywords + JSON field checks?
+- Only after a concrete failed attempt, classify as unmeasurable with a specific reason why the approach you tried doesn't work.
+- An insight classified as unmeasurable means Stage 5 will NOT produce a fix for it. That is a real cost. Treat every unmeasurable classification as a missed fix.
+
+After checks, if any produced a fix action: apply fixes and re-run (counts as one iteration). If all checks pass → the metric set is clean. **Stop iterating.**
+
+### Design principles
+
+- **Target one metric per insight.** Every insight should have a metric unless it is genuinely unmeasurable (see above). If you end up with fewer metrics than insights, you are being too conservative. Directional-only metrics (denominator < 5) still count — they produce fixes in Stage 5. Only apply the redundancy check (Check D) to merge metrics that truly overlap; do not use the metric count as a reason to skip building detectors.
+- **Express every metric as a ratio or percentage.** Absolute counts aren't comparable across trace sets.
+- **Prefer per-event denominators over per-thread.** "% of EditScript calls with errors" is sharper than "% of threads with any EditScript error." Per-thread denominators compress information — a thread with 10 violations and a thread with 1 both count the same.
+- **One metric per behavioral change.** If two would always move together, keep only the sharper one. Use Check D (overlap audit) to enforce this mechanically, not just by intuition.
+- **Build a metric for EVERY insight. "Unmeasurable" is a last resort, not a default.** Before classifying an insight as unmeasurable, you MUST attempt to build a programmatic detector. The bar for "unmeasurable" is: you tried a concrete approach, it fundamentally cannot work (not just "it's noisy"), and you can explain why in one sentence.
+
+  Specifically:
+  - **"Agent claims X but tool response says Y"** — this is ALWAYS measurable. Use regex to extract values (dollar amounts, IDs, flight numbers) from agent text, compare against structured JSON fields in the preceding tool response. Noisy matches are fine — a metric that catches 70% of fabrications is far more useful than a qualitative note that catches 0%.
+  - **"Agent violates policy rule Z"** — if the policy rule can be stated as a condition on trace data (tool call ordering, presence/absence of a call, argument values), build a detector. Only classify as qualitative-only if the rule requires understanding the *meaning* of free-text agent output beyond keyword/pattern matching.
+  - **"Insufficient data"** — if the detector logic is clear but n < 5, build the detector anyway and label it `"confidence": "directional-only"`. Do NOT skip building the metric. A directional-only metric still produces a fix in Stage 5.
+
+  If after genuine effort an insight truly cannot be measured programmatically, classify it as:
+  - `"qualitative-only"` — requires semantic understanding that regex/JSON comparison cannot approximate. Must explain what specific semantic judgment is needed and why pattern matching fails.
+  - `"insufficient-data"` — detector exists but denominator is 0 (not just small — literally zero applicable events). Note what scenarios would need to appear in traces.
+  - `"needs-ground-truth"` — requires task-specific expected outcomes that aren't in the trace format.
+
+  Record any remaining unmeasurable insights in the output JSON under a `"unmeasurable"` key. **The goal is for this list to be as short as possible — ideally empty.**
+
+## Outputs
+
+- `eval/compute_baselines.py` — runnable script with `--traces-dir` and `--output` CLI args
+- `eval/baseline_metrics.json` — computed baseline values, structured as:
+  ```json
+  {
+    "M1": {
+      "name": "single_tool_call_compliance",
+      "value": 0.414,
+      "numerator": 12,
+      "denominator": 29,
+      "confidence": "full"
+    },
+    "M5": {
+      "name": "cancellation_policy_compliance",
+      "value": 0.0,
+      "numerator": 0,
+      "denominator": 2,
+      "confidence": "directional-only",
+      "extreme_justification": "0% correct: both cancellations in dataset were on ineligible reservations"
+    },
+    "warnings": ["M5 and M6 have denominator < 5; excluded from priority ranking"],
+    "unmeasurable": [
+      {
+        "insight_id": "d7494740",
+        "name": "Cabin Change Constraints",
+        "classification": "insufficient-data",
+        "reason": "Only 1 update_reservation_flights call in dataset"
+      }
+    ]
+  }
+  ```

.claude/skills/kayba-pipeline/stage-4-rubric/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: kayba-stage-4-rubric
+description: Organize computed metrics into a tiered evaluation rubric with leading, lagging, and quality indicators. Trigger when the user says "run stage 4", "build rubric", "tier metrics", or when invoked by the kayba-pipeline orchestrator. Requires eval/baseline_metrics.json and eval/compute_baselines.py to exist.
+---
+
+# Stage 4: Rubric Definition
+
+Organize metrics into a tiered evaluation rubric. Detect and resolve redundancy quantitatively. Ensure every insight is accounted for.
+
+## Inputs
+
+- `eval/baseline_metrics.json` — computed baseline values from Stage 3
+- `eval/compute_baselines.py` — to understand what each metric measures
+- `eval/stage1_insights_summary.md` — the original insights
+- `eval/stage2_domain_context.md` — domain context
+
+Read all four files before starting.
+
+## Process
+
+### 1. Quantitative redundancy check
+
+Before tiering, check every pair of metrics for overlap. Two metrics are redundancy candidates if ANY of the following hold:
+
+- **Denominator overlap >70%**: compute `|denom_events(A) ∩ denom_events(B)| / min(|denom(A)|, |denom(B)|)`. If >0.70, they are candidates. To compute this, trace through the detector functions in `compute_baselines.py` and determine which trace events (turns, calls, threads) each denominator iterates over. When denominators are identical sets (same loop, same filter), overlap is 100%.
+- **Same skill set**: the metrics map to the exact same set of insight/skill IDs from Stage 1.
+- **Logical subsumption**: one metric's positive case is a strict subset of the other's (e.g., "turn has exactly 1 tool call" is a subset of "turn has no user-facing content alongside tool calls" only if every single-call turn also has no content — check this, don't assume it).
+
+For each candidate pair, make an explicit decision with reasoning:
+
+| Pair | Denom overlap | Skill overlap | Subsumption? | Decision | Reasoning |
+|------|---------------|---------------|--------------|----------|-----------|
+| M1/M2 | 100% (same 29 turns) | identical | No — can violate one without the other | **Keep both** | Independently actionable: batching vs. content leaking are distinct fixes |
+
+Valid decisions: **keep both** (with reasoning why they're independently actionable), **merge** (combine into one metric, specify how), or **drop** (specify which and why). "They feel different" is not sufficient reasoning — cite the specific behavior that one catches and the other misses.
+
+Final count target: 5-7 metrics after redundancy resolution.
+
+### 2. Tier each metric
+
+Use this decision flowchart for every metric:
+
+```
+Q1: Can a SINGLE skill/instruction change directly move this metric?
+    → If the agent follows one new instruction and the metric improves,
+      regardless of other behaviors: LEADING.
+
+Q2: Does moving this metric require MULTIPLE skills to be adopted together?
+    → If improvement depends on several upstream behaviors all working
+      (e.g., proper turn structure + confirmation flow + execution):
+      LAGGING.
+
+Q3: Does moving this metric require domain reasoning beyond following instructions?
+    → If the agent needs to correctly interpret policy rules, evaluate
+      eligibility criteria, or make judgment calls that can't be reduced
+      to a single instruction: QUALITY.
+```
+
+Apply the flowchart to each metric and record the Q1/Q2/Q3 answer that determined the tier. If a metric could arguably be two tiers, pick the lower one (Leading < Lagging < Quality) and note the ambiguity.
+
+Tier summary for reference:
+
+| Tier | Purpose | Moves when... | Diagnostic signal |
+|------|---------|---------------|-------------------|
+| **Leading** | Behaviors a single skill directly changes | Skill is adopted | If leading moves but lagging doesn't → skill adopted but not solving the right problem |
+| **Lagging** | Aggregate outcomes requiring multiple skills | Multiple skills coordinate | If lagging moves but leading doesn't → something else improved, not your skills |
+| **Quality** | Requires domain understanding, not just instruction-following | Agent reasons correctly | If quality moves but lagging doesn't → agent got lucky or metric is mis-tiered |
+
+### 3. Flag low-confidence baselines
+
+Any metric with denominator < 5 events is a **low-confidence baseline**. These metrics:
+- ARE included in the rubric (they measure real behaviors)
+- Are marked with `**Confidence: low** (n=X)` in the rubric
+- Must NOT drive priority decisions in Stage 5 — they inform direction only
+- Should note what denominator size would make them reliable (rule of thumb: n >= 10 for a rate metric to be meaningful, n >= 30 for statistical comparisons)
+
+### 4. Set direction
+
+For each metric, indicate whether it should go **up higher** or **down lower**. Don't set arbitrary numerical targets — baseline + direction is enough.
+
+**Ceiling guard:** If a metric's baseline is already 100%, its direction MUST be `"��� maintain"` or `"— already optimal"`, never `"↑"` as if it needs to go higher. A 100% metric is at ceiling — the goal is to sustain it, not improve it. Similarly, if a metric is at 0% and the desired direction is `"↓"`, mark it `"↓ maintain"` or `"— already at floor"`. Do not let any downstream stage (Stage 5 action plan, Stage 7 fixes) list a ceiling/floor metric as needing improvement.
+
+### 5. Map insights to metrics (completeness check)
+
+For every insight from `eval/stage1_insights_summary.md`, assign it to one of three categories:
+
+1. **Mapped** — directly linked to one or more metrics. List which ones.
+2. **Indirectly mapped** — supports a metric but isn't the primary driver. List the metric and explain the indirect relationship.
+3. **Qualitative-only** — no programmatic metric captures this insight. Explicitly mark it and state why (e.g., "requires LLM-as-judge," "measures explanation quality," "efficiency pattern with no clear denominator").
+
+Every insight MUST appear in exactly one category. If you find an insight that should have a metric but doesn't, note it as a gap for future Stage 3 iterations — but do not invent metrics at this stage.
+
+At the end, report:
+- `X / N insights mapped to metrics`
+- `Y / N insights indirectly mapped`
+- `Z / N insights qualitative-only`
+
+### 6. Add invalidation notes
+
+For each metric, write one sentence answering: "What would make this tier assignment wrong?"
+
+Examples:
+- M1 (Leading): "Wrong if fixing batching also requires the agent to change its confirmation flow — that would make it Lagging."
+- M5 (Quality): "Wrong if cancellation compliance can be fixed by a single checklist instruction without requiring the agent to reason about policy — that would make it Leading."
+
+These notes exist so Stage 5 can catch tier errors. If Stage 5 finds evidence that a tier is wrong (e.g., a single skill would move a "Quality" metric), it should flag the conflict rather than silently inheriting the error.
+
+### 7. Write the rubric
+
+Write to `eval/baseline_metrics.md`:
+
+```markdown
+# Eval Rubric — Baseline Metrics
+
+## Summary
+| # | Metric | Tier | Baseline | Direction | Confidence |
+|---|--------|------|----------|-----------|------------|
+| M1 | First-call success rate | Leading | 37.6% | up | ok (n=29) |
+| M2 | ... | ... | ... | ... | ... |
+
+## Tier Definitions
+
+- **Leading** — Single skill directly moves this. Should change first after deployment.
+- **Lagging** — Multiple skills must coordinate. Improves as a consequence of adoption.
+- **Quality** — Requires domain reasoning beyond instruction-following. Hardest to move.
+
+## Metric Details
+
+### M1: [name]
+**Tier:** Leading
+**Baseline:** 37.6% (685 / 1,821)
+**Confidence:** ok (n=1821) | low (n=X) — needs n>=Y for reliable comparison
+**Direction:** up higher is better
+**What it measures:** [description]
+**How it's computed:** [reference to function in compute_baselines.py]
+**Skills that should move this:** [list insight/skill IDs from stage 1]
+**Tier rationale:** [which flowchart question determined the tier]
+**Invalidation note:** [what would make this tier wrong]
+
+### M2: [name]
+...
+
+## Redundancy Analysis
+
+| Pair | Denom overlap | Skill overlap | Subsumption? | Decision | Reasoning |
+|------|---------------|---------------|--------------|----------|-----------|
+| ... | ... | ... | ... | ... | ... |
+
+## Insight Coverage
+
+### Mapped (X / N)
+- `insight_id` — [title] → M1, M3
+
+### Indirectly mapped (Y / N)
+- `insight_id` — [title] → supports M5 via [explanation]
+
+### Qualitative-only (Z / N)
+- `insight_id` — [title] — [why no metric: e.g., "requires LLM-as-judge"]
+```
+
+## Outputs
+
+- `eval/baseline_metrics.md` — human-readable tiered rubric with redundancy analysis, confidence flags, insight coverage, and invalidation notes

.claude/skills/kayba-pipeline/stage-5-action-plan/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: kayba-stage-5-action-plan
+description: Triage each insight into discard/code-fix/prompt-fix and produce a prioritized action plan with specific recommendations. Trigger when the user says "run stage 5", "make action plan", "triage skills", or when invoked by the kayba-pipeline orchestrator. Requires eval outputs from stages 1-4.
+---
+
+# Stage 5: Action Plan
+
+Triage each insight and produce a concrete, prioritized action plan.
+
+## Inputs
+
+- `eval/stage1_insights_summary.md` — insights from Kayba
+- `eval/stage2_domain_context.md` — domain context
+- `eval/baseline_metrics.md` — the evaluation rubric
+- `eval/baseline_metrics.json` — baseline values
+- `eval/compute_baselines.py` — measurement code
+
+Read all files before starting.
+
+## Process
+
+### 1. Triage each insight
+
+For each insight/skill, answer three questions in order: Is it valid? Is it already handled? Is it a code fix or prompt fix?
+
+#### 1a. Validity check
+
+- Does it describe a real, recurring problem visible in traces — or noise from a one-off edge case?
+- Is it actionable — can the agent actually change this behavior given its tools and context?
+- If not valid → verdict: **discard** with a one-sentence reason.
+
+#### 1b. "Already handled" verification
+
+Do not rely on memory or assumption. Run these checks and cite what you find:
+
+1. **Grep the codebase** for 2-3 key terms from the insight (tool names, error strings, behavioral keywords). Example: for an insight about cancellation eligibility, grep for `cancel`, `eligibility`, `criteria`.
+2. **Read the existing system prompt text** — check `AGENT_INSTRUCTION` in the agent file and the domain policy file. Quote any existing language that addresses this behavior.
+3. **Verdict:**
+   - If existing text partially covers it → **keep** as a strengthening fix, note what's missing.
+   - If no existing coverage → **keep**.
+   - If existing prompt text already covers the behavior thoroughly AND the baseline metric is >= 95% → **discard** (cite the existing text and metric). A high baseline alone is NOT sufficient to discard — if the metric is below 95%, there are still failures to fix. An 87% baseline means 1 in 8 attempts still fails; that is worth fixing.
+
+#### 1c. Code-vs-prompt decision tree
+
+Walk through this tree for every non-discarded insight:
+
+```
+Q1: Can the agent fix this by following different instructions?
+    (Does it have the right tools, correct data in tool responses,
+     and sufficient context to behave correctly?)
+  │
+  ├─ YES → PROMPT FIX
+  │        The agent has everything it needs but acts wrong.
+  │        A system prompt addition would fix it.
+  │
+  └─ NO → Q2: What is the agent missing?
+           │
+           ├─ Tool doesn't exist, schema is wrong, API returns
+           │  incomplete data, infrastructure drops information,
+           │  timeout/error not surfaced to agent
+           │  → CODE FIX
+           │    Name the file, function, and specific change.
+           │
+           └─ The agent has partial information but the prompt
+              can't fully compensate (e.g., needs a new tool
+              but a heuristic prompt workaround exists)
+              → PROMPT FIX (primary) + CODE FIX (optional)
+                Note both. Mark the code fix as "optional" with
+                a one-sentence justification for why it's lower priority.
+```
+
+**Ambiguity default:** When genuinely uncertain, default to **prompt fix** and add a note: `"Classification uncertain — defaulting to prompt fix. Revisit if prompt change doesn't move metrics."` This is safer because prompt fixes are cheaper to test and revert, and Stage 7 handles prompt fixes and code fixes through different paths.
+
+Use the reflector's reasoning from Stage 1 insights — it often explicitly identifies root causes that clarify the code-vs-prompt distinction.
+
+### 2. Consolidate related insights
+
+Before writing recommendations, merge insights that are redundant. Two insights should merge when ALL three conditions hold:
+
+1. **Same target behavior** — they describe the agent doing (or failing to do) the same thing.
+2. **Overlapping fix text** — the prompt instructions you'd write for each would share >50% of their content.
+3. **Addressing one substantially addresses the other** — fixing insight A would fix >80% of the cases described by insight B.
+
+**When NOT to merge** — two insights about the same tool or domain area but different failure modes should remain separate. Example: "agent doesn't check cancellation eligibility" and "agent doesn't execute cancellation after user confirms" both involve `cancel_reservation` but are completely different behavioral failures with different prompt fixes. Keep them separate.
+
+For each merge, document:
+- Which insight IDs are combined
+- Which insight's framing is primary (use the one with stronger trace evidence)
+- What, if anything, is lost from the secondary insight (add it as a sub-point)
+
+### 3. Write specific recommendations
+
+For each insight (after merging):
+
+- **Discards:** one sentence on why it's not valid or actionable.
+- **Code fixes:** what code/schema/infrastructure to change. Name the file, the function, the specific change. If Stage 7 needs to find the right code location, give it enough to grep for.
+- **Prompt fixes:** the exact instruction text to add to the system prompt, where it should go (e.g., appended to `AGENT_INSTRUCTION`, added to domain policy, or as a standalone skill block), and why this wording over alternatives.
+
+### 4. Assess risk per fix
+
+For each non-discarded fix, assess whether the change could break currently-working behaviors:
+
+| Risk | Definition | Example |
+|------|-----------|---------|
+| **None** | Change is additive; no existing behavior could be affected | Adding a new metric to compute_baselines.py |
+| **Low** | Change targets a behavior that is currently failing; working cases are unrelated | Adding a cancellation checklist when current cancellation compliance is 0% |
+| **Medium** | Change modifies a behavior where some cases already work correctly | Strengthening confirmation protocol when 28.6% already succeed — could the new wording break the working 28.6%? |
+| **High** | Change rewrites or constrains a behavior that mostly works | Restricting tool-call patterns when 41.4% already comply — overly rigid wording could cause the agent to under-call tools |
+
+For Medium and High risk fixes, add a one-sentence mitigation: what to watch for, or how to word the prompt to preserve working cases.
+
+### 5. Handle qualitative-only insights — STILL PRODUCE FIXES
+
+Some insights from Stage 3 may be flagged as "unmeasurable." **These still get fixes.** An insight that the agent fabricates data or violates policy is a real problem whether or not we can measure it programmatically. Treat them the same as any other insight:
+
+- Run the same triage (validity → already-handled → code-vs-prompt) as every other insight.
+- Include them in the **priority-ranked implementation list** alongside all other fixes. They are NOT second-class.
+- Use the trace evidence from the insight (not the metric) to assess impact and priority. If the insight has strong trace evidence showing clear failures, rank it accordingly.
+- For prioritization: since there is no metric denominator, use confidence = 0.5 and estimate impact from the severity described in the insight evidence.
+- In the fix entry, note that this fix has no programmatic metric for automated before/after comparison, so improvement should be verified via manual trace review or LLM-as-judge after generating new traces.
+
+Only relegate an insight to a non-actionable "Monitor Items" section if the triage concludes it should be **discarded** (not valid or not actionable). Being unmeasurable is NOT a reason to skip fixing it.
+
+### 6. Link to metrics
+
+For each non-discarded fix, identify which metric(s) from the rubric would move if this fix is implemented. Use the metric IDs from `eval/baseline_metrics.md` (e.g., M1, M2).
+
+### 7. Prioritize
+
+Rank non-discarded fixes using this formula:
+
+```
+Priority Score = Impact × Confidence × Tier Bonus ÷ Risk Factor
+```
+
+Where:
+- **Impact** = estimated metric delta. Use the gap between baseline and 100% as the ceiling. A fix expected to close 50% of that gap on M1 (baseline 41.4%) has impact = 0.5 × (1.0 - 0.414) = 0.293.
+- **Confidence** = sample size reliability. Use the denominator from `baseline_metrics.json`:
+  - denominator >= 20: confidence = 1.0
+  - denominator 10-19: confidence = 0.8
+  - denominator 5-9: confidence = 0.6
+  - denominator < 5: confidence = 0.3
+- **Tier Bonus** = leading metrics get a 1.5x multiplier (they validate adoption), lagging and quality get 1.0x. Rationale: leading metrics move first and tell you if your fix is even being adopted — you want those signals early.
+- **Risk Factor** = None: 1.0, Low: 1.0, Medium: 1.5, High: 2.0
+
+You do not need to compute exact scores to three decimal places. The formula is a tiebreaker and sanity check. The point is:
+- High-impact, high-confidence, leading-metric fixes with low risk go first.
+- Low-confidence fixes (small denominators) get deprioritized even if the metric is at 0%.
+- High-risk fixes get deprioritized unless impact is overwhelming.
+
+After scoring, apply one manual adjustment pass: if a fix is a prerequisite for another fix (e.g., "confirmation protocol" must exist before "post-confirmation execution" can be measured), promote the prerequisite even if its standalone score is lower.
+
+## Output format
+
+Write to `eval/action_plan.md`:
+
+```markdown
+# Action Plan
+
+## Summary
+- Total insights: N
+- Discarded: X (with reasons)
+- Code fixes: Y
+- Prompt fixes: Z
+- Fixes without programmatic metric (verify manually): Q
+
+## Implementation Priority
+| Rank | Fix | Type | Metrics | Risk | Score rationale |
+|------|-----|------|---------|------|-----------------|
+| 1 | [name] | prompt | M1, M2 | Low | [one-line: why this ranks here] |
+| 2 | ... | ... | ... | ... | ... |
+
+---
+
+## Skill: [insight ID(s)] — [title]
+**Summary:** [one-line description of what the skill addresses]
+**Verdict:** `prompt fix` | `code fix` | `discard`
+**Classification path:** [which branch of the decision tree — e.g., "Agent has tools and data but acts wrong → prompt fix"]
+**Rationale:** [why this verdict — reference specific trace evidence from insights]
+**Risk:** None | Low | Medium | High — [one-sentence justification]
+**Risk mitigation:** [for Medium/High only — what to watch for or how to preserve working cases]
+**Recommendation:** [specific change to make]
+**Files to modify:** [list of files, for code fixes]
+**Metric link:** [which metrics would move, with baseline values]
+**Already-handled check:** [what you grepped, what existing prompt text you found, verdict]
+
+---
+[repeat for each insight]
+
+## Consolidated Prompt Skills
+[After all per-insight entries, list the final merged prompt skill texts in priority order, ready for Stage 7 to implement]
+
+## Monitor Items (Non-Actionable Only)
+[Only insights that were triaged as genuinely non-actionable — e.g., the agent cannot change this behavior, or the insight is noise. Unmeasurable insights that are still real problems should appear in the priority list above, NOT here.]
+```
+
+Group related insights under cluster headings when they address the same underlying behavior. For merged insights, list all constituent insight IDs in the heading.
+
+## Outputs
+
+- `eval/action_plan.md`

.claude/skills/kayba-pipeline/stage-6-hitl/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: kayba-stage-6-hitl
+description: Human-In-The-Loop gate that presents the action plan with full context, collects an informed approval/modification/rejection decision, and records the outcome. Trigger when the user says "run stage 6", "HITL review", "approve action plan", or when invoked by the kayba-pipeline orchestrator. Requires eval/action_plan.md and eval/baseline_metrics.md to exist.
+---
+
+# Stage 6: Human-In-The-Loop Gate
+
+Present the action plan with enough context for an informed decision, collect the user's approval, and record the outcome.
+
+The goal is not rubber-stamping. The user must receive enough information to genuinely evaluate, modify, or reject the plan -- even if they have not seen Stages 1-5.
+
+## Inputs
+
+- `eval/action_plan.md` -- the prioritized action plan from Stage 5
+- `eval/baseline_metrics.md` -- the evaluation rubric with baseline values
+- `eval/baseline_metrics.json` -- raw metric data (for exact numerator/denominator counts)
+- `eval/stage1_insights_summary.md` -- original insights (for trace evidence references)
+
+Read all four files before starting.
+
+## Process
+
+### 1. Build the executive summary
+
+Compute and present the following counts from the action plan:
+
+- Total insights analyzed (raw count before deduplication)
+- Distinct actionable items after deduplication
+- Breakdown: prompt fixes, code fixes, discarded
+- Discard rate with one-line reason per discard (e.g., "5ac7f4ce: efficiency optimization, conflicts with turn discipline constraint")
+
+Format:
+
+```
+EXECUTIVE SUMMARY
+-----------------
+Insights analyzed:    19 (raw) -> 12 distinct after dedup
+Actionable:           9  (8 prompt fixes, 1 code fix)
+Discarded:            3  (reasons listed below)
+
+Discards:
+  - 5ac7f4ce (Upfront Info Collection): conflicts with higher-priority turn discipline
+  - fe2d51cb (Proactive Reservation Lookup): already default behavior, no failure evidence
+  - 1fa1b826 (Cancellation Denial Enumeration): subsumed into cancellation checklist
+```
+
+### 2. Present the top 3 highest-impact changes
+
+For each of the top 3 fixes by priority, present:
+
+**Before/after behavior** -- use concrete examples from actual traces referenced in the insights. Quote the specific agent behavior that was wrong (before) and describe what the agent should do instead (after). Reference the trace task ID.
+
+**Target metric delta** -- which metric(s) this fix targets, the current baseline value, and the expected direction. Do not fabricate precise target numbers. Use the format: "M1: 41.4% -> higher (target: 90%+)" only when the action plan provides a target; otherwise use "M1: 41.4% -> up".
+
+**Risk rating** -- assess each fix:
+- `Low` -- additive prompt instruction, no behavioral side effects expected
+- `Medium` -- changes existing behavior, could affect adjacent workflows
+- `High` -- modifies code/infrastructure, or could degrade a metric while improving another
+
+Format each as a numbered block:
+
+```
+#1: Turn Discipline (covers 55c00c40, d9683144)
+    Type:     prompt fix
+    Metrics:  M1 (41.4% -> up), M2 (20.7% -> up)
+    Risk:     Low
+
+    BEFORE (task_1, task_5, task_7, ...):
+      Agent batches 2-3 tool calls per turn (e.g., get_reservation + get_flight_status
+      in a single response). Also includes user-facing text alongside tool calls.
+
+    AFTER:
+      Exactly one tool call per response. No user-facing content in tool-call turns.
+      Agent processes each result before making the next call.
+```
+
+### 3. Present the full prioritized fix list
+
+Display all non-discarded fixes in a table:
+
+```
+| Priority | Fix Name                          | Type       | Target Metrics  | Risk   | Effort |
+|----------|-----------------------------------|------------|-----------------|--------|--------|
+| 1        | Turn Discipline                   | prompt fix | M1, M2          | Low    | Low    |
+| 2        | Post-Confirmation Execution       | prompt fix | M3              | Low    | Low    |
+| 3        | Cancellation Checklist            | prompt fix | M5              | Low    | Low    |
+| ...      | ...                               | ...        | ...             | ...    | ...    |
+```
+
+Effort ratings:
+- `Low` -- single prompt addition, under 5 lines
+- `Medium` -- multiple prompt additions or minor code change
+- `High` -- significant code changes, new metric implementation, or architectural changes
+
+### 4. Present "What we are NOT fixing and why"
+
+List every discarded insight with:
+- Insight ID and name
+- One-line reason for discard
+- What would change your mind (under what conditions should this be revisited)
+
+This section exists so the user can override a discard if they disagree.
+
+### 5. Flag small-sample and low-confidence items
+
+Any metric with denominator < 5 must be explicitly called out:
+
+```
+LOW-CONFIDENCE METRICS (small sample size):
+  - M5 (Cancellation Policy Compliance): based on 2 observations -- directional only
+  - M6 (Compensation Execution Rate): based on 1 observation -- directional only
+
+Fixes targeting these metrics (Cancellation Checklist, Compensation Rules) are
+still recommended because the policy violations are clear from trace evidence,
+but the measured improvement may not be statistically meaningful until the
+trace corpus grows.
+```
+
+Also flag any fix where the action plan notes uncertainty or partial evidence.
+
+### 6. Show the insight-to-fix traceability chain
+
+For each fix, present the chain: insight -> metric -> fix -> expected improvement. This can be a compact list or a table. The purpose is to let the user verify that nothing was lost or invented between stages.
+
+```
+TRACEABILITY:
+  55c00c40 (Tool Call Discipline) -> M1, M2 -> Skill 1 (Turn Discipline) -> M1 up, M2 up
+  6ea141e1 (Execution Discipline) -> M3 -> Skill 2 (Post-Confirmation) -> M3 up
+  0f4a952b + 6ce88ebb (Cancellation) -> M5 -> Skill 3 (Cancellation Checklist) -> M5 up
+  ...
+```
+
+### 7. Collect the decision
+
+Present exactly three options:
+
+```
+OPTIONS:
+  [A] Approve all -- implement all 9 fixes as described
+  [B] Approve with modifications -- review each fix individually
+  [C] Reject -- return to Stage 5 with feedback
+```
+
+Use the appropriate mechanism to collect the user's choice (direct question or AskUserQuestion if available).
+
+#### If the user selects [A] Approve all
+
+Record the decision and proceed. No further interaction needed.
+
+#### If the user selects [B] Approve with modifications
+
+Walk through each fix individually, in priority order. For each fix, present:
+- The fix name, type, and target metrics
+- The recommended prompt/code change (quote the exact text from the action plan)
+- Risk and effort ratings
+
+Then ask: "Approve / Skip / Modify?"
+
+- **Approve** -- keep as-is
+- **Skip** -- remove from the plan, record reason
+- **Modify** -- ask the user what to change, record the original and the modification
+
+After walking through all fixes, present a summary of changes:
+- Fixes approved as-is: N
+- Fixes skipped: M (list with reasons)
+- Fixes modified: K (list with what changed)
+
+Ask for final confirmation: "Proceed with this modified plan?"
+
+Then update `eval/action_plan.md`:
+- Remove skipped fixes (move to a "Skipped by HITL" section at the bottom with reasons)
+- Update modified fixes with the user's changes, preserving the original recommendation in a "Original recommendation" sub-field
+- Add a header note: "Modified during HITL review on [date]. See eval/stage6_decision.md for details."
+
+#### If the user selects [C] Reject
+
+Ask the user for specific feedback:
+- What was wrong with the plan?
+- Which insights or metrics should be reconsidered?
+- Any new constraints or priorities?
+
+Record the feedback in `eval/stage6_decision.md` and signal that Stage 5 should be re-run with the user's feedback incorporated.
+
+## Output format
+
+### eval/stage6_decision.md
+
+Write this file regardless of which option was selected.
+
+```markdown
+# Stage 6: HITL Decision Record
+
+## Date
+[timestamp]
+
+## Decision
+[Approve all | Approve with modifications | Reject]
+
+## What was presented
+- Total insights: N (M distinct after dedup)
+- Actionable fixes: X (Y prompt, Z code)
+- Discarded: W
+- Metrics: [list metric IDs and baselines]
+- Low-confidence flags: [list metrics with small denominators]
+
+## Top 3 changes presented
+1. [fix name] -- [type] -- targets [metrics] -- risk [rating]
+2. ...
+3. ...
+
+## Decision details
+
+### If Approve all:
+User approved all N fixes without modification.
+Reasoning: [any reasoning the user provided, or "No additional reasoning provided"]
+
+### If Approve with modifications:
+| Fix | Original Status | Decision | Reason |
+|-----|----------------|----------|--------|
+| Turn Discipline | Priority 1 | Approved | -- |
+| Compensation Rules | Priority 5 | Modified | User changed wording to... |
+| Cabin Change Rules | Priority 8 | Skipped | User considers low priority |
+
+Modifications detail:
+- [Fix name]: Original: "..." -> Modified: "..." -- User rationale: "..."
+
+### If Reject:
+User feedback: [verbatim feedback]
+Specific concerns: [list]
+Re-run instructions for Stage 5: [what to change]
+
+## Traceability snapshot
+[Copy of the traceability chain from step 6, so the decision record is self-contained]
+```
+
+### eval/action_plan.md (updated, only if modifications were made)
+
+If the user selected [B] and made changes:
+- Add a modification header at the top of the file
+- Update individual fix entries with user changes
+- Move skipped fixes to a "Skipped by HITL" section
+- Preserve original recommendations as sub-fields for auditability
+
+## Rules
+
+- Do NOT auto-approve. The entire point of this stage is human judgment.
+- Do NOT summarize so aggressively that the user cannot evaluate. When in doubt, include more context.
+- Do NOT proceed to Stage 7 until a clear approval (full or modified) is recorded.
+- Do NOT modify `eval/action_plan.md` unless the user explicitly requests modifications.
+- Do NOT skip the small-sample warnings. If M5 has denominator 2 and M6 has denominator 1, the user must know this.
+- Do NOT fabricate target metric values. Use targets from the action plan when available; otherwise state direction only.
+- Always present the "What we are NOT fixing" section. Omitting discards hides information the user needs.
+- If the user asks clarifying questions, answer them fully before re-presenting the decision options.
+
+## Outputs
+
+- `eval/stage6_decision.md` -- full record of what was presented, decided, and why
+- `eval/action_plan.md` -- updated only if the user selected "Approve with modifications"

.claude/skills/kayba-pipeline/stage-7-fixer/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: kayba-stage-7-fixer
+description: Implement the approved fixes from the action plan and log all changes. Trigger when the user says "run stage 7", "implement fixes", "apply action plan", or when invoked by the kayba-pipeline orchestrator. Requires eval/action_plan.md to exist.
+---
+
+# Stage 7: Fix Implementation
+
+Implement every non-discarded fix from the approved action plan.
+
+## Inputs
+
+- `eval/action_plan.md` -- the approved action plan from Stage 5 (possibly modified during HITL in Stage 6)
+- `eval/stage6_decision.md` -- if it exists, the HITL decision record from Stage 6 (contains user modifications)
+- `eval/baseline_metrics.json` -- the pre-fix baseline metrics from Stage 3 (for reference in changes log)
+
+Read the action plan and stage6 decision (if present) before starting.
+
+## Pre-flight: Git Safety Checkpoint
+
+Before making ANY changes to source files:
+
+1. Run `git status` to confirm the working tree state
+2. Create a safety commit or stash:
+   ```
+   git stash push -m "pre-pipeline-fixes-$(date +%Y%m%d-%H%M%S)"
+   ```
+   If there are no uncommitted changes to stash, create a lightweight tag instead:
+   ```
+   git tag pre-pipeline-fixes-$(date +%Y%m%d-%H%M%S)
+   ```
+3. Record the stash ref or tag name in `eval/changes_log.md` under a "Rollback" section so the user can restore if needed
+
+This ensures every fix is reversible with a single `git stash pop` or `git checkout`.
+
+## Pre-flight: HITL Modification Check
+
+If `eval/stage6_decision.md` exists:
+
+1. Read it and identify any items the user modified, added, or re-prioritized during Stage 6
+2. Build a set of `HITL_MODIFIED_IDS` -- the insight/skill IDs that the user changed
+3. When logging each fix later, tag modified items with `[HITL-MODIFIED]` in the changes log so reviewers know which fixes reflect user judgment vs. the original pipeline output
+
+If the file does not exist, assume no HITL modifications were made.
+
+## Pre-flight: Conflict Scan
+
+Before implementing any fixes, scan the action plan for potential conflicts:
+
+1. Build a map of `file_path -> [fix IDs that touch it]`
+2. If two or more fixes modify the same file, flag them as **co-located**
+3. If two or more fixes modify the same section (within ~20 lines of each other), flag them as **overlapping**
+4. For overlapping fixes: plan to apply them sequentially in priority order, re-reading the file between each edit to ensure the second fix still makes sense on top of the first
+5. Log any detected conflicts at the top of `eval/changes_log.md` under a "Conflict Notes" section
+
+## Process
+
+Work through the action plan in priority order. For each non-discarded fix:
+
+### 1. Understand the fix
+
+- Read the recommendation carefully
+- Read the referenced files in the codebase
+- Understand the surrounding code before making changes
+- Check if this fix was flagged as co-located or overlapping in the conflict scan. If overlapping with a previously-applied fix, re-read the target file to see the current state after prior edits
+
+### 2. Implement the change
+
+**For code fixes:**
+- Find the relevant files
+- Make the minimal, targeted change described in the recommendation
+- Do not refactor surrounding code unless the fix obviously breaks without light adjacent cleanup (e.g., an import is missing, a variable was renamed). If you make adjacent cleanup, log it explicitly as "adjacent cleanup" in the change entry
+- Do not add features beyond what was recommended
+
+**For prompt fixes:**
+- Find the system prompt file (use domain context from Stage 2 if needed)
+- Add the recommended instruction at the appropriate location
+- Do not rewrite existing prompt text unless the recommendation explicitly says to
+
+### 3. Log the change
+
+Append to `eval/changes_log.md`:
+
+```markdown
+## Fix N: [skill/insight name] [HITL-MODIFIED if applicable]
+**Type:** code fix | prompt fix
+**Verdict from action plan:** [quote the recommendation]
+**Files modified:**
+- `path/to/file.py` -- [what changed and why]
+**Before:**
+\```
+[relevant snippet before change]
+\```
+**After:**
+\```
+[relevant snippet after change]
+\```
+**Linked metrics:** [which metrics this should improve]
+**Conflict notes:** [if this fix overlapped with another, note it here; otherwise "none"]
+```
+
+### 4. Handle uncertainty (NEEDS REVIEW workflow)
+
+If a fix requires changes you are unsure about:
+
+1. Do NOT implement it
+2. Log it as `NEEDS REVIEW` in the changes log with:
+   - What specifically is unclear
+   - What information would resolve the ambiguity
+   - The files and lines you examined
+3. **Continue to the next fix** -- do not block the pipeline
+4. At the end of all fixes, collect all NEEDS REVIEW items into a dedicated section (see Output format below). The pipeline does NOT stop; these items are presented to the user after all other fixes are applied.
+
+## Post-Fix: Next Steps (Do NOT Re-run Baselines)
+
+Do NOT re-run `compute_baselines.py` as part of this stage. The baseline metrics were computed against the original traces, which reflect old agent behavior. Re-running against the same traces will show zero movement for prompt-only fixes and is misleading.
+
+Instead, after all fixes are applied, include a **Next Steps** section in the changes log that tells the user:
+
+1. Generate new traces by running the agent with the updated prompts/code
+2. Then re-run baselines against the new traces:
+   ```bash
+   python eval/compute_baselines.py --traces-dir <new_traces_folder> --output eval/post_fix_metrics.json
+   ```
+3. Compare `eval/post_fix_metrics.json` against `eval/baseline_metrics.json` to measure actual improvement
+
+## Rules
+
+- Do NOT modify trace files
+- Do NOT make changes beyond what the action plan recommends (except adjacent cleanup logged explicitly)
+- Make minimal, targeted changes -- don't clean up or refactor surrounding code
+- If the action plan says "discard", skip that entry entirely
+- You MAY write `eval/changes_log.md` as the primary output
+- Do NOT run `eval/compute_baselines.py` -- baselines should only be re-computed after new traces are generated with the updated agent
+
+## Output format
+
+Write `eval/changes_log.md`:
+
+```markdown
+# Changes Log
+
+## Rollback
+- **Safety ref:** `git stash` ref or tag name
+- **To undo all fixes:** `git stash pop` or `git checkout <tag>`
+
+## Conflict Notes
+- [any file/region conflicts detected, or "No conflicts detected"]
+
+## Summary
+- Code fixes applied: N
+- Prompt fixes applied: M
+- Skipped / needs review: K
+- HITL-modified items: J
+
+---
+
+## Fix 1: [skill name]
+...
+
+## Fix 2: [skill name]
+...
+
+---
+
+## Needs Review
+[Collected list of all NEEDS REVIEW items with context, or "None -- all fixes applied successfully"]
+
+For each NEEDS REVIEW item:
+- **Fix N: [skill name]**
+- **What is unclear:** [specific ambiguity]
+- **What would resolve it:** [information needed]
+- **Files examined:** [paths and lines]
+
+---
+
+## Next Steps
+
+To measure actual improvement:
+1. Generate new traces by running the agent with the updated prompts/code
+2. Re-run baselines:
+\```bash
+python eval/compute_baselines.py --traces-dir <new_traces_folder> --output eval/post_fix_metrics.json
+\```
+3. Compare `eval/post_fix_metrics.json` against `eval/baseline_metrics.json` to measure metric deltas
+```
+
+## Outputs
+
+- `eval/changes_log.md` -- full log of all changes, conflicts, NEEDS REVIEW items, and next steps
+- The actual code/prompt changes in the repository
+- A git stash or tag for rollback

.env.example

@@ -0,0 +1,69 @@
+# API Keys for LLM Providers
+# Copy this file to .env and add your actual API keys
+
+# OpenAI
+OPENAI_API_KEY=your-openai-api-key-here
+
+# Anthropic (Claude)
+ANTHROPIC_API_KEY=your-anthropic-api-key-here
+
+# Google (Gemini)
+GOOGLE_API_KEY=your-google-api-key-here
+
+# DeepSeek
+DEEPSEEK_API_KEY=your-deepseek-api-key-here
+
+# Ollama Cloud
+OLLAMA_API_KEY=your_api_key
+
+# Cohere
+COHERE_API_KEY=your-cohere-api-key-here
+
+# Bedrock bearer token (passed as api_key to LiteLLM, not as AWS_ACCESS_KEY_ID)
+BEDROCK_API_KEY=your-bedrock-api-key-here
+
+# Azure OpenAI (optional)
+AZURE_API_KEY=your-azure-api-key-here
+AZURE_API_BASE=https://your-resource.openai.azure.com
+AZURE_API_VERSION=2024-02-15-preview
+
+# AWS Bedrock (optional)
+AWS_ACCESS_KEY_ID=your-aws-access-key
+AWS_SECRET_ACCESS_KEY=your-aws-secret-key
+AWS_REGION_NAME=us-east-1
+
+# Hugging Face (optional)
+HUGGINGFACE_API_KEY=your-huggingface-api-key-here
+
+# Replicate (optional)
+REPLICATE_API_KEY=your-replicate-api-key-here
+
+# Together AI (optional)
+TOGETHER_API_KEY=your-together-api-key-here
+
+# Model Configuration (optional)
+DEFAULT_MODEL=gpt-4o-mini
+DEFAULT_TEMPERATURE=0.0
+DEFAULT_MAX_TOKENS=512
+
+# Cost Tracking (optional)
+TRACK_COSTS=true
+MAX_BUDGET=10.0
+
+# Opik Observability (optional)
+# Disable Opik tracing when not running a local Opik server
+# Either variable works:
+# OPIK_ENABLED=false
+# OPIK_DISABLED=true
+
+# Benchmark Configuration
+# Cache directories for benchmark data (optional - defaults to ~/.cache/huggingface)
+BENCHMARK_CACHE_DIR=/path/to/benchmark/cache
+HF_DATASETS_CACHE=/path/to/huggingface/cache
+HF_HUB_CACHE=/path/to/huggingface/hub/cache
+
+# AppWorld configuration (required for AppWorld benchmark)
+APPWORLD_ROOT=/path/to/appworld/data
+
+# Results output directory (optional)
+BENCHMARK_RESULTS_DIR=./benchmark_results

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/kayba-banner.png filter=lfs diff=lfs merge=lfs -text
+benchmarks/tasks/tau_bench/Tau2Benchmark[[:space:]]Result[[:space:]]Haiku4.5.png filter=lfs diff=lfs merge=lfs -text
+examples/seahorse-emoji-ace.gif filter=lfs diff=lfs merge=lfs -text
+mlflow.db filter=lfs diff=lfs merge=lfs -text

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to deploy (e.g. 0.8)"
+        required: true
+        default: "dev"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for mike versioning
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: pip install mkdocs-material mike
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy versioned docs (on tag)
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          mike deploy --push --update-aliases $VERSION latest
+          mike set-default --push latest
+
+      - name: Deploy dev docs (on main push)
+        if: github.ref == 'refs/heads/main'
+        run: mike deploy --push dev
+
+      - name: Deploy manually triggered version
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          mike deploy --push --update-aliases ${{ github.event.inputs.version }} latest
+          mike set-default --push latest

.github/workflows/publish.yml

@@ -0,0 +1,290 @@
+name: Publish Packages
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: 'Publish to TestPyPI instead of PyPI'
+        required: false
+        default: 'false'
+        type: choice
+        options:
+          - 'true'
+          - 'false'
+
+jobs:
+  # ── ace-framework (Python) ──────────────────────────────────────────
+
+  build-ace:
+    name: Build ace-framework
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+
+    - name: Build package
+      run: python -m build
+
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: ace-framework-dist
+        path: dist/
+
+  # ── kayba-tracing (Python) ─────────────────────────────────────────
+
+  build-kayba-tracing:
+    name: Build kayba-tracing
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+
+    - name: Build package
+      run: python -m build sdk/python
+
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: kayba-tracing-dist
+        path: sdk/python/dist/
+
+  # ── @kayba_ai/tracing (TypeScript) ────────────────────────────────────
+
+  build-kayba-tracing-ts:
+    name: Build @kayba_ai/tracing
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        registry-url: 'https://registry.npmjs.org'
+
+    - name: Install dependencies
+      run: npm ci
+      working-directory: sdk/typescript
+
+    - name: Build
+      run: npm run build
+      working-directory: sdk/typescript
+
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: kayba-tracing-ts-dist
+        path: |
+          sdk/typescript/dist/
+          sdk/typescript/package.json
+
+  # ── @kayba_ai/openclaw-tracing (TypeScript) ───────────────────────────
+
+  build-openclaw-tracing:
+    name: Build @kayba_ai/openclaw-tracing
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        registry-url: 'https://registry.npmjs.org'
+
+    - name: Install dependencies
+      run: npm ci
+      working-directory: sdk/openclaw
+
+    - name: Build
+      run: npm run build
+      working-directory: sdk/openclaw
+
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: openclaw-tracing-dist
+        path: |
+          sdk/openclaw/dist/
+          sdk/openclaw/package.json
+          sdk/openclaw/openclaw.plugin.json
+          sdk/openclaw/README.md
+
+  # ── Publish to TestPyPI ────────────────────────────────────────────
+
+  publish-to-testpypi:
+    name: Publish ace-framework to TestPyPI
+    if: github.event.inputs.test_pypi == 'true' || github.event_name == 'workflow_dispatch'
+    needs: [build-ace]
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/ace-framework/
+    permissions:
+      id-token: write
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: ace-framework-dist
+        path: dist/
+
+    - name: Publish to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        skip-existing: true
+
+  publish-kayba-tracing-to-testpypi:
+    name: Publish kayba-tracing to TestPyPI
+    if: github.event.inputs.test_pypi == 'true' || github.event_name == 'workflow_dispatch'
+    needs: [build-kayba-tracing]
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/kayba-tracing/
+    permissions:
+      id-token: write
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: kayba-tracing-dist
+        path: dist/
+
+    - name: Publish to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        skip-existing: true
+
+  # ── Publish to PyPI ────────────────────────────────────────────────
+
+  publish-to-pypi:
+    name: Publish ace-framework to PyPI
+    if: github.event_name == 'release'
+    needs: [build-ace]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ace-framework/
+    permissions:
+      id-token: write
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: ace-framework-dist
+        path: dist/
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-kayba-tracing-to-pypi:
+    name: Publish kayba-tracing to PyPI
+    if: github.event_name == 'release'
+    needs: [build-kayba-tracing]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/kayba-tracing/
+    permissions:
+      id-token: write
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: kayba-tracing-dist
+        path: dist/
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  # ── Publish to npm ─────────────────────────────────────────────────
+
+  publish-to-npm:
+    name: Publish @kayba_ai/tracing to npm
+    if: github.event_name == 'release'
+    needs: [build-kayba-tracing-ts]
+    runs-on: ubuntu-latest
+    environment:
+      name: npm
+      url: https://www.npmjs.com/package/@kayba_ai/tracing
+    permissions:
+      contents: read
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        registry-url: 'https://registry.npmjs.org'
+
+    - name: Install dependencies
+      run: npm ci
+      working-directory: sdk/typescript
+
+    - name: Build
+      run: npm run build
+      working-directory: sdk/typescript
+
+    - name: Publish to npm
+      run: npm publish --access public
+      working-directory: sdk/typescript
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-openclaw-tracing-to-npm:
+    name: Publish @kayba_ai/openclaw-tracing to npm
+    if: github.event_name == 'release'
+    needs: [build-openclaw-tracing]
+    runs-on: ubuntu-latest
+    environment:
+      name: npm
+      url: https://www.npmjs.com/package/@kayba_ai/openclaw-tracing
+    permissions:
+      contents: read
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        registry-url: 'https://registry.npmjs.org'
+
+    - name: Install dependencies
+      run: npm ci
+      working-directory: sdk/openclaw
+
+    - name: Build
+      run: npm run build
+      working-directory: sdk/openclaw
+
+    - name: Publish to npm
+      run: npm publish --access public
+      working-directory: sdk/openclaw
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,47 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop, lanzelot-dev ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:  # Allow manual triggering
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.12']  # Matches pyproject.toml requires-python == 3.12.*
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+
+    - name: Install dependencies
+      run: uv sync --extra mcp --extra tracing
+
+    - name: Run tests with coverage
+      run: |
+        uv run pytest -m "not requires_api"
+
+    - name: Upload coverage reports (Linux only)
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-report
+        path: htmlcov/
+        retention-days: 30
+
+    - name: Type checking (Linux only)
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        uv run mypy ace/ --ignore-missing-imports

.gitignore

@@ -0,0 +1,124 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project specific
+*.pdf
+*.png
+!benchmarks/tasks/tau_bench/*.png
+!examples/browser-use/**/*.png
+!assets/*.png
+ACE_IMPROVEMENTS.md
+ACE_ROADMAP.md
+DEMO_TODO.md
+*.egg-info/
+reports/
+docs/method_outline.md
+logs/
+
+# Generated skillbook and result files
+*_skillbook.json
+ace_domain_skillbook.json
+kayba_learned.json
+kayba_test_skillbook.json
+my_agent.json
+my_trained_agent.json
+*.log
+
+# Checkpoint files (generated during training)
+**/checkpoints/*.json
+*_checkpoint_*.json
+*_latest.json
+evaluation_results/*.json
+
+# Benchmark data and cache
+benchmark_results/
+benchmark_cache/
+tau_benchmark_results/
+results/
+appworld_data/
+*.arrow
+*.parquet
+huggingface_cache/
+
+# MkDocs build output
+site/
+
+# Sensitive/private data (NEVER commit!)
+.private/
+
+# GSD planning artifacts (NEVER commit!)
+.planning/
+
+# Node build artifacts
+node_modules/
+
+# Local scratch / experiment outputs
+tmp/
+
+spyfly-traces

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ace-eval"]
+	path = ace-eval
+	url = git@github.com:kayba-ai/ace-eval.git

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  # Black - code formatting (auto-fixes)
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black
+        args: [--line-length=88]
+        language_version: python3.12
+
+  # MyPy - type checking (blocks commits on errors)
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        args: [--ignore-missing-imports, --warn-unused-configs]
+        additional_dependencies:
+          - types-requests
+          - types-pyyaml
+        files: ^ace/
+        language_version: python3.12

.specify/memory/constitution.md

@@ -0,0 +1,121 @@
+<!--
+  Sync Impact Report
+  ==================
+  Version change: 1.0.0 → 1.1.0
+  Principles added:
+    - IV. Clean & Modular Code
+  Principles unchanged:
+    - I. Ease of Use First
+    - II. Practical Value
+    - III. Simplicity
+  Sections unchanged:
+    - Development Standards
+    - Quality Gates
+    - Governance
+  Removed sections: None
+  Templates validated:
+    ✅ .specify/templates/plan-template.md — Constitution Check section compatible
+    ✅ .specify/templates/spec-template.md — No conflicts
+    ✅ .specify/templates/tasks-template.md — No conflicts
+    ✅ .specify/templates/checklist-template.md — No conflicts
+  Follow-up TODOs: None
+-->
+
+# ACE Framework Constitution
+
+## Core Principles
+
+### I. Ease of Use First
+
+Every public API, integration, and workflow MUST prioritize developer
+experience above all else.
+
+- New users MUST be able to install and run a working example in under
+  5 minutes with no more than 3 lines of code.
+- Sensible defaults MUST be provided for every configuration option.
+  Users MUST NOT be required to understand internals to get started.
+- Breaking changes to the public API MUST follow deprecation warnings
+  for at least one minor release before removal.
+- Documentation MUST include a copy-pasteable quick start for every
+  integration (LiteLLM, LangChain, browser-use, Claude Code).
+
+### II. Practical Value
+
+Every feature MUST solve a real, demonstrable problem for users
+building AI agents.
+
+- Features MUST NOT be added speculatively. Each addition MUST have a
+  concrete use case tied to agent improvement or developer workflow.
+- Performance claims MUST be backed by reproducible benchmarks or
+  examples. No unsubstantiated marketing language in docs or code.
+- Integration wrappers MUST add measurable value (learning, skillbook
+  evolution) beyond what the wrapped framework already provides.
+
+### III. Simplicity
+
+Prefer the simplest solution that works. Complexity MUST be justified.
+
+- YAGNI: Do not build for hypothetical future requirements. Three
+  similar lines of code are better than a premature abstraction.
+- New abstractions MUST be used in at least two places before
+  extraction into a shared utility.
+- Dependencies MUST be kept minimal. Optional extras (observability,
+  LangChain, transformers) stay optional — the core install MUST
+  remain lightweight.
+
+### IV. Clean & Modular Code
+
+All code MUST be clean, modular, and extensible.
+
+- Modules MUST have a single, clear responsibility. Each file MUST
+  do one thing well and expose a well-defined interface.
+- Public APIs MUST be designed for extension without modification.
+  New integrations, LLM providers, and adapters MUST be addable
+  without changing existing code (open/closed principle).
+- Internal boundaries MUST be respected: core library (`ace/`),
+  integrations (`ace/integrations/`), LLM providers
+  (`ace/llm_providers/`), and observability (`ace/observability/`)
+  MUST NOT have circular dependencies.
+- Functions and classes MUST be small enough to understand at a
+  glance. If a function requires scrolling, it MUST be decomposed.
+
+## Development Standards
+
+- **Language**: Python 3.12 with type hints on all public APIs.
+- **Formatting**: Black (line length 88). All code MUST pass
+  `black --check` before merge.
+- **Testing**: pytest with coverage enforcement (`--cov-fail-under=25`).
+  New features MUST include tests. Bug fixes MUST include regression
+  tests.
+- **Distribution**: PyPI package `ace-framework`. Core install MUST NOT
+  exceed ~150MB. Heavy dependencies belong in optional extras.
+- **Commit style**: Conventional Commits (`feat(scope): subject`).
+
+## Quality Gates
+
+- All PRs MUST pass CI (formatting, type checks, test suite) before
+  merge.
+- Public API changes MUST update relevant documentation (README,
+  docstrings, quick start guides).
+- Benchmark results MUST NOT regress without explicit justification in
+  the PR description.
+- Skillbook format changes MUST maintain backward compatibility with
+  existing saved skillbooks or provide a migration path.
+
+## Governance
+
+This constitution is the highest-authority document for the ACE
+Framework project. All design decisions, PRs, and code reviews MUST
+verify compliance with these principles.
+
+- **Amendments**: Any change to this constitution MUST be documented
+  with a version bump, rationale, and updated `LAST_AMENDED_DATE`.
+- **Versioning**: MAJOR for principle removals or redefinitions, MINOR
+  for new principles or material expansions, PATCH for clarifications.
+- **Compliance**: Use `CLAUDE.md` for runtime development guidance.
+  This constitution defines the non-negotiable rules that `CLAUDE.md`
+  guidance MUST NOT contradict.
+- **Review**: Constitution compliance SHOULD be checked at the start
+  of each feature planning cycle (`/speckit.plan` Constitution Check).
+
+**Version**: 1.1.0 | **Ratified**: 2026-02-25 | **Last Amended**: 2026-02-25

.specify/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+eval $(get_feature_paths)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /speckit.specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if [[ ${#docs[@]} -eq 0 ]]; then
+        json_docs="[]"
+    else
+        json_docs=$(printf '"%s",' "${docs[@]}")
+        json_docs="[${json_docs%,}]"
+    fi
+    
+    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+    
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi

.specify/scripts/bash/common.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# Common functions and variables for all scripts
+
+# Get repository root, with fallback for non-git repositories
+get_repo_root() {
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        git rev-parse --show-toplevel
+    else
+        # Fall back to script location for non-git repos
+        local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        (cd "$script_dir/../../.." && pwd)
+    fi
+}
+
+# Get current branch, with fallback for non-git repositories
+get_current_branch() {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
+        echo "$SPECIFY_FEATURE"
+        return
+    fi
+
+    # Then check git if available
+    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
+        git rev-parse --abbrev-ref HEAD
+        return
+    fi
+
+    # For non-git repos, try to find the latest feature directory
+    local repo_root=$(get_repo_root)
+    local specs_dir="$repo_root/specs"
+
+    if [[ -d "$specs_dir" ]]; then
+        local latest_feature=""
+        local highest=0
+
+        for dir in "$specs_dir"/*; do
+            if [[ -d "$dir" ]]; then
+                local dirname=$(basename "$dir")
+                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
+                    local number=${BASH_REMATCH[1]}
+                    number=$((10#$number))
+                    if [[ "$number" -gt "$highest" ]]; then
+                        highest=$number
+                        latest_feature=$dirname
+                    fi
+                fi
+            fi
+        done
+
+        if [[ -n "$latest_feature" ]]; then
+            echo "$latest_feature"
+            return
+        fi
+    fi
+
+    echo "main"  # Final fallback
+}
+
+# Check if we have git available
+has_git() {
+    git rev-parse --show-toplevel >/dev/null 2>&1
+}
+
+check_feature_branch() {
+    local branch="$1"
+    local has_git_repo="$2"
+
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if [[ "$has_git_repo" != "true" ]]; then
+        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
+        return 0
+    fi
+
+    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
+        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
+        echo "Feature branches should be named like: 001-feature-name" >&2
+        return 1
+    fi
+
+    return 0
+}
+
+get_feature_dir() { echo "$1/specs/$2"; }
+
+# Find feature directory by numeric prefix instead of exact branch match
+# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
+find_feature_dir_by_prefix() {
+    local repo_root="$1"
+    local branch_name="$2"
+    local specs_dir="$repo_root/specs"
+
+    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
+    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
+        # If branch doesn't have numeric prefix, fall back to exact match
+        echo "$specs_dir/$branch_name"
+        return
+    fi
+
+    local prefix="${BASH_REMATCH[1]}"
+
+    # Search for directories in specs/ that start with this prefix
+    local matches=()
+    if [[ -d "$specs_dir" ]]; then
+        for dir in "$specs_dir"/"$prefix"-*; do
+            if [[ -d "$dir" ]]; then
+                matches+=("$(basename "$dir")")
+            fi
+        done
+    fi
+
+    # Handle results
+    if [[ ${#matches[@]} -eq 0 ]]; then
+        # No match found - return the branch name path (will fail later with clear error)
+        echo "$specs_dir/$branch_name"
+    elif [[ ${#matches[@]} -eq 1 ]]; then
+        # Exactly one match - perfect!
+        echo "$specs_dir/${matches[0]}"
+    else
+        # Multiple matches - this shouldn't happen with proper naming convention
+        echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
+        echo "Please ensure only one spec directory exists per numeric prefix." >&2
+        echo "$specs_dir/$branch_name"  # Return something to avoid breaking the script
+    fi
+}
+
+get_feature_paths() {
+    local repo_root=$(get_repo_root)
+    local current_branch=$(get_current_branch)
+    local has_git_repo="false"
+
+    if has_git; then
+        has_git_repo="true"
+    fi
+
+    # Use prefix-based lookup to support multiple branches per spec
+    local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
+
+    cat <<EOF
+REPO_ROOT='$repo_root'
+CURRENT_BRANCH='$current_branch'
+HAS_GIT='$has_git_repo'
+FEATURE_DIR='$feature_dir'
+FEATURE_SPEC='$feature_dir/spec.md'
+IMPL_PLAN='$feature_dir/plan.md'
+TASKS='$feature_dir/tasks.md'
+RESEARCH='$feature_dir/research.md'
+DATA_MODEL='$feature_dir/data-model.md'
+QUICKSTART='$feature_dir/quickstart.md'
+CONTRACTS_DIR='$feature_dir/contracts'
+EOF
+}
+
+check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+

.specify/scripts/bash/create-new-feature.sh

@@ -0,0 +1,297 @@
+#!/usr/bin/env bash
+
+set -e
+
+JSON_MODE=false
+SHORT_NAME=""
+BRANCH_NUMBER=""
+ARGS=()
+i=1
+while [ $i -le $# ]; do
+    arg="${!i}"
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --short-name)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            # Check if the next argument is another option (starts with --)
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            SHORT_NAME="$next_arg"
+            ;;
+        --number)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            BRANCH_NUMBER="$next_arg"
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
+            echo ""
+            echo "Options:"
+            echo "  --json              Output in JSON format"
+            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
+            echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --help, -h          Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
+            echo "  $0 'Implement OAuth2 integration for API' --number 5"
+            exit 0
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+    i=$((i + 1))
+done
+
+FEATURE_DESCRIPTION="${ARGS[*]}"
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>" >&2
+    exit 1
+fi
+
+# Function to find the repository root by searching for existing project markers
+find_repo_root() {
+    local dir="$1"
+    while [ "$dir" != "/" ]; do
+        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
+            echo "$dir"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# Function to get highest number from specs directory
+get_highest_from_specs() {
+    local specs_dir="$1"
+    local highest=0
+    
+    if [ -d "$specs_dir" ]; then
+        for dir in "$specs_dir"/*; do
+            [ -d "$dir" ] || continue
+            dirname=$(basename "$dir")
+            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
+            number=$((10#$number))
+            if [ "$number" -gt "$highest" ]; then
+                highest=$number
+            fi
+        done
+    fi
+    
+    echo "$highest"
+}
+
+# Function to get highest number from git branches
+get_highest_from_branches() {
+    local highest=0
+    
+    # Get all branches (local and remote)
+    branches=$(git branch -a 2>/dev/null || echo "")
+    
+    if [ -n "$branches" ]; then
+        while IFS= read -r branch; do
+            # Clean branch name: remove leading markers and remote prefixes
+            clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
+            
+            # Extract feature number if branch matches pattern ###-*
+            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
+                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
+                number=$((10#$number))
+                if [ "$number" -gt "$highest" ]; then
+                    highest=$number
+                fi
+            fi
+        done <<< "$branches"
+    fi
+    
+    echo "$highest"
+}
+
+# Function to check existing branches (local and remote) and return next available number
+check_existing_branches() {
+    local specs_dir="$1"
+
+    # Fetch all remotes to get latest branch info (suppress errors if no remotes)
+    git fetch --all --prune 2>/dev/null || true
+
+    # Get highest number from ALL branches (not just matching short name)
+    local highest_branch=$(get_highest_from_branches)
+
+    # Get highest number from ALL specs (not just matching short name)
+    local highest_spec=$(get_highest_from_specs "$specs_dir")
+
+    # Take the maximum of both
+    local max_num=$highest_branch
+    if [ "$highest_spec" -gt "$max_num" ]; then
+        max_num=$highest_spec
+    fi
+
+    # Return next number
+    echo $((max_num + 1))
+}
+
+# Function to clean and format a branch name
+clean_branch_name() {
+    local name="$1"
+    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
+}
+
+# Resolve repository root. Prefer git information when available, but fall back
+# to searching for repository markers so the workflow still functions in repositories that
+# were initialised with --no-git.
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    REPO_ROOT=$(git rev-parse --show-toplevel)
+    HAS_GIT=true
+else
+    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
+    if [ -z "$REPO_ROOT" ]; then
+        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
+        exit 1
+    fi
+    HAS_GIT=false
+fi
+
+cd "$REPO_ROOT"
+
+SPECS_DIR="$REPO_ROOT/specs"
+mkdir -p "$SPECS_DIR"
+
+# Function to generate branch name with stop word filtering and length filtering
+generate_branch_name() {
+    local description="$1"
+    
+    # Common stop words to filter out
+    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
+    
+    # Convert to lowercase and split into words
+    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+    
+    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
+    local meaningful_words=()
+    for word in $clean_name; do
+        # Skip empty words
+        [ -z "$word" ] && continue
+        
+        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
+        if ! echo "$word" | grep -qiE "$stop_words"; then
+            if [ ${#word} -ge 3 ]; then
+                meaningful_words+=("$word")
+            elif echo "$description" | grep -q "\b${word^^}\b"; then
+                # Keep short words if they appear as uppercase in original (likely acronyms)
+                meaningful_words+=("$word")
+            fi
+        fi
+    done
+    
+    # If we have meaningful words, use first 3-4 of them
+    if [ ${#meaningful_words[@]} -gt 0 ]; then
+        local max_words=3
+        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
+        
+        local result=""
+        local count=0
+        for word in "${meaningful_words[@]}"; do
+            if [ $count -ge $max_words ]; then break; fi
+            if [ -n "$result" ]; then result="$result-"; fi
+            result="$result$word"
+            count=$((count + 1))
+        done
+        echo "$result"
+    else
+        # Fallback to original logic if no meaningful words found
+        local cleaned=$(clean_branch_name "$description")
+        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
+    fi
+}
+
+# Generate branch name
+if [ -n "$SHORT_NAME" ]; then
+    # Use provided short name, just clean it up
+    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
+else
+    # Generate from description with smart filtering
+    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
+fi
+
+# Determine branch number
+if [ -z "$BRANCH_NUMBER" ]; then
+    if [ "$HAS_GIT" = true ]; then
+        # Check existing branches on remotes
+        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+    else
+        # Fall back to local directory check
+        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+        BRANCH_NUMBER=$((HIGHEST + 1))
+    fi
+fi
+
+# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
+FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+
+# GitHub enforces a 244-byte limit on branch names
+# Validate and truncate if necessary
+MAX_BRANCH_LENGTH=244
+if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
+    # Calculate how much we need to trim from suffix
+    # Account for: feature number (3) + hyphen (1) = 4 chars
+    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
+    
+    # Truncate suffix at word boundary if possible
+    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
+    # Remove trailing hyphen if truncation created one
+    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
+    
+    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
+    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
+    
+    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
+    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
+    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
+fi
+
+if [ "$HAS_GIT" = true ]; then
+    git checkout -b "$BRANCH_NAME"
+else
+    >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
+fi
+
+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+mkdir -p "$FEATURE_DIR"
+
+TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
+SPEC_FILE="$FEATURE_DIR/spec.md"
+if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
+
+# Set the SPECIFY_FEATURE environment variable for the current session
+export SPECIFY_FEATURE="$BRANCH_NAME"
+
+if $JSON_MODE; then
+    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
+else
+    echo "BRANCH_NAME: $BRANCH_NAME"
+    echo "SPEC_FILE: $SPEC_FILE"
+    echo "FEATURE_NUM: $FEATURE_NUM"
+    echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
+fi

.specify/scripts/bash/setup-plan.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+ARGS=()
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json]"
+            echo "  --json    Output results in JSON format"
+            echo "  --help    Show this help message"
+            exit 0 
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+done
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+# Check if we're on a proper feature branch (only for git repos)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# Ensure the feature directory exists
+mkdir -p "$FEATURE_DIR"
+
+# Copy plan template if it exists
+TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
+if [[ -f "$TEMPLATE" ]]; then
+    cp "$TEMPLATE" "$IMPL_PLAN"
+    echo "Copied plan template to $IMPL_PLAN"
+else
+    echo "Warning: Plan template not found at $TEMPLATE"
+    # Create a basic plan file if template doesn't exist
+    touch "$IMPL_PLAN"
+fi
+
+# Output results
+if $JSON_MODE; then
+    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
+        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
+else
+    echo "FEATURE_SPEC: $FEATURE_SPEC"
+    echo "IMPL_PLAN: $IMPL_PLAN" 
+    echo "SPECS_DIR: $FEATURE_DIR"
+    echo "BRANCH: $CURRENT_BRANCH"
+    echo "HAS_GIT: $HAS_GIT"
+fi
+

.specify/scripts/bash/update-agent-context.sh

@@ -0,0 +1,810 @@
+#!/usr/bin/env bash
+
+# Update agent context files with information from plan.md
+#
+# This script maintains AI agent context files by parsing feature specifications 
+# and updating agent-specific configuration files with project information.
+#
+# MAIN FUNCTIONS:
+# 1. Environment Validation
+#    - Verifies git repository structure and branch information
+#    - Checks for required plan.md files and templates
+#    - Validates file permissions and accessibility
+#
+# 2. Plan Data Extraction
+#    - Parses plan.md files to extract project metadata
+#    - Identifies language/version, frameworks, databases, and project types
+#    - Handles missing or incomplete specification data gracefully
+#
+# 3. Agent File Management
+#    - Creates new agent context files from templates when needed
+#    - Updates existing agent files with new project information
+#    - Preserves manual additions and custom configurations
+#    - Supports multiple AI agent formats and directory structures
+#
+# 4. Content Generation
+#    - Generates language-specific build/test commands
+#    - Creates appropriate project directory structures
+#    - Updates technology stacks and recent changes sections
+#    - Maintains consistent formatting and timestamps
+#
+# 5. Multi-Agent Support
+#    - Handles agent-specific file paths and naming conventions
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, Amazon Q Developer CLI, or Antigravity
+#    - Can update single agents or all existing agent files
+#    - Creates default Claude file if no agent files exist
+#
+# Usage: ./update-agent-context.sh [agent_type]
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qodercli
+# Leave empty to update all existing agent files
+
+set -e
+
+# Enable strict error handling
+set -u
+set -o pipefail
+
+#==============================================================================
+# Configuration and Global Variables
+#==============================================================================
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
+AGENT_TYPE="${1:-}"
+
+# Agent-specific file paths  
+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
+COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
+CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
+QWEN_FILE="$REPO_ROOT/QWEN.md"
+AGENTS_FILE="$REPO_ROOT/AGENTS.md"
+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
+AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
+ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
+CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
+QODER_FILE="$REPO_ROOT/QODER.md"
+AMP_FILE="$REPO_ROOT/AGENTS.md"
+SHAI_FILE="$REPO_ROOT/SHAI.md"
+Q_FILE="$REPO_ROOT/AGENTS.md"
+AGY_FILE="$REPO_ROOT/.agent/rules/specify-rules.md"
+BOB_FILE="$REPO_ROOT/AGENTS.md"
+
+# Template file
+TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
+
+# Global variables for parsed plan data
+NEW_LANG=""
+NEW_FRAMEWORK=""
+NEW_DB=""
+NEW_PROJECT_TYPE=""
+
+#==============================================================================
+# Utility Functions
+#==============================================================================
+
+log_info() {
+    echo "INFO: $1"
+}
+
+log_success() {
+    echo "✓ $1"
+}
+
+log_error() {
+    echo "ERROR: $1" >&2
+}
+
+log_warning() {
+    echo "WARNING: $1" >&2
+}
+
+# Cleanup function for temporary files
+cleanup() {
+    local exit_code=$?
+    rm -f /tmp/agent_update_*_$$
+    rm -f /tmp/manual_additions_$$
+    exit $exit_code
+}
+
+# Set up cleanup trap
+trap cleanup EXIT INT TERM
+
+#==============================================================================
+# Validation Functions
+#==============================================================================
+
+validate_environment() {
+    # Check if we have a current branch/feature (git or non-git)
+    if [[ -z "$CURRENT_BRANCH" ]]; then
+        log_error "Unable to determine current feature"
+        if [[ "$HAS_GIT" == "true" ]]; then
+            log_info "Make sure you're on a feature branch"
+        else
+            log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if plan.md exists
+    if [[ ! -f "$NEW_PLAN" ]]; then
+        log_error "No plan.md found at $NEW_PLAN"
+        log_info "Make sure you're working on a feature with a corresponding spec directory"
+        if [[ "$HAS_GIT" != "true" ]]; then
+            log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if template exists (needed for new files)
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_warning "Template file not found at $TEMPLATE_FILE"
+        log_warning "Creating new agent files will fail"
+    fi
+}
+
+#==============================================================================
+# Plan Parsing Functions
+#==============================================================================
+
+extract_plan_field() {
+    local field_pattern="$1"
+    local plan_file="$2"
+    
+    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
+        head -1 | \
+        sed "s|^\*\*${field_pattern}\*\*: ||" | \
+        sed 's/^[ \t]*//;s/[ \t]*$//' | \
+        grep -v "NEEDS CLARIFICATION" | \
+        grep -v "^N/A$" || echo ""
+}
+
+parse_plan_data() {
+    local plan_file="$1"
+    
+    if [[ ! -f "$plan_file" ]]; then
+        log_error "Plan file not found: $plan_file"
+        return 1
+    fi
+    
+    if [[ ! -r "$plan_file" ]]; then
+        log_error "Plan file is not readable: $plan_file"
+        return 1
+    fi
+    
+    log_info "Parsing plan data from $plan_file"
+    
+    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
+    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
+    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
+    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
+    
+    # Log what we found
+    if [[ -n "$NEW_LANG" ]]; then
+        log_info "Found language: $NEW_LANG"
+    else
+        log_warning "No language information found in plan"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        log_info "Found framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        log_info "Found database: $NEW_DB"
+    fi
+    
+    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
+        log_info "Found project type: $NEW_PROJECT_TYPE"
+    fi
+}
+
+format_technology_stack() {
+    local lang="$1"
+    local framework="$2"
+    local parts=()
+    
+    # Add non-empty parts
+    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
+    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
+    
+    # Join with proper formatting
+    if [[ ${#parts[@]} -eq 0 ]]; then
+        echo ""
+    elif [[ ${#parts[@]} -eq 1 ]]; then
+        echo "${parts[0]}"
+    else
+        # Join multiple parts with " + "
+        local result="${parts[0]}"
+        for ((i=1; i<${#parts[@]}; i++)); do
+            result="$result + ${parts[i]}"
+        done
+        echo "$result"
+    fi
+}
+
+#==============================================================================
+# Template and Content Generation Functions
+#==============================================================================
+
+get_project_structure() {
+    local project_type="$1"
+    
+    if [[ "$project_type" == *"web"* ]]; then
+        echo "backend/\\nfrontend/\\ntests/"
+    else
+        echo "src/\\ntests/"
+    fi
+}
+
+get_commands_for_language() {
+    local lang="$1"
+    
+    case "$lang" in
+        *"Python"*)
+            echo "cd src && pytest && ruff check ."
+            ;;
+        *"Rust"*)
+            echo "cargo test && cargo clippy"
+            ;;
+        *"JavaScript"*|*"TypeScript"*)
+            echo "npm test \\&\\& npm run lint"
+            ;;
+        *)
+            echo "# Add commands for $lang"
+            ;;
+    esac
+}
+
+get_language_conventions() {
+    local lang="$1"
+    echo "$lang: Follow standard conventions"
+}
+
+create_new_agent_file() {
+    local target_file="$1"
+    local temp_file="$2"
+    local project_name="$3"
+    local current_date="$4"
+    
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_error "Template not found at $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    if [[ ! -r "$TEMPLATE_FILE" ]]; then
+        log_error "Template file is not readable: $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    log_info "Creating new agent context file from template..."
+    
+    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
+        log_error "Failed to copy template file"
+        return 1
+    fi
+    
+    # Replace template placeholders
+    local project_structure
+    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
+    
+    local commands
+    commands=$(get_commands_for_language "$NEW_LANG")
+    
+    local language_conventions
+    language_conventions=$(get_language_conventions "$NEW_LANG")
+    
+    # Perform substitutions with error checking using safer approach
+    # Escape special characters for sed by using a different delimiter or escaping
+    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    
+    # Build technology stack and recent change strings conditionally
+    local tech_stack
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
+    elif [[ -n "$escaped_lang" ]]; then
+        tech_stack="- $escaped_lang ($escaped_branch)"
+    elif [[ -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_framework ($escaped_branch)"
+    else
+        tech_stack="- ($escaped_branch)"
+    fi
+
+    local recent_change
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
+    elif [[ -n "$escaped_lang" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang"
+    elif [[ -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_framework"
+    else
+        recent_change="- $escaped_branch: Added"
+    fi
+
+    local substitutions=(
+        "s|\[PROJECT NAME\]|$project_name|"
+        "s|\[DATE\]|$current_date|"
+        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
+        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
+        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
+        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
+        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
+    )
+    
+    for substitution in "${substitutions[@]}"; do
+        if ! sed -i.bak -e "$substitution" "$temp_file"; then
+            log_error "Failed to perform substitution: $substitution"
+            rm -f "$temp_file" "$temp_file.bak"
+            return 1
+        fi
+    done
+    
+    # Convert \n sequences to actual newlines
+    newline=$(printf '\n')
+    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
+    
+    # Clean up backup files
+    rm -f "$temp_file.bak" "$temp_file.bak2"
+    
+    return 0
+}
+
+
+
+
+update_existing_agent_file() {
+    local target_file="$1"
+    local current_date="$2"
+    
+    log_info "Updating existing agent context file..."
+    
+    # Use a single temporary file for atomic update
+    local temp_file
+    temp_file=$(mktemp) || {
+        log_error "Failed to create temporary file"
+        return 1
+    }
+    
+    # Process the file in one pass
+    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
+    local new_tech_entries=()
+    local new_change_entry=""
+    
+    # Prepare new technology entries
+    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
+        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
+        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
+    fi
+    
+    # Prepare new change entry
+    if [[ -n "$tech_stack" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
+    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+    fi
+    
+    # Check if sections exist in the file
+    local has_active_technologies=0
+    local has_recent_changes=0
+    
+    if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then
+        has_active_technologies=1
+    fi
+    
+    if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then
+        has_recent_changes=1
+    fi
+    
+    # Process file line by line
+    local in_tech_section=false
+    local in_changes_section=false
+    local tech_entries_added=false
+    local changes_entries_added=false
+    local existing_changes_count=0
+    local file_ended=false
+    
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # Handle Active Technologies section
+        if [[ "$line" == "## Active Technologies" ]]; then
+            echo "$line" >> "$temp_file"
+            in_tech_section=true
+            continue
+        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            # Add new tech entries before closing the section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            in_tech_section=false
+            continue
+        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
+            # Add new tech entries before empty line in tech section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            continue
+        fi
+        
+        # Handle Recent Changes section
+        if [[ "$line" == "## Recent Changes" ]]; then
+            echo "$line" >> "$temp_file"
+            # Add new change entry right after the heading
+            if [[ -n "$new_change_entry" ]]; then
+                echo "$new_change_entry" >> "$temp_file"
+            fi
+            in_changes_section=true
+            changes_entries_added=true
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            echo "$line" >> "$temp_file"
+            in_changes_section=false
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
+            # Keep only first 2 existing changes
+            if [[ $existing_changes_count -lt 2 ]]; then
+                echo "$line" >> "$temp_file"
+                ((existing_changes_count++))
+            fi
+            continue
+        fi
+        
+        # Update timestamp
+        if [[ "$line" =~ \*\*Last\ updated\*\*:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
+            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
+        else
+            echo "$line" >> "$temp_file"
+        fi
+    done < "$target_file"
+    
+    # Post-loop check: if we're still in the Active Technologies section and haven't added new entries
+    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    # If sections don't exist, add them at the end of the file
+    if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        echo "" >> "$temp_file"
+        echo "## Active Technologies" >> "$temp_file"
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then
+        echo "" >> "$temp_file"
+        echo "## Recent Changes" >> "$temp_file"
+        echo "$new_change_entry" >> "$temp_file"
+        changes_entries_added=true
+    fi
+    
+    # Move temp file to target atomically
+    if ! mv "$temp_file" "$target_file"; then
+        log_error "Failed to update target file"
+        rm -f "$temp_file"
+        return 1
+    fi
+    
+    return 0
+}
+#==============================================================================
+# Main Agent File Update Function
+#==============================================================================
+
+update_agent_file() {
+    local target_file="$1"
+    local agent_name="$2"
+    
+    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
+        log_error "update_agent_file requires target_file and agent_name parameters"
+        return 1
+    fi
+    
+    log_info "Updating $agent_name context file: $target_file"
+    
+    local project_name
+    project_name=$(basename "$REPO_ROOT")
+    local current_date
+    current_date=$(date +%Y-%m-%d)
+    
+    # Create directory if it doesn't exist
+    local target_dir
+    target_dir=$(dirname "$target_file")
+    if [[ ! -d "$target_dir" ]]; then
+        if ! mkdir -p "$target_dir"; then
+            log_error "Failed to create directory: $target_dir"
+            return 1
+        fi
+    fi
+    
+    if [[ ! -f "$target_file" ]]; then
+        # Create new file from template
+        local temp_file
+        temp_file=$(mktemp) || {
+            log_error "Failed to create temporary file"
+            return 1
+        }
+        
+        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
+            if mv "$temp_file" "$target_file"; then
+                log_success "Created new $agent_name context file"
+            else
+                log_error "Failed to move temporary file to $target_file"
+                rm -f "$temp_file"
+                return 1
+            fi
+        else
+            log_error "Failed to create new agent file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    else
+        # Update existing file
+        if [[ ! -r "$target_file" ]]; then
+            log_error "Cannot read existing file: $target_file"
+            return 1
+        fi
+        
+        if [[ ! -w "$target_file" ]]; then
+            log_error "Cannot write to existing file: $target_file"
+            return 1
+        fi
+        
+        if update_existing_agent_file "$target_file" "$current_date"; then
+            log_success "Updated existing $agent_name context file"
+        else
+            log_error "Failed to update existing agent file"
+            return 1
+        fi
+    fi
+    
+    return 0
+}
+
+#==============================================================================
+# Agent Selection and Processing
+#==============================================================================
+
+update_specific_agent() {
+    local agent_type="$1"
+    
+    case "$agent_type" in
+        claude)
+            update_agent_file "$CLAUDE_FILE" "Claude Code"
+            ;;
+        gemini)
+            update_agent_file "$GEMINI_FILE" "Gemini CLI"
+            ;;
+        copilot)
+            update_agent_file "$COPILOT_FILE" "GitHub Copilot"
+            ;;
+        cursor-agent)
+            update_agent_file "$CURSOR_FILE" "Cursor IDE"
+            ;;
+        qwen)
+            update_agent_file "$QWEN_FILE" "Qwen Code"
+            ;;
+        opencode)
+            update_agent_file "$AGENTS_FILE" "opencode"
+            ;;
+        codex)
+            update_agent_file "$AGENTS_FILE" "Codex CLI"
+            ;;
+        windsurf)
+            update_agent_file "$WINDSURF_FILE" "Windsurf"
+            ;;
+        kilocode)
+            update_agent_file "$KILOCODE_FILE" "Kilo Code"
+            ;;
+        auggie)
+            update_agent_file "$AUGGIE_FILE" "Auggie CLI"
+            ;;
+        roo)
+            update_agent_file "$ROO_FILE" "Roo Code"
+            ;;
+        codebuddy)
+            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
+            ;;
+        qodercli)
+            update_agent_file "$QODER_FILE" "Qoder CLI"
+            ;;
+        amp)
+            update_agent_file "$AMP_FILE" "Amp"
+            ;;
+        shai)
+            update_agent_file "$SHAI_FILE" "SHAI"
+            ;;
+        q)
+            update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
+            ;;
+        agy)
+            update_agent_file "$AGY_FILE" "Antigravity"
+            ;;
+        bob)
+            update_agent_file "$BOB_FILE" "IBM Bob"
+            ;;
+        generic)
+            log_info "Generic agent: no predefined context file. Use the agent-specific update script for your agent."
+            ;;
+        *)
+            log_error "Unknown agent type '$agent_type'"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qodercli|generic"
+            exit 1
+            ;;
+    esac
+}
+
+update_all_existing_agents() {
+    local found_agent=false
+    
+    # Check each possible agent file and update if it exists
+    if [[ -f "$CLAUDE_FILE" ]]; then
+        update_agent_file "$CLAUDE_FILE" "Claude Code"
+        found_agent=true
+    fi
+    
+    if [[ -f "$GEMINI_FILE" ]]; then
+        update_agent_file "$GEMINI_FILE" "Gemini CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$COPILOT_FILE" ]]; then
+        update_agent_file "$COPILOT_FILE" "GitHub Copilot"
+        found_agent=true
+    fi
+    
+    if [[ -f "$CURSOR_FILE" ]]; then
+        update_agent_file "$CURSOR_FILE" "Cursor IDE"
+        found_agent=true
+    fi
+    
+    if [[ -f "$QWEN_FILE" ]]; then
+        update_agent_file "$QWEN_FILE" "Qwen Code"
+        found_agent=true
+    fi
+    
+    if [[ -f "$AGENTS_FILE" ]]; then
+        update_agent_file "$AGENTS_FILE" "Codex/opencode"
+        found_agent=true
+    fi
+    
+    if [[ -f "$WINDSURF_FILE" ]]; then
+        update_agent_file "$WINDSURF_FILE" "Windsurf"
+        found_agent=true
+    fi
+    
+    if [[ -f "$KILOCODE_FILE" ]]; then
+        update_agent_file "$KILOCODE_FILE" "Kilo Code"
+        found_agent=true
+    fi
+
+    if [[ -f "$AUGGIE_FILE" ]]; then
+        update_agent_file "$AUGGIE_FILE" "Auggie CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$ROO_FILE" ]]; then
+        update_agent_file "$ROO_FILE" "Roo Code"
+        found_agent=true
+    fi
+
+    if [[ -f "$CODEBUDDY_FILE" ]]; then
+        update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
+        found_agent=true
+    fi
+
+    if [[ -f "$SHAI_FILE" ]]; then
+        update_agent_file "$SHAI_FILE" "SHAI"
+        found_agent=true
+    fi
+
+    if [[ -f "$QODER_FILE" ]]; then
+        update_agent_file "$QODER_FILE" "Qoder CLI"
+        found_agent=true
+    fi
+
+    if [[ -f "$Q_FILE" ]]; then
+        update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
+        found_agent=true
+    fi
+
+    if [[ -f "$AGY_FILE" ]]; then
+        update_agent_file "$AGY_FILE" "Antigravity"
+        found_agent=true
+    fi
+    if [[ -f "$BOB_FILE" ]]; then
+        update_agent_file "$BOB_FILE" "IBM Bob"
+        found_agent=true
+    fi
+    
+    # If no agent files exist, create a default Claude file
+    if [[ "$found_agent" == false ]]; then
+        log_info "No existing agent files found, creating default Claude file..."
+        update_agent_file "$CLAUDE_FILE" "Claude Code"
+    fi
+}
+print_summary() {
+    echo
+    log_info "Summary of changes:"
+    
+    if [[ -n "$NEW_LANG" ]]; then
+        echo "  - Added language: $NEW_LANG"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        echo "  - Added framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        echo "  - Added database: $NEW_DB"
+    fi
+    
+    echo
+
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qodercli]"
+}
+
+#==============================================================================
+# Main Execution
+#==============================================================================
+
+main() {
+    # Validate environment before proceeding
+    validate_environment
+    
+    log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
+    
+    # Parse the plan file to extract project information
+    if ! parse_plan_data "$NEW_PLAN"; then
+        log_error "Failed to parse plan data"
+        exit 1
+    fi
+    
+    # Process based on agent type argument
+    local success=true
+    
+    if [[ -z "$AGENT_TYPE" ]]; then
+        # No specific agent provided - update all existing agent files
+        log_info "No agent specified, updating all existing agent files..."
+        if ! update_all_existing_agents; then
+            success=false
+        fi
+    else
+        # Specific agent provided - update only that agent
+        log_info "Updating specific agent: $AGENT_TYPE"
+        if ! update_specific_agent "$AGENT_TYPE"; then
+            success=false
+        fi
+    fi
+    
+    # Print summary
+    print_summary
+    
+    if [[ "$success" == true ]]; then
+        log_success "Agent context update completed successfully"
+        exit 0
+    else
+        log_error "Agent context update completed with errors"
+        exit 1
+    fi
+}
+
+# Execute main function if script is run directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi
+

.specify/templates/agent-file-template.md

@@ -0,0 +1,28 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+
+```text
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

.specify/templates/checklist-template.md

@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+  
+  The /speckit.checklist command MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+  
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference

.specify/templates/constitution-template.md

@@ -0,0 +1,50 @@
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. CLI Interface -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

.specify/templates/plan-template.md

@@ -0,0 +1,104 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

.specify/templates/spec-template.md

@@ -0,0 +1,115 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

.specify/templates/tasks-template.md

@@ -0,0 +1,251 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+  
+  The /speckit.tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md
+
+This file provides guidance to coding agents working in this repository.
+
+## Repository Guidelines
+
+### Pipeline-First Development (MANDATORY)
+**All new functionality MUST be implemented as pipeline Steps composed via the Pipeline engine.** Do NOT write standalone scripts, ad-hoc loops, or inline logic that bypasses the pipeline. Before writing any code:
+
+1. Read `docs/design/PIPELINE_DESIGN.md` to understand the Step → Pipeline → Branch model.
+2. Implement logic as a `Step` class with `requires`/`provides` declarations and a `__call__(self, ctx) -> ctx` method.
+3. Compose steps using `Pipeline().then(...)` and `.branch(...)` — never manual for-loops or direct function chaining.
+4. Use `StepContext.replace()` for immutable context updates — never mutate context directly.
+5. Put integration-specific data in `metadata`, not new context fields, unless the field is shared across multiple pipelines.
+
+**Anti-patterns to reject:**
+- Writing a function that calls multiple steps manually instead of composing them in a Pipeline
+- Inline reflection/evaluation logic instead of creating a ReflectStep or EvaluateStep
+- Ad-hoc `ThreadPoolExecutor` usage instead of `async_boundary` and `max_workers` on steps
+- Standalone scripts that duplicate pipeline functionality without using the pipeline engine
+- Bypassing `requires`/`provides` contracts by accessing context fields not declared in `requires`
+
+If a task seems like it cannot fit the pipeline model, explain why to the user before proceeding — do not silently circumvent it.
+
+### Core Code Protection
+**Do NOT modify core modules (`ace/core/`, `pipeline/`) without explicit user approval.** Before proposing any change to these directories:
+1. Read the relevant design docs (`docs/design/ACE_ARCHITECTURE.md`, `docs/design/PIPELINE_DESIGN.md`) thoroughly.
+2. Evaluate whether the change is truly required or if it can be achieved outside the core (e.g., in an integration, step, or example).
+3. Clearly explain the proposed change and its justification to the user **before** making any edits.
+4. Wait for the user to explicitly accept before proceeding.
+
+### Documentation Maintenance
+Before working on code in `ace/`, read `docs/design/ACE_ARCHITECTURE.md` to understand the current architecture.
+Before working on code in `pipeline/` or `ace/core/`, read `docs/design/PIPELINE_DESIGN.md` to understand the pipeline engine.
+
+**Docs MUST be kept in sync with code.** Any change that alters a public API, renames a concept, adds/removes a module, or changes execution flow **requires** a corresponding update to the relevant docs. Do not merge code changes that make the documentation inaccurate.
+
+Key design docs:
+- `docs/design/ACE_ARCHITECTURE.md` — ACE architecture: layers, core concepts, roles, steps, runners, integrations
+- `docs/design/ACE_REFERENCE.md` — ACE code reference: full implementations, API signatures, usage examples
+- `docs/design/ACE_DECISIONS.md` — design decisions and rejected alternatives (ACE, pipeline, migration)
+- `docs/design/PIPELINE_DESIGN.md` — pipeline engine: steps, StepProtocol, Pipeline, Branch, concurrency
+- If you need to work with collected traces from Logfire, read `agent-guides/logfire.md`
+
+### Project Structure
+- `ace/` — core library: roles (PydanticAI-backed), skillbook, steps, runners, providers, RR, integrations, observability
+- `pipeline/` — generic pipeline engine that `ace` is built on (see `docs/design/PIPELINE_DESIGN.md`)
+- `ace-eval/` — evaluation framework (submodule, separate repo)
+- `tests/` — unit/integration tests (pytest)
+- `examples/` — runnable demos grouped by integration
+- `agent-guides/` — internal development guides for LLM agents; not part of the public docs site
+- `docs/` — guides and reference material
+  - `docs/design/ACE_ARCHITECTURE.md` — architecture and concepts (keep in sync with code)
+  - `docs/design/ACE_REFERENCE.md` — code reference and examples (keep in sync with code)
+  - `docs/design/ACE_DECISIONS.md` — design decisions and rejected alternatives
+  - `docs/design/PIPELINE_DESIGN.md` — pipeline engine design doc (keep in sync with code)
+
+### Commands
+- `uv sync` — install all dependencies
+- `uv run pytest` — run tests (coverage enforced `--cov-fail-under=25`)
+- `uv run pytest -m unit` / `-m integration` / `-m slow` — run by marker
+- `uv run black ace/ tests/ examples/` — format code
+- `uv run mypy ace/` — type check
+
+### Coding Style
+- PEP 8 with Black formatting (line length 88)
+- Type hints and docstrings for public APIs
+- Python 3.12 target
+- Test files: `tests/test_*.py`; functions: `test_*`; classes: `Test*`
+
+### Testing
+- Pytest is the primary runner
+- Add tests for new features; include regression tests for bug fixes
+
+### Commits
+- Conventional Commits: `feat(scope): subject`, `fix(scope): subject`
+- Do NOT add `Co-Authored-By` trailers to commit messages
+- PRs should include description, test results, and relevant docs updates
+
+### ACE Roles (quick reference)
+
+| Role | Responsibility | Key Class |
+|------|---------------|-----------|
+| **Agent** | Executes tasks using skillbook strategies | `Agent` |
+| **Reflector** | Analyzes execution results | `Reflector` |
+| **SkillManager** | Updates the skillbook with new strategies | `SkillManager` |
+
+### Integration Runners
+
+| Runner | Framework | Use Case |
+|--------|-----------|----------|
+| `ACELiteLLM` | LiteLLM (100+ providers) | Simple self-improving agent |
+| `ACELangChain` | LangChain | Wrap chains/agents with learning |
+| `ACEBrowserUse` | browser-use | Browser automation with learning |
+| `ACEClaudeCode` | Claude Code CLI | Coding tasks with learning |
+
+NEVER USE FALLBACKS OR IMPLEMENT THINGS I NEVER ASKED FOR.
+IF IT'S STRAIGHFORWARD, IMPLEMENT IT STRAIGHFORWARD.

CHANGELOG.md

@@ -0,0 +1,445 @@
+# Changelog
+
+All notable changes to ACE Framework will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.12.0] - 2026-05-06
+
+### Added
+- **Cross-trace generalization gate** for the SkillManager — four-criterion check
+  (≥3 instances across ≥2 domains, named slot, no API-specific params in the
+  action, verifiable runtime trigger) that constrains when SM may write a broad
+  skill subsuming existing narrow ones. Backed by [skill_generalization.md](ace-eval/research/skill_generalization.md)
+  (14 cited sources).
+- **Action-equivalence rule** for within-run skill writing — splits on action,
+  not on trigger surface. Prevents over-decomposition of structurally identical
+  rules.
+- **Atomicity rule** in `insight` formatting — one trigger + one action per
+  skill, with explicit good/bad shape examples in the prompt.
+- **Insight format guidance** in the SM prompt sourced from the in-context-
+  learning research doc ([icl_skill_formatting.md](ace-eval/research/icl_skill_formatting.md)) — 15-50 word cap, imperative
+  voice, positive framing default, examples only for format/shape rules.
+- **Evidence-only tagging** — SM tags only skills the reflection actually
+  implicates, instead of iterating over every injected_skill_id.
+- **Broaden-via-comparison rule** for UPDATE — when two skills target the same
+  root cause in different niches, broaden `issue` rather than adding a duplicate.
+- **Prompt caching for SM** via `CachePoint(ttl="5m")` mirroring RR's caching;
+  cache_read/write tokens forwarded in run metadata.
+- **SM behavior spec + harness** — `ace-eval/scripts/sm_behavior_check.py`,
+  `sm_iterative_check.py`, `sm_stability_check.py` and matching scenario
+  fixtures cover replay stability, convergence, scope expansion, and the
+  below-threshold gate boundary.
+
+### Changed
+- **`update_skills` signature** — `source` is now optional; `SkillbookView`
+  was dropped from the parameter list (callers pass the real `Skillbook`
+  directly).
+- **Hard removal cap removed** — SM no longer auto-removes skills whose
+  `harmful_count >= 3`. Heavily-used skills can legitimately accumulate
+  harmful tags without being net-negative; REMOVE now requires explicit
+  reflection evidence.
+- **TauBench evaluator** — `evaluation_type=ALL_WITH_NL_ASSERTIONS` on both
+  `run_task` and `run_tasks` call sites in
+  `ace-eval/src/ace_eval/e2e/benchmarks/tau_bench.py`. Retail (and any future
+  benchmark with `NL_ASSERTION` in `reward_basis`) now produces real reward
+  numbers instead of crashing on every task during reward computation.
+
+### Removed
+- **Skillbook v1 legacy aliases** on `Skill` and `UpdateOperation` — v2 schema
+  is now the only schema.
+
+## [0.11.0] - 2026-04-29
+
+### Added
+- **`RecursiveAgent` core abstraction** — extracted from RR into `ace/core/recursive_agent.py`; provides a generic recursive PydanticAI agent with sandbox, microcompaction, default tool set, and depth-aware sub-agent registration. Reusable across roles beyond the Reflector.
+- **Skillbook v2 schema** — full rewrite of `ace/core/skillbook.py` with section-grouped storage, richer `InsightSource` provenance, and BM25-backed retrieval (`rank-bm25` runtime dependency).
+- **Agentic SkillManager** — `SkillManager` rewritten as a tool-calling loop (`ace/implementations/sm_tools.py`). Provenance is now populated by the SkillManager agent directly rather than a dedicated step.
+- **RR skillbook tools for the Reflector** — Reflector can introspect and propose updates to the skillbook from inside the recursive loop.
+- **Anthropic prompt caching enabled by default** for RR agents; `cache_read_tokens` and `cache_write_tokens` are forwarded in run metadata for cost accounting.
+- **Logfire spans around recursive agent sessions** for end-to-end observability of nested RR runs.
+- **Online / offline mode** in the ACE runner.
+- **`nest-asyncio`** added to the dev extra to support nested loops in notebooks and live test scripts.
+
+### Changed
+- **RR collapsed into a single `RRStep`** — the orchestrator/worker split, batch machinery, and `AttachInsightSourcesStep` have been removed. RR now runs as a true recursive loop with depth-bounded sub-agent delegation and microcompaction of stale tool results.
+- **Reflector prompts** simplified, deduplicated, and made input-agnostic; added early-skillbook-skim and parallel-tool guidance.
+- **`record_observation` tool renamed to `think`** to clarify it is a scratch reasoning channel, not persistent storage.
+- **Native evidence summaries** are produced inside RR before final synthesis.
+- **Skillbook prompt format is now markdown** — `Skillbook.as_prompt()` returns a section-grouped markdown list instead of TOON. The `python-toon` dependency has been dropped.
+- **`metered_model` and `sandbox`** moved from `ace/rr/` into `ace/core/` to reflect their cross-role use.
+- **Pytest defaults** — `uv run pytest` now excludes `integration` and `requires_api` markers by default; coverage flags removed from `addopts` (run with `--cov` explicitly when needed).
+- **Observability** — `tool_arguments` and `tool_response` are no longer scrubbed by the Logfire callback so tool I/O remains inspectable.
+
+### Removed
+- `ace/rr/` legacy package layout (`agent.py`, `runner.py`, `trace_context.py`, `message_trimming.py`, batch helpers). Functionality is now in `ace/core/recursive_agent.py` and `ace/implementations/rr/`.
+- `AttachInsightSourcesStep` and its pipeline wiring — provenance is attached by the SkillManager agent.
+- `python-toon` runtime dependency.
+- TAG handling from the SkillManager.
+- Citation scanning from the Reflector.
+
+## [0.10.0] - 2026-04-13
+
+### Added
+- **Usage metering hook** — `RecursiveConfig.usage_callback: (RequestUsage, model_id) -> None` fires once per pydantic-ai model request (orchestrator turns, sub-agent runs, tool-call follow-ups). Implemented via `ace.rr.MeteredModel`, a `pydantic_ai.models.wrapper.WrapperModel` subclass, so metering lives at the framework's own model boundary — no per-call-site plumbing. Callback exceptions are caught and logged so metering never crashes the pipeline.
+- **Pre-built model instance support** — `RRStep`, `create_rr_agent`, `create_sub_agent`, and `RecursiveConfig.subagent_model` now accept either a model-id string or a pre-built `pydantic_ai.models.Model` instance. Enables callers that need a custom provider (e.g. cross-account Bedrock with STS-assumed credentials) to inject a fully-configured model rather than resolving from a string.
+- **Sub-agent `model_settings`** — `create_sub_agent` now threads an explicit `ModelSettings` parameter into its `PydanticAgent` constructor.
+
+### Notes
+- Back-compat: existing `RRStep(model="...")` callers continue to work unchanged. The widened type signature is additive.
+
+## [0.9.4] - 2026-04-11
+
+### Added
+- **Kayba tracing SDK** — `ace.tracing` module wraps MLflow tracing with Kayba-native configuration, folder organization, and input sanitization (`pip install ace-framework[tracing]`)
+
+## [0.9.3] - 2026-04-01
+
+### Added
+- **Structured design docs** — split ACE_DESIGN.md into architecture, reference, and decisions docs under docs/design/
+- **Simplified Skill model** — removed unused tag counters (helpful/harmful/neutral) and TagStep from the pipeline
+- **Cleaner InsightSource provenance** — restored error_identification and learning_text fields
+
+## [0.9.2] - 2026-03-31
+
+### Added
+- **Insight source provenance** — `InsightSource` typed model captures the origin of each skillbook update (trace ID, sample question, epoch/step, reflection summary, integration metadata); provenance is now populated by the SkillManager agent directly
+- **Claude SDK step** — `ClaudeSDKStep` integration for running Claude Code sub-agents from within ACE pipelines
+- **RR sub-agent code execution** — Recursive Reflector can now delegate to code-execution sub-agents at runtime
+- **RR raw trace batch helpers** — `build_raw_trace_batches` and related runtime utilities for feeding raw traces directly into the RR pipeline
+
+### Fixed
+- **Logfire scrubbing** — added scrubbing callback to stop Logfire over-redacting trace content (reasoning, answers, messages now visible in Logfire UI)
+- **RR combined-batch normalization** — fixed ordering/deduplication of combined task batches in multi-sample runs
+
+### Docs
+- Logfire query API guide clarifications
+- MCP client setup guide and compatibility tests
+- Design docs updated to reflect insight source provenance model
+
+## [0.9.1] - 2026-03-26
+
+### Fixed
+- **CLI packaging** — include .md data files in wheel so `kayba setup` and skill install work on pip/uv-installed packages
+
+## [0.9.0] - 2026-03-26
+
+### Added
+- **PydanticAI migration** — ACE roles (Agent, Reflector, SkillManager) rebuilt on PydanticAI agents with structured output, replacing the legacy role system
+- **Recursive Reflector** — PydanticAI-powered trace analysis agent with sandboxed code execution, sub-agent delegation, and working memory (`save_notes` tool)
+- **Kayba CLI** — full hosted API client with trace upload/management, interactive run, insights, prompts, batch processing, materialization, and integration commands (`kayba` entry point)
+
+## [0.8.8] - 2026-03-17
+
+### Added
+- **Pipeline hooks & cancellation** — `PipelineHook` protocol and `CancellationToken` for observing and controlling pipeline execution
+- **Kayba pipeline skills for Claude Code** — 7-stage dynamic evaluation pipeline that generates custom benchmarks tailored to your agent's domain. Instead of static test suites, the skills analyze your API, build domain-aware metrics and rubrics, create action plans, and run human-in-the-loop validation — all as composable Claude Code skills
+- **`kayba setup` command** — one command to install the full evaluation skill pipeline into your `.claude/skills/` directory, ready to use inside Claude Code out of the box
+
+### Docs
+- Documented `kayba setup` skills installation
+
+### Try it free
+**7-day free trial** — Try the full Kayba evaluation pipeline on our hosted solution with zero setup. Sign up at [kayba.ai](https://kayba.ai) and run `kayba setup` to start building dynamic evals for your agents today.
+
+## [0.8.7] - 2026-03-17
+
+### Added
+- **Improved Opik trace naming** — traces now display the question text (first 80 chars) instead of generic names like "ace_pipeline" or "rr_reflect"
+- **Thread ID support for Opik** — `OpikStep` and `RROpikStep` accept an optional `thread_id` parameter for grouping related traces
+
+## [0.8.5] - 2026-03-04
+
+### Added
+- **Self-contained RR module** (`ace/rr/`) — sandbox, subagent, trace_context, config, code_extraction, message_trimming extracted from `ace/reflector/` into a standalone package
+- **v5.6 prompt promoted as default** — new prompt evolution (v4 → v5.1–v5.6) for the `ace` RR pipeline
+- **`build_steps()` API** — all runners gain a `build_steps()` classmethod for pipeline customization
+- **Shared `CallBudget`** — single budget instance shared across RR pipeline steps
+- **ACE MCP server (optional)** — stdio MCP server in `ace.integrations.mcp` with tools: `ace.ask`, `ace.learn.sample`, `ace.learn.feedback`, `ace.skillbook.get`, `ace.skillbook.save`, `ace.skillbook.load`
+- **Session-scoped state management** — in-memory `session_id` registry with TTL cleanup and per-session async locking
+- **MCP packaging + CLI** — optional `mcp` extra and `ace-mcp` entrypoint
+- **MCP docs and demo client** — integration guide and stdio client example
+- **Composing pipelines guide** — new `docs/guides/composing-pipelines.md`
+- **RR examples** — `rr_demo.py`, `rr_opik_demo.py`, `compose_custom_pipeline.py`
+
+### Changed
+- **RR backward-compat shims** — original `ace/reflector/` files now re-export from `ace.rr` (no duplication)
+- **`RRStep` dual protocol** — implements both `StepProtocol` and `ReflectorLike`
+- **Sandbox hardening** — hardened `getattr` in sandbox execution environment
+- **Opik made opt-in** — moved `opik` from hard dependency to `observability` extra
+- **Safety controls** — runtime request limits (`max_prompt_chars`, `max_samples_per_call`) and optional root-bound path enforcement for save/load via `ACE_MCP_SKILLBOOK_ROOT`
+- **Schema-driven validation** — MCP request/response models aligned to `specs/002-ace-mcp-server/contracts/tool-schemas.md`
+- **`learn_from_feedback` routed through pipeline** — feedback learning now uses the pipeline engine
+
+### Testing
+- Added MCP test suite: models, registry, handlers, and server registration/startup smoke tests
+- Added optional-dependency boundary checks for the MCP integration
+- RR steps at 94%, sandbox at 92%, runner at 74%, MCP models at 100%
+
+## [0.8.4] - 2026-02-27
+
+### Added
+- **OpenClaw integration** — learn from OpenClaw session transcripts (JSONL) via new `OpenClawToTraceStep` and `LoadTracesStep` pipeline steps (#86)
+- **ExportSkillbookMarkdownStep** — export skillbook to markdown file
+- OpenClaw example script and integration docs
+
+## [0.8.3] - 2026-02-21
+
+### Added
+- **Pipeline engine** — generic pipeline framework with branching, async boundaries, and parallel execution (#78)
+- **Trace passthrough** — `_build_traces()` helper and raw trace data passed to RecursiveReflector sandbox
+
+## [0.8.2] - 2026-02-18
+
+### Added
+- **RecursiveReflector None-response guard** — gracefully handles empty/None LLM responses (e.g. from Gemini) with retry prompt instead of crashing
+- **`LiteLLMClient.complete_messages()`** — native multi-turn completion that preserves structured message lists
+
+## [0.8.1] - 2026-02-18
+
+### Added
+- **Insight source tracing** — `InsightSource` dataclass tracks skill provenance (epoch, sample, trace refs, error identification, learning text)
+- **Sample.id** promoted to first-class field with UUID auto-generation
+- **Skillbook query API** — `source_map()`, `source_summary()`, `source_filter()` for skill lineage
+- Insight sources wired through `OfflineACE`, `OnlineACE`, and async learning pipelines
+- `UpdateOperation.learning_index` for linking operations to reflector learnings
+- Bedrock e2e example (`examples/litellm/bedrock_insight_source_test.py`)
+- `docs/INSIGHT_SOURCES.md` guide
+
+## [0.8.0] - 2026-02-17
+
+### Added
+- **Recursive reflector** with sandboxed code execution for validation
+- **TAU-bench integration** with config-driven YAML profiles, prompt sweep, capture/replay, and label support
+- **v3 prompt templates** for agent, reflector, and skill manager roles
+- **Trace context module** exposing agent system prompt and execution context to reflector
+
+### Fixed
+- Opik cloud mode support when `OPIK_API_KEY` is set
+- Bedrock/SageMaker API key lookup skipped for managed providers
+- Reflector trace quality improvements (user messages, turn separators)
+
+### Changed
+- v3 prompts set as default prompt version
+- Reflector now includes agent system prompt in trace context
+
+## [0.7.3] - 2026-02-04
+
+### Added
+- ACE learning for Claude Code via `/ace-learn` (transcript-based learning and skillbook updates).
+- CLI patching to minimize Claude Code system prompt overhead for learning runs.
+
+### Fixed
+- Claude Code transcript parsing for feedback and last-prompt extraction edge cases.
+
+### Changed
+- Unified agent guidance into `AGENTS.md` with `CLAUDE.md` symlink.
+
+## [0.7.0] - 2025-12-04
+
+### ⚠️ Breaking Changes
+- **Complete terminology rename** - Playbook → Skillbook, Bullet → Skill
+  - `Playbook` → `Skillbook`
+  - `Bullet` → `Skill`
+  - `Generator` → `Agent`
+  - `Curator` → `SkillManager`
+  - `OfflineAdapter` → `OfflineACE`
+  - `OnlineAdapter` → `OnlineACE`
+  - `DeltaOperation` → `UpdateOperation`
+  - `DeltaBatch` → `UpdateBatch`
+  - **Migration**: Update imports and method calls to use new names
+  - **JSON files**: Change `"bullets"` key to `"skills"` in saved skillbooks
+
+### Added
+- **Deduplication consolidation_operations field** - SkillManagerOutput now properly captures consolidation operations from LLM responses
+
+### Fixed
+- **Deduplication not working** - Added `consolidation_operations` field to SkillManagerOutput Pydantic model. Previously, Instructor was silently dropping these operations.
+
+## [0.5.0] - 2025-11-20
+
+### ⚠️ Breaking Changes
+- **Playbook format changed to TOON (Token-Oriented Object Notation)**
+  - `Playbook.as_prompt()` now returns TOON format instead of markdown
+  - **Reason**: 16-62% token savings for improved scalability and reduced inference costs
+  - **Migration**: No action needed if using playbook with Generator/Curator/Reflector
+  - **Debugging**: Use `playbook._as_markdown_debug()` or `str(playbook)` for human-readable output
+  - **Details**: Uses tab delimiters and excludes internal metadata (created_at, updated_at)
+
+### Added
+- **ACELiteLLM integration** - Simple conversational agent with automatic learning
+- **ACELangChain integration** - Wrap LangChain Runnables with ACE learning
+- **Custom integration pattern** - Wrap ANY agentic system with ACE learning
+  - Base utilities in `ace/integrations/base.py` with `wrap_playbook_context()` helper
+  - Complete working example in `examples/custom_integration_example.py`
+  - Integration Pattern: Inject playbook → Execute agent → Learn from results
+- **Integration exports** - Import ACEAgent, ACELiteLLM, ACELangChain from `ace` package root
+- **TOON compression for playbooks** - 16-62% token reduction vs markdown
+- **Citation-based tracking** - Strategies cited inline as `[section-00001]`, auto-extracted from reasoning
+- **Enhanced browser traces** - Full execution logs (2200+ chars) passed to Reflector
+- **Test coverage** - Improved from 28% to 70% (241 tests total)
+
+### Changed
+- **Renamed SimpleAgent → ACELiteLLM** - Clearer naming for conversational agent integration
+- `Playbook.__str__()` returns markdown (TOON reserved for LLM consumption via `as_prompt()`)
+
+### Fixed
+- **Browser-use trace integration** - Reflector now receives complete execution traces
+  - Fixed initial query duplication (task appeared in both question and reasoning)
+  - Fixed missing trace data (reasoning field now contains 2200+ chars vs 154 chars)
+  - Fixed screenshot attribute bug causing AttributeError on step.state.screenshot
+  - Fixed invalid bullet ID filtering - hallucinated/malformed citations now filtered out
+  - Added comprehensive regression tests to catch these issues
+  - Impact: Reflector can now properly analyze browser agent's thought process
+  - Test coverage improved: 69% → 79% for browser_use.py
+- Prompt v2.1 test assertions updated to match current format
+- All 206 tests now pass (was 189)
+
+## [0.4.0] - 2025-10-26
+
+### Added
+- **Production Observability** with Opik integration
+  - Enterprise-grade monitoring and tracing
+  - Automatic token usage and cost tracking for all LLM calls
+  - Real-time cost monitoring via Opik dashboard
+  - Graceful degradation when Opik is not installed
+- **Browser Automation Demos** showing ACE vs baseline performance
+  - Domain checker demo with learning capabilities
+  - Form filler demo with adaptive strategies
+  - Side-by-side comparison of baseline vs ACE-enhanced automation
+- Support for UV package manager (10-100x faster than pip)
+  - Added uv.lock for reproducible builds
+  - UV-specific installation and development instructions
+- Improved documentation structure with multiple guides
+  - QUICK_START.md for 5-minute quickstart
+  - API_REFERENCE.md for complete API documentation
+  - PROMPT_ENGINEERING.md for advanced techniques
+  - SETUP_GUIDE.md for development setup
+  - TESTING_GUIDE.md for testing procedures
+- Optional dependency groups for modular installation
+  - `observability` for Opik integration
+  - `demos` for browser automation examples
+  - `langchain` for LangChain support
+  - `transformers` for local model support
+  - `dev` for development tools
+  - `all` for all features combined
+
+### Changed
+- **Replaced explainability module with observability**
+  - Removed empty ace/explainability directory
+  - Migrated to production-grade Opik monitoring
+  - Updated all documentation to reflect this change
+- Improved Python version requirements consistency (3.12 everywhere)
+- Enhanced README with clearer examples and installation options
+- Reorganized examples directory for better discoverability
+- Updated CLAUDE.md with comprehensive codebase guidance
+
+### Fixed
+- Package configuration in pyproject.toml
+- Documentation references to non-existent explainability module
+- Python version inconsistencies across documentation files
+
+### Removed
+- Empty ace/explainability module (replaced by observability)
+- Outdated references to explainability features in documentation
+
+## [0.3.0] - 2025-10-16
+
+### Added
+- **Experimental v2 Prompts** with state-of-the-art prompt engineering
+  - Confidence scoring at bullet and answer levels
+  - Domain-specific variants for math and code generation
+  - Hierarchical structure with identity headers and metadata
+  - Concrete examples and anti-patterns for better guidance
+  - PromptManager for version control and A/B testing
+- Comprehensive prompt engineering documentation (`docs/PROMPT_ENGINEERING.md`)
+- Advanced examples demonstrating v2 prompts (`examples/advanced_prompts_v2.py`)
+- Comparison script for v1 vs v2 prompts (`examples/compare_v1_v2_prompts.py`)
+- Playbook persistence with `save_to_file()` and `load_from_file()` methods
+- Example demonstrating playbook save/load functionality (`examples/playbook_persistence.py`)
+- py.typed file for PEP 561 type hint support
+- Mermaid flowchart visualization in README showing ACE learning loop
+
+### Changed
+- Enhanced docstrings with comprehensive examples throughout codebase
+- Improved README with v2 prompts section and visual diagrams
+- Updated formatting to comply with Black code style
+
+### Fixed
+- README incorrectly referenced non-existent docs/ directory
+- Test badge URL in README (test.yml → tests.yml)
+- Code formatting issues detected by GitHub Actions
+
+## [0.2.0] - 2025-10-15
+
+### Added
+- LangChain integration via `LangChainLiteLLMClient` for advanced workflows
+- Router support for load balancing across multiple model deployments
+- Comprehensive example for LangChain usage (`examples/langchain_example.py`)
+- Optional installation group: `pip install ace-framework[langchain]`
+- PyPI badges and Quick Links section in README
+- CHANGELOG.md for version tracking
+
+### Fixed
+- Parameter filtering in LiteLLM and LangChain clients (refinement_round, max_refinement_rounds)
+- GitHub Actions workflow using deprecated artifact actions v3 → v4
+
+### Changed
+- Improved README with better structure and badges
+- Updated .gitignore to exclude build artifacts and development files
+
+### Removed
+- Unnecessary development files from repository
+
+## [0.1.1] - 2025-10-15
+
+### Fixed
+- GitHub Actions workflow for PyPI publishing
+- Updated artifact upload/download actions from v3 to v4
+
+## [0.1.0] - 2025-10-15
+
+### Added
+- Initial release of ACE Framework
+- Core ACE implementation based on paper (arXiv:2510.04618)
+- Three-role architecture: Generator, Reflector, and Curator
+- Playbook system for storing and evolving strategies
+- LiteLLM integration supporting 100+ LLM providers
+- Offline and Online adaptation modes
+- Async and streaming support
+- Example scripts for quick start
+- Comprehensive test suite
+- PyPI packaging and GitHub Actions CI/CD
+
+### Features
+- Self-improving agents that learn from experience
+- Delta operations for incremental playbook updates
+- Support for OpenAI, Anthropic, Google, and more via LiteLLM
+- Type hints and modern Python practices
+- MIT licensed for open source use
+
+[0.9.4]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.9.3...v0.9.4
+[0.9.3]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.9.2...v0.9.3
+[0.9.2]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.9.1...v0.9.2
+[0.9.1]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.9.0...v0.9.1
+[0.9.0]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.8.9...v0.9.0
+[0.8.8]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.8.7...v0.8.8
+[0.8.7]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.8.6...v0.8.7
+[0.8.5]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.8.4...v0.8.5
+[0.8.4]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.8.3...v0.8.4
+[0.8.3]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.8.2...v0.8.3
+[0.8.2]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.8.1...v0.8.2
+[0.8.1]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.8.0...v0.8.1
+[0.8.0]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.7.3...v0.8.0
+[0.7.3]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.7.0...v0.7.3
+[0.7.0]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/Kayba-ai/agentic-context-engine/releases/tag/v0.1.0

CLAUDE.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Guidelines
+
+### Pipeline-First Development (MANDATORY)
+**All new functionality MUST be implemented as pipeline Steps composed via the Pipeline engine.** Do NOT write standalone scripts, ad-hoc loops, or inline logic that bypasses the pipeline. Before writing any code:
+
+1. Read `docs/design/PIPELINE_DESIGN.md` to understand the Step → Pipeline → Branch model.
+2. Implement logic as a `Step` class with `requires`/`provides` declarations and a `__call__(self, ctx) -> ctx` method.
+3. Compose steps using `Pipeline().then(...)` and `.branch(...)` — never manual for-loops or direct function chaining.
+4. Use `StepContext.replace()` for immutable context updates — never mutate context directly.
+5. Put integration-specific data in `metadata`, not new context fields, unless the field is shared across multiple pipelines.
+
+**Anti-patterns to reject:**
+- Writing a function that calls multiple steps manually instead of composing them in a Pipeline
+- Inline reflection/evaluation logic instead of creating a ReflectStep or EvaluateStep
+- Ad-hoc `ThreadPoolExecutor` usage instead of `async_boundary` and `max_workers` on steps
+- Standalone scripts that duplicate pipeline functionality without using the pipeline engine
+- Bypassing `requires`/`provides` contracts by accessing context fields not declared in `requires`
+
+If a task seems like it cannot fit the pipeline model, explain why to the user before proceeding — do not silently circumvent it.
+
+### Core Code Protection
+**Do NOT modify core modules (`ace/core/`, `pipeline/`) without explicit user approval.** Before proposing any change to these directories:
+1. Read the relevant design docs (`docs/design/ACE_ARCHITECTURE.md`, `docs/design/PIPELINE_DESIGN.md`) thoroughly.
+2. Evaluate whether the change is truly required or if it can be achieved outside the core (e.g., in an integration, step, or example).
+3. Clearly explain the proposed change and its justification to the user **before** making any edits.
+4. Wait for the user to explicitly accept before proceeding.
+
+### Documentation Maintenance
+Before working on code in `ace/`, read `docs/design/ACE_ARCHITECTURE.md` to understand the current architecture.
+Before working on code in `pipeline/` or `ace/core/`, read `docs/design/PIPELINE_DESIGN.md` to understand the pipeline engine.
+
+**Docs MUST be kept in sync with code.** Any change that alters a public API, renames a concept, adds/removes a module, or changes execution flow **requires** a corresponding update to the relevant docs. Do not merge code changes that make the documentation inaccurate.
+
+Key design docs:
+- `docs/design/ACE_ARCHITECTURE.md` — ACE architecture: layers, core concepts, roles, steps, runners, integrations
+- `docs/design/ACE_REFERENCE.md` — ACE code reference: full implementations, API signatures, usage examples
+- `docs/design/ACE_DECISIONS.md` — design decisions and rejected alternatives (ACE, pipeline, migration)
+- `docs/design/PIPELINE_DESIGN.md` — pipeline engine: steps, StepProtocol, Pipeline, Branch, concurrency
+- If you need to work with collected traces from Logfire, read `agent-guides/logfire.md`
+
+### Project Structure
+- `ace/` — core library: roles (PydanticAI-backed), skillbook, steps, runners, providers, RR, integrations, observability
+- `pipeline/` — generic pipeline engine that `ace` is built on (see `docs/design/PIPELINE_DESIGN.md`)
+- `ace-eval/` — evaluation framework (submodule, separate repo)
+- `tests/` — unit/integration tests (pytest)
+- `examples/` — runnable demos grouped by integration
+- `agent-guides/` — internal development guides for LLM agents; not part of the public docs site
+- `docs/` — guides and reference material
+  - `docs/design/ACE_ARCHITECTURE.md` — architecture and concepts (keep in sync with code)
+  - `docs/design/ACE_REFERENCE.md` — code reference and examples (keep in sync with code)
+  - `docs/design/ACE_DECISIONS.md` — design decisions and rejected alternatives
+  - `docs/design/PIPELINE_DESIGN.md` — pipeline engine design doc (keep in sync with code)
+
+### Commands
+- `uv sync` — install all dependencies
+- `uv run pytest` — run tests (excludes `integration` and `requires_api` markers by default)
+- `uv run pytest -m unit` / `-m integration` / `-m slow` — run by marker
+- `uv run black ace/ tests/ examples/` — format code
+- `uv run mypy ace/` — type check
+
+### Coding Style
+- PEP 8 with Black formatting (line length 88)
+- Type hints and docstrings for public APIs
+- Python 3.12 target
+- Test files: `tests/test_*.py`; functions: `test_*`; classes: `Test*`
+
+### Testing
+- Pytest is the primary runner
+- Add tests for new features; include regression tests for bug fixes
+
+### Commits
+- Conventional Commits: `feat(scope): subject`, `fix(scope): subject`
+- Do NOT add `Co-Authored-By` trailers to commit messages
+- PRs should include description, test results, and relevant docs updates
+
+### ACE Roles (quick reference)
+
+| Role | Responsibility | Key Class |
+|------|---------------|-----------|
+| **Agent** | Executes tasks using skillbook strategies | `Agent` |
+| **Reflector** | Analyzes execution results | `Reflector` |
+| **SkillManager** | Updates the skillbook with new strategies | `SkillManager` |
+
+### Integration Runners
+
+| Runner | Framework | Use Case |
+|--------|-----------|----------|
+| `ACELiteLLM` | LiteLLM (100+ providers) | Simple self-improving agent |
+| `ACELangChain` | LangChain | Wrap chains/agents with learning |
+| `ACEBrowserUse` | browser-use | Browser automation with learning |
+| `ACEClaudeCode` | Claude Code CLI | Coding tasks with learning |
+
+NEVER USE FALLBACKS OR IMPLEMENT THINGS I NEVER ASKED FOR. 
+
+Keep your answers concise and to the point. If you don't know something, say you don't know instead of making assumptions or fabricating information. Always ask clarifying questions if the user's request is ambiguous or lacks necessary details.

CONTRIBUTING.md

@@ -0,0 +1,183 @@
+**By submitting a pull request to this repository, you agree to the terms below.**
+
+## Contributor Terms
+
+(a) The contribution is your original work and you have the right to submit it.
+(b) You license your contribution under the project's current license (Apache-2.0).
+(c) You grant the maintainers the right to relicense your contribution as part of the project under any future open-source or commercial license.
+
+---
+
+# Contributing to ACE Framework
+
+Thank you for your interest in contributing to the Agentic Context Engine! We welcome contributions from the community.
+
+## How to Contribute
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:
+
+- A clear and descriptive title
+- Steps to reproduce the issue
+- Expected behavior vs actual behavior
+- Environment details (OS, Python version, package versions)
+- Any relevant error messages or logs
+
+### Suggesting Enhancements
+
+Enhancement suggestions are welcome! Please provide:
+
+- A clear description of the enhancement
+- Use cases and benefits
+- Possible implementation approach (optional)
+- Any potential drawbacks or considerations
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests to ensure nothing breaks
+5. Commit your changes using conventional commits (see below)
+6. Push to your branch
+7. Open a Pull Request
+
+## Branch Naming Convention
+
+Use consistent prefixes for branch names:
+
+| Prefix | Purpose | Example |
+|--------|---------|---------|
+| `feature/` | New features | `feature/john/benchmarks` |
+| `fix/` | Bug fixes | `fix/jane/memory-leak` |
+| `docs/` | Documentation changes | `docs/john/api-reference` |
+| `refactor/` | Code refactoring | `refactor/jane/llm-client` |
+| `test/` | Test additions/fixes | `test/john/integration-suite` |
+| `chore/` | Maintenance tasks | `chore/jane/update-deps` |
+
+**Format:** `<type>/<developer>/<description>`
+
+**Rules:**
+- Use lowercase with hyphens (kebab-case)
+- Use your GitHub username or first name as developer identifier
+- Keep descriptions short but descriptive
+- Include issue number if applicable: `fix/john/123-login-error`
+- Never push directly to `main` - always use feature branches
+
+## Worktree Workflow
+
+We use git worktrees to work on multiple branches simultaneously without switching. Each branch gets its own directory.
+
+### Claude Code Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `/create-branch` | Create branch + worktree | `/create-branch feature add-caching` |
+| `/checkout-branch` | Switch to branch (creates worktree if needed) | `/checkout-branch add-caching` |
+| `/list-branches` | List branches with worktree status | `/list-branches` or `/list-branches feature` |
+| `/remove-branch` | Remove branch + worktree | `/remove-branch feature/john/add-caching` |
+
+### Worktree Path Convention
+
+Worktrees are created as siblings to the main worktree:
+- Branch: `feature/john/add-caching`
+- Worktree: `../feature-john-add-caching`
+
+### Manual Worktree Commands
+
+```bash
+# List all worktrees
+git worktree list
+
+# Add worktree for existing branch
+git worktree add ../path-name branch-name
+
+# Add worktree with new branch
+git worktree add -b new-branch ../path-name
+
+# Remove worktree
+git worktree remove ../path-name
+
+# Prune stale worktree references
+git worktree prune
+```
+
+### Benefits
+
+- **Parallel development**: Work on multiple features without stashing
+- **Faster context switching**: No need to rebuild dependencies
+- **Cleaner git history**: No accidental commits to wrong branch
+- **IDE-friendly**: Open each worktree in separate IDE windows
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/your-username/agentic-context-engine.git
+cd agentic-context-engine
+
+# Install all dependencies (uses UV - 10-100x faster than pip)
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run linting and formatting
+uv run black ace/ tests/ examples/
+uv run mypy ace/
+
+# Run specific test files
+uv run pytest tests/test_skillbook.py
+uv run pytest -m unit  # Only unit tests
+uv run pytest -m integration  # Only integration tests
+```
+
+## Commit Message Format
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) for clear commit history and automatic changelog generation.
+
+Format: `<type>(<scope>): <subject>`
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Adding tests
+- `chore`: Maintenance tasks
+
+Examples:
+```
+feat(llm): add support for new LLM provider
+fix(adapter): resolve memory leak in online mode
+docs(readme): update installation instructions
+```
+
+## Code Style
+
+- Follow PEP 8
+- Use type hints where possible
+- Add docstrings to all public functions and classes
+- Keep line length under 100 characters
+- Use Black for automatic formatting
+
+## Testing
+
+- Write tests for new features
+- Ensure all tests pass before submitting PR
+- Aim for good test coverage
+- Use meaningful test names
+
+## Documentation
+
+- Update README.md if adding new features
+- Add docstrings to new code
+- Update CHANGELOG.md following Keep a Changelog format
+- Include examples for new functionality
+
+## Questions?
+
+Feel free to open an issue for any questions or join the discussion in [GitHub Discussions](https://github.com/Kayba-ai/agentic-context-engine/discussions).
+

Dockerfile

@@ -1,19 +1,20 @@
-FROM mcr.microsoft.com/playwright:v1.44.0-jammy
+FROM python:3.10-slim
 
 WORKDIR /app
 
-# Install python and pip
-RUN apt-get update && apt-get install -y python3 python3-pip && rm -rf /var/lib/apt/lists/*
+# Install uv for fast dependency resolution as recommended by ACE
+RUN pip install uv
 
-COPY requirements.txt .
-RUN pip3 install --no-cache-dir -r requirements.txt
+# Copy the ACE repository and our FastAPI files
+COPY . /app
 
-# Install playwright browsers
-RUN pip3 install playwright
-RUN playwright install chromium
-
-COPY . .
+# Install ACE framework using uv (referencing the local pyproject.toml in the cloned repo)
+# and install FastAPI components
+RUN uv pip install --system fastapi uvicorn pydantic litellm
+# Since the cloned directory has pyproject.toml, we can install the local package
+RUN uv pip install --system -e .
 
 EXPOSE 7860
 
+# We need the user to pass API keys in Space Secrets (e.g. OPENAI_API_KEY, GROQ_API_KEY)
 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,10 +1,224 @@
----
-title: Logic Engine
-emoji: 🏃
-colorFrom: indigo
-colorTo: yellow
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<a href="https://kayba.ai"><img src="assets/kayba-banner.png" alt="Kayba - Stop fixing agents by hand" width="1080"/></a>
+
+# Agentic Context Engine (ACE)
+
+[![GitHub stars](https://img.shields.io/github/stars/kayba-ai/agentic-context-engine)](https://github.com/kayba-ai/agentic-context-engine/stargazers)
+[![Kayba Website](https://img.shields.io/badge/kayba.ai-6B8BA8?style=flat&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAIpElEQVR42q1XbWwU1xU9d2Z29sPe2V3jyHVwDNixkiBiqKKixA1IBloKCRJSAaU4ip0PhaiJE0JSqSU/WqlpihpXiaJGmJBGSiGOEj4MjsuHhDApENzEjYHaxTbGJUUuBsvaHXt3vbuzM6c/1l6MvW7+5EpPu/t23rvnnvfm3HsFgArAzsvLu1/TtF+SrAYQBKDguzUHgCkipyyRHfFI5AIAVQDA7/evE5E9IhIgp64hAJmxkwggItmRWUOQhENmliHXPpx4nmMiUmuaZrPk5+cvVBSlQ0S8JNMZRkRy7AIRgaqqsG0HyWQCqVQKjuMAABRFhdutw+32QASwbWcagOwXW0Q0kilFUX6giai/FsGkc23agqypqoZ02oJpmvB6vZi/YAHmlZaisLAQiqJgeHgYl/v7MTAwADoODMOAoigTAGVyTwGgkUyLiO44zm/EMIxhEZlDZh+YGvOEcxWmGUEwGMRjjz2GjRs2YunSpfDl+QAAdtrG+Pg4TNPEpUuX0PTxxzh48ADGx8fh9XpBTg9IKAI4pCmGYSQAceekHAJFVRCJRLB27Vq8/tvXseT7SwAAHR0dOHz4MDo6OnD9+nVYloX8vHyUlZdhcWUlUpaF5uZm9Pf3Q1XV20BM3AMASMMwjIRhGMw1CgoKCIAvvPACU8kkSXJgYIBPPPEEjUCAE7zmHHPvnMuqqioWFRXR7/czEAjk8mHlYCBzXpqmIRwOY9OmTfho70eZqP/RgdraWvT29kJEcN999+Ghhx7C3eV3w+P1IBwOo7u7G+3t7RgcHITH44HH44HjOFOjnmqTDExFF2AwGKTP5+OCBQt47T/XmE6n2dXVxbvuuosAWFRUxIaGBl7/73VONytlsedSD7dt20afz8f8/HwGg0HOwrKV8wgmqX/zD2+SJGPRGNesWUMALCkpYVtbW8ZZ0mLn151sOdzC5uZmfvXlV4xFY1kwB/YfoGEY/w/ETACBQID5+fksKvoeey71kCT/2tpKXdfpdru55y97SJKdX3dy3bp1LCwspNvtpsfjYUFBAVetXMVjx44xmcjcmU8++YS6rjMQCOS6BzMBhEIhqqrKVatWMRaN0bEdPv/z5wmA1dXVTCaT7LnUw7KysuyF03WdiqJQRKhpGl0uF3fu3EkrZZEkt2/fTgAsKCiYAUDJpXa2baOsrAxerxfxeBy9vb0AgJUrV0LXdTT8sQEDAwNYvXo1PvjgA5xqO4VDzYewefNmuN1ueDwe1NfX48jRIwCBl7e+jIULFyIej0NRbnc5A8DkTfX7/RBFkEgmYI6aAICysjKMjY7h+PHjCAaD8Pv9OHToEHa9twv33HMP9u7di3f/9C5EFOi6jtdeew1DQ0MovKMQGzdsRCKR+BYAItB1HQBgmqMgCU3VsnNpK40rV67gxtANkMT+/fvR0tKCDz/8EFU/rMKXf/8StXW12PLss4jH4+jq6kJ7ezsIoqqqCrquZ1/JaQAyE4oIysvLoaoqLvf1IRaNId+fj/KycgDAyZMnYaUtpO00HMfBli1b8NRTTyMUCmFkZASNjY2wbRt1dXV46623cPGfF7Fi5Qok4gnMmz8PwWAQ6XQ6NwMiAsuyUFFRgVAohPMXzqPvch9UVcVP1qyBoggOHDyIM2fOYHHlYgQCATQ2NuLP77+PQCCQAd1/GclEEqXzSrF582ZcvHARra2tUDUNXo8XPq8vmz1nAFBVBfF4HEVFRaioqIBpmmhqagIAPPLIWvxo1Y8xNjaKhoYGpFIpjIyMYPuvtuPVX7yKSCQCkiicUwiPx4NIOILly5bh8ccfR9vJNui6C8lkElbauo1+AMgqYSiUEZ8n657kG797I/vanD1zliTZ19vHBx54gACy77yqqnS5XPR6vdQ0jUePHKVlWezu6mZxcTEB8J133iFJfvHFOfr9fhq360FGBwJGZtLn87G0tJSdX3eyoqKCIsJFixbx6r+vkiSvXbvG+vp6FhcXU9O07CiZO5d79+xlOp1mdCzK8fFxfvPNN3zmmWfYfq6dJLl79+4pWjAdwASqSQne1biLx48dnxAZN5csWcLzneezEtvb08sD+/fzvV3vsampiVf6rzCVSDEei7OpqYnLli1jS0sLk8kkw+Ew01aa69evp6IoDIVCMwFkJiaSUF4eS0pKaEZM7vj9DgKg2+1mcXEx3377bd68cZO5LBaNcWRkhPfee282ZwxcGaBt2zz9t9P0+Xy55PgWA4ZxiwUR4aZNm0iSO3bsoMfjoaIoVFWVlfdX8qWXXmLjzkZevXqVfX193Lp1Kx999FFGo1Hu3r2bJXNL2H6unalkhpXq6mpqmjYRvTEbAzOz4SvbXiFJtp1s44MPPkiXy3Vb0XH69GmeOHEi+/u5555jMplkV1cXU4kU6ZAv1r84Wx6YPR0bgQBDoRABsK62jqlkiiS579N9rKmp4eLFi+n3+/n5qc957tw5lpeXs6amhvs+3cdwOELHdhiPxTPORaaf+1QWcgEITMmMGSYqKyv5Wctn2fMeGxtjd3c3BwcHOTw8zBtDN7L/2WmbZ8+e5YoVKwhgFuczSjK4Z2tnNE1DNBqF4zhYvnw5Nvx0Ax5++GHMnz8fLpcLJGFZFgYHB3HhwgUcOnwYra2tSCTGEQgEZkjv9JJMDMMYBmTOlLp9Sh2f+VQUFQAxNjYG27YRDIZw553FKCgogCIKRsdGMXR9CDeHb8JxCMMwoKoKbNuezTEBAemMimEY+0Rkw63GRHI2JoBAVRVABGkrDctKZaNTFBW67oLL5co0gY6TqwCdaraIqCRbJC8vb5Gqqh0i4r7Vmk1nYmbRckvTJdsXfovTyZbLmXBuichSJRaLdYnIz0hGRUTL9IXIycAkLpKgQziOA8exp0Q8y9Jb8zLhPCYiNaZpnlcBqMlk8l8ej+cYyTkA7gCgT6L9DocNIAzgqIg8bZrmCQDq/wBcV6BSGdN3ewAAAABJRU5ErkJggg==&logoColor=white)](https://kayba.ai)
+[![Discord](https://img.shields.io/discord/1429935408145236131?label=Discord&logo=discord&logoColor=white&color=5865F2)](https://discord.gg/mqCqH7sTyK)
+[![Twitter Follow](https://img.shields.io/twitter/follow/kaybaai?style=social)](https://twitter.com/kaybaai)
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://kayba-ai.github.io/agentic-context-engine/latest/)
+
+> [!TIP]
+> ACE is the open-source engine behind [Kayba](https://kayba.ai). If you'd rather have the whole loop managed for you, from failure investigation to fixes shipped as PRs, [get a demo](https://kayba.ai).
+
+---
+
+**AI agents don't learn from experience.** They repeat the same mistakes every session, forget what worked, and ignore what failed. ACE is the open-source engine that adds a persistent learning loop. It also powers [Kayba](https://kayba.ai), the managed service that does this for your production agents automatically.
+
+<img src="examples/seahorse-emoji-ace.gif" alt="ACE learns from mistakes in real time" width="70%"/>
+
+> The agent claims a seahorse emoji exists. ACE reflects on the error, and on the next attempt, the agent responds correctly — without human intervention.
+
+---
+
+## Proven Results
+
+| Metric | Result | Context |
+|:-------|:-------|:--------|
+| **2x consistency** | Doubles pass^4 on Tau2 airline benchmark | 15 learned strategies, no reward signals |
+| **49% token reduction** | Browser automation costs cut nearly in half | 10-run learning curve |
+| **$1.50 learning cost** | Claude Code translated 14k lines to TypeScript | Zero build errors, all tests passing |
+
+---
+
+## Quick Start
+
+```bash
+uv add ace-framework
+```
+
+**Option A** — Interactive setup (recommended):
+
+```bash
+ace setup            # Walks you through model selection, API keys, and connection validation
+```
+
+**Option B** — Manual configuration:
+
+```bash
+export OPENAI_API_KEY="your-key"    # or ANTHROPIC_API_KEY, or any of 100+ supported providers
+```
+
+Then use it:
+
+```python
+from ace import ACELiteLLM
+
+agent = ACELiteLLM(model="gpt-4o-mini")
+
+# First attempt — the agent may hallucinate
+answer = agent.ask("Is there a seahorse emoji?")
+
+# Feed a correction — ACE extracts a strategy and updates the Skillbook
+agent.learn_from_feedback("There is no seahorse emoji in Unicode.")
+
+# Subsequent calls benefit from the learned strategy
+answer = agent.ask("Is there a seahorse emoji?")
+
+# Inspect what the agent has learned
+print(agent.get_strategies())
+```
+
+No fine-tuning, no training data, no vector database.
+
+[-> Quick Start Guide](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/quick-start/) | [-> Setup Guide](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/setup/) | [-> Hosted API: Where Do Traces Come From?](https://kayba-ai.github.io/agentic-context-engine/latest/integrations/hosted-api/#where-do-traces-come-from)
+
+---
+
+## How It Works
+
+ACE maintains a **Skillbook** — a persistent collection of strategies that evolves with every task. Three specialized roles manage the learning loop:
+
+| Role | Responsibility |
+|:-----|:---------------|
+| **Agent** | Executes tasks, enhanced with Skillbook strategies |
+| **Reflector** | Analyzes execution traces to extract what worked and what failed |
+| **SkillManager** | Curates the Skillbook — adds, refines, and removes strategies |
+
+The **Recursive Reflector** is the key innovation: instead of summarizing traces in a single pass, it writes and executes Python code in a sandboxed environment to programmatically search for patterns, isolate errors, and iterate until it finds actionable insights.
+
+```mermaid
+flowchart LR
+    Skillbook[(Skillbook)]
+    Start([Task]) --> Agent[Agent]
+    Agent <--> Environment[Environment]
+    Environment -- Trace --> Reflector[Reflector]
+    Reflector --> SkillManager[SkillManager]
+    SkillManager -- Updates --> Skillbook
+    Skillbook -. Strategies .-> Agent
+```
+
+All roles are backed by [PydanticAI](https://ai.pydantic.dev/) agents with structured output validation. PydanticAI routes to 100+ LLM providers through its LiteLLM integration, with native support for OpenAI, Anthropic, Google, Bedrock, Groq, and more.
+
+*Based on the [ACE paper](https://arxiv.org/abs/2510.04618) (Stanford & SambaNova) and [Dynamic Cheatsheet](https://arxiv.org/abs/2504.07952).*
+
+---
+
+## Runners
+
+| Runner | Class | Description |
+|:-------|:------|:------------|
+| **LiteLLM** | `ACELiteLLM` | Batteries-included agent with `.ask()`, `.learn()`, `.save()` — accepts any [LiteLLM model string](https://docs.litellm.ai/docs/providers) |
+| **Core** | `ACE` | Full learning loop with batch epochs and evaluation |
+| **Trace Analyser** | `TraceAnalyser` | Learn from pre-recorded traces without re-running tasks |
+| **browser-use** | `BrowserUse` | Browser automation that improves with each run |
+| **LangChain** | `LangChain` | Wrap any LangChain chain or agent with learning |
+| **Claude Code** | `ClaudeCode` | Claude Code CLI tasks with learning |
+
+```bash
+uv add 'ace-framework[browser-use]'    # Browser automation
+uv add 'ace-framework[langchain]'      # LangChain
+uv add 'ace-framework[logfire]'        # Observability (auto-instruments PydanticAI)
+uv add 'ace-framework[mcp]'            # MCP server for IDE integration
+uv add 'ace-framework[deduplication]'  # Embedding-based skill deduplication
+```
+
+Have existing agent logs? Extract strategies from them directly:
+
+```python
+from ace import ACELiteLLM
+
+agent = ACELiteLLM(model="gpt-4o-mini")
+agent.learn_from_traces(your_existing_traces)
+print(agent.get_strategies())
+```
+
+[-> Examples](examples/)
+
+---
+
+## Benchmarks
+
+### Tau2 — Multi-Step Agentic Tasks
+
+[tau2-bench](https://github.com/sierra-research/tau2-bench) by Sierra Research: airline domain tasks requiring tool use and policy adherence. Claude Haiku 4.5 agent, strategies learned on the train split with no reward signals, evaluated on the held-out test split.
+
+<img src="benchmarks/tasks/tau_bench/Tau2Benchmark Result Haiku4.5.png" alt="Tau2 Benchmark — ACE doubles consistency at pass^4" width="35%"/>
+
+*pass^k = probability all k independent attempts succeed. ACE doubles consistency at pass^4 with 15 learned strategies.*
+
+### Claude Code — Autonomous Translation
+
+ACE + Claude Code translated this library from Python to TypeScript with zero supervision:
+
+| Metric | Result |
+|:-------|:-------|
+| Duration | ~4 hours |
+| Commits | 119 |
+| Lines written | ~14,000 |
+| Build errors | 0 |
+| Tests | All passing |
+| Learning cost | ~$1.50 |
+
+---
+
+## Pipeline Architecture
+
+ACE is built on a composable pipeline engine. Each step declares what it requires and what it produces:
+
+```
+AgentStep -> EvaluateStep -> ReflectStep -> UpdateStep -> DeduplicateStep
+```
+
+Use `learning_tail()` for the standard learning sequence, or compose custom pipelines:
+
+```python
+from ace import Pipeline, AgentStep, EvaluateStep, learning_tail
+
+steps = [AgentStep(agent, skillbook), EvaluateStep(env)] + learning_tail(reflector, skill_manager, skillbook)
+pipeline = Pipeline(steps)
+```
+
+The pipeline engine ([`pipeline/`](pipeline/)) is framework-agnostic with `requires`/`provides` contracts, immutable context, and error isolation. See [Pipeline Design](docs/design/PIPELINE_DESIGN.md) and [Architecture](docs/design/ACE_ARCHITECTURE.md).
+
+---
+
+## CLI
+
+| Command | Description |
+|:--------|:------------|
+| `ace setup` | Interactive setup — model selection, API keys, connection validation |
+| `ace models <query>` | Search available models with pricing |
+| `ace validate <model>` | Test a model connection |
+| `ace config` | Show current configuration |
+| `kayba` | Cloud CLI — upload traces, fetch insights, manage prompts |
+| `ace-mcp` | MCP server for IDE integration |
+
+---
+
+## Documentation
+
+- [Full Documentation](https://kayba-ai.github.io/agentic-context-engine/latest/) — Guides, API reference, examples
+- [Quick Start](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/quick-start/) — 5-minute setup
+- [Setup Guide](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/setup/) — Configuration and providers
+- [Hosted API Guide](https://kayba-ai.github.io/agentic-context-engine/latest/integrations/hosted-api/) — Hosted CLI, trace upload, prompt install
+- [Architecture](docs/design/ACE_ARCHITECTURE.md) — Core concepts and system design
+- [Code Reference](docs/design/ACE_REFERENCE.md) — Implementations, API, usage examples
+- [Design Decisions](docs/design/ACE_DECISIONS.md) — Rejected alternatives and rationale
+- [Pipeline Engine](docs/design/PIPELINE_DESIGN.md) — Step composition and context flow
+- [Examples](examples/) — Runnable demos
+- [Changelog](CHANGELOG.md) — Version history
+
+---
+
+## Contributing
+
+Contributions are welcome. See [Contributing Guidelines](CONTRIBUTING.md).
+
+---
+
+<div align="center">
+
+**Built by [Kayba](https://kayba.ai) and the open-source community.**
+
+</div>

ace.toml

@@ -0,0 +1,2 @@
+[default]
+model = "us.writer.palmyra-x5-v1:0"

ace/__init__.py

@@ -0,0 +1,197 @@
+"""ACE — Agentic Context Engine.
+
+All public symbols are lazily imported to keep ``import ace`` fast.
+Direct attribute access (``ace.ACE``, ``from ace import ACE``)
+works — the underlying module is loaded on first use.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Static analysis / IDE autocomplete — never executed at runtime.
+    from pipeline import Branch, MergeStrategy, Pipeline, SampleResult, StepProtocol
+
+    from .core import (
+        ACEStepContext,
+        EnvironmentResult,
+        InsightSource,
+        Sample,
+        SimpleEnvironment,
+        Skill,
+        Skillbook,
+        SkillbookView,
+        TaskEnvironment,
+        TraceIdentity,
+        UpdateBatch,
+        UpdateOperation,
+    )
+    from .deduplication import DeduplicationManager, SimilarityDetector
+    from .implementations import Agent, Reflector, SkillManager
+    from .integrations import wrap_skillbook_context
+    from .protocols import DeduplicationConfig
+    from .providers import ACEModelConfig, ModelConfig
+    from .steps.rr_step import RRConfig, RRStep
+    from .tracing import configure as configure_tracing
+    from .runners import (
+        ACE,
+        ACELiteLLM,
+        ACERunner,
+        BrowserUse,
+        ClaudeCode,
+        LangChain,
+        TraceAnalyser,
+    )
+    from .steps import (
+        AgentStep,
+        CheckpointStep,
+        DeduplicateStep,
+        EvaluateStep,
+        ExportSkillbookMarkdownStep,
+        LoadTracesStep,
+        ObservabilityStep,
+        PersistStep,
+        ReflectStep,
+        UpdateStep,
+        learning_tail,
+    )
+
+# ---- lazy import mapping: name -> (module_path, attribute) ----------------
+
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # Pipeline engine (re-exported from pipeline/)
+    "Pipeline": ("pipeline", "Pipeline"),
+    "Branch": ("pipeline", "Branch"),
+    "MergeStrategy": ("pipeline", "MergeStrategy"),
+    "StepProtocol": ("pipeline", "StepProtocol"),
+    "SampleResult": ("pipeline", "SampleResult"),
+    # ACE context
+    "ACEStepContext": ("ace.core", "ACEStepContext"),
+    "SkillbookView": ("ace.core", "SkillbookView"),
+    # Core data types
+    "InsightSource": ("ace.core", "InsightSource"),
+    "Skill": ("ace.core", "Skill"),
+    "Skillbook": ("ace.core", "Skillbook"),
+    "TraceIdentity": ("ace.core", "TraceIdentity"),
+    "UpdateOperation": ("ace.core", "UpdateOperation"),
+    "UpdateBatch": ("ace.core", "UpdateBatch"),
+    "Sample": ("ace.core", "Sample"),
+    "EnvironmentResult": ("ace.core", "EnvironmentResult"),
+    "TaskEnvironment": ("ace.core", "TaskEnvironment"),
+    "SimpleEnvironment": ("ace.core", "SimpleEnvironment"),
+    # Implementations
+    "Agent": ("ace.implementations", "Agent"),
+    "Reflector": ("ace.implementations", "Reflector"),
+    "SkillManager": ("ace.implementations", "SkillManager"),
+    # Deduplication
+    "DeduplicationConfig": ("ace.protocols", "DeduplicationConfig"),
+    "DeduplicationManager": ("ace.deduplication", "DeduplicationManager"),
+    "SimilarityDetector": ("ace.deduplication", "SimilarityDetector"),
+    # Integrations
+    "wrap_skillbook_context": ("ace.integrations", "wrap_skillbook_context"),
+    # Config
+    "ModelConfig": ("ace.providers", "ModelConfig"),
+    "ACEModelConfig": ("ace.providers", "ACEModelConfig"),
+    # Runners
+    "ACE": ("ace.runners", "ACE"),
+    "ACELiteLLM": ("ace.runners", "ACELiteLLM"),
+    "ACERunner": ("ace.runners", "ACERunner"),
+    "BrowserUse": ("ace.runners", "BrowserUse"),
+    "ClaudeCode": ("ace.runners", "ClaudeCode"),
+    "LangChain": ("ace.runners", "LangChain"),
+    "TraceAnalyser": ("ace.runners", "TraceAnalyser"),
+    # Steps
+    "AgentStep": ("ace.steps", "AgentStep"),
+    "EvaluateStep": ("ace.steps", "EvaluateStep"),
+    "ReflectStep": ("ace.steps", "ReflectStep"),
+    "UpdateStep": ("ace.steps", "UpdateStep"),
+    "DeduplicateStep": ("ace.steps", "DeduplicateStep"),
+    "CheckpointStep": ("ace.steps", "CheckpointStep"),
+    "LoadTracesStep": ("ace.steps", "LoadTracesStep"),
+    "ExportSkillbookMarkdownStep": ("ace.steps", "ExportSkillbookMarkdownStep"),
+    "ObservabilityStep": ("ace.steps", "ObservabilityStep"),
+    "PersistStep": ("ace.steps", "PersistStep"),
+    "learning_tail": ("ace.steps", "learning_tail"),
+    # Recursive Reflector
+    "RRStep": ("ace.steps.rr_step", "RRStep"),
+    "RRConfig": ("ace.steps.rr_step", "RRConfig"),
+    # Tracing
+    "configure_tracing": ("ace.tracing", "configure"),
+}
+
+
+def __getattr__(name: str) -> object:
+    if name in _LAZY_IMPORTS:
+        module_path, attr = _LAZY_IMPORTS[name]
+        import importlib
+
+        module = importlib.import_module(module_path)
+        value = getattr(module, attr)
+        # Cache on the module so __getattr__ is only called once per name.
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'ace' has no attribute {name!r}")
+
+
+__all__ = [
+    # Pipeline composition
+    "Pipeline",
+    "Branch",
+    "MergeStrategy",
+    "StepProtocol",
+    "SampleResult",
+    # ACE context
+    "ACEStepContext",
+    "SkillbookView",
+    # Core data types
+    "InsightSource",
+    "Skill",
+    "Skillbook",
+    "TraceIdentity",
+    "UpdateOperation",
+    "UpdateBatch",
+    # Environments
+    "Sample",
+    "EnvironmentResult",
+    "TaskEnvironment",
+    "SimpleEnvironment",
+    # Implementations
+    "Agent",
+    "Reflector",
+    "SkillManager",
+    # Config
+    "ModelConfig",
+    "ACEModelConfig",
+    # Runners
+    "ACE",
+    "ACELiteLLM",
+    "ACERunner",
+    "BrowserUse",
+    "ClaudeCode",
+    "LangChain",
+    "TraceAnalyser",
+    # Steps
+    "AgentStep",
+    "EvaluateStep",
+    "ReflectStep",
+    "UpdateStep",
+    "DeduplicateStep",
+    "CheckpointStep",
+    "LoadTracesStep",
+    "ExportSkillbookMarkdownStep",
+    "ObservabilityStep",
+    "PersistStep",
+    "learning_tail",
+    # Recursive Reflector
+    "RRStep",
+    "RRConfig",
+    # Deduplication
+    "DeduplicationConfig",
+    "DeduplicationManager",
+    "SimilarityDetector",
+    # Tracing
+    "configure_tracing",
+    # Utilities
+    "wrap_skillbook_context",
+]

ace/cli/__init__.py

@@ -0,0 +1,39 @@
+"""Kayba CLI."""
+
+import click
+
+from ace.cli.cloud import (
+    upload,
+    traces,
+    run,
+    insights,
+    prompts,
+    status,
+    materialize,
+    batch,
+    setup,
+    integrations,
+)
+
+
+@click.group()
+@click.version_option(package_name="ace-framework")
+def cli():
+    """Kayba CLI."""
+    pass
+
+
+cli.add_command(upload)
+cli.add_command(traces)
+cli.add_command(run)
+cli.add_command(insights)
+cli.add_command(prompts)
+cli.add_command(status)
+cli.add_command(materialize)
+cli.add_command(batch)
+cli.add_command(setup)
+cli.add_command(integrations)
+
+
+def main():
+    cli()

ace/cli/client.py

@@ -0,0 +1,310 @@
+"""HTTP client for the Kayba hosted API."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any, Dict, List, Optional
+
+
+class KaybaAPIError(Exception):
+    """Structured error from the Kayba API."""
+
+    def __init__(self, code: str, message: str, status_code: int = 0):
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        super().__init__(f"[{code}] {message}")
+
+
+DEFAULT_BASE_URL = "https://use.kayba.ai/api"
+MAX_TRACE_UPLOAD_BODY_BYTES = 900_000
+
+
+def _chunk_trace_uploads(
+    traces: List[Dict[str, Any]],
+) -> List[List[Dict[str, Any]]]:
+    """Split uploads into request-sized batches under the body size cap."""
+    batches: List[List[Dict[str, Any]]] = []
+    current: List[Dict[str, Any]] = []
+    current_size = len('{"traces":[]}')
+
+    for trace in traces:
+        trace_size = len(
+            json.dumps(trace, ensure_ascii=False, separators=(",", ":")).encode(
+                "utf-8"
+            )
+        )
+        separator_size = 1 if current else 0
+        candidate_size = current_size + separator_size + trace_size
+
+        if current and candidate_size > MAX_TRACE_UPLOAD_BODY_BYTES:
+            batches.append(current)
+            current = [trace]
+            current_size = len('{"traces":[]}') + trace_size
+            continue
+
+        current.append(trace)
+        current_size = candidate_size
+
+    if current:
+        batches.append(current)
+
+    return batches
+
+
+class KaybaClient:
+    """HTTP client for the Kayba hosted API.
+
+    Args:
+        api_key: Kayba API key. Falls back to KAYBA_API_KEY env var.
+        base_url: API base URL. Falls back to KAYBA_API_URL env var,
+                  then to https://use.kayba.ai/api.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ):
+        try:
+            import requests
+        except ImportError as exc:
+            raise KaybaAPIError(
+                "DEPENDENCY_MISSING",
+                "The hosted Kayba CLI requires the cloud extra. Install with "
+                "`uv add \"ace-framework[cloud]\"` or "
+                "`pip install 'ace-framework[cloud]'`.",
+            ) from exc
+
+        self.api_key = api_key or os.environ.get("KAYBA_API_KEY", "")
+        if not self.api_key:
+            raise KaybaAPIError(
+                "AUTH_MISSING",
+                "No API key provided. Set KAYBA_API_KEY or pass --api-key.",
+            )
+        self.base_url = (
+            base_url or os.environ.get("KAYBA_API_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.session: Any = requests.Session()
+        self.session.headers["Authorization"] = f"Bearer {self.api_key}"
+
+    @staticmethod
+    def _summarize_http_body(body: str, limit: int = 240) -> str:
+        """Collapse whitespace so raw HTML and proxy errors stay readable."""
+        snippet = re.sub(r"\s+", " ", body or "").strip()
+        if not snippet:
+            return "Unexpected non-JSON error from the Kayba API."
+        if len(snippet) <= limit:
+            return snippet
+        return snippet[: limit - 3] + "..."
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Send a request and return parsed JSON, raising on API errors."""
+        url = f"{self.base_url}{path}"
+        resp = self.session.request(method, url, json=json, params=params)
+
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                err = body.get("error", {})
+                if isinstance(err, str):
+                    raise KaybaAPIError(
+                        code="API_ERROR",
+                        message=err,
+                        status_code=resp.status_code,
+                    )
+                message = err.get("message", resp.text)
+                if (
+                    resp.status_code == 413
+                    or "maximum content size" in message.lower()
+                    or "too large" in message.lower()
+                ):
+                    raise KaybaAPIError(
+                        code="PAYLOAD_TOO_LARGE",
+                        message=message,
+                        status_code=resp.status_code,
+                    )
+                raise KaybaAPIError(
+                    code=err.get("code", "UNKNOWN"),
+                    message=message,
+                    status_code=resp.status_code,
+                )
+            except (ValueError, KeyError, AttributeError):
+                message = self._summarize_http_body(resp.text)
+                if resp.status_code == 413:
+                    message = (
+                        "Upload rejected because the request body is too large. "
+                        "Try smaller traces or upload fewer files at once."
+                    )
+                elif resp.status_code in (401, 403):
+                    message = "Authentication failed; check KAYBA_API_KEY"
+                else:
+                    message = f"HTTP {resp.status_code} from Kayba API: {message}"
+                raise KaybaAPIError(
+                    code="HTTP_ERROR",
+                    message=message,
+                    status_code=resp.status_code,
+                )
+
+        if resp.status_code == 204:
+            return {}
+        return resp.json()
+
+    # -- Traces --
+
+    def upload_traces(self, traces: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Upload trace files.
+
+        Args:
+            traces: List of dicts with keys: filename, content, fileType.
+        """
+        batches = _chunk_trace_uploads(traces)
+        if len(batches) == 1:
+            return self._request("POST", "/traces", json={"traces": traces})
+
+        combined: Dict[str, Any] = {"count": 0, "traces": []}
+        for batch in batches:
+            result = self._request("POST", "/traces", json={"traces": batch})
+            uploaded = result.get("traces", [])
+            combined["count"] += result.get("count", len(uploaded) or len(batch))
+            combined["traces"].extend(uploaded)
+            for key, value in result.items():
+                if key not in {"count", "traces"} and key not in combined:
+                    combined[key] = value
+        return combined
+
+    def list_traces(self) -> Dict[str, Any]:
+        """List all traces (metadata only, no content)."""
+        return self._request("GET", "/traces")
+
+    def get_trace(self, trace_id: str) -> Dict[str, Any]:
+        """Get a single trace with full content."""
+        return self._request("GET", f"/traces/{trace_id}")
+
+    def get_traces(self, trace_ids: List[str]) -> Dict[str, Any]:
+        """Batch get traces by IDs (with content)."""
+        return self._request("POST", "/traces/batch", json={"ids": trace_ids})
+
+    def delete_trace(self, trace_id: str) -> Dict[str, Any]:
+        """Delete a single trace."""
+        return self._request("DELETE", f"/traces/{trace_id}")
+
+    def delete_traces(self, trace_ids: List[str]) -> Dict[str, Any]:
+        """Delete multiple traces."""
+        results = []
+        errors = []
+        for tid in trace_ids:
+            try:
+                self.delete_trace(tid)
+                results.append(tid)
+            except KaybaAPIError as e:
+                errors.append({"id": tid, "error": str(e)})
+        return {"deleted": results, "errors": errors}
+
+    # -- Insights --
+
+    def generate_insights(
+        self,
+        *,
+        trace_ids: Optional[List[str]] = None,
+        model: Optional[str] = None,
+        epochs: Optional[int] = None,
+        reflector_mode: Optional[str] = None,
+        anthropic_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Start async insight generation."""
+        body: Dict[str, Any] = {}
+        if trace_ids:
+            body["traceIds"] = trace_ids
+        if model:
+            body["model"] = model
+        if epochs is not None:
+            body["epochs"] = epochs
+        if reflector_mode:
+            body["reflectorMode"] = reflector_mode
+        if anthropic_key:
+            body["anthropicApiKey"] = anthropic_key
+        return self._request("POST", "/insights/generate", json=body)
+
+    def list_insights(
+        self,
+        *,
+        status: Optional[str] = None,
+        section: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """List insights, optionally filtered."""
+        params: Dict[str, str] = {}
+        if status:
+            params["status"] = status
+        if section:
+            params["section"] = section
+        return self._request("GET", "/insights", params=params or None)
+
+    def triage_insight(
+        self,
+        insight_id: str,
+        status: str,
+        note: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Accept or reject a single insight."""
+        body: Dict[str, Any] = {"status": status}
+        if note:
+            body["note"] = note
+        return self._request("PATCH", f"/insights/{insight_id}", json=body)
+
+    # -- Jobs --
+
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        """Get job status."""
+        return self._request("GET", f"/jobs/{job_id}")
+
+    def materialize_job(self, job_id: str) -> Dict[str, Any]:
+        """Materialize completed job results into the skillbook."""
+        return self._request("POST", f"/jobs/{job_id}")
+
+    # -- Prompts --
+
+    def generate_prompt(
+        self,
+        *,
+        insight_ids: Optional[List[str]] = None,
+        label: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Generate a prompt from accepted insights."""
+        body: Dict[str, Any] = {}
+        if insight_ids:
+            body["insightIds"] = insight_ids
+        if label:
+            body["label"] = label
+        return self._request("POST", "/prompts/generate", json=body)
+
+    def list_prompts(self) -> Dict[str, Any]:
+        """List all prompt versions."""
+        return self._request("GET", "/prompts")
+
+    def get_prompt(self, prompt_id: str) -> Dict[str, Any]:
+        """Get a specific prompt by ID."""
+        return self._request("GET", f"/prompts/{prompt_id}")
+
+    # -- Integrations --
+
+    def get_integrations(self) -> Dict[str, Any]:
+        """Get current integration settings."""
+        return self._request("GET", "/integrations")
+
+    def update_integration(self, name: str, config: Dict[str, Any]) -> Dict[str, Any]:
+        """Update an integration's config."""
+        return self._request("PUT", f"/integrations/{name}", json=config)
+
+    def test_integration(self, name: str) -> Dict[str, Any]:
+        """Test an integration connection."""
+        return self._request("POST", f"/integrations/{name}/test")