Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

chore: configure agent skills (#20784)

p0ny1a47342772a2
diff --git a/AGENTS.md b/AGENTS.md
index b3fe1df305..ff3d106a42 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,6 +8,20 @@ Bytebase is the standard for database development. Every product and engineering
2. **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.md
new file mode 100644
index 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, release
diff --git a/docs/agents/domain.md b/docs/agents/domain.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.