databao 0.3.3.dev3__tar.gz → 0.3.4.dev1__tar.gz

databao-0.3.4.dev1/.claude/agents/reviewer.md

@@ -0,0 +1,8 @@
+---
+name: reviewer
+description: Read-only reviewer for code and architecture reviews. Cannot edit or write files.
+tools: Read, Glob, Grep, Bash
+---
+
+You are a read-only reviewer. You can inspect code, run non-mutating
+commands, and produce findings — but you must never modify files.

databao-0.3.4.dev1/.claude/settings.json

@@ -0,0 +1 @@
+{}

databao-0.3.4.dev1/.claude/skills/autosteer/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: autosteer
+description: Run the full development pipeline autonomously without pausing between phases. Stops only on quality-gate failures.
+argument-hint: "[ticket-id-or-task-description]"
+---
+
+# Autosteer
+
+Suspends the **pacing rule** from `CLAUDE.md`. Proceed through all phases
+without confirmation, stopping **only** on quality-gate failures.
+
+## Activation
+
+- Do **not** pause between phases or present plans for approval.
+- **Do** stop on quality-gate failure (`make check`, `make test`,
+  `make test-cov-check`). Attempt fix twice, then stop and report.
+
+## Steps
+
+### 1. Resolve the ticket
+
+If argument is a ticket ID (`DBA-XXX`, number, or URL): fetch with
+`get_issue`, move to **Develop**.
+
+If free-text: create via `create_issue` in **DBA** project (derive
+summary, description, type; default Task). Move to **Develop**.
+
+If no argument: ask user once, then proceed autonomously.
+
+### 2. Execute phases
+
+Follow **After Completing Work** in `CLAUDE.md` (phases 1-7), with:
+- Phase 2 (implement): up to two retries on test failure.
+- Phase 3 (validate): run quality gates per **Quality Gates** in `CLAUDE.md`.
+  Two fix attempts, then stop.
+- Phase 4 (review): fix Critical/High findings, note Medium/Low.
+- Phase 5-7: use `create-branch`, `create-pr` skills. Skip pre-push pause.
+
+### 3. Report
+
+Output: ticket ID/link, branch name, PR URL, unfixed review findings.
+
+## Guardrails
+
+- Never commit or push to `main`.
+- Never skip quality gates.
+- Never create a ticket without at least a task description.
+- Stage specific files -- never `git add -A` or `git add .`.
+- If `gh` or YouTrack MCP unavailable, stop and inform user.

databao-0.3.4.dev1/.claude/skills/check-coverage/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: check-coverage
+description: Run test coverage measurement, analyze results, and fix gaps when coverage falls below the 80% threshold.
+---
+
+# Check Coverage
+
+## Steps
+
+### 1. Run `make test-cov-check`
+
+If tests pass and coverage >= 80%, done.
+
+### 2. If tests fail
+
+- **Existing tests broke**: fix production code, not tests.
+- **New tests fail**: fix the test.
+- **Ambiguous**: read test intent. If behavior intentionally changed, update
+  test and document in commit message.
+
+### 3. If coverage below 80%
+
+Check "Missing" column. Prioritize:
+1. New code you just wrote (must have tests).
+2. Critical paths (error handling, validation, CLI logic).
+3. Utility functions with clear contracts.
+
+Do NOT: add trivial tests just to raise numbers, add `# pragma: no cover`
+without justification, or test third-party/Streamlit internals.
+
+### 4. Write tests
+
+Add to `tests/test_<module>.py`. Use `project_layout` fixture when needed.
+One behavior per test function.
+
+### 5. Re-run `make test-cov-check`
+
+Repeat until threshold met.
+
+### 6. HTML report (optional)
+
+`make test-cov` -- opens `htmlcov/index.html`.
+
+## Failure handling
+
+- Missing `pytest-cov`: run `uv sync --dev`.
+- Uncoverable lines (platform-specific, external calls): add
+  `# pragma: no cover` with reason, note in commit message.

databao-0.3.4.dev1/.claude/skills/check-coverage/evals/evals.json

@@ -0,0 +1,38 @@
+{
+  "skill_name": "check-coverage",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Check test coverage and fix any gaps.",
+      "expected_output": "Agent runs coverage check, identifies uncovered lines, and proposes meaningful tests.",
+      "assertions": [
+        "Agent runs `make test-cov-check` or equivalent pytest-cov command",
+        "Agent examines the coverage report to identify uncovered lines",
+        "Agent proposes tests for uncovered code rather than adding pragma comments",
+        "Agent does NOT add trivial or empty tests solely to raise the number"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "The CI is failing because test coverage dropped below 80%. Fix it.",
+      "expected_output": "Agent identifies which lines lost coverage, writes targeted tests, and re-verifies.",
+      "assertions": [
+        "Agent runs `make test-cov-check` to reproduce the failure",
+        "Agent identifies specific uncovered lines from the report",
+        "Agent writes tests in the corresponding tests/test_<module>.py file",
+        "Agent re-runs `make test-cov-check` to verify the fix",
+        "Agent does NOT lower the coverage threshold in pyproject.toml"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Some tests are failing after my code change. Also coverage is below threshold.",
+      "expected_output": "Agent fixes test failures FIRST, then addresses coverage gaps.",
+      "assertions": [
+        "Agent fixes existing test failures before addressing coverage",
+        "Agent fixes production code (not tests) when existing tests break",
+        "Agent addresses coverage only after all tests pass"
+      ]
+    }
+  ]
+}

databao-0.3.4.dev1/.claude/skills/check-pr-comments/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: check-pr-comments
+description: Fetch unresolved PR review threads, triage them, implement fixes, validate, reply in-thread, and resolve.
+compatibility: gh must be installed and authenticated.
+---
+
+# Address PR Comments
+
+## Steps
+
+### 1. Identify the PR
+
+Run `gh auth status`. Use the user-supplied PR number/URL, or detect from
+current branch: `gh pr view --json number,title,url,headRefName,baseRefName`.
+If no PR found, ask the user.
+
+### 2. Fetch unresolved review threads
+
+Get repo owner/name: `gh repo view --json owner,name -q '.owner.login + " " + .name'`
+
+Fetch threads via GraphQL:
+
+```bash
+gh api graphql -f query="
+  query(\$owner:String!, \$repo:String!, \$number:Int!) {
+    repository(owner:\$owner, name:\$repo) {
+      pullRequest(number:\$number) {
+        reviewThreads(first:100) {
+          pageInfo { hasNextPage endCursor }
+          nodes {
+            id isResolved isOutdated
+            comments(first:20) {
+              pageInfo { hasNextPage endCursor }
+              nodes { id author{login} body path line url }
+            }
+          }
+        }
+      }
+    }
+  }" -F owner=<OWNER> -F repo=<REPO> -F number=<PR_NUMBER>
+```
+
+If `hasNextPage` is true, re-run the query adding `after: "<endCursor>"`
+to the corresponding connection (e.g., `reviewThreads(first:100, after:"<cursor>")`).
+Focus on `isResolved: false` threads.
+
+### 3. Triage table -- stop for approval
+
+Present a Markdown table before any edits:
+
+| Comment | File | Triage |
+| --- | --- | --- |
+| <paraphrase> | `path` or `PR-level` | Implement / Reply only / Blocked |
+
+Wait for **explicit** user approval before proceeding.
+
+### 4. Apply fixes
+
+Address one thread at a time, minimal changes. Fix root cause once when
+multiple threads share it.
+
+### 5. Validate
+
+Run smallest meaningful validation for the changed area. Do not claim
+"fixed" without running validation or stating it is unverified.
+
+### 6. Reply and resolve
+
+Reply in-thread:
+```bash
+gh api graphql -f query="mutation(\$threadId:ID!, \$body:String!) {
+  addPullRequestReviewThreadReply(input:{pullRequestReviewThreadId:\$threadId, body:\$body})
+  { comment { url } }
+}" -F threadId=<ID> -f body='Addressed in <summary>.'
+```
+
+Resolve only after reply and real fix:
+```bash
+gh api graphql -f query="mutation(\$threadId:ID!) {
+  resolveReviewThread(input:{threadId:\$threadId}) { thread { id isResolved } }
+}" -F threadId=<ID>
+```
+
+For explanation-only replies, leave thread open unless user says to resolve.
+
+## Guardrails
+
+- No edits, replies, or resolves before user approves the triage table.
+- No unrelated cleanups while addressing comments.
+- No silent thread resolution without a reply and real fix.

databao-0.3.4.dev1/.claude/skills/check-pr-comments/evals/evals.json

@@ -0,0 +1,42 @@
+{
+  "skill_name": "check-pr-comments",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Use the GitHub CLI to address the unresolved review comments on PR #123, make the necessary fixes, and reply to the threads.",
+      "expected_output": "Agent verifies gh access, inspects unresolved review threads for the PR, presents a Markdown triage table, and then pauses for explicit approval before any code changes or GitHub replies.",
+      "assertions": [
+        "Agent runs `gh auth status` before relying on GitHub CLI API calls",
+        "Agent identifies the target PR explicitly rather than scanning arbitrary repository comments",
+        "Agent fetches review threads with `gh api graphql` or an equivalent gh-based API call that preserves thread state",
+        "Agent presents a Markdown table that includes comment summary, referenced file, and triage decision before implementation",
+        "Agent explicitly asks for or waits for user approval after showing the triage table",
+        "Agent does NOT apply code changes or post GitHub replies before approval"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Check the GitHub review comments on my current branch's PR using gh.",
+      "expected_output": "Agent discovers the PR from the current branch with gh, shows a Markdown triage table for unresolved review threads, and waits for approval before working through them.",
+      "assertions": [
+        "Agent uses `gh pr view --json` or equivalent to discover the PR for the current branch when no PR number is given",
+        "Agent asks for a PR number or URL if no PR can be inferred from the current branch",
+        "Agent prioritizes unresolved threads over already resolved ones",
+        "Agent classifies each unresolved thread as `Implement`, `Reply only`, or `Blocked`",
+        "Agent does NOT treat the initial request itself as sufficient approval to edit code"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "A reviewer left an inline PR comment, but I think the current implementation is correct. Handle it with the GitHub CLI.",
+      "expected_output": "Agent inspects the code and the comment, marks the thread as reply-only in the Markdown triage table, and waits for approval before posting or drafting the response.",
+      "assertions": [
+        "Agent reads the referenced code before deciding whether a code change is needed",
+        "Agent allows for an explanation-only outcome when the reviewer request should not be implemented",
+        "Agent marks explanation-only threads as `Reply only` in the triage table",
+        "Agent waits for approval before replying on GitHub",
+        "Agent does NOT resolve the thread silently without addressing it in a reply"
+      ]
+    }
+  ]
+}

databao-0.3.4.dev1/.claude/skills/create-branch/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: create-branch
+description: Create a feature branch following project naming conventions. Use when starting work on a ticket, after understanding the scope, or when the agent needs to branch off main for new work.
+---
+
+# Create Branch
+
+Create a feature branch following the `<nickname>/<descriptive-branch-name>`
+convention used in this repository.
+
+## Steps
+
+### 1. Detect the user's nickname
+
+Resolve the nickname using the first approach that succeeds:
+
+1. **Memory** — check if a stored memory already contains the user's nickname.
+2. **`make nickname`** — outputs the local part of `git config user.email` (before `@`).
+3. **Ask** — if neither works, ask the user.
+
+Once resolved, save the nickname to memory for future conversations.
+
+### 2. Derive a descriptive branch name
+
+Combine the ticket ID (if available) and a short slug describing the change:
+
+- Use lowercase kebab-case: `fix-auth-timeout`, `add-mcp-tool-list`
+- Keep it under 50 characters
+- If a YouTrack ticket is known (e.g., `DBA-123`), prefer including it:
+  `<nickname>/DBA-123-fix-auth-timeout`
+
+### 3. Ensure a clean starting point
+
+- Fetch latest: `git fetch origin`
+- If the working tree has uncommitted changes, warn the user and ask whether
+  to stash or proceed.
+- Branch from `main` (or the base branch the user specifies):
+  `git checkout -b <nickname>/<branch-name> origin/main`
+
+### 4. Confirm
+
+Report the created branch name to the user.
+
+## Guardrails
+
+- Never create branches directly on `main` — always branch _from_ main.
+- Never silently discard uncommitted changes.
+- If the user is already on a feature branch, ask before switching.

databao-0.3.4.dev1/.claude/skills/create-branch/evals/evals.json

@@ -0,0 +1,38 @@
+{
+  "skill_name": "create-branch",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Create a branch for ticket DBA-150 about fixing the status command output.",
+      "expected_output": "Agent detects nickname from remotes, creates a branch like <nickname>/DBA-150-fix-status-output from origin/main.",
+      "assertions": [
+        "Agent resolves the nickname from memory or git email",
+        "Agent fetches from origin before creating the branch",
+        "Branch name follows `<nickname>/<descriptive-name>` pattern",
+        "Branch is created from origin/main, not from the current HEAD of an unrelated branch",
+        "Agent reports the created branch name to the user"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I need a new branch for some exploratory work, no ticket yet.",
+      "expected_output": "Agent creates a branch with a descriptive name without a ticket prefix.",
+      "assertions": [
+        "Agent resolves the nickname from memory or git email",
+        "Agent asks or derives a descriptive slug for the branch",
+        "Branch name does NOT include a ticket ID since none was provided",
+        "Agent does NOT require a ticket to proceed"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Create a branch for DBA-200. I have uncommitted changes in my working tree.",
+      "expected_output": "Agent warns about uncommitted changes and asks user how to proceed before branching.",
+      "assertions": [
+        "Agent detects or warns about uncommitted changes",
+        "Agent asks the user whether to stash, commit, or abort before switching branches",
+        "Agent does NOT silently discard uncommitted changes"
+      ]
+    }
+  ]
+}

databao-0.3.4.dev1/.claude/skills/create-pr/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: create-pr
+description: Stage, commit, push, and open a GitHub PR following project conventions. Use when code is ready to ship.
+compatibility: gh must be installed and authenticated.
+---
+
+# Create PR
+
+## Steps
+
+### 1. Verify preconditions
+
+- Must NOT be on `main`. If so, run `create-branch` skill first.
+- Check `git status` for changes. If clean, inform user and stop.
+
+### 2. Run quality gates
+
+Run all three gates from **Quality Gates** in `CLAUDE.md`. Do not commit
+until they pass.
+
+### 3. Stage and commit
+
+- Extract ticket ID from branch name (`DBA-<number>`) or ask user.
+- Stage specific files (never `git add -A`).
+- Commit per **Commit Messages** in `CLAUDE.md`.
+
+### 4. Pause for confirmation
+
+Show branch, commit(s), and draft PR description. Wait for explicit approval.
+
+> **Autosteer exception**: skip this pause.
+
+### 5. Push and create PR
+
+Push with `-u` flag. Create PR via `gh pr create` using this template:
+
+```
+## Summary
+<1-3 sentence overview>
+
+## Changes
+
+### <Logical change 1>
+<Brief description>
+<details><summary>Files</summary>
+
+- `path/to/file`
+</details>
+
+## Test Plan
+- [ ] <Verification step>
+```
+
+### 6. Report
+
+Output the PR URL.
+
+## Guardrails
+
+- Never push to `main`.
+- Never push without user confirmation (except autosteer).
+- Never skip commit prefix when ticket is known.
+- Never use `git add -A` or `git add .`.
+- If `gh` unavailable, show manual push/PR instructions.

databao-0.3.4.dev1/.claude/skills/create-pr/evals/evals.json

@@ -0,0 +1,38 @@
+{
+  "skill_name": "create-pr",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Create a PR for the changes on my current branch. The ticket is DBA-180.",
+      "expected_output": "Agent stages changes, commits with [DBA-180] prefix, presents a draft PR, pauses for confirmation, then pushes and creates the PR.",
+      "assertions": [
+        "Agent commits with a message prefixed by [DBA-180]",
+        "Agent presents a draft PR description to the user before pushing",
+        "Agent waits for explicit user confirmation before pushing",
+        "Agent pushes with the -u flag",
+        "PR description follows the Summary / Changes / Test Plan template",
+        "Agent reports the PR URL after creation"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Ship my changes as a PR. I'm on a feature branch but I don't remember the ticket number.",
+      "expected_output": "Agent tries to extract the ticket ID from the branch name; if not found, asks the user.",
+      "assertions": [
+        "Agent attempts to extract a ticket ID from the current branch name",
+        "If no ticket ID is found in the branch name, agent asks the user",
+        "Agent does NOT push without a commit message prefix when a ticket is expected"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Create a PR. I'm currently on the main branch.",
+      "expected_output": "Agent refuses to push directly to main and suggests creating a feature branch first.",
+      "assertions": [
+        "Agent detects that the current branch is main",
+        "Agent does NOT push to main",
+        "Agent suggests creating a feature branch or switching to one"
+      ]
+    }
+  ]
+}

databao-0.3.4.dev1/.claude/skills/eval-skills/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: eval-skills
+description: Run structured evaluations on skills to measure quality and track improvements.
+argument-hint: "[skill-name ...] (e.g. local-code-review review-architecture)"
+---
+
+# Eval Skills
+
+## Steps
+
+### 1. Determine skills to evaluate
+
+If names provided via `$ARGUMENTS`, evaluate those. Otherwise list skills
+with `evals/evals.json` files and ask user to pick (accept "all").
+
+### 2. Create iteration directory
+
+```bash
+mkdir -p .claude/evals-workspace/iteration-<N>
+```
+
+Use next sequential number.
+
+### 3. Run eval cases
+
+For each test case in `evals.json`, run twice:
+
+- **With skill**: subagent with skill loaded, save to `iteration-<N>/<skill>-<id>/with_skill/outputs/`
+- **Without skill**: subagent without skill, save to `iteration-<N>/<skill>-<id>/without_skill/outputs/`
+
+Each run starts with clean context.
+
+### 4. Grade
+
+Evaluate assertions against output. Save `grading.json`:
+```json
+{
+  "assertion_results": [{"text": "...", "passed": true, "evidence": "..."}],
+  "summary": {"passed": 3, "failed": 1, "total": 4, "pass_rate": 0.75}
+}
+```
+
+Require concrete evidence for every PASS.
+
+### 5. Aggregate
+
+Save `iteration-<N>/benchmark.json` with mean pass rates (with/without skill) and delta.
+
+### 6. Present results
+
+Show per-eval pass rates, overall delta, always-pass candidates (remove?),
+always-fail candidates (revise?). Save feedback to `feedback.json`.
+
+## Iteration loop
+
+Update SKILL.md based on findings, run new iteration, compare benchmarks,
+stop when pass rates plateau.

databao-0.3.4.dev1/.claude/skills/local-code-review/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: local-code-review
+description: Review local code changes for correctness, regressions, missing tests, and Databao-specific risks.
+argument-hint: "[scope: staged | branch | files:<path>]"
+context: fork
+agent: reviewer
+---
+
+# Local Code Review
+
+You are reviewing code changes for Databao CLI with NO prior context.
+
+## Scope
+
+Review scope: $ARGUMENTS (default: `branch`)
+
+- `staged` -- `git diff --cached`
+- `branch` -- diff against main
+- `files:<path>` -- specific files/directories
+
+## Steps
+
+### 1. Discover changes
+
+Run `git status --short`, then inspect the relevant diff. Read diffs before
+reading large surrounding files.
+
+### 2. Review
+
+1. Read the diff carefully.
+2. Read surrounding implementation for changed logic.
+3. Check related tests -- identify where tests should have changed but did not.
+
+#### Databao-specific priorities
+
+Pay extra attention when changes touch:
+- CLI/API/UI behavior (defaults, help text, argument handling, output)
+- Agent/executor/model-provider wiring (provider defaults, tool contracts)
+- MCP/plugin/integration boundaries
+- Config/build/init flows, datasource/schema/context logic
+- Packaging/deps/lockfile (extras, entrypoints, transitive impact)
+- Test coverage for changed behavior
+
+#### Validation
+
+Run non-mutating checks only:
+- `uv run pytest <targeted paths>` or full suite if practical
+- `uv run ruff check <paths>`, `uv run ruff format --check <paths>`
+- `uv run mypy <paths>`, `uv lock --check`
+
+Never run `--fix` or mutating formatters in review mode.
+
+### 3. Report findings
+
+Order by severity. Each finding:
+- Severity label + concise title
+- Why it matters
+- File and line reference
+- Remediation direction (brief)
+
+Then: open questions, testing gaps, validation performed.
+
+No findings? Say so, mention residual risk or untested surface.
+
+## Guardrails
+
+- Short code snippets for fixes, not full rewrites.
+- Do not bury findings under summaries.
+- Do not claim tests passed unless you ran them.
+- Prefer evidence from the diff over style opinions.

databao-0.3.4.dev1/.claude/skills/local-code-review/evals/evals.json

@@ -0,0 +1,51 @@
+{
+  "skill_name": "local-code-review",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "/local-code-review branch",
+      "expected_output": "Agent determines branch review scope from git, inspects the actual diff, and returns a findings-first review or an explicit no-findings verdict with file references and a testing note.",
+      "assertions": [
+        "Agent determines scope from the current branch diff against the main branch or merge base",
+        "Agent inspects the actual git diff before broad repository scanning",
+        "Output presents findings first or explicitly states that no findings were found",
+        "Output references files and line numbers for any reported findings",
+        "Output includes a testing gap or validation-performed note"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "/local-code-review staged",
+      "expected_output": "Agent performs staged-changes scope discovery from git, stays read-only, and returns severity-ordered findings tied to the staged diff.",
+      "assertions": [
+        "Agent inspects staged changes via git diff --cached",
+        "Agent reads the diff for changed files before reading large surrounding files",
+        "Output orders findings by severity and ties them to concrete behavior risks",
+        "Output includes open questions or assumptions",
+        "Agent does NOT edit any files"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "/local-code-review files:src/databao_cli/mcp/",
+      "expected_output": "Agent reviews the specified files/directory, reading them and their recent git history.",
+      "assertions": [
+        "Agent focuses review on files under src/databao_cli/mcp/",
+        "Agent reads the actual file contents or diffs for the specified path",
+        "Output presents findings with file and line references",
+        "Agent does NOT edit any files"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "/local-code-review",
+      "expected_output": "Agent defaults to branch scope when no argument is provided and runs a branch review.",
+      "assertions": [
+        "Agent defaults to reviewing the branch diff against main",
+        "Agent inspects the repo's available tooling before choosing validation commands",
+        "If validation is run, agent uses non-mutating commands",
+        "Agent does NOT run mutating commands such as formatter fixes"
+      ]
+    }
+  ]
+}