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. Each item moves through a clear lifecycle: open → implemented → done, with a human verifying the result before it is marked done.

Action items are what connect planning to delivery: a coding agent (such as Claude Code or the autopilot plugins) can pick one up, implement it in an isolated branch, and report back with the commit and testing notes.

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 — Claude Code, the autopilot plugins, and other local agents — push all of 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. An agent picks up an 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. Once your agent is connected over MCP, it pulls queued action items from DevSpec, reading each item's intent, acceptance criteria, and surrounding project context — so it starts with everything it needs instead of a blank prompt.

From there the agent does the heavy lifting: it implements each item in an isolated branch, runs your project's checks, and pushes the result to the dedicated branch. DevSpec watches that branch to track testing and deployment, so finished work flows straight into your normal review and release process.

Supported Coding Agents

DevSpec connects to AI coding agents over MCP, so the agent you already use can read your project's context and act on its action items. Telling DevSpec which agent you use lets it tailor its setup commands and connection instructions to that specific tool — there is no generic configuration to adapt by hand, and you can switch agents later without redoing your setup.

Supported agents fall into two families:

• Terminal-based agents run in your command line and work across the whole repository. Claude Code is the most deeply integrated — it runs the autopilot plugin to pick up queued action items automatically, implement them in isolated worktrees, and push the results back. Codex, Antigravity, and Grok Build follow the same terminal workflow, processing one action item (or batch) per invocation via skills.
• Editor-based agents 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.

Today Claude Code, Codex, Cursor, Grok Build, and Antigravity are ready to select as preferred agents. Whichever you pick, DevSpec configures the same underlying MCP connection, so the difference is which workflow fits how you already work — in the terminal or in your editor.

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.