Guides·Sep 5, 2026·4 min read

Where the specs live

Specs are easier to work with when they follow a familiar structure and you can find the changes that need your attention.

Putting specs in files made it easier to resume work with an AI agent. After a few projects, keeping track of those files became a job of its own.

What a workspace looks like

Part three covers why specs belong outside the chat. I use OpenSpec to organise them, with the agreed behaviour, work in progress and past decisions under one directory:

openspec/
├── config.yaml       project context and rules for writing specs
├── specs/            agreed behaviour, one folder per capability
└── changes/
    ├── add-a-thing/   proposal, design, spec deltas and tasks
    └── archive/      completed changes, in dated folders

A change starts with a proposal. If there are decisions worth discussing, it gets a design. Spec deltas describe what should change, and a task list breaks down the work. Archiving folds the accepted deltas into specs/ and moves the change folder into the archive.

The archive keeps the reasoning with the work. When a decision comes up again, I can see the alternatives and the reasons for the choice. When I drafted this article, this site had 59 archived changes and SpecForge, the viewer I built for these workspaces, had 115.

Written to be read

The specs need to be easy to read and review. AI tends to write long, and the structure can change from one proposal to the next. I do not want to work out how a document is organised every time I open one.

openspec/config.yaml holds the project context and rules OpenSpec passes to the agent when it writes an artifact. Here is a shortened version of mine:

rules:
  proposal:
    - Use a descriptive title, not the change slug.
    - Tag each What Changes bullet [HIGH], [MED] or [LOW].
    - Describe the impact file by file.
  design:
    - Write a design when there is a decision worth discussing.
    - Record each decision as "Chosen:" / "Rejected — why:".
    - Draw flows as Mermaid diagrams.
  specs:
    - Use concrete values: sizes, counts, colours and routes.

With a consistent structure, I know where to find the reason for a change and what it affects. Recording rejected options helps me see what the agent considered. Concrete values make review easier too: I can check 44px; “large enough” leaves me guessing.

I also ask the agent to choose a format that suits the content. Each pair below, shown in SpecForge, is the same information written twice: what arrives without the rule, then what the rule asks for.

Mermaid diagrams for flows and state machines.

Maths notation for formulas.

SVG for visuals that need exact geometry.

Code fences for commands, paths and expected output.

The Mermaid rule came from trying to read designs drawn in ASCII art. I added it to the configuration so I would not have to ask again. These rules accumulate as I use the project, alongside the more portable knowledge in skills from part two.

One change, one worktree

I give each change its own git worktree: a separate checkout on its own branch. Several agents can work at once, and I can review one branch without disturbing another checkout. Part four covers the loop that runs the work.

The checkout includes the specs. If a proposal is committed before the worktree is created, both checkouts can contain it:

main checkout:
  openspec/changes/add-spec-workspace-guide/

worktree:
  openspec/changes/add-spec-workspace-guide/

Two folders, one change.

The copies can diverge as the agent updates tasks and revises the design on its branch. I need to see which copy I am reading, but I do not want the same change counted twice.

Keeping track across projects

Across four repositories, each with its own worktrees, checking progress meant opening an editor, finding the right folder and reading it, then repeating that for the next project. Easy enough, but only when I remembered to do it.

I wanted one place to see what was still open, with the proposal, tasks and commits close at hand when I needed a closer look.

A badge for all of it

That is why I built SpecForge. Its desktop app watches the workspaces you register and shows the number of active changes in the menu bar. A change that appears in several worktrees counts once. The badge disappears at zero.

Clicking it opens the workspace tree. I can read a proposal, check the tasks and inspect the commit graph beside them. It brings the planning and the code changes together without making me switch projects in my editor.

The desktop app and browser UI render the formats I ask the agent to use: Mermaid diagrams, maths, SVG images and highlighted code. Figures can be opened in a larger view. The terminal UI shows diagram and SVG fences as code.

SpecForge is read-only. It does not edit specs, tick checkboxes or touch git. I still review and test the work; the viewer makes it easier to find.

Try it

There is a desktop app, a terminal UI and a browser UI. With Node.js and npm installed, you can start the browser UI locally:

npx @avantmedia/specforge

The command downloads the package if needed. SpecForge is still early, v0.x software, and only reads OpenSpec today. The desktop builds are unsigned; the npm route avoids the manual Gatekeeper step. The SpecForge page has the downloads and details.

SpecForge itself is built using OpenSpec. If you already keep track of your work comfortably in an editor, you may not need it. I built it for the point where checking several projects had become something I kept putting off.