Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
chore: configure agent skills (#20784)
p0ny1a47342772a2
diff --git a/AGENTS.md b/AGENTS.mdindex b3fe1df305..ff3d106a42 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -8,6 +8,20 @@ Bytebase is the standard for database development. Every product and engineering2. **Govern change and access as code.** Reviewed, enforced, and recorded by policy, not by discipline.3. **Make the safe path the easy path.** Safe by default, simple by design — so no one routes around it.+## Agent skills++### Issue tracker++Issues are tracked in Linear via Linear MCP when available, falling back to `linctl`; agent-created issues go to Linear team `BOT`; GitHub PRs may link back to Linear issues, but GitHub Issues and PRs are not the triage surface. See `docs/agents/issue-tracker.md`.++### Triage labels++Triage roles use the default canonical labels: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, and `wontfix`. See `docs/agents/triage-labels.md`.++### Domain docs++This repo uses a single-context domain-doc layout. See `docs/agents/domain.md`.+## Project Architecture- Database schema is defined in `./backend/migrator/migration/LATEST.sql`diff --git a/CONTEXT.md b/CONTEXT.mdnew file mode 100644index 0000000000..758a3b7058--- /dev/null+++ b/CONTEXT.md@@ -0,0 +1,61 @@+# Bytebase++Bytebase is a governed database development workspace. It turns proposed database work into reviewable plans and staged execution across managed database resources.++## Language++**Workspace**:+The top-level collaboration boundary that contains projects, database connections, environments, users, and policies.+_Avoid_: Project, organization++**Project**:+A governance boundary for an application or team's databases. It owns issue workflow, approvals, labels, rollout limits, and database membership.+_Avoid_: Workspace, repository, environment++**Instance**:+A registered database server, cluster, or service connection that Bytebase syncs and operates against. An instance can contain many databases.+_Avoid_: Database, environment++**Database**:+A named database inside an instance that Bytebase tracks and assigns to a project. It is the usual target of schema, data, export, and access work.+_Avoid_: Instance, schema++**Environment**:+A lifecycle tier such as development, staging, or production used to classify and order database work. Environments classify instances, databases, and rollout stages; they are not projects.+_Avoid_: Project, instance, deployment++**Database Change**:+A requested modification to database structure or data managed through Bytebase's workflow. Use this term instead of bare "change" when the object is a database operation.+_Avoid_: Change, rollout, migration++**Plan**:+A reviewable proposal for database work in a project. A plan describes what should happen and to which targets before execution begins.+_Avoid_: Rollout, issue, migration++**Bytebase Issue**:+A project-scoped request and review record for database changes, data exports, role grants, or access grants. It may carry approval state and may link to a plan; it is distinct from Linear or GitHub issues.+_Avoid_: Linear issue, GitHub issue, ticket, plan++**Rollout**:+The execution of a plan, organized into stages and tasks. A rollout exists once a plan is ready to be executed and tracks progress through target environments.+_Avoid_: Plan, issue, release++**Rollout Stage**:+A group of rollout tasks for one environment. Stages express environment order within a rollout.+_Avoid_: Environment, task++**Task**:+A single executable unit within a rollout stage, targeting a database or instance. Tasks are execution work; they are not planning items or issue-tracker tasks.+_Avoid_: Plan spec, checklist item, Linear task++**Task Run**:+A recorded attempt to execute a task. Use this term when discussing execution logs, status transitions, or results rather than the task definition itself.+_Avoid_: Task++**Release**:+A packaged set of database change inputs used to coordinate deployment across targets. It is the change artifact, not the approval record or execution.+_Avoid_: Plan, rollout, issue++**Changelog**:+The recorded history of a database migration after execution. It is evidence that a change ran, not the proposed change itself.+_Avoid_: Change request, releasediff --git a/docs/agents/domain.md b/docs/agents/domain.mdnew file mode 100644index 0000000000..030a581387--- /dev/null+++ b/docs/agents/domain.md@@ -0,0 +1,40 @@+# Domain Docs++How the engineering skills should consume this repo's domain documentation when exploring the codebase.++## Layout++This repo uses a **single-context** domain-doc layout:++- `CONTEXT.md` at the repo root for project domain language.+- `docs/adr/` at the repo root for architectural decisions.++## Before exploring, read these++- **`CONTEXT.md`** at the repo root.+- **`docs/adr/`** — read ADRs that touch the area you're about to work in.++If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.++## File structure++```text+/+├── CONTEXT.md+├── docs/adr/+│ ├── 0001-event-sourced-orders.md+│ └── 0002-postgres-for-write-model.md+└── src/+```++## Use the glossary's vocabulary++When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.++If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).++## Flag ADR conflicts++If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:++> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.mdnew file mode 100644index 0000000000..ac8c9c60b5--- /dev/null+++ b/docs/agents/issue-tracker.md@@ -0,0 +1,48 @@+# Issue tracker: Linear++Issues and PRDs for this repo live in Linear. Linear is the source of truth for incoming requests, triage state, and implementation issues.++Use Linear MCP for Linear operations when available; otherwise use `linctl`. The repo is GitHub-hosted for code review and implementation history: GitHub PRs should reference or attach to the relevant Linear issue, but GitHub Issues and GitHub PRs are not treated as the request tracker or triage queue.++## Agent-created issue isolation++Agent-created issues must go to Linear team `BOT`, not the main product backlog. This keeps exploratory triage, generated PRDs, and wayfinding tickets out of the team's normal planning queue.++Only create or move issues into a product Linear team when the user explicitly names that team and asks to publish there. Otherwise, publish new issues to team `BOT` and leave promotion to a product team as a human decision.++## Conventions++Prefer Linear MCP tools for create/read/update/comment operations when the session exposes them. If Linear MCP is unavailable, use these `linctl` commands:++- **Check the target team**: `linctl team get BOT`.+- **Create an issue**: `linctl issue create --team BOT --title "..." --description "..." --labels needs-triage`.+- **Read an issue**: `linctl issue get <issue-key>`.+- **List issues**: `linctl issue list --team BOT` and filter by triage label/status using the mappings in `triage-labels.md`.+- **Search issues**: `linctl issue search "<query>" --team BOT`.+- **Comment on an issue**: `linctl comment create <issue-key> --body "..."`.+- **Apply / remove triage labels**: use `linctl issue update <issue-key> --labels ...`. `linctl issue update --labels` replaces labels, so fetch the current issue first and pass the full intended label set.+- **Close**: `linctl issue update <issue-key> --state "Done"` or the appropriate canceled/won't-fix workflow state, and leave a closing comment when context is needed.+- **Attach a GitHub PR**: `linctl issue attach <issue-key> --pr <pr-number-or-url>`.++## Pull requests as a triage surface++GitHub PRs are **not** a request surface for triage. They may link to Linear issues, but `/triage` should not pull GitHub PRs into the request queue.++## When a skill says "publish to the issue tracker"++Create a Linear issue in team `BOT` using Linear MCP or `linctl` unless the user explicitly names a product Linear team and asks to publish there.++## When a skill says "fetch the relevant ticket"++Fetch the Linear issue referenced by the user, normally by Linear issue key or URL, using Linear MCP or `linctl issue get <issue-key>`.++## Wayfinding operations++Used by `/wayfinder`. The **map** is a Linear issue in team `BOT` with child Linear issues as tickets.++- **Map**: a single Linear issue holding the Notes / Decisions-so-far / Fog body. Label it with the tracker equivalent of `wayfinder:map` if that label exists; otherwise use the issue title or description to identify it as the map.+- **Child ticket**: a Linear issue in team `BOT`. Record ticket type in a label or description field: `research`, `prototype`, `grilling`, or `task`. Link the child to the map with `linctl issue update <child-key> --parent <map-key>` when Linear parent relationships fit.+- **Blocking**: use Linear issue relations: `linctl issue relation add <child-key> --blocked-by <blocker-key>`. List blockers with `linctl issue relation list <child-key>`.+- **Frontier query**: list open child tickets for the map, drop claimed or blocked tickets, and choose the first remaining ticket in map order.+- **Claim**: assign the Linear issue before starting work: `linctl issue assign <issue-key>` or `linctl issue update <issue-key> --assignee me`.+- **Resolve**: comment with the answer, mark the child ticket done, then append a context pointer to the map's Decisions-so-far.diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.mdnew file mode 100644index 0000000000..b716855d48--- /dev/null+++ b/docs/agents/triage-labels.md@@ -0,0 +1,15 @@+# Triage Labels++The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.++| Label in mattpocock/skills | Label in our tracker | Meaning |+| -------------------------- | -------------------- | ---------------------------------------- |+| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |+| `needs-info` | `needs-info` | Waiting on reporter for more information |+| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |+| `ready-for-human` | `ready-for-human` | Requires human implementation |+| `wontfix` | `wontfix` | Will not be actioned |++When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.++Edit the right-hand column to match whatever vocabulary you actually use.