AgSpec: give coding agents a contract before they touch the code

Coding agents rarely fail because they cannot write a function. They fail because the task left three reasonable interpretations open, the API contract lived in one person’s head, or “done” meant code written to one person and behavior verified to another. The agent fills those gaps with plausible guesses, and a fast implementation arrives at the wrong destination. AgSpec puts a deliberate contract between the task and the first code change.

That contract is not a giant requirements document. It is a small set of linked Markdown artifacts, each with one job, stored directly on the Agentis task. Product intent stays separate from observable behavior, observable behavior stays separate from technical design, and the implementation checklist is derived only after those three agree.

Four artifacts, four decisions

A complete AgSpec answers four questions in dependency order. Splitting the answers matters: when scope, requirements and implementation details share one document, a technical edit can quietly change the promised behavior and a product clarification can invalidate half the plan without anyone noticing.

• proposal.md explains why the change exists, what is in scope, what is explicitly out, and which capabilities are new or changing.
• <capability>-spec.md defines what the system must do through normative requirements and observable WHEN/THEN scenarios. Each declared capability gets exactly one spec.
• design.md explains how the change will work: components, data flow, contracts, security, migration, trade-offs and test strategy.
• tasks.md maps every observable outcome to a stable acceptance criterion, implementation work and a separate verification step.

Task
  -> grill-me interview
  -> proposal.md
  -> <capability>-spec.md
  -> design.md
  -> tasks.md
  -> implementation + verification

The order is the control mechanism. A design cannot be complete while the required behavior is undecided. A checklist cannot be trustworthy while the design still contains a blocking question. AgSpec makes those dependencies explicit instead of letting implementation discover them accidentally.

The interview starts with evidence, not questions

Run /agspec-create on the current Agentis task and the authoring agent first reads the task, project documentation, relevant code and any existing specification files. It loads the grill-me workflow, but that does not mean dumping a questionnaire on the user. Decisions that can be established from the repository are resolved from evidence. Only genuine product choices or implementation blockers are asked, one at a time, with a recommended answer and the reason behind it.

The interview follows dependencies. An answer about compatibility may open a migration question; a decision about tenancy may require an authorization boundary; choosing asynchronous delivery may expose retry and idempotency behavior. The next question depends on the previous answer, so a static batch of ten questions would hide exactly the decision tree the process is meant to explore.

“Research what the project already knows. Ask only for decisions the project cannot make. Write the specification only when no blocking ambiguity remains.”

Scenarios turn intent into observable behavior

Capability specs are the center of the contract. They do not describe files to edit or functions to call. They describe behavior another person can observe and a test can prove. Normative language removes the escape hatches: the system MUST do something under a stated condition, and the scenario says what outcome follows.

### Requirement: Authorized users can export billing data
The system MUST export only data visible in the active tenant.

#### Scenario: Cross-tenant records exist
- **WHEN** an authorized user exports the selected month
- **THEN** the file contains no records from another tenant

That scenario can survive a complete implementation rewrite. It remains true whether the export uses a synchronous endpoint, a queued job or a stored artifact. The design chooses the mechanism; the capability spec protects the outcome.

Done becomes a traceable state

The tasks document converts each independently observable scenario outcome into a stable AC identifier. Every AC points back to its source requirement and must have at least one implementation checkbox and one verification checkbox. The distinction prevents a common fiction in agent work: treating “the code exists” as proof that “the behavior works”.

| ID | Acceptance criterion | Source |
| --- | --- | --- |
| AC-1 | Export contains no cross-tenant records. | billing-export / Cross-tenant records exist |

- [ ] 2.1 [AC-1] Apply tenant scope to the export query; complete when every export path uses the active tenant.
- [ ] 3.1 [AC-1] Run pytest tests/test_billing_export.py; pass when the cross-tenant isolation case succeeds.

Verification must name an executable command or a precise manual procedure and its expected result. “Test the export” is not a completion condition. A specific pytest command that must pass for authorized, forbidden, empty and cross-tenant cases is.

The specification travels with the task

AgSpec files are not scratch notes in one agent’s worktree. They are Markdown specifications attached to the Agentis task and exposed through five MCP operations: list, read, create, edit and delete. Any MCP-compatible agent can load the same contract, regardless of which agent authored it or which machine starts the next run.

• Create is create-only, so it cannot silently overwrite an existing artifact.
• Edit applies one atomic patch across one or more files, so a failed change does not leave half a document set behind.
• Stale source context rejects the edit instead of overwriting a newer concurrent revision.
• Every mutation remains tied to the task and can be audited by caller, operation, filename and time.

This storage model changes handoffs. One agent can run the interview and write the contract; another can implement it tomorrow; a third can resume only the remaining verification next week. The task carries both the decisions and the progress, so continuity does not depend on replaying a conversation window.

Updates preserve completed work

Specifications change, especially after implementation reveals an edge case. Running /agspec-create again updates the existing artifact set instead of replacing it. Semantically unchanged acceptance criteria keep their IDs. Unchanged checklist items keep their number, text and checkbox state. Completed work is never deleted, renumbered, rewritten or reopened; newly required corrective work becomes a new pending item.

That rule is more than tidy bookkeeping. Stable IDs preserve review comments and test mappings, while immutable completed checkboxes preserve the historical claim that a specific completion condition was met at a specific stage. If the desired behavior changes later, the contract records new work rather than rewriting history to make the old implementation look incomplete.

Implementation is a separate, guarded phase

The authoring command never edits production code. Implementation starts separately with /agspec-implement. Before touching the repository, the implementing agent loads proposal.md, design.md, tasks.md and every capability spec declared by the proposal. If one is missing, the documents contradict each other or a blocking decision remains open, the run stops and names the blocker instead of inventing an answer.

When the contract is ready, the agent implements pending items in dependency order, performs each item’s own completion condition, runs the prescribed verification and marks only the work actually completed. A later run resumes from the unchecked items. A safe subset can be implemented on its own, but skipped or failed verification remains visibly pending.

• Use AgSpec for changes spanning several components, APIs, data models, permissions or user scenarios.
• Use it when another person or agent will implement the task, or when delivery will span multiple runs.
• Use it when acceptance, security or migration behavior must be reviewable before code exists.
• Skip the full workflow for a tiny isolated edit whose intent, implementation and verification are already unambiguous.

AgSpec is not ceremony for making agents slower. It moves the expensive uncertainty to the cheapest part of the process: before code, migrations and tests have committed the team to an interpretation. The reward is not merely a better plan. It is a durable contract that can be reviewed before implementation, enforced during it and resumed long after the original conversation is gone.