Spec Editor

The Spec Editor holds your project's spec and its architecture document. Connected agents read both as the governing record of what the project is, what it is built with, and what it must not do.

Where to find it

Open Spec Editor in the sidebar (item 2, or press Ctrl+2). The panel has 2 tabs at the top: Spec and Architecture. The editor works on the project currently selected in the app.

Anyone can read the spec. Who can change it depends on your role when the project is shared with a team (see Rules and limits).

What you see on the Spec tab

The header shows the project name, the subtitle "Project Specification", the date the project was created, and a Save button. Below the header the cards appear in this order.

Description

The Description card holds a rich text description of the project. It is read-only until you click the pencil icon in the card header. While editing, the check icon saves and returns the card to read mode. The X icon discards your description changes and restores the text you started with.

Tech stack

The Tech Stack card lists the technologies the project uses. Entries come from 2 sources:

• Detected entries. When you import a repository, Vibeless reads each manifest it finds (such as a package.json or Cargo.toml) and adds one entry per manifest. Each entry shows a label, the manifest path, the lockfile if one exists, and up to 8 tags. Detected entries are read-only here.
• Manual entries. Click Add custom to add a technology that no manifest declares, such as a hosting service. Enter a Name and an optional Category / language, then click Add. Manual entries carry a Manual badge and stay editable inline. A trash icon removes them.

Manual entries survive a later re-import of the repository. A manual row left without a name is dropped when you save.

Detected entries also record the dependency versions from their manifest. These are the "pinned versions" the drift check uses. Drift is a gap between what the project record says and what the code does. When you run a drift check, each pinned dependency is compared with the same manifest in the repository:

• If the manifest now declares an incompatible version, the check reports a High finding.
• If the manifest no longer declares the dependency, the check reports a Medium finding.
• If the manifest itself is no longer found, the entry is skipped, not flagged.

Manual entries carry no versions, so the drift check does not compare them.

Goal statement

The Goal Statement card is a single text field for a one-sentence goal for the project. Agents see it near the top of their session briefing.

Constraints

A constraint is a rule the project must follow, such as "No new runtime dependencies without review". The Constraints card lists them as editable rows. Click Add to add a row and the trash icon to remove one.

Some constraints also carry an enforcement pattern that the drift check can match against code. These appear under Machine-enforced rules with a lock icon. They are read-only in the Spec Editor and are kept unchanged when you save. You manage them from the Dashboard's Enforcement tab (see Dashboard).

Non-goals

A non-goal is something the project has decided not to do, such as "No mobile app in this release". The Non-Goals card works like the constraints list: type each non-goal on its own row. Path globs that let the drift check flag changes in out-of-scope folders are added through enforcement proposals, not typed here. A non-goal that carries path globs is not shown on this card.

Each list card (Tech Stack, Constraints, Non-Goals) shows a View / Edit all button with a count. It opens the full list in a side sheet. Edits in the sheet and in the card are the same edits.

What you see on the Architecture tab

The Architecture tab holds one Markdown document, headed Architecture Document, that describes how the project is built. The tab has 3 parts.

The editor

A code-style Markdown editor with line numbers and word wrap. You type plain Markdown. A Save button sits in the header.

The toolbar

The toolbar wraps the text you have selected in Markdown:

The last 2 buttons decrease and increase the editor font size, between 8 and 32. The app remembers the size on this computer.

The architecture helper

The Architecture helper box below the editor is an LLM assistant that drafts architecture text for you. It needs a paid plan, and each request uses credits from your plan's budget. The free plan has no LLM features.

1. Describe what you want in the text box, for example a new section or an expansion of an existing one.
2. Click Generate. The helper reads your current document and streams a draft into a preview below the box.
3. Read the draft. Click Insert into editor to add it to the end of your document. If the document is empty, the draft becomes the whole document.
4. Click Save. Inserting does not save on its own.

To turn the architecture into phases, use Generate from Architecture in the Phase Planner. A phase is a stage of work that groups related tickets. See Phase Planner.

How saving works

Nothing in the Spec Editor saves automatically.

• On the Spec tab, Save (or Ctrl+S) writes every field at once: description, tech stack, goal, constraints, and non-goals. The description card's check icon does the same full save. A "Spec saved" message confirms it.
• On the Architecture tab, Save (or Ctrl+S) writes the document. An "Architecture saved" message confirms it.

Unsaved edits are not kept if you switch between the Spec and Architecture tabs, open another panel, or switch projects. Save first.

Each Spec tab save is recorded in Version History, one event per changed field, and you can review those events there (see Logs). Architecture saves are recorded against the architecture document itself, so they do not appear in the Version History event list.

How agents use the spec

Agents connect to Vibeless through MCP and read the spec with these tools:

Claude Code and Codex also receive a session briefing (the SessionStart digest) when a session starts. It contains the project name, the goal, a condensed tech stack, the constraints, the first 1,500 characters of the architecture document, and the project's decisions, with decisions that carry forbids listed first. When the spec map may be out of date, it also carries a staleness line. It points the agent to vibeless_get_architecture when the document is longer. The briefing does not include the description or the non-goals. On the Claude Code profile, the agent reads those through vibeless_get_project_context.

Agents read the spec but never write constraint patterns, non-goal path globs, or decision forbids. A forbid is a dependency name on a decision that the decision rules out. These fields change only through enforcement proposals on the Dashboard's Enforcement tab, which a person accepts or rejects there (see Dashboard).

Rules and limits

On a project you work on alone, you can change everything in the Spec Editor.

On a project shared with a team, your role decides what you can save:

On a shared project, only a maintainer can change the Spec tab, because every project field governs agents. The same rule covers decision forbids (see Logs) and phase path globs (see Phase Planner).

The architecture helper needs a paid plan and uses credits. Paid plans differ by credit budget, not by features.

If something looks wrong

• A save fails with a message about maintainers. You are an editor on a shared project. Ask a maintainer to make the spec change.
• A save fails with a message about a view-only seat. You are a viewer. Ask a maintainer for editor or maintainer access.
• Your edits disappeared. You switched tabs, panels, or projects before saving. Re-enter the changes and click Save.
• The tech stack is empty. No repository has been imported yet. Import one, or add entries with Add custom.
• The drift check reports a tech stack mismatch you expected. You upgraded a dependency on purpose. Re-import the repository so the detected entry records the new version.
• A machine-enforced rule is wrong. You cannot edit it on the Spec tab. Manage it from the Dashboard's Enforcement tab.