Spec-driven development that actually sticks

Teams building with coding agents have seen unequivocally that agents produce better outputs when you iterate with them on a solid plan first. This makes sense, once they have goals and a plan to get there, they can go execute. The problem is that most spec workflows stop at the feature boundary. You write a plan, build the thing, and ship it. But then the spec is no longer leveraged, it doesn’t accumulate into anything. You can verify that this feature meets its acceptance criteria, but you have no way to see if all your other features are still in place as intended.

gjalla solves this by providing an interface to aggregate your specs and use them at the points of highest leverage: when planning new features and when verifying pull requests. Here’s how it works.

What is spec-driven development?

Spec-driven development is the name given to the workflow of writing specs before having agents implement code. The idea is that you write your requirements, then your technical design, then your tasks. The agent executes against your task to implement the technical design and meet the requirements.

I like to think of it like a coloring book: you define the lines, which are the boundaries and expectations of your end goal. Then your agent fills in the color.

There are tools like Kiro IDE, SpecKit, OpenSpec, and others that help facilitate the workflow. The biggest gap is that none of these tools or platforms give a mechanism to know when your agent has drawn outside the lines of your full system. They may tell you that you’re outside the lines on a single feature, but you care about the system as a whole.

Specs aren’t just pre-flight checklists. They’re the ongoing record of intent that steers every future agent, in every future session, on every future feature.

How to use gjalla for aggregate spec driven development

Step 1: Connect your repo

Creating a project in the gjalla dashboard prompts you to install the GitHub App. The initial analysis takes a little while, but when it’s done gjalla has backfilled a master spec from what it finds in your code: behavioral capabilities, architecture components, data flows, API surface, tech stack.

You can view and edit these under Explore > Capabilities in the portal. Fill in any nuances you want tracked, or specific acceptance criteria that matters to you. This becomes your baseline… the starting master spec that every future change layers on top of.

Step 2: Install the CLI (or ask your agent to do it)

pipx install gjalla
gjalla setup

Setting up the CLI is what gives your agent the steering it needs to save nearly 50% on token use during planning while designing a solution that fits within your current architecture and constraints. Better aligned & cheaper! It injects guidance into your agent’s configuration files to steer them to a) fetch the context about the state of the system from your master spec, b) use gjalla spec new for planning new features, c) have each commit associated with its spec automatically.

When setup runs, say yes to both prompts: agent guidance (injects the spec workflow into your agent’s config) and commit hooks (pre-commit validates the attestation; post-commit uploads the spec to gjalla automatically). Without both, spec tracking won’t be automatic.

Step 3: Plan with gjalla spec new

Before any code gets written, your agent runs:

gjalla spec new add-rate-limiting

This scaffolds .gjalla/changes/add-rate-limiting/ pre-populated with your project’s architecture context. Your agent fills in four files:

• proposal.md: what you’re building and why. Problem statement, goals, non-goals.
• design.md: which elements are affected, what decisions are being made, how system state changes.
• delta.md: behavioral delta specs using ADDED, MODIFIED, REMOVED markers. Just the changes, not the whole system.
• tasks.md: implementation checklist in dependency order.

You review the plan before any code is written, same as you’re probably already doing. Catching a wrong architectural decision or behavioral nuance at the spec stage is a five-minute fix. After implementation it’s a refactor.

Step 4: Commit. Spec is saved alongside your code diff.

When your agent commits, the spec gets associated with the commit and uploaded to your gjalla project. It’s tracked and ready to be verified on pull request review.

Step 5: PR review verifies intent

When a PR opens, gjalla’s capability review checks the implementation against the spec. More importantly, it flags if any prior requirements have been silently broken. In other words, you can catch unexpected drift before it hits production.

Step 6: Merge: spec goes live

Once the PR merges, the change spec is absorbed into the master spec, so aggregate capabilities and tech design are automatically updated. The docs your team looks at and the context your agent pulls are a) always the same, b) reflective of the entire system, and c) always up to date.

What accumulates over time

As you build, your master spec reflects the actual intent behind your system. Automatically both machine and human readable.

Specs stop being documentation you maintain and start being guardrails that accumulate.

tl;dr

gjalla helps you build a living master spec that your team and agents use as context and as guardrails to prevent drift as you ship.

1. Create a gjalla project and connect your GitHub.
2. Install and setup the gjalla CLI (or ask your agent to do it).
3. Save tokens, maintain understanding, and prevent drift.