Core Concepts

DevSpec is built from a small set of concepts that fit together. Understanding them makes everything else click: a project is the workspace, repositories and databases give the AI context about your system, sessions are where you talk to it, action items track the work that comes out of those conversations, and knowledge is what DevSpec remembers across all of them.

What is a Project?

A Project is your central workspace in DevSpec. It usually represents a single product, service, or initiative. It ties together everything the AI needs to understand your system: your code (Git repositories), data (databases), logs, and team members so the AI has complete context.

You can connect multiple repositories and databases to one project, invite teammates, and scope every AI session to it. Because the AI shares context across everything in the project, answers draw from your code, schema, and prior discussions at the same time.

What is a Repository?

A Repository is a Git codebase you connect to a project — from GitHub, Bitbucket, GitLab, or Gitea. DevSpec clones and indexes it so the AI can read and reason about your actual code rather than guessing.

A single project can hold many repositories (a frontend, a backend, shared libraries, infrastructure), and the index spans all of them, so cross-repo questions work naturally.

What is a Database?

A Database is a data source you connect to a project so the AI becomes schema-aware. DevSpec reads your tables, columns, and relationships and uses them to answer questions and write code that matches your real data model — no more inventing column names.

How We Use Your Database

When you connect a database, DevSpec is given read-only access to your schema — and only your schema. We read the structure of your data (tables, columns, types, relationships, indexes, and policies); we never read, query, or store the actual rows inside it.

That schema awareness powers three things:

• Read-only schema sync. DevSpec introspects your database structure and keeps a current snapshot of it. It connects to read metadata only, never to write — your data is never modified and your row-level content is never stored.
• Context for coding agents. Agents use the schema to write accurate SQL, correct migrations, and backend logic that matches your real data models — instead of guessing at table and column names.
• Answering data questions. In a session you can ask things like "how is billing tracked?" and the AI answers from your actual database structure rather than assumptions.

DevSpec only ever reads your schema. To stay on the safe side, connect a staging database — or a read-only user — when you first evaluate DevSpec.

Why Connect Logs?

Connecting a log source — Axiom or Grafana Loki — gives DevSpec access to your runtime logs and error traces. This is what lets the AI reason about how your code actually behaves once it is running, not just how it reads on the page.

Log access powers three things:

• Investigating production bugs. When something breaks in production, the AI can query your logs directly — reading the error traces and surrounding events — instead of guessing from the code alone.
• Analyzing error traces. The AI ties errors back to the code paths that produced them, so a vague "it's throwing 500s" becomes a specific, actionable diagnosis.
• Closing the loop after a deploy. Once a change ships, the AI can check the logs to confirm the new code is behaving as expected — turning "it built" into "it works in production."

Connecting logs is optional — most teams add it later from project settings. As with databases, start with a staging account or a scoped, read-only token while you evaluate DevSpec.

What is a Session?

A Session is a conversation with DevSpec's AI, scoped to a project. Every session inherits the project's full context — code, schema, knowledge, and earlier discussions — so you can pick up where you left off instead of re-explaining your system each time.

Sessions are where most work begins: you describe a problem or idea, the AI helps you think it through, and the outcomes are captured as action items and knowledge.

What is an Action Item?

An Action Item is a tracked unit of work — a bug, feature, improvement, task, or query — usually created out of a session. Lifecycle and agent activity are separate, and completion authority is defined by the served devspec://product/implementation-contract plus recorded evidence rather than copied client policy.

Action items connect planning to implementation when a user explicitly requests the work. For a conversation request, the server authorizes an exact owner/delegated target. The agent reserves the requested ids, claims one item at a time, implements in an isolated branch, and records the commit and testing evidence.

What is a Dedicated Branch?

A Dedicated Branch is the Git branch you set aside for DevSpec when you connect a repository. AI coding agents running in tools such as Claude Code, Pi, and OpenCode push their work to this branch. Keeping one branch dedicated to agent work means their commits always land in a predictable place, and DevSpec always knows which branch to watch for testing and deployment.

Because agents are continuously pushing here, human developers should not push to the dedicated branch directly. If people and agents commit to the same branch at the same time, their changes collide — so let the agents own this branch and do your own work elsewhere.

The dedicated branch is also where the pull request workflow begins. After an explicit request, an agent reserves and claims the named action item, implements it in an isolated worktree, and pushes the result to the dedicated branch. From there the change flows into your main branch the usual way — through a pull request you review and merge — so every agent contribution still passes the same review and checks as any other.

How Coding Agents Work

DevSpec and your coding agent split the work between them. DevSpec plans and remembers — it holds your project's context (code, schema, logs, and past decisions) and turns conversations into tracked action items. The agent executes — it writes the actual code. That division of labor is what closes the gap between planning the work and actually shipping it.

The connection between the two is your access token, but connection presence does not authorize implementation. A current direct request or server-authorized exact-target owner/delegated canonical command names the work. The agent calls reserve_work_items for those ids, then claim_work_item one at a time while reading the item's intent, acceptance criteria, and project context.

From there the agent implements each claimed item in an isolated branch, runs project checks, and delivers according to configured settings. Internal assignment-named reservation rows coordinate claims only. Typed controls and owner-scoped automations remain separate from action-item acquisition. DevSpec watches delivery and deployment so recorded work flows into normal review and release processes.

Supported Coding Tools

DevSpec connects live coding agents over MCP so they can read your project's context and act on its action items. Telling DevSpec which coding tools you use lets it tailor setup commands and connection instructions to each tool—without pretending that selecting a tool has started an agent. You can switch tools later without redoing your setup.

Supported tools fall into two families:

• Terminal-based tools run in your command line and work across the whole repository. Claude Code is deeply integrated, while Pi, Codex, OpenCode, Antigravity, and Grok Build support their own terminal workflows and DevSpec commands.
• Editor-based tools live inside your IDE, alongside the file you are editing. Cursor connects through a DevSpec extension that adds command-palette actions and registers the MCP server for you. Antigravity is a similar editor-based integration.

Pick the tool you use under Settings → Connections and follow its steps; come back for another whenever you start using one. DevSpec configures the same underlying connection model, so the difference is which terminal or editor workflow fits how you already work. Wherever DevSpec pre-selects a tool, it is the one you connected most recently.

What is Knowledge?

Knowledge is what DevSpec remembers about your project across sessions: architecture decisions, coding conventions, recurring patterns, and known risks. It is captured automatically from your conversations and reused as context in future ones, so the AI keeps getting more useful the more you work in a project.