> ## Documentation Index > Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt > Use this file to discover all available pages before exploring further. # Core Building Blocks > The primitives behind every Overcut automation: workspaces and projects, the agent harness, workflows, and the runtime that connects them to your Git, tickets, and chat. Overcut organizes engineering automation into a small set of primitives. Once you know what each one is, where it lives, and which boundary it crosses, you can read any workflow, pick the right scope for new work, and reason about what an agent can or can't do at runtime. This page is the orientation map. Each block links to the detailed reference for the topic. ## The hierarchy Every building block belongs to one of three layers: | Layer | What it holds | Examples | | ------------- | ------------------------------------------------ | -------------------------------------------------------------------------- | | **Workspace** | Shared infrastructure for the whole organization | Integrations, LLM Models, Teams, Workspace Secrets | | **Project** | A bounded agent harness owned by one team | Agent Roles, Skills, MCP Servers, Repositories, Vault, Channels, Workflows | | **Runtime** | What exists only while work is happening | Executions, Interactive Sessions, Memories, Retrospectives | A workspace can contain one project or many. The split exists so each scope of work runs against a narrow harness with its own credentials and audit trail, while integrations, models, and team membership stay shared. For the full breakdown, see [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces). *** ## Workspace The **workspace** is the top-level container. It holds everything that should be configured once for the whole organization. * **Integrations**: OAuth connections to GitHub, GitLab, Azure DevOps, Bitbucket, Jira, Linear, ClickUp, and Slack. See the [Integrations overview](/docs/integrations/overview). * **LLM Models**: which models are available to projects, and the workspace default. See [LLM Models](/docs/reference/llm-models). * **Teams, Roles, Users**: who has access, and at what permission level. * **Workspace Secrets**: platform-wide credentials such as the Claude API key. *** ## Project A **project** is the unit of work and ownership. It bundles the agent harness for one scope (one product, one environment, one customer) and the team that runs it. Each project has its own: * **Repositories** it is allowed to read from and act on * **Project Channels** (the Slack channels it can post to and be triggered from) * **Agent Roles**, **Skills**, and **MCP Servers** that define what its agents can do * **Project Vault** for project-scoped secrets * **Workflows** and their **Executions** Projects are isolated by default: vault, repositories, and history from one project are not visible to another. Create a new project when the work targets a different codebase, needs different credentials, or should be owned by a different team. Stay in one project when scope, secrets, and people are shared. *** ## The agent harness The harness is the set of resources, inside a project, that an agent can see and call. A narrow harness produces sharper, more predictable runs than a wide one. The harness is composed of six building blocks. ### Repositories Repositories are connected at the workspace level, then granted to each project. A project either uses every workspace repository or a chosen subset (the **Allow access to all repositories** toggle on **Project Settings → Project Repositories**). Beyond raw access, repositories carry three pieces of metadata that make them useful at runtime: * **[Repository Mapping](/docs/repositories/repository-mapping)**: which repositories a given ticket relates to, so the [`repo.identify`](/docs/workflows/repo-identify) action can pick the right code for the work. * **[Repository Caching](/docs/repositories/repository-caching)**: pre-cloned repositories on the runner so workflows start fast. * **[Repository Indexing](/docs/repositories/repository-indexing)**: semantic code search so agents find relevant context without scanning the tree. ### Integrations Integrations are the OAuth connections that let Overcut listen to events and act through provider APIs. They are configured once at the workspace level, then exposed to projects through repositories and channels. | Provider | What it enables | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | [GitHub](/docs/integrations/github), [GitLab](/docs/integrations/gitlab), [Azure DevOps](/docs/integrations/azure-devops), [Bitbucket](/docs/integrations/bitbucket) | Read and write code, open PRs, comment, react to PR and issue events. | | [Jira](/docs/integrations/jira), [Linear](/docs/integrations/linear), [ClickUp](/docs/integrations/clickup) | Read and write tickets, comment, react to lifecycle events. | | [Slack](/docs/integrations/slack) | Trigger workflows from `@overcut` mentions, the `/overcut` slash command, or channel messages; let agents reply, edit, react, and continue threads. | Agent tools are **provider-agnostic**. An instruction like "open a pull request" or "create a ticket" works across every connected integration without changing the agent. See the [Agent Tools Reference](/docs/reference/tools). The workspace-level Integrations page: connected provider organizations (GitHub, ClickUp, GitLab, Jira, Linear, Azure DevOps, Slack) listed as cards with a Disconnect button, alongside a left-rail of all orgs grouped under the Integrations tree. ### Channels A **channel** is a Slack channel that a specific project is allowed to use. Channels are registered on **Project Settings → Project Channels** and each one has a routing mode: * **Interactive**: only `@overcut` mentions and `/overcut` slash commands start workflows. * **Active**: every top-level channel message is also a trigger event. Useful for incident channels, alert channels, and routing on bot posts. Once a channel is registered, agents in that project can post, reply in threads, edit, and react inside it, and an [interactive session](/docs/reference/interactive-sessions) can continue in a Slack thread the same way it does on a PR or issue. ### Agent Roles An **agent role** is a reusable AI worker. Each role is built on one of five **base agent types**, which determine its default toolset and built-in role instructions: | Base Type | Default tools | Best for | | -------------------- | ------------- | ----------------------------------------------- | | **Senior Developer** | 30 | Implementation, debugging, full code lifecycle | | **Tech Writer** | 25 | Documentation, spec writing, structured content | | **Code Reviewer** | 24 | PR reviews, code quality, CI monitoring | | **Product Manager** | 18 | Ticket management, planning, triage | | **Custom** | 0 | Hand-pick every tool | You extend a base type with additional instructions, extra tools, MCP servers, and skills to produce specialized agents (for example, a "Backend Developer" and a "Frontend Developer", both built on Senior Developer). See [Base Agent Types](/docs/reference/base-agents). Agent roles are project-scoped. Each role lives in exactly one project's harness. The Agent Roles page: a grid of nine project agents (Backend Developer, Code Reviewer, Daily Planning Product Manager, DevOps Engineer, Docs Technical Writer, Frontend Developer, House Keeping Agent, QA Engineer, Security Reviewer) each shown with its color tag, description, model, and a sample of its tools. ### Skills A **skill** is a reusable set of instructions that lives in one of your connected repositories, packaged in the open [Agent Skills](https://github.com/anthropics/skills) format. After a skill is added to a project, you assign it to the agent roles that should follow it. Skills are the right place for guidance that should be authored once and applied consistently: framework conventions, review checklists, escalation rules, naming standards. Keeping them in a repository means they version with the code they describe. See [Skills](/docs/reference/skills). The Skills page: a left rail listing the project's skills (PR Description, Test Plan, Architecture Diagram, Release Notes, Customer Reply, Incident Postmortem) and a right pane showing the selected PR Description skill with its source repo, path, pinned ref, last-synced metadata, and a read-only SKILL.md preview. ### MCP Servers **MCP Servers** give agents access to external tools through the [Model Context Protocol](https://modelcontextprotocol.io/): a database, an internal API, a third-party service, a custom toolset. Install common servers with one click from the [MCP Catalog](/docs/quick-starts/mcp-catalog), or configure a custom server. Each server can be assigned to specific agent roles, and you can restrict which of its tools an agent is allowed to call. See [MCP Servers](/docs/reference/mcp-servers). The MCP Servers page: a left rail of installed servers (Figma, Datadog, Notion, Playwright, Sentry, PagerDuty, Postgres) with the Figma server selected. The right pane shows General (server name), Configuration (a JSON stdio config), and an Allowed Tools list (get_file, get_file_nodes, get_file_images, ...). ### Project Vault The **Project Vault** stores credentials that workflows, agents, and MCP servers need at execution time: API keys, tokens, database passwords. Secrets are encrypted at rest, injected into the execution sandbox as environment variables, and never sent to the LLM. See [Vault](/docs/reference/vault). The Project Vault is distinct from **Workspace Secrets**, which holds platform-wide credentials like the Claude API key. *** ## Workflows A **workflow** is one orchestration: a graph that turns an event into an outcome (a reviewed PR, a drafted spec, a triaged ticket, a resolved incident). Workflows live inside a project, and every workflow has one **trigger** and one or more **steps**. The Workflow Builder canvas for a Ticket Triage workflow: an Issue Opened trigger feeds an Identify Repository step, a Triage Ticket agent.run, and a Post Recommendation step, with workflow-level settings on the right. The trigger says when the workflow runs. It can be a Git event (PR opened, issue labeled, comment added), a ticket event, a CI run result, a [scheduled cron](/docs/workflows/scheduled-workflows), a manual click, or an `@overcut` mention or `/overcut` slash command on any PR, ticket, or Slack channel. Events are normalized across providers, so one workflow can react to GitHub, GitLab, or Bitbucket without conditional logic. See [Triggers](/docs/workflows/triggers). A step is one operation in the graph. Some steps are deterministic ([`git.clone`](/docs/workflows/git-clone), [`repo.identify`](/docs/workflows/repo-identify), [`script.run`](/docs/workflows/run-script), [`ci.executeWorkflow`](/docs/workflows/ci-execute-workflow)). Use Run Script for repeatable inline bash commands that should run in the workflow execution container without an AI agent. Other steps run an agent: [`agent.run`](/docs/workflows/agent-run) for a focused task, [`agent.session`](/docs/workflows/agent-session) for an interactive conversation. Outputs from one step flow into the next. Every workflow has a published history and an auto-saved draft, so you can compare versions and restore an earlier definition without losing in-progress edits. See [Workflow Version History](/docs/reference/workflow-history). The Workflows page: a project's catalog of workflows (PR Reviewer, Ticket Triage, Root Cause Analyzer, CVE Remediator, Changelog Generator, Daily Planning, ...) with status, priority, trigger event, slash command, agents, and last-updated columns. *** ## Runtime These building blocks only exist while a workflow is running, or once it has finished. ### Executions An **execution** is one run of a workflow: the trigger event, the path through the graph, every step's input and output, and the agent's chain of reasoning. Executions are visible from the project's **Executions** page in real time. Overcut coordinates concurrent runs so they don't fight over the same resource: * **Resource locking**: only one workflow runs against a given issue, PR, or repository at a time. * **Priority queuing**: a 1 to 100 scale (lower runs first) when several workflows target the same resource. * **Event deduplication**: rapid-fire events on the same resource merge while queued. See [Workflow Execution Control](/docs/workflows/workflow-execution-control). The Executions page: a table of recent workflow runs across PR Reviewer, Slack Incident Responder, Ticket Triage, and other workflows, each row showing trigger, duration, and status (Completed, Failed, Timeout, Skipped, Stopped). ### Interactive sessions An [interactive session](/docs/reference/interactive-sessions) is an ongoing conversation between users and an agent that started with `agent.session`. Comments on the originating PR, issue, or Slack thread route directly into the live session instead of starting a new workflow, so context is preserved. Sessions end on a keyword, a timeout, or a slash command interrupt. Cleanup behavior is covered in [Session Cleanup](/docs/workflows/session-cleanup). ### Memories A **memory** is a piece of knowledge that survives between runs of the same workflow: a coding convention, a recurring issue pattern, a decision made earlier. Agents read and write memories automatically during a run; no extra setup is required. Memories are scoped to one workflow, so each workflow builds its own institutional knowledge. See [Workflow Memory](/docs/how-to/workflows/workflow-memory). ### Self-improvement Workflows get sharper over time through **retrospectives**: automated reviews that look at recent executions, identify patterns, promote tentative findings into active memories, and adjust the weight of existing ones. Retrospectives run when **Auto-Improve Workflows** is enabled at the workspace level and the workflow has retrospectives configured in its **Self-Improvement** panel. See [Workflow Self-Improvement](/docs/how-to/workflows/workflow-self-improvement). ### Monitoring Every step of every execution streams structured logs, inputs, and outputs to the **Executions** page and the project **Dashboard**. From there you can replay a step, inspect what an agent saw, and follow links back to the PR, ticket, or Slack message that triggered the run. *** ## How the blocks compose Reading these in order, the full path of one automation is: 1. A user, a service, or a clock fires an event that matches a **trigger** in a **workflow**. 2. Overcut checks **project** scope (repositories, channels, vault) and queues the **execution**. 3. **Actions** run in order. Some are deterministic (`git.clone`, `repo.identify`, `script.run`, `ci.executeWorkflow`). Some hand off to an **agent role**, which uses its **base type**, **skills**, **MCP servers**, and the project's tools to do the work. 4. The agent reads and writes **memories**, posts back to the originating PR, ticket, or Slack thread, and (optionally) opens an **interactive session** for follow-up comments. 5. The **execution** is recorded, surfaced in monitoring, and made eligible for the next **retrospective**. ## Where to go next * New to the platform: start with the [Quick Starts](/docs/quick-starts) and [Playbooks](/docs/quick-starts/playbooks). * Designing a new workflow: open the [Workflow Builder guide](/docs/how-to/workflow-builder). * Shaping a project's harness: read [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces) and [Base Agent Types](/docs/reference/base-agents). * Connecting tools: browse the [Integrations overview](/docs/integrations/overview) and the [MCP Catalog](/docs/quick-starts/mcp-catalog).