# Glossary

Canonical term definitions for Goodboy. Use these in code, UI, docs, and issues.

| Term                         | Definition                                                                                                                                                                                                                                                                                                                               |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **workspace**                | A registered git repository directory. Sessions are scoped to a workspace and run inside isolated worktrees alongside the repo.                                                                                                                                                                                                          |
| **session**                  | A goal-oriented container inside a workspace. Owns the git worktree, the branch, the shared context slots, the budget, and the list of agents. Auto-spawns one default agent on creation. Has a user-selectable status (wip / waiting / blocked / done). Supports soft-delete and archive. _DB table:_ `sessions`.                       |
| **agent**                    | An independent chat thread inside a session. Has its own provider/model/effort/verbosity, its own message history, its own kind label, and its own status (pending / running / completed / failed). User spawns agents from the sidebar at will; rename inline via the pencil icon. Supports soft-delete. _DB table:_ `agents`.          |
| **agent kind**               | One of 8 role labels: scout, planner, implementer, debugger, tester, reviewer, docs, generic. Determines default model, effort, and optional system prompt. Inferred from agent name or first user turn; overridable manually via the kind menu.                                                                                         |
| **shared context**           | The synthetic slots (goal, files touched, decisions, open questions, last summary) attached to a session. Visible in the right-side context panel; auto-populated by the summarizer after every agent turn. All agents in the session read the same context. Slots are collapsible, rendered as markdown, and have history tracking.     |
| **plan**                     | A first-class artifact captured from a planner agent's output via `<<plan>>...<<plan>>` markers. Session-scoped. Status: active / consumed / superseded. Other agents consume plans; consumption is tracked. Viewable in the plans modal with tree rendering. _DB table:_ `session_plans`.                                               |
| **plan consumption**         | A record that an agent consumed (read and acted on) a specific plan. Tracked per agent per plan with timestamp. _DB table:_ `plan_consumptions`.                                                                                                                                                                                         |
| **next action**              | A suggested follow-up action (scout / plan / implement) inferred by the summarizer after each agent turn. Displayed as clickable chips below the chat. Clicking a chip spawns a pre-configured agent with the right kind, model, effort, and initial prompt.                                                                             |
| **session status**           | User-selectable lifecycle label on a session: wip, waiting, blocked, done. Displayed as an icon in the sidebar session row. Persisted to DB.                                                                                                                                                                                             |
| **workflow** _(beta)_        | An optional preset that pre-spawns N named agents at session creation (e.g. scout → planner → implementer → reviewer). Comes from the seeded library, settings authoring, or the planner agent ("design custom" chip). After spawn, the agents are independent and live alongside any free-form ones. _DB table:_ `workflows` + `steps`. |
| **step**                     | One agent role inside a workflow. Carries a name, a prompt prefix, and optional provider/model overrides. Becomes the seed for one pre-spawned agent.                                                                                                                                                                                    |
| **planner**                  | A cheap-tier provider call that turns a free-text theme into a `PlannerOutput` (workflow name + ordered steps). Surfaced as the "design custom" chip in the new-session dialog.                                                                                                                                                          |
| **worktree**                 | The git worktree directory for a session — the path on disk where files live while the session is active. Removed when the session ends; the branch is preserved.                                                                                                                                                                        |
| **branch**                   | The git branch the worktree checks out. Named `<prefix>/<slug>` by default. Preserved after the session ends for manual review or merge.                                                                                                                                                                                                 |
| **skill**                    | A markdown + scripts automation invocable from chat via `/skill-name`. Discovered from `<workspace>/.kay/skills/*.md` or `<workspace>/.claude/skills/<name>/SKILL.md`; auto-rescanned on workspace add. Per-workspace, not global.                                                                                                       |
| **permission rule** _(beta)_ | A matcher pattern for tool-call interception. Determines whether a tool invocation is allowed, denied, or requires confirmation.                                                                                                                                                                                                         |
| **turn**                     | One user prompt → one assistant response, including all streaming events in between. The atomic unit of interaction within an agent.                                                                                                                                                                                                     |
| **parallel group** _(beta)_  | Multiple agents executing in parallel on throwaway worktrees, merged back at completion. Workflow-driven; opt-in via global settings → Agent.                                                                                                                                                                                            |
| **notification**             | A persistent feed entry (info / warning / error) for budget alerts, session events, and system messages. Viewable in the notification center (bell icon in sidebar top). Supports toasts for transient display. _DB table:_ `notifications`.                                                                                             |
| **diff comment**             | A user annotation on a specific file + line in the diff viewer. Can be open, resolved, consumed (by a reviewer agent), or deleted. _DB table:_ `diff_comments`.                                                                                                                                                                          |
| **initialization (db wipe)** | Settings → Initialization → "Wipe local database". Drops every workspace / session / agent / message in `~/.goodboy/data.db` and re-runs migrations on next boot. API keys in the OS keychain are not touched.                                                                                                                           |
